---
title: "AI 코딩 도구를 잘 쓰는 팀은 프롬프트가 아니라 작업 계약서를 만든다"
slug: "ai-work-system-02-task-contracts"
canonicalUrl: "https://moonshotnotes.com/posts/ai-work-system-02-task-contracts/"
sourceUrl: "https://moonshotnotes.com/posts/ai-work-system-02-task-contracts/"
markdownUrl: "https://moonshotnotes.com/agent/posts/ai-work-system-02-task-contracts.md"
language: "ko"
category: "Workflow"
updatedAt: "2026-05-11"
agentTokenEstimate: 2746
---

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

AI 코딩 도구를 팀 개발에 적용하기 위해 필요한 AI_GUIDE, TASK_CONTRACT, AI_WORK_LOG, VERIFY_REPORT, PR_TEMPLATE 작성법을 정리합니다.

## Agent metadata

- Source: https://moonshotnotes.com/posts/ai-work-system-02-task-contracts/
- Markdown: https://moonshotnotes.com/agent/posts/ai-work-system-02-task-contracts.md
- Language: ko
- Category: Workflow
- Tags: AI Coding, Prompt Engineering, Task Contract, Code Review, Human In The Loop, Developer Workflow
- Updated: 2026-05-11
- Estimated tokens: 2746

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

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

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

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

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

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

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

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

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

| 기준 | 내용 |
|---|---|
| 분석 기준일 | 2026-05-10 |
| 주요 참고자료 | Claude Code Docs, OpenAI Agents SDK, MCP Specification |
| 글의 목적 | AI 코딩 도구를 개인 실험이 아니라 팀 개발 프로세스로 다루기 위한 문서 구조 설계 |
| 핵심 문서 | AI_GUIDE.md, TASK_CONTRACT.md, VERIFY_REPORT.md, AI_WORK_LOG.md, PR_TEMPLATE.md |

## 핵심 요약

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

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

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

| 구분 | 프롬프트 | 작업 계약서 |
|---|---|---|
| 목적 | 이번 작업을 요청 | 작업의 기준을 정의 |
| 범위 | 대화마다 달라짐 | 반복적으로 재사용 |
| 안정성 | 작성자 역량에 의존 | 팀 규칙으로 표준화 |
| 검증 | 빠지기 쉬움 | 완료 기준에 포함 |
| 리뷰 | 대화창에 묻힘 | PR과 문서로 남음 |

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

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

```md
# TASK_CONTRACT

## 목표
관리자 통계 API의 p95 응답 시간을 줄인다.

## 수정 가능 범위
- `src/admin/stats/**`
- `tests/admin/stats/**`

## 수정 금지 범위
- 로그인/세션 로직
- 결제 로직
- DB migration
- `.env*`

## 완료 기준
- 기존 응답 필드 유지
- cache miss 시 DB fallback 유지
- lint/typecheck/unit test 통과
- 변경 요약과 rollback 방법 작성
```

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

## 5개 문서가 연결되는 흐름

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

```mermaid
%% AI 작업 문서는 프로젝트 규칙에서 PR 승인까지 한 흐름으로 연결된다.
flowchart TD
  A["AI_GUIDE.md<br/>프로젝트 기본 규칙"] --> B["TASK_CONTRACT.md<br/>이번 작업 계약"]
  B --> C["AI 작업 실행"]
  C --> D["AI_WORK_LOG.md<br/>판단과 실패 기록"]
  D --> E["VERIFY_REPORT.md<br/>완료 증거"]
  E --> F["PR_TEMPLATE.md<br/>팀 승인"]
```

| 단계 | 문서 | 역할 |
|---|---|---|
| 프로젝트 기본 규칙 | AI_GUIDE.md | 항상 지켜야 할 규칙 |
| 작업 시작 | TASK_CONTRACT.md | 이번 작업의 계약 |
| 작업 중 | 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 문서](https://code.claude.com/docs/en/best-practices)는 지속적으로 보존해야 할 규칙을 `CLAUDE.md` 같은 파일에 두고, 불필요하게 긴 항상 로드 문서는 피하라고 설명합니다.

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

```md
# AI_GUIDE.md

## 프로젝트 개요
이 프로젝트는 Next.js 기반 정적 블로그 서비스다.
콘텐츠는 markdown으로 관리하고, 빌드는 Cloudflare Pages에 배포한다.

## 디렉터리 구조
- `src/app`: App Router 페이지
- `src/components`: UI 컴포넌트
- `src/content/posts`: 블로그 글
- `src/lib`: 공통 유틸
- `tests`: 테스트 코드

## 작업 원칙
- 기존 URL 구조를 변경하지 않는다.
- SEO 관련 메타 필드는 삭제하지 않는다.
- 글 본문 수정 시 frontmatter를 유지한다.
- `.env*` 파일은 읽거나 수정하지 않는다.
- 빌드 설정 변경은 사람 승인 없이 하지 않는다.

## 검증 명령
npm run lint
npm run typecheck
npm run build

## 사람 승인 필요
- dependency 추가/삭제
- 배포 설정 변경
- Cloudflare 설정 변경
- 로그인/결제 관련 코드 변경

## 금지 작업
- `.env*` 접근
- secret 출력
- production 배포 명령 실행
- 대량 파일 삭제
```

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

| 항목 | 작성 방법 |
|---|---|
| 프로젝트 개요 | 3~5줄로 짧게 |
| 디렉터리 구조 | AI가 자주 탐색할 경로 중심 |
| 작업 원칙 | 팀 컨벤션과 금지 사항 중심 |
| 검증 명령 | 실제 실행 가능한 명령만 |
| 승인 필요 | 위험도가 높은 작업만 |
| 금지 작업 | secret, 배포, 삭제 중심 |

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

## 문서 2: TASK_CONTRACT.md

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

```md
# TASK_CONTRACT

## 작업 이름
관리자 통계 API 캐시 적용

## 목표
관리자 첫 화면에서 호출되는 통계 API의 응답 시간을 줄인다.

## 배경
현재 `/admin/stats/summary` API는 매 요청마다 DB 집계를 수행한다.
피크 시간대에 응답 시간이 3초 이상으로 증가하고 있다.

## 현재 증상
- p95 응답 시간이 3초 이상
- DB CPU 사용률 상승
- 같은 API가 프론트엔드에서 중복 호출됨

## 수정 가능 범위
- `src/admin/stats/**`
- `src/lib/cache/**`
- `tests/admin/stats/**`

## 수정 금지 범위
- `src/auth/**`
- `src/payment/**`
- `migrations/**`
- `.env*`

## 완료 기준
- [ ] 기존 응답 필드 유지
- [ ] cache hit 시 Redis 응답
- [ ] cache miss 시 DB fallback
- [ ] Redis 장애 시 기존 DB 조회로 fallback
- [ ] lint 통과
- [ ] typecheck 통과
- [ ] unit test 통과
- [ ] 변경 요약 작성
- [ ] rollback 방법 작성

## 검증 명령
npm run lint
npm run typecheck
npm test -- admin/stats

## 사람 승인 필요
- Redis TTL 정책 변경
- DB schema 변경
- dependency 추가
```

핵심은 다섯 가지입니다.

```text
목표
범위
금지
검증
승인
```

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

## 문서 3: VERIFY_REPORT.md

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

```md
# VERIFY_REPORT

## 작업 요약
관리자 통계 API에 cache aside 구조를 추가했다.
Redis 장애 시 기존 DB 조회로 fallback되도록 처리했다.

## 변경 파일
- `src/admin/stats/service.ts`
- `src/admin/stats/cache.ts`
- `tests/admin/stats/cache.test.ts`

## 요구사항 충족 여부
- [x] 기존 응답 필드 유지
- [x] cache hit 시 Redis 응답
- [x] cache miss 시 DB fallback
- [x] Redis 장애 시 DB fallback
- [x] 변경 요약 작성

## 실행한 검증 명령
npm run lint
npm run typecheck
npm test -- admin/stats

## 검증 결과
- lint: 통과
- typecheck: 통과
- unit test: 통과

## 실패했던 항목
- 초기 테스트에서 Redis mock reset 누락으로 실패
- `beforeEach`에서 mock 초기화 후 해결

## 남은 리스크
- 실제 운영 p95 개선은 배포 후 모니터링 필요
- TTL 300초가 비즈니스 요구사항에 맞는지 확인 필요

## 사람 확인 필요
- TTL 정책
- Redis 장애 시 DB 부하 증가 가능성
- 운영 모니터링 지표
```

| 항목 | 의미 |
|---|---|
| 변경 파일 | 리뷰 범위 |
| 요구사항 충족 여부 | 작업 계약서와 대조 |
| 실행한 검증 | 실제 evidence |
| 실패했던 항목 | 숨기지 말아야 할 정보 |
| 남은 리스크 | 운영 판단 |
| 사람 확인 필요 | 최종 승인 기준 |

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

## 문서 4: AI_WORK_LOG.md

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

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

```md
# AI_WORK_LOG

## 작업 목표
관리자 통계 API 응답 속도 개선

## 참고한 컨텍스트
- `TASK_CONTRACT.md`
- `src/admin/stats/service.ts`
- `tests/admin/stats/service.test.ts`
- 최근 slow query 로그

## 작업 계획
1. 현재 API 응답 구조 확인
2. Redis cache wrapper 확인
3. cache aside 구조 추가
4. unit test 추가
5. lint/typecheck/test 실행
6. VERIFY_REPORT 작성

## 주요 판단
- DB schema 변경은 필요하지 않음
- cache key는 날짜와 관리자 권한 범위를 포함해야 함
- Redis 장애 시 API 실패보다 DB fallback이 더 안전함

## 실패한 시도
- 처음에는 cache key에 권한 범위를 포함하지 않아 테스트 케이스 추가 필요
- Redis mock 초기화 누락으로 테스트 실패

## 최종 결과
- cache key 수정
- 테스트 통과
- VERIFY_REPORT 작성 완료
```

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

## 문서 5: PR_TEMPLATE.md

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

```md
## 변경 요약

## 관련 이슈

## AI 사용 여부
- [ ] 사용하지 않음
- [ ] 요구사항 정리에 사용
- [ ] 코드 탐색에 사용
- [ ] 코드 수정에 사용
- [ ] 테스트 생성에 사용
- [ ] 로그 분석에 사용
- [ ] PR 요약 작성에 사용

## AI에게 제공한 컨텍스트
- [ ] TASK_CONTRACT
- [ ] AI_GUIDE
- [ ] 실패 로그
- [ ] 관련 파일
- [ ] 테스트 결과

## 검증 결과
- [ ] lint 통과
- [ ] typecheck 통과
- [ ] unit test 통과
- [ ] integration test 통과
- [ ] 수동 QA 완료

## AI 변경 검토 항목
- [ ] 수정 금지 범위를 건드리지 않았다.
- [ ] 기존 API 응답 필드를 제거하지 않았다.
- [ ] 보안 민감 파일을 읽거나 수정하지 않았다.
- [ ] dependency 변경이 없다.
- [ ] rollback 방법이 있다.

## 남은 리스크

## 리뷰어가 중점적으로 볼 부분
```

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

## 팀 규칙으로 운영하는 방법

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

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

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

| 작업 크기 | 필요한 문서 |
|---|---|
| 작은 수정 | PR_TEMPLATE만 |
| 일반 기능 수정 | TASK_CONTRACT + VERIFY_REPORT |
| 리팩터링 | TASK_CONTRACT + AI_WORK_LOG + VERIFY_REPORT |
| 성능 개선 | TASK_CONTRACT + 측정 기준 + VERIFY_REPORT |
| 로그인/결제/DB 변경 | 사람 승인 필수 + 전체 문서 |

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

## 적용 단계별 로드맵

### 1단계: 개인 프로젝트

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

```text
AI_GUIDE.md
TASK_CONTRACT.md
VERIFY_REPORT.md
```

### 2단계: 팀 프로젝트

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

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

### 3단계: 조직 단위

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

```text
secret 접근 금지
운영 배포 금지
DB 변경 승인 필수
민감 도메인 코드 수정 승인 필수
```

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

## 체크리스트

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

```text
[ ] 프로젝트 루트에 AI_GUIDE.md가 있다.
[ ] AI_GUIDE.md에 수정 금지 범위가 있다.
[ ] AI_GUIDE.md에 검증 명령이 있다.
[ ] 중간 이상 작업에는 TASK_CONTRACT를 작성한다.
[ ] TASK_CONTRACT에 완료 기준이 있다.
[ ] TASK_CONTRACT에 사람 승인 필요 항목이 있다.
[ ] AI 작업 후 VERIFY_REPORT를 작성한다.
[ ] VERIFY_REPORT에 실행한 검증 명령과 결과가 있다.
[ ] AI_WORK_LOG에 실패한 시도와 주요 판단을 남긴다.
[ ] PR_TEMPLATE에 AI 사용 여부가 있다.
[ ] 로그인/결제/DB/배포 변경은 AI 자동 실행하지 않는다.
[ ] 리뷰어가 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](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts)는 서버가 prompt template을 제공하고, 사용자가 명시적으로 선택해 사용할 수 있는 구조를 설명합니다. 이 글의 해석은 프롬프트 템플릿이 작업 계약서 위에서 동작해야 한다는 것입니다.

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

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

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

## 마무리

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

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

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

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

## 요약 카드

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

```text
한 줄 요약:
AI 코딩 도구를 팀에 적용하려면 프롬프트보다 작업 계약서가 먼저다.

핵심 문서:
AI_GUIDE.md, TASK_CONTRACT.md, VERIFY_REPORT.md, AI_WORK_LOG.md, PR_TEMPLATE.md

가장 큰 리스크:
AI가 만든 변경의 범위와 검증 근거가 PR에 남지 않는 것

지금 바로 할 일:
프로젝트 루트에 AI_GUIDE.md를 만들고, PR_TEMPLATE에 AI 사용 여부 체크박스를 추가한다.
```