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

Let’s say two people on a team entrust the same bug to AI. One person said, “Please fix the slow admin statistics API,” and the other person gave a failure log, editable path, no-edit area, and verification command.

The first job was completed quickly, but the review revealed missing cache keys and lack of testing. The second task took a little longer, but left the PR with the scope of changes, failed attempts, validations run, and remaining risks.

The difference was not the wording of the prompt, but the presence or absence of a work contract.

As you use AI coding tools, you will want to get better at writing prompts. I worry about how to tell people to make better code, how to ask people to write better tests, and how to request refactoring safely.

Prompts are important. However, when teams start using AI coding tools, prompts alone are not enough. This is because each developer has a different way of speaking, the information they provide to AI is different, and the standards for completion are different.

As a result, AI task quality is swayed more by the quality of task input than by model performance.

What your team needs isn't a genius prompt. This is a repeatable work contract.

1What to entrust to AI2How much can AI change?3What should AI verify?4What evidence should AI leave behind?5Where should a person approve

In this article, we outline five documents you need to incorporate AI coding tools into your team development workflow.

Key takeaways

• For your team to use AI coding tools reliably, you need a Work Agreement before a prompt.
• A work contract is a document that clearly tells the AI ​​the goals, scope, off-limits areas, completion criteria, and verification orders.
• Claude Code Document deals importantly with persistence rule documents such asCLAUDE.md, validation criteria, permission settings, and context management.
• MCP Prompts describes a structure in which the server provides a prompt template and the user can explicitly select it.
• The fact of the official document is "the functionality provided by the tool", and the interpretation of this article is "the team should operationalize that functionality as a repeatable contract document."
• For teams, just five documents can significantly stabilize the quality of AI work.

Why work contracts come before prompts

A prompt is a request. The work contract is the standard.

It’s not enough to tell AI, “Please improve the performance of the admin statistics API.” AI doesn't know performance criteria, which files can be modified, which response fields should be maintained, whether caches are allowed, whether the DB schema can be changed, and what testing criteria are.

This is what happens if you turn the same request into a work contract:

1# TASK_CONTRACT2 3## target4Reduces the p95 response time of the administrator statistics API.5 6## Editable range7-`src/admin/stats/**`8-`tests/admin/stats/**`9 10## No modification range11- Login/session logic12- Payment logic13- DB migration14-`.env*`15 16## Completion criteria17- Maintain existing response fields18- Maintain DB fallback in case of cache miss19- lint/typecheck/unit test passed20- Create change summary and rollback method

This document is good for AI, but it's also good for people. The scope of the work becomes clear and it becomes clear what the reviewer should be looking for.

Flow connecting 5 documents

The five documents are not played separately. It leads to one development event.

Once you create this structure, AI work no longer happens inside the chat window. This becomes a development event for the project.

Document 1: AI_GUIDE.md

AI_GUIDE.mdis a task guide for AI placed in the project root. While a README for human developers explains how to run a project,AI_GUIDE.mdexplains how an AI should work within a project.

[Claude Code Documentation] (https://code.claude.com/docs/en/best-practices) explains that rules that need to be kept persistent should be placed in files such asCLAUDE.md, and that unnecessarily long always-loaded documents should be avoided.

What the official documentation confirms is that Claude Code supports persistence rules and context management. The interpretation of this article is to not tie the functionality to a specific tool file name, but to reorganize it into the team's repeatableAI_GUIDE.mdconcept.

1# AI_GUIDE.md2 3## Project Overview4This project is a static blog service based on Next.js.5Content is managed with markdown, and builds are distributed to Cloudflare Pages.6 7## Directory structure8-`src/app`: App Router page9-`src/components`: UI component10-`src/content/posts`: Blog post11-`src/lib`: Common utility12-`tests`: test code13 14## Working Principle15- Do not change the existing URL structure.16- SEO-related meta fields are not deleted.17- Maintain frontmatter when editing the text of the post.18- The`.env*`file is not read or modified.19- Do not change build settings without human approval.20 21## Verification command22npm run lint23npm run typecheck24npm run build25 26## Requires human approval27- Add/delete dependency28- Change deployment settings29- Change Cloudflare settings30- Changes to login/payment related codes31 32## Prohibited operations33- Access`.env*`34- output secret35- Run the production deployment command36- Bulk file deletion

Writing principles should be short and clear.

AI_GUIDE.md's goal is not to make AI smarter. It's about making sure AI doesn't do things it shouldn't do.

Document 2: TASK_CONTRACT.md

TASK_CONTRACT.mdis a contract written for each individual task. It tells you what the task is, what its scope is, and what needs to be met to complete it.

1# TASK_CONTRACT2 3## task name4Apply Admin Statistics API Cache5 6## target7Reduces the response time of the statistics API called from the administrator's home screen.8 9## background10Currently,`/admin/stats/summary`API performs DB aggregation for every request.11Response times are increasing to over 3 seconds during peak hours.12 13## Current symptoms14- p95 response time is over 3 seconds15- DB CPU usage increased16- The same API is called repeatedly from the frontend.17 18## Editable range19-`src/admin/stats/**`20-`src/lib/cache/**`21-`tests/admin/stats/**`22 23## No modification range24-`src/auth/**`25-`src/payment/**`26-`migrations/**`27-`.env*`28 29## Completion criteria30- [ ] Maintain existing response fields31- [ ] Redis response when cache hit32- [ ] DB fallback in case of cache miss33- [ ] In case of Redis failure, fallback to existing DB inquiry34- [ ] lint pass35- [ ] typecheck passed36- [ ] Unit test passed37- [ ] Create change summary38- [ ] Write rollback method39 40## Verification command41npm run lint42npm run typecheck43npm test -- admin/stats44 45## Requires human approval46- Redis TTL policy change47- DB schema change48- Add dependency

There are five key points.

1target2range3prohibition4verification5approval

Having these five things will greatly reduce the chances of your AI task failing.

Document 3: VERIFY_REPORT.md

The most dangerous moment when entrusting a task to AI is the moment when you literally believe that it is “done.” Explanation is not verification.

1# VERIFY_REPORT2 3## Task summary4A cache aside structure was added to the administrator statistics API.5In case of Redis failure, fallback to existing DB inquiry was handled.6 7## change file8-`src/admin/stats/service.ts`9-`src/admin/stats/cache.ts`10-`tests/admin/stats/cache.test.ts`11 12## Whether requirements are met13- [x] Maintain existing response fields14- [x] Redis response when cache hit15- [x] DB fallback in case of cache miss16- [x] DB fallback in case of Redis failure17- [x] Create change summary18 19## Verification command executed20npm run lint21npm run typecheck22npm test -- admin/stats23 24## Verification result25- lint: Pass26- typecheck: passed27- unit test: passed28 29## Items that failed30- Initial test failed due to missing Redis mock reset31- Solved after mock initialization in`beforeEach`32 33## Remaining risks34- Improvements to actual operational p95 require monitoring after deployment.35- Need to check if TTL 300 seconds meets business requirements36 37## Human verification required38-TTL policy39- Possibility of increased DB load in case of Redis failure40- Operational monitoring indicators

With this documentation, reviewers don't have to dig through the entire chat window.

Document 4: AI_WORK_LOG.md

AI_WORK_LOG.mdis a log that records what decisions AI made during work. If your task is simple, you may not need it. But as the task becomes more complex, it becomes more important.

[OpenAI Agents SDK Tracing] (https://openai.github.io/openai-agents-js/guides/tracing/) explains that it can be used for debugging and monitoring by recording LLM generation, tool call, handoff, guardrail, etc. during agent run. To paraphrase the example, even without tool-level tracing, the team can start with a document-level execution history.

1# AI_WORK_LOG2 3## Task Goal4Improved administrator statistics API response speed5 6## Referenced context7-`TASK_CONTRACT.md`8-`src/admin/stats/service.ts`9-`tests/admin/stats/service.test.ts`10- Recent slow query log11 12## Work plan131. Check the current API response structure142. Check Redis cache wrapper153. Add cache aside structure164. Add unit test175. Run lint/typecheck/test186. Create VERIFY_REPORT19 20## Main judgment21- DB schema change is not required22- The cache key must include the date and administrator privilege range.23- DB fallback is safer than API failure in case of Redis failure24 25## failed attempt26- Initially, the cache key did not include a permission range, so additional test cases were needed.27- Test failed due to missing Redis mock initialization28 29## Final result30- Edit cache key31- Pass the test32- VERIFY_REPORT completed

AI run history is a document that answers the question, “Why did this change?”

Document 5: PR_TEMPLATE.md

Ultimately, PR is where AI work enters the actual codebase. It should be possible to check whether AI is used in PR and the verification results.

1## Summary of changes2 3## Related issues4 5## Whether to use AI6- [ ] Not used7- [ ] Used to organize requirements8- [ ] Used for code navigation9- [ ] Used to modify code10- [ ] Used to create tests11- [ ] Used for log analysis12- [ ] Used to create PR summary13 14## Context provided to AI15- [ ] TASK_CONTRACT16- [ ] AI_GUIDE17- [ ] Failure log18- [ ] Related files19- [ ] Test results20 21## Verification result22- [ ] lint pass23- [ ] typecheck passed24- [ ] Unit test passed25- Pass the [ ] integration test26- [ ] Manual QA completed27 28## AI Change Review Items29- [ ] The modification prohibition range was not touched.30- [ ] The existing API response field was not removed.31- [ ] Security-sensitive files were not read or modified.32- [ ] There is no dependency change.33- [ ] There is a rollback method.34 35## Remaining risks36 37## What reviewers should focus on

This template is not a document for monitoring AI. This document is for officially incorporating AI into the team development process.

How to operate by team rules

Creating a document is not the end. Must operate by team rules.

11. When AI participates in code modification, it is indicated in PR.22. For medium or higher tasks, create TASK_CONTRACT.33. Login/payment/distribution/DB change are prohibited from automatic AI execution.44. Code created by AI is also subject to the same review standards as human code.55. AI changes without test results are not merged.

You can adjust the documents you need according to the size of your work.

Forcing every document on every task from the beginning is cumbersome. Depending on the size and risk of the job, applying it will last longer.

Roadmap for each stage of application

Step 1: Personal Project

In my personal projects, I start with just three things.

1AI_GUIDE.md2TASK_CONTRACT.md3VERIFY_REPORT.md

Step 2: Team Project

In a team project, you add a PR template.

1Whether AI is used2Context provided to AI3AI-executed verification4Human verified items

Step 3: Organizational units

Organizational units require permissions and approval gates.

1secret access prohibited2Operational distribution prohibited3DB change approval required4Sensitive domain code modification approval required

[OpenAI Agents SDK's human-in-the-loop] (https://openai.github.io/openai-agents-js/guides/human-in-the-loop/) provides a flow that sets approval requirements for sensitive tool calls, stops execution before approval, and resumes after approval. The interpretation of this article is that the organizational AI coding environment should have the same boundaries.

checklist

Check the items below before adding them as team rules.

1[ ] AI_GUIDE.md is in the project root.2[ ] There is a modification prohibition range in AI_GUIDE.md.3[ ] There is a verification command in AI_GUIDE.md.4[ ] For medium or higher tasks, create TASK_CONTRACT.5[ ] There is a completion standard in TASK_CONTRACT.6[ ] TASK_CONTRACT contains an item that requires human approval.7[ ] Write VERIFY_REPORT after AI work.8[ ] VERIFY_REPORT contains the executed verification command and results.9[ ] Leave failed attempts and major decisions in AI_WORK_LOG.10[ ] PR_TEMPLATE determines whether to use AI.11[ ] Login/payment/DB/distribution changes are not automatically executed by AI.12[ ] The reviewer checks the AI ​​change review items.

Q&A

Q1. Wouldn't it actually be slow because there are too many documents?

You can adjust it according to the size of your work. Small CSS modifications don't need to require all documentation. However, dangerous tasks such as performance improvement, refactoring, and login/payment/DB changes require documentation.

Q2. What is the difference between AI_GUIDE.md and README?

README is a document for human developers to understand and run a project. AI_GUIDE is the rules that AI must follow when working on a project. If README is “How to run this project,” AI_GUIDE is closer to “What should AI not do in this project?”

Q3. Is this the same concept as Claude Code's CLAUDE.md?

Recommended file names may vary depending on the tool. In Claude Code, you can useCLAUDE.mdas a persistence rule document.AI_GUIDE.mdhere is a generalized concept that is not dependent on any specific tool.

Q4. Don't need a prompt template?

You need it. MCP Prompts explains the structure in which the server provides a prompt template and the user can explicitly select and use it. The interpretation of this article is that the prompt template should run on top of the work contract.

1Set standards with a work contract,2Standardize repeated execution with prompt templates.

Q5. Should all AI operations be logged?

There is no need to record every conversation. However, it is better to leave behind AI work that influenced code changes. In particular, you should leave out files you modified, contexts you provided, validations you ran, failed attempts, and human approval required.

finish

Teams that use AI coding tools well don’t just use prompts well.

Document your work. Set permissions. Establish verification standards. Leave evidence available for review. Make what the AI ​​does into trackable development events.

1A prompt is a request.2The work contract is the standard.3The verification report is evidence.4The PR template is the team's approval process.

Teams that use AI create code quickly. Teams running AI can create it quickly while explaining what has changed, why it has changed, and how it has been verified.

summary card

The essence of this article can be condensed into an execution perspective as follows.

1One line summary:2When applying AI coding tools to a team, a work contract comes first before a prompt.3 4Key documents:5AI_GUIDE.md, TASK_CONTRACT.md, VERIFY_REPORT.md, AI_WORK_LOG.md, PR_TEMPLATE.md6 7Biggest risks:8The scope and verification basis of changes made by AI do not remain in PR.9 10What to do right now:11Create AI_GUIDE.md in the project root and add a checkbox for whether to use AI in PR_TEMPLATE.