AI 코딩 도구를 잘 쓰는 팀은 프롬프트가 아니라 작업 계약서를 만든다

Workflow · 2026-05-11 · 6분 읽기

한 팀에서 같은 버그를 두 명이 AI에게 맡겼다고 해봅시다. 한 사람은 "관리자 통계 API 느린 것 좀 고쳐줘"라고 말했고, 다른 사람은 실패 로그, 수정 가능 경로, 수정 금지 영역, 검증 명령을 함께 줬습니다.

첫 번째 작업은 빠르게 끝났지만 리뷰에서 cache key 누락과 테스트 부족이 발견됐습니다. 두 번째 작업은 시간이 조금 더 걸렸지만 PR에 변경 범위, 실패했던 시도, 실행한 검증, 남은 리스크가 남았습니다.

차이는 프롬프트 문장력이 아니라 작업 계약의 유무였습니다.

AI 코딩 도구를 쓰다 보면 프롬프트를 더 잘 쓰고 싶어집니다. 어떻게 말해야 코드를 더 잘 만들지, 어떻게 시켜야 테스트를 더 잘 짤지, 어떻게 요청해야 리팩터링을 안전하게 할지 고민하게 됩니다.

프롬프트는 중요합니다. 하지만 팀 단위로 AI 코딩 도구를 쓰기 시작하면 프롬프트만으로는 부족합니다. 개발자마다 말하는 방식이 다르고, AI에게 제공하는 정보도 다르고, 완료 기준도 다르기 때문입니다.

결과적으로 AI 작업 품질은 모델 성능보다 작업 입력의 품질에 더 많이 흔들립니다.

팀에 필요한 것은 천재적인 프롬프트가 아닙니다. 반복 가능한 작업 계약서입니다.

1AI에게 무엇을 맡길 것인가2AI가 어디까지 바꿔도 되는가3AI가 무엇을 검증해야 하는가4AI가 어떤 증거를 남겨야 하는가5사람은 어디에서 승인해야 하는가

이 글에서는 AI 코딩 도구를 팀 개발 워크플로우에 넣기 위해 필요한 문서 5가지를 정리합니다.

핵심 요약

• AI 코딩 도구를 팀에서 안정적으로 쓰려면 프롬프트보다 작업 계약서가 먼저 필요합니다.
• 작업 계약서는 AI에게 목표, 범위, 금지 영역, 완료 기준, 검증 명령을 명확하게 알려주는 문서입니다.
• Claude Code 문서는 CLAUDE.md 같은 지속 규칙 문서, 검증 기준, 권한 설정, 컨텍스트 관리를 중요하게 다룹니다.
• MCP Prompts는 서버가 prompt template을 제공하고 사용자가 명시적으로 선택해 사용할 수 있는 구조를 설명합니다.
• 공식 문서의 사실은 "도구가 제공하는 기능"이고, 이 글의 해석은 "팀이 그 기능을 반복 가능한 계약 문서로 운영해야 한다"는 것입니다.
• 팀 단위에서는 다섯 문서만 있어도 AI 작업 품질을 크게 안정화할 수 있습니다.

프롬프트보다 작업 계약서가 먼저인 이유

프롬프트는 요청입니다. 작업 계약서는 기준입니다.

AI에게 "관리자 통계 API 성능 개선해줘"라고 말하는 것만으로는 부족합니다. AI는 성능 기준, 수정 가능 파일, 유지해야 할 응답 필드, 캐시 허용 여부, DB schema 변경 가능 여부, 테스트 기준을 모릅니다.

같은 요청을 작업 계약서로 바꾸면 이렇게 됩니다.

1# TASK_CONTRACT2 3## 목표4관리자 통계 API의 p95 응답 시간을 줄인다.5 6## 수정 가능 범위7- `src/admin/stats/**`8- `tests/admin/stats/**`9 10## 수정 금지 범위11- 로그인/세션 로직12- 결제 로직13- DB migration14- `.env*`15 16## 완료 기준17- 기존 응답 필드 유지18- cache miss 시 DB fallback 유지19- lint/typecheck/unit test 통과20- 변경 요약과 rollback 방법 작성

이 문서는 AI에게도 좋지만 사람에게도 좋습니다. 작업 범위가 명확해지고, 리뷰어가 무엇을 봐야 하는지도 분명해집니다.

5개 문서가 연결되는 흐름

다섯 문서는 각각 따로 노는 것이 아닙니다. 하나의 개발 이벤트로 연결됩니다.

AI_GUIDE.md
프로젝트 기본 규칙

TASK_CONTRACT.md
이번 작업 계약

AI 작업 실행

AI_WORK_LOG.md
판단과 실패 기록

VERIFY_REPORT.md
완료 증거

PR_TEMPLATE.md
팀 승인

이 구조를 만들면 AI 작업은 더 이상 대화창 안에서 일어난 일이 아닙니다. 프로젝트의 개발 이벤트가 됩니다.

문서 1: AI_GUIDE.md

AI_GUIDE.md는 프로젝트 루트에 두는 AI용 작업 가이드입니다. 사람 개발자를 위한 README가 프로젝트 실행 방법을 설명한다면, AI_GUIDE.md는 AI가 프로젝트 안에서 어떻게 일해야 하는지 설명합니다.

Claude Code 문서는 지속적으로 보존해야 할 규칙을 CLAUDE.md 같은 파일에 두고, 불필요하게 긴 항상 로드 문서는 피하라고 설명합니다.

공식 문서에서 확인되는 사실은 Claude Code가 지속 규칙과 컨텍스트 관리를 지원한다는 점입니다. 이 글의 해석은 그 기능을 특정 도구 파일명에 묶지 말고, 팀의 반복 가능한 AI_GUIDE.md 개념으로 재구성하자는 것입니다.

1# AI_GUIDE.md2 3## 프로젝트 개요4이 프로젝트는 Next.js 기반 정적 블로그 서비스다.5콘텐츠는 markdown으로 관리하고, 빌드는 Cloudflare Pages에 배포한다.6 7## 디렉터리 구조8- `src/app`: App Router 페이지9- `src/components`: UI 컴포넌트10- `src/content/posts`: 블로그 글11- `src/lib`: 공통 유틸12- `tests`: 테스트 코드13 14## 작업 원칙15- 기존 URL 구조를 변경하지 않는다.16- SEO 관련 메타 필드는 삭제하지 않는다.17- 글 본문 수정 시 frontmatter를 유지한다.18- `.env*` 파일은 읽거나 수정하지 않는다.19- 빌드 설정 변경은 사람 승인 없이 하지 않는다.20 21## 검증 명령22npm run lint23npm run typecheck24npm run build25 26## 사람 승인 필요27- dependency 추가/삭제28- 배포 설정 변경29- Cloudflare 설정 변경30- 로그인/결제 관련 코드 변경31 32## 금지 작업33- `.env*` 접근34- secret 출력35- production 배포 명령 실행36- 대량 파일 삭제

작성 원칙은 짧고 명확해야 합니다.

AI_GUIDE.md의 목표는 AI를 똑똑하게 만드는 것이 아닙니다. AI가 하면 안 되는 일을 하지 않게 만드는 것입니다.

문서 2: TASK_CONTRACT.md

TASK_CONTRACT.md는 개별 작업마다 작성하는 계약서입니다. 이번 작업은 무엇이고, 어디까지가 범위이며, 무엇을 만족해야 완료인지 알려줍니다.

1# TASK_CONTRACT2 3## 작업 이름4관리자 통계 API 캐시 적용5 6## 목표7관리자 첫 화면에서 호출되는 통계 API의 응답 시간을 줄인다.8 9## 배경10현재 `/admin/stats/summary` API는 매 요청마다 DB 집계를 수행한다.11피크 시간대에 응답 시간이 3초 이상으로 증가하고 있다.12 13## 현재 증상14- p95 응답 시간이 3초 이상15- DB CPU 사용률 상승16- 같은 API가 프론트엔드에서 중복 호출됨17 18## 수정 가능 범위19- `src/admin/stats/**`20- `src/lib/cache/**`21- `tests/admin/stats/**`22 23## 수정 금지 범위24- `src/auth/**`25- `src/payment/**`26- `migrations/**`27- `.env*`28 29## 완료 기준30- [ ] 기존 응답 필드 유지31- [ ] cache hit 시 Redis 응답32- [ ] cache miss 시 DB fallback33- [ ] Redis 장애 시 기존 DB 조회로 fallback34- [ ] lint 통과35- [ ] typecheck 통과36- [ ] unit test 통과37- [ ] 변경 요약 작성38- [ ] rollback 방법 작성39 40## 검증 명령41npm run lint42npm run typecheck43npm test -- admin/stats44 45## 사람 승인 필요46- Redis TTL 정책 변경47- DB schema 변경48- dependency 추가

핵심은 다섯 가지입니다.

1목표2범위3금지4검증5승인

이 다섯 가지가 있으면 AI 작업의 실패 확률이 크게 줄어듭니다.

문서 3: VERIFY_REPORT.md

AI에게 작업을 맡길 때 가장 위험한 순간은 "다 했습니다"라는 말을 그대로 믿는 순간입니다. 설명은 검증이 아닙니다.

1# VERIFY_REPORT2 3## 작업 요약4관리자 통계 API에 cache aside 구조를 추가했다.5Redis 장애 시 기존 DB 조회로 fallback되도록 처리했다.6 7## 변경 파일8- `src/admin/stats/service.ts`9- `src/admin/stats/cache.ts`10- `tests/admin/stats/cache.test.ts`11 12## 요구사항 충족 여부13- [x] 기존 응답 필드 유지14- [x] cache hit 시 Redis 응답15- [x] cache miss 시 DB fallback16- [x] Redis 장애 시 DB fallback17- [x] 변경 요약 작성18 19## 실행한 검증 명령20npm run lint21npm run typecheck22npm test -- admin/stats23 24## 검증 결과25- lint: 통과26- typecheck: 통과27- unit test: 통과28 29## 실패했던 항목30- 초기 테스트에서 Redis mock reset 누락으로 실패31- `beforeEach`에서 mock 초기화 후 해결32 33## 남은 리스크34- 실제 운영 p95 개선은 배포 후 모니터링 필요35- TTL 300초가 비즈니스 요구사항에 맞는지 확인 필요36 37## 사람 확인 필요38- TTL 정책39- Redis 장애 시 DB 부하 증가 가능성40- 운영 모니터링 지표

이 문서가 있으면 리뷰어는 대화창 전체를 뒤질 필요가 없습니다.

문서 4: AI_WORK_LOG.md

AI_WORK_LOG.md는 AI가 작업 중 어떤 판단을 했는지 남기는 로그입니다. 작업이 단순하면 필요 없을 수 있습니다. 하지만 작업이 복잡해질수록 중요합니다.

OpenAI Agents SDK Tracing은 agent run 중 LLM generation, tool call, handoff, guardrail 등을 기록해 디버깅과 모니터링에 사용할 수 있다고 설명합니다. 예시로 바꾸면, 도구 수준의 tracing이 없더라도 팀은 문서 수준의 실행 기록부터 시작할 수 있습니다.

1# AI_WORK_LOG2 3## 작업 목표4관리자 통계 API 응답 속도 개선5 6## 참고한 컨텍스트7- `TASK_CONTRACT.md`8- `src/admin/stats/service.ts`9- `tests/admin/stats/service.test.ts`10- 최근 slow query 로그11 12## 작업 계획131. 현재 API 응답 구조 확인142. Redis cache wrapper 확인153. cache aside 구조 추가164. unit test 추가175. lint/typecheck/test 실행186. VERIFY_REPORT 작성19 20## 주요 판단21- DB schema 변경은 필요하지 않음22- cache key는 날짜와 관리자 권한 범위를 포함해야 함23- Redis 장애 시 API 실패보다 DB fallback이 더 안전함24 25## 실패한 시도26- 처음에는 cache key에 권한 범위를 포함하지 않아 테스트 케이스 추가 필요27- Redis mock 초기화 누락으로 테스트 실패28 29## 최종 결과30- cache key 수정31- 테스트 통과32- VERIFY_REPORT 작성 완료

AI 실행 기록은 "왜 이렇게 바뀌었지?"라는 질문에 답하기 위한 문서입니다.

문서 5: PR_TEMPLATE.md

AI 작업이 실제 코드베이스에 들어오는 지점은 결국 PR입니다. PR에서 AI 사용 여부와 검증 결과를 확인할 수 있어야 합니다.

1## 변경 요약2 3## 관련 이슈4 5## AI 사용 여부6- [ ] 사용하지 않음7- [ ] 요구사항 정리에 사용8- [ ] 코드 탐색에 사용9- [ ] 코드 수정에 사용10- [ ] 테스트 생성에 사용11- [ ] 로그 분석에 사용12- [ ] PR 요약 작성에 사용13 14## AI에게 제공한 컨텍스트15- [ ] TASK_CONTRACT16- [ ] AI_GUIDE17- [ ] 실패 로그18- [ ] 관련 파일19- [ ] 테스트 결과20 21## 검증 결과22- [ ] lint 통과23- [ ] typecheck 통과24- [ ] unit test 통과25- [ ] integration test 통과26- [ ] 수동 QA 완료27 28## AI 변경 검토 항목29- [ ] 수정 금지 범위를 건드리지 않았다.30- [ ] 기존 API 응답 필드를 제거하지 않았다.31- [ ] 보안 민감 파일을 읽거나 수정하지 않았다.32- [ ] dependency 변경이 없다.33- [ ] rollback 방법이 있다.34 35## 남은 리스크36 37## 리뷰어가 중점적으로 볼 부분

이 템플릿은 AI를 감시하기 위한 문서가 아닙니다. AI를 팀 개발 프로세스 안으로 정식 편입하기 위한 문서입니다.

팀 규칙으로 운영하는 방법

문서를 만든다고 끝이 아닙니다. 팀 규칙으로 운영해야 합니다.

11. AI가 코드 수정에 참여하면 PR에 표시한다.22. 중간 이상 작업은 TASK_CONTRACT를 작성한다.33. 로그인/결제/배포/DB 변경은 AI 자동 실행 금지다.44. AI가 만든 코드도 사람 코드와 같은 리뷰 기준을 적용한다.55. 테스트 결과 없는 AI 변경은 merge하지 않는다.

작업 크기에 따라 필요한 문서를 조절하면 됩니다.

처음부터 모든 작업에 모든 문서를 강제하면 번거롭습니다. 작업 크기와 위험도에 따라 적용하는 편이 오래 갑니다.

적용 단계별 로드맵

1단계: 개인 프로젝트

개인 프로젝트에서는 세 가지만 시작합니다.

1AI_GUIDE.md2TASK_CONTRACT.md3VERIFY_REPORT.md

2단계: 팀 프로젝트

팀 프로젝트에서는 PR 템플릿을 추가합니다.

1AI 사용 여부2AI에게 제공한 컨텍스트3AI가 실행한 검증4사람이 확인한 항목

3단계: 조직 단위

조직 단위에서는 권한과 승인 게이트가 필요합니다.

1secret 접근 금지2운영 배포 금지3DB 변경 승인 필수4민감 도메인 코드 수정 승인 필수

OpenAI Agents SDK의 human-in-the-loop는 민감한 tool call에 approval requirement를 설정하고 승인 전 실행을 멈췄다가 승인 후 재개하는 흐름을 제공합니다. 이 글의 해석은 조직 단위 AI 코딩 환경도 같은 경계를 가져야 한다는 것입니다.

체크리스트

팀 규칙으로 넣기 전에 아래 항목을 확인합니다.

1[ ] 프로젝트 루트에 AI_GUIDE.md가 있다.2[ ] AI_GUIDE.md에 수정 금지 범위가 있다.3[ ] AI_GUIDE.md에 검증 명령이 있다.4[ ] 중간 이상 작업에는 TASK_CONTRACT를 작성한다.5[ ] TASK_CONTRACT에 완료 기준이 있다.6[ ] TASK_CONTRACT에 사람 승인 필요 항목이 있다.7[ ] AI 작업 후 VERIFY_REPORT를 작성한다.8[ ] VERIFY_REPORT에 실행한 검증 명령과 결과가 있다.9[ ] AI_WORK_LOG에 실패한 시도와 주요 판단을 남긴다.10[ ] PR_TEMPLATE에 AI 사용 여부가 있다.11[ ] 로그인/결제/DB/배포 변경은 AI 자동 실행하지 않는다.12[ ] 리뷰어가 AI 변경 검토 항목을 확인한다.

Q&A

Q1. 문서가 너무 많아져서 오히려 느려지지 않을까?

작업 크기에 따라 조절하면 됩니다. 작은 CSS 수정에 모든 문서를 요구할 필요는 없습니다. 하지만 성능 개선, 리팩터링, 로그인/결제/DB 변경처럼 위험한 작업에는 문서가 필요합니다.

Q2. AI_GUIDE.md와 README는 어떻게 다른가?

README는 사람 개발자가 프로젝트를 이해하고 실행하기 위한 문서입니다. AI_GUIDE는 AI가 프로젝트에서 작업할 때 지켜야 할 규칙입니다. README가 "이 프로젝트는 어떻게 실행하나"라면, AI_GUIDE는 "AI는 이 프로젝트에서 무엇을 하면 안 되나"에 가깝습니다.

Q3. Claude Code의 CLAUDE.md와 같은 개념인가?

도구별로 권장 파일명은 다를 수 있습니다. Claude Code에서는 CLAUDE.md를 지속 규칙 문서로 사용할 수 있습니다. 여기서 말하는 AI_GUIDE.md는 특정 도구에 종속되지 않는 일반화된 개념입니다.

Q4. 프롬프트 템플릿은 필요 없나?

필요합니다. MCP Prompts는 서버가 prompt template을 제공하고, 사용자가 명시적으로 선택해 사용할 수 있는 구조를 설명합니다. 이 글의 해석은 프롬프트 템플릿이 작업 계약서 위에서 동작해야 한다는 것입니다.

1작업 계약서로 기준을 정하고,2프롬프트 템플릿으로 반복 실행을 표준화한다.

Q5. 모든 AI 작업을 기록해야 하나?

모든 대화를 다 기록할 필요는 없습니다. 하지만 코드 변경에 영향을 준 AI 작업은 남기는 편이 좋습니다. 특히 수정한 파일, 제공한 컨텍스트, 실행한 검증, 실패한 시도, 사람 승인 필요 항목은 남겨야 합니다.

마무리

AI 코딩 도구를 잘 쓰는 팀은 프롬프트만 잘 쓰지 않습니다.

작업을 문서화합니다. 권한을 정합니다. 검증 기준을 세웁니다. 리뷰 가능한 evidence를 남깁니다. AI가 한 일을 추적 가능한 개발 이벤트로 만듭니다.

1프롬프트는 요청이다.2작업 계약서는 기준이다.3검증 리포트는 증거다.4PR 템플릿은 팀의 승인 절차다.

AI를 쓰는 팀은 빠르게 코드를 만듭니다. AI를 운영하는 팀은 빠르게 만들면서도 무엇이 바뀌었고, 왜 바뀌었고, 어떻게 검증됐는지 설명할 수 있습니다.

요약 카드

이 글의 핵심을 실행 관점으로 압축하면 다음과 같습니다.

1한 줄 요약:2AI 코딩 도구를 팀에 적용하려면 프롬프트보다 작업 계약서가 먼저다.3 4핵심 문서:5AI_GUIDE.md, TASK_CONTRACT.md, VERIFY_REPORT.md, AI_WORK_LOG.md, PR_TEMPLATE.md6 7가장 큰 리스크:8AI가 만든 변경의 범위와 검증 근거가 PR에 남지 않는 것9 10지금 바로 할 일:11프로젝트 루트에 AI_GUIDE.md를 만들고, PR_TEMPLATE에 AI 사용 여부 체크박스를 추가한다.

댓글

GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.