AI 시대의 개발자는 무엇을 설계해야 할까

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:

1What AI Knows and Starts with2What tools can AI run?3How much can AI fix?4Where to stop dangerous work5What will prove completion?6How to track what AI has done

This 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.

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.

1Please fix this feature.2Please improve performance.3Please clean up the code.4Please add some tests.5Please 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.

In practice, it should be viewed this way.

1Leaving work to AI means2Rather than outsourcing the code writing3It 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.

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:

1Forces you to blindly read the entire codebase.2Paste all unrelated logs.3It provides a mix of old documentation and the latest implementation.4They say, “Improve it on your own” without success criteria.5It does not indicate areas that are prohibited from modification.

A good context separates goals, scope, prohibitions, and verification.

1# TASK_CONTEXT2 3## target4Reduces the response time of the administrator statistics API.5 6## Current Problem7-`/admin/stats/summary`response takes more than 3 seconds during peak times.8- DB CPU usage increases.9- The same API is being called repeatedly on the front end.10 11## Related files12-`src/admin/stats/**`13-`src/lib/cache/**`14-`tests/admin/stats/**`15 16## No modification range17- Login/session logic18- Payment related table19- Set up operational deployment20-`.env*`21 22## Completion criteria23- Pass existing tests24- Improved Admin Statistics API p95 response time25- Returns the same data as the existing response even in a cache miss situation26- Create change summary and rollback method27 28## Verification command29npm run lint30npm run typecheck31npm test32npm run test:integration

This 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.

The principle is this:

1Show the AI ​​only what it needs,2Let it run only as much as needed,3Dangerous things must be stopped.

Permission design: How much can I change?

When AI can modify files, the question changes.

1Is AI good at writing code?

The more important question is this.

1Has AI made something that shouldn't be changed unchangeable?

Allowing and blocking permissions alone are not enough. Tasks should be stratified according to risk.

[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.

1ai_permissions:2read:3allow:4- "src/**"5- "tests/**"6- "docs/**"7 8write:9allow:10- "src/features/current-task/**"11- "tests/features/current-task/**"12deny:13- ".env*"14- "infra/**"15- "migrations/**"16 17commands:18allow:19- "npm run lint"20- "npm run typecheck"21- "npm test"22require_approval:23- "npm install"24- "npm run db:migrate"25deny:26- "rm -rf"27- "printenv"28- "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:

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.

It is better to request the following format from AI.

1# VERIFY_REPORT2 3## change file4-`src/admin/stats/service.ts`5-`src/admin/stats/cache.ts`6-`tests/admin/stats.test.ts`7 8## Whether requirements are met9- [x] Improved administrator statistics API response speed10- [x] Maintain existing DB query fallback in case of cache miss11- [x] Maintain existing response fields12 13## Verification performed14- [x] npm run lint15- [x] npm run typecheck16- [x] npm test17 18## Remaining risks19- Improvement of p95 based on actual operational traffic requires monitoring after deployment20- In case of Redis failure, fallback load may increase.21 22## Human verification required23- Need to check if the TTL value of 300 seconds meets business requirements

Requiring 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:

1What prompt changed this code?2What files did AI read?3What tests did you run?4What were the failed attempts?5To what extent have people approved?6Why 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.

1## Whether to use AI tasks2- [ ] Not used3- [ ] Used for drafting4- [ ] Used to modify code5- [ ] Used to create tests6- [ ] Used for log analysis7 8## Context provided to AI9- Issue:10- Related documents:11- Failure log:12- Editable range:13- Modification prohibited range:14 15## Verification executed by AI16- [ ] lint17- [ ] typecheck18- [ ] unit test19- [ ] integration test20- [ ] e2e test21 22## Human checked items23- [ ] meets requirements24- [ ] Maintain existing behavior25- [ ] No security impact26- [ ] rollback possible27- [ ] Check operation monitoring points

The 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

1# TASK_CONTRACT2 3## target4## background5## Editable range6## No modification range7## Completion criteria8## Verification command9## Items requiring human approval

Pattern 2. AI-specific README

1# AI_GUIDE.md2 3## Project structure4- src/app: routing5- src/features: Function unit module6- src/lib: Common utilities7- tests: tests8 9## Work Rules10- Prohibit removal of existing API response fields11- DB migration is prohibited without human approval.12- Prohibit reading env files13- No refactoring without testing14 15## Verification command16npm run lint17npm run typecheck18npm test

Pattern 3. Hazardous work approval gate

High-risk operations are divided into auto-allowed, approval-required, and default-prohibited as shown below.

1Auto-allow:2- Read files3- Run tests4- Run lint5- Edit docs6 7Approval required:8- Change package.json9- DB migration10- Modification of login/payment logic11-shell write command12 13Default Prohibition:14-.env access15- output secret16- production distribution17- Data deletion

Pattern 4. AI execution record

1# AI_WORK_LOG2 3## Task Goal4## Context used5## change file6## Command executed7## failed attempt8## Final verification result9## Remaining risks

Adoption Checklist

When applying it to a team for the first time, check the items below.

1[ ] The work objectives to be given to AI are summarized in one paragraph.2[ ] The range that can be modified and the range that cannot be modified are separated.3[ ] Related files and unrelated files are separated.4[ ] Completion criteria are divided into functional, testing, regression, and operational criteria.5[ ] There is a list of commands that AI can execute.6[ ] There is a list of commands that require human approval.7[ ] Access to.env, secret, and production data is blocked.8[ ] Records tests executed and omitted by AI.9[ ] Leave information on whether AI work is used and verification results in PR.10[ ] 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.

1What to show AI2What will we let AI do?3How much can AI change?4When to stop doing dangerous work5What will prove completion?6How to track what AI has done

Without 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.

1One line summary:2The core competency of developers in the AI ​​era moves from writing code to designing AI work systems.3 4The most important concepts:5Context, Tool, Permission, Guardrail, Evidence, Trace6 7Biggest risks:8Failure to track what the AI ​​knew, what it did, and what it verified.9 10What to do right now:11Create AI_GUIDE.md in the project root, and start by writing down the modification prohibition range and verification commands.