Let's say our hypothetical internal dashboard API is slow. Operational alerts show response delays, but the exact location of the bottleneck and performance criteria are not yet clear. The team leaves it to the AI coding tool to “improve performance.”
AI moves fast. Add a cache, create a test, and report that your response time has decreased. But the review reveals a problem. The user permission scope is missing from the cache key, and although there is a cache miss fallback, it has not been verified how the source storage load increases in case of a cache failure.
This failure is not just a matter of code generation capabilities. The problem is that execution is entrusted to AI without contracting out performance standards, scope for modification, response structure to be preserved, failure fallback, and completion evidence.
When using an AI coding tool, the first thing you notice is its code generation ability. Create components, add tests, suggest refactorings, and even run terminal commands. However, when put into a practical project, the bottleneck occurs somewhere else.
The most common reason AI fails is not because of bad code. Because work boundaries are not designed
Claude Code official document explains that Claude Code is not a simple chatbot, but an agentic coding environment that reads files, executes commands, changes code, and solves problems. The same document explains that the context window can quickly fill up with dialog, file content, and command output, and as it fills up, initial instructions can be lost or mistakes can increase.
These are the facts that can be confirmed in the official document. The interpretation of this article is the next step. As AI becomes more of an executor that handles files and commands, development teams should design the following six things before the number of lines of code:
What AI Knows and Starts withWhat tools can AI run?How much can AI fix?Where to stop dangerous workWhat will prove completion?How to track what AI has doneThis article addresses the question one step further than “What should we entrust to AI?” How to design the structure of work so that AI does not fail.
| standard | detail |
|---|---|
| Analysis base date | 2026-05-10 |
| Key references | Claude Code Best Practices, OpenAI Agents SDK, Model Context Protocol, A2A Protocol |
| purpose of writing | Summary of AI development workflow design perspective rather than how to use AI development tools |
| Applicable to | Developers, tech leaders, and startup development teams who have started using AI coding tools for practical projects |
Key takeaways
- AI coding tools are increasingly becoming less like code generators and more like executors acting within a development environment.
- Developers are not just good at writing prompts; they need to design the context, tools, permissions, and verification criteria in which AI can work.
- MCP defines a standardized way for LLM applications to connect to external data and tools, and covers server features such as Resources, Prompts, and Tools.
- OpenAI Agents SDK Guardrails and Human-in-the-loop describe the structure of inspecting agent execution, stopping it, and resuming it after human approval.
- Ultimately, developers in the AI era should write less code, but design the work structure more elaborately to prevent AI from failing.
The bottleneck in AI coding is not code generation
If you ask a human developer like the following, most people will ask back.
Please fix this feature.Please improve performance.Please clean up the code.Please add some tests.Please check the deployment error.People usually ask questions. Find out which feature is problematic, what the performance criteria are, how much can be refactored, whether existing behavior should be maintained, and where the operational logs are.
AI is often left to execute without asking this question. The AI then moves quickly, but it also quickly goes in the wrong direction.
| request | Common mistakes AI makes | Information you actually need |
|---|---|---|
| improve performance | Change structure without measurement | Baseline indicators, measurement methods, location of bottlenecks |
| Please refactor it | Breaking public API or response structures | Modifiable range, interfaces to preserve |
| add a test | Create only normal cases and omit regression cases | Failure cases, boundary values, existing failure cases |
| Please fix the bug | Prevents only symptoms and leaves the cause behind | Reproduction procedures, logs, expected behavior |
| Analyze the log | Conclusion based on incomplete logs | Duration, request ID, deployment history, external API status |
In practice, it should be viewed this way.
Leaving work to AI meansRather than outsourcing the code writingIt operates another task execution environment.Traditional system design and AI task design
Existing system design dealt with traffic, DB, cache, queues, and failure response. It is more accurate to think of AI task design as having an additional execution agent.
The two are not different stories. It extends the way of thinking that used to design servers, DBs, and APIs to how AI behaves during the development process.
| Existing system design | AI job design |
|---|---|
| API Gateway | AI Tool Gateway |
| DB permissions | AI file/command permissions |
| cache strategy | Context compression/selection strategy |
| Queues and Retries | AI job steps and retries |
| monitoring | AI execution history and trace |
| failure response | AI malfunction rollback |
| security policy | secret access blocking, approval gate |
Context Design: What to Show
The context given to AI is the world that AI judges. [Claude Code's Operational Description] (https://code.claude.com/docs/en/how-claude-code-works) covers that the context window contains conversation history, file contents, command output, system instructions, etc. More context is not always better, and irrelevant information can cloud your judgment.
Bad context looks like this:
Forces you to blindly read the entire codebase.Paste all unrelated logs.It provides a mix of old documentation and the latest implementation.They say, “Improve it on your own” without success criteria.It does not indicate areas that are prohibited from modification.A good context separates goals, scope, prohibitions, and verification.
# TASK_CONTEXT ## targetReduces the response time of the administrator statistics API. ## Current Problem-`/admin/stats/summary`response takes more than 3 seconds during peak times.- DB CPU usage increases.- The same API is being called repeatedly on the front end. ## Related files-`src/admin/stats/**`-`src/lib/cache/**`-`tests/admin/stats/**` ## No modification range- Login/session logic- Payment related table- Set up operational deployment-`.env*` ## Completion criteria- Pass existing tests- Improved Admin Statistics API p95 response time- Returns the same data as the existing response even in a cache miss situation- Create change summary and rollback method ## Verification commandnpm run lintnpm run typechecknpm testnpm run test:integrationThis document is not just for AI. Make the scope of work clear to human developers and explain the intent of the change to reviewers.
Tool design: what will make it run
Connecting your tools to AI makes them powerful. You can automate file search, code modification, test execution, log search, issue search, and PR creation. But linking tools means linking permissions.
MCP specification describes MCP as an open protocol for integrating LLM applications with external data sources and tools. The interpretation of this article is simple. If an AI tool can call an external system, those calls must fall within the development team's operational permissions model.
| work steps | tools to allow | tool to block |
|---|---|---|
| Requirements Analysis | Document search, issue inquiry | File modification, distribution |
| Code navigation | read-only search | shell write command |
| avatar | Fix restricted files | Infrastructure changes, secret access |
| test | test, lint, typecheck | production distribution |
| Ready for release | Summary of diff, write PR | Change DB directly |
The principle is this:
Show the AI only what it needs,Let it run only as much as needed,Dangerous things must be stopped.Permission design: How much can I change?
When AI can modify files, the question changes.
Is AI good at writing code?The more important question is this.
Has AI made something that shouldn't be changed unchangeable?Allowing and blocking permissions alone are not enough. Tasks should be stratified according to risk.
| Privilege level | Allow Action | Approval method |
|---|---|---|
| Level 0 | Read, search, summarize | auto allow |
| Level 1 | Run tests, run lint | auto allow |
| Level 2 | Fix restricted files | check diff |
| Level 3 | Change dependencies, create migration | Human approval required |
| Level 4 | DB change, infrastructure change | Separate procedure required |
| Level 5 | Operational data deletion, secret access | default ban |
[OpenAI Agents SDK's human-in-the-loop document] (https://openai.github.io/openai-agents-js/guides/human-in-the-loop/) provides a flow that stops execution in a sensitive tool call, approves or rejects the human, and then resumes in the same run state. The same thinking can be applied to AI coding.
ai_permissions:read:allow:- "src/**"- "tests/**"- "docs/**" write:allow:- "src/features/current-task/**"- "tests/features/current-task/**"deny:- ".env*"- "infra/**"- "migrations/**" commands:allow:- "npm run lint"- "npm run typecheck"- "npm test"require_approval:- "npm install"- "npm run db:migrate"deny:- "rm -rf"- "printenv"- "deploy production"This file does not need to be directly linked to the actual runtime. Initially, just a team rules document can be effective.
Guardrail Design: When to Stop
If permissions are “what to allow,” then guardrail is “when to stop.”
OpenAI Agents SDK Guardrails describes a structure that checks input and output before or during agent execution, and stops execution when a problem is detected. If we translate it into working code, it looks like this:
| stopping condition | reason | next action |
|---|---|---|
Attempt to access.env | risk of secret exposure | stop immediately |
| Create migration | Risk of data corruption | Request for human approval |
| Change login/session logic | security impact | Write a design description first |
| test failed | regression risk | Report cause of failure |
| Bulk file modification | No review possible | Resubmit Change Plan |
Guardrail isn't about telling AI to "watch out." It is a structure that sets a condition for stopping before taking a risky action and does not treat a risky outcome as completion.
Evidence Design: What will prove completion?
Saying “I’m done” by AI is different than actually completing it. AI is particularly good at explaining things, so we have to be more careful.
| Evidence type | example |
|---|---|
| function proof | Check operation according to requirements |
| test evidence | unit, integration, e2e results |
| type proof | typecheck result |
| static analysis evidence | lint result |
| performance proof | before/after latency |
| operational evidence | Log, monitoring, rollback plan |
| review evidence | diff summary, change intent |
It is better to request the following format from AI.
# VERIFY_REPORT ## change file-`src/admin/stats/service.ts`-`src/admin/stats/cache.ts`-`tests/admin/stats.test.ts` ## Whether requirements are met- [x] Improved administrator statistics API response speed- [x] Maintain existing DB query fallback in case of cache miss- [x] Maintain existing response fields ## Verification performed- [x] npm run lint- [x] npm run typecheck- [x] npm test ## Remaining risks- Improvement of p95 based on actual operational traffic requires monitoring after deployment- In case of Redis failure, fallback load may increase. ## Human verification required- Need to check if the TTL value of 300 seconds meets business requirementsRequiring this level of reporting makes AI work a verifiable unit of change rather than just code generation.
Trace Design: How to Trace
If you only do AI work once or twice, you can just look at the chat window. As your team continues writing, you'll need to answer the following questions:
What prompt changed this code?What files did AI read?What tests did you run?What were the failed attempts?To what extent have people approved?Why did you choose this structure?OpenAI Agents SDK Tracing explains the structure that can be used for debugging and monitoring by recording LLM generation, tool call, handoff, guardrail, custom event, etc. during agent run. When applied, even if the team does not have SDK-level tracing right away, it can start with a PR template.
## Whether to use AI tasks- [ ] Not used- [ ] Used for drafting- [ ] Used to modify code- [ ] Used to create tests- [ ] Used for log analysis ## Context provided to AI- Issue:- Related documents:- Failure log:- Editable range:- Modification prohibited range: ## Verification executed by AI- [ ] lint- [ ] typecheck- [ ] unit test- [ ] integration test- [ ] e2e test ## Human checked items- [ ] meets requirements- [ ] Maintain existing behavior- [ ] No security impact- [ ] rollback possible- [ ] Check operation monitoring pointsThe key is not to hide AI, but to make AI-involved tasks a traceable development event.
Practical application pattern
You don't need to create a platform from scratch. Documentation and checklists alone can significantly reduce your failure rate.
Pattern 1. AI work contract
# TASK_CONTRACT ## target## background## Editable range## No modification range## Completion criteria## Verification command## Items requiring human approvalPattern 2. AI-specific README
# AI_GUIDE.md ## Project structure- src/app: routing- src/features: Function unit module- src/lib: Common utilities- tests: tests ## Work Rules- Prohibit removal of existing API response fields- DB migration is prohibited without human approval.- Prohibit reading env files- No refactoring without testing ## Verification commandnpm run lintnpm run typechecknpm testPattern 3. Hazardous work approval gate
High-risk operations are divided into auto-allowed, approval-required, and default-prohibited as shown below.
Auto-allow:- Read files- Run tests- Run lint- Edit docs Approval required:- Change package.json- DB migration- Modification of login/payment logic-shell write command Default Prohibition:-.env access- output secret- production distribution- Data deletionPattern 4. AI execution record
# AI_WORK_LOG ## Task Goal## Context used## change file## Command executed## failed attempt## Final verification result## Remaining risksAdoption Checklist
When applying it to a team for the first time, check the items below.
[ ] The work objectives to be given to AI are summarized in one paragraph.[ ] The range that can be modified and the range that cannot be modified are separated.[ ] Related files and unrelated files are separated.[ ] Completion criteria are divided into functional, testing, regression, and operational criteria.[ ] There is a list of commands that AI can execute.[ ] There is a list of commands that require human approval.[ ] Access to.env, secret, and production data is blocked.[ ] Records tests executed and omitted by AI.[ ] Leave information on whether AI work is used and verification results in PR.[ ] There is a rollback standard that can be rolled back in case of failure.Q&A
Q1. Aren’t good prompts enough?
It's not enough. Prompts are requests, and work contracts are operating rules. In practice, context, file access scope, executable commands, test criteria, and approval procedures must come together.
Q2. Is this structure necessary even for small projects?
You don't have to make it all from scratch. However, there must be at least three things: a modifiable scope, a completion criterion, and a verification command. Without these three, the cost of reviewing AI-generated results becomes high.
Q3. Wouldn’t it be okay if AI runs the tests on its own?
Running tests is different from understanding validation criteria. People need to decide which tests are sufficient and which regressions are important.
Q4. Do I need to know MCP or A2A right now?
Even if you don't implement it right away, it's good to know the concept. MCP is a direction in which AI handles tools and context in a standardized way, and A2A is a direction that seeks to standardize communication and collaboration of different AI agent systems.
finish
Developers in the AI era can write less code. However, the number of things to design increases.
What to show AIWhat will we let AI do?How much can AI change?When to stop doing dangerous workWhat will prove completion?How to track what AI has doneWithout this structure, AI will produce code quickly, but teams will take on more review costs and operational risk. Conversely, if this structure is created well, AI becomes not a simple code generator but an execution partner that handles repetitive tasks and assists verification within the development process.
summary card
The essence of this article can be condensed into an execution perspective as follows.
One line summary:The core competency of developers in the AI era moves from writing code to designing AI work systems. The most important concepts:Context, Tool, Permission, Guardrail, Evidence, Trace Biggest risks:Failure to track what the AI knew, what it did, and what it verified. What to do right now:Create AI_GUIDE.md in the project root, and start by writing down the modification prohibition range and verification commands.
댓글
GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.