0.1 How Should We Think About AI Agents?
When you first encounter an AI Agent, a natural question arises:
“Is this just a tool, or is it something different?”
People come to it with different expectations.
| Perspective |
Expectation |
What Goes Wrong in Practice |
| A useful tool |
Press a button, get a result |
Starting with “just figure it out” → results don’t match intent → disappointment |
| A convenient automation |
Handles repetitive tasks for me |
Strong at simple repetition, but automation without context generates errors |
| Something that does my job for me |
Do whatever I tell it to |
Accepting output without verification → quality incidents |
None of these perspectives are wrong. But relying on any one of them alone makes it hard to get real value from an AI Agent.
0.2 The Perspective of This Guide — AI Agent as a Collaboration Partner
This guide treats the AI Agent as a cowork partner — a collaboration partner, not just a tool.
A tool does exactly what it is told. An AI Agent, by contrast, reads context, infers missing information, and sometimes suggests a better approach. At the same time, it can also charge ahead confidently in the wrong direction.
This is more like a human colleague than a tool. That is why the most effective way to work with an AI Agent is to collaborate with it as you would a colleague, not to treat it as a tool.
The AI Agent as a collaboration partner:
- A colleague who fills in the gaps where you are lacking
- A colleague who produces better results the clearer your instructions are
- A colleague who needs periodic check-ins to stay on track
- A colleague where verifying the output remains your responsibility
💡 The right expectation is not “the AI Agent does my job for me” —
it is “working with an AI Agent, I can accomplish more and do it better than I could alone.”
0.3 Practical Example 1 — A Senior Working with an AI Agent in a Junior Role
Situation
The team has a heavy workload but no junior developers.
A senior developer is handling everything alone — design, coding, documentation, and testing.
The senior needs to focus on architecture and design, but implementation and documentation are consuming most of their time.
The AI Agent’s Role: Junior Developer
[Role Division]
Senior (Human) AI Agent (Junior Role)
───────────── ─────────────────────
① Requirements analysis & design
② Implementation instructions ──→ ③ Code implementation
④ Unit test authoring
⑤ Execution report writing
⑥ Code review & verification ←──
⑦ Revision instructions ────────→ ⑧ Revisions applied
⑨ Release decision & deployment
How It Works in Practice
Step 1 — The senior completes the design and issues implementation instructions.
> Implement the user authentication API according to the design below.
> - Design document: docs/auth-design.md
> - Stack: NestJS + Passport.js + Prisma
> - Scope: sign-up, login (social login excluded)
> - When done: summarize the implementation results in ./reports/auth-impl-report.md
Step 2 — The AI Agent implements and reports.
The AI Agent writes the code, runs the tests, and saves an execution report to a file.
Step 3 — The senior reviews the report and verifies the code.
Using the execution report as the baseline, the senior confirms whether the implementation matches the intent.
If there are issues, revision instructions are issued; if not, the release decision is made.
The Key Principles of This Structure
| Principle |
Explanation |
| Design is done by the human |
The AI Agent’s role is to “execute” the design |
| Instructions must be clear |
Telling a junior “just figure it out” leads to unpredictable results — the same applies here |
| Output must always be verified |
You would not deploy a junior’s code without a code review — same rule applies |
| Intermediate artifacts are saved as files |
Communication is document-based, not verbal |
The senior stays focused on high-value work — design and verification —
while delegating execution work — implementation, documentation, and testing — to the AI Agent.
The cycle of seniors working overtime because there are no juniors is broken.
0.4 Practical Example 2 — A Junior Growing Alongside an AI Agent in a Senior Role
Situation
A startup has no senior developers.
A junior developer has been put in charge of all development, but lacks confidence in architectural decisions and technical judgment.
With no senior to consult, they make solo decisions every time — and often end up reversing them later.
The AI Agent’s Role: Senior Developer (Mentor + Reviewer)
[Role Division]
Junior (Human) AI Agent (Senior Role)
───────────── ─────────────────────
① Draft requirements
② Request requirements review ──→ ③ Point out gaps & contradictions + ask questions
④ Refine & finalize
⑤ Request design review ─────────→ ⑥ Design review + propose alternatives
⑦ Make direction decision
⑧ Implementation (coding directly)
⑨ Request code review ──────────→ ⑩ Review + improvement feedback
⑪ Apply revisions & learn
⑫ Release decision
How It Works in Practice
Step 1 — The junior writes a requirements draft and asks for a review.
The junior documents the requirements to the best of their knowledge. Perfection is not required.
This is the equivalent of showing a draft to a senior and saying, “Can you check if I missed anything?”
> We need to build a new payment system.
> My draft requirements are in docs/payment-requirements.md.
> Please review this draft.
> - Point out anything missing or contradictory
> - If there are decisions I need to make, list them as questions
> - Save the results to docs/payment-requirements-review.md
Step 2 — The AI Agent surfaces the gaps in the requirements.
The AI Agent analyzes the draft and asks questions about things the junior had not considered.
[Example AI Agent Review — docs/payment-requirements-review.md]
■ Missing Items
- No retry policy defined for payment failures
- No partial refund scenario
- Inventory deduction order for concurrent payment requests is undefined
■ Decisions Required
Q1. Has a payment gateway been chosen? (Toss Payments / iamport / custom integration)
Q2. Is recurring billing (subscriptions) in scope for this sprint?
Q3. Is there a data retention policy for payment records? (PCI-DSS compliance consideration)
■ Contradictions
- Section 3.2 "real-time notifications" conflicts with Section 4.1 "batch processing"
→ Need to specify which events are real-time and which are batch
Step 3 — The junior provides answers and finalizes the requirements.
By answering the AI Agent’s questions one by one, items they had not initially thought of get addressed.
> Thanks for the review. Here are my answers.
> - Q1: Going with Toss Payments. We already have a contract with them.
> - Q2: Recurring billing is out of scope for this sprint. We'll tackle it in Sprint 2.
> - Q3: PCI-DSS is overkill for our scale — we'll go with a no-card-storage approach.
> - Concurrent inventory deduction: handle with pessimistic locking.
> - Real-time vs. batch: payment completion and failures are real-time; settlements are daily batch.
>
> Please update docs/payment-requirements.md with the above.
> Get my approval before applying any changes.
💡 This process is the heart of junior growth.
When a senior simply asks “have you considered this?” —
the junior has one more item to think about on their own next time.
Step 4 — Architecture is discussed using the finalized requirements as a baseline.
> Review the architecture options based on the finalized docs/payment-requirements.md.
> - Do not implement anything yet. Present 2–3 design approaches with the pros and cons of each.
> - Take our situation into account (3-person team, Toss Payments integration, under 10,000 orders/month).
> - Save the results to docs/payment-architecture-review.md
Step 5 — The AI Agent presents design alternatives.
The AI Agent compares technical options based on the finalized requirements and documents them.
Each option includes pros and cons, risks, and a rationale for the recommendation.
Step 6 — The junior reads, understands, and decides.
The important thing is not to blindly follow the AI Agent’s recommendation, but to understand the reasoning and make the decision yourself. If something is unclear, ask again.
> Can you explain more about why you recommended event sourcing in Option 2?
> Is that architecture appropriate for our scale (under 10,000 orders/month)?
Step 7 — The junior implements directly, then asks the AI Agent for a code review.
> Please review the code in the src/payment/ directory.
> - Check whether it follows the design I chose (Option 1 from docs/payment-architecture-review.md)
> - Check whether it fully implements the finalized requirements (docs/payment-requirements.md)
> - Check for security vulnerabilities
> - If there are improvements to be made, explain why
> - Save the review results to docs/payment-code-review.md
Step 8 — Incorporate the feedback and learn.
Read the AI Agent’s review, understand why each piece of feedback was given, and make the changes.
Through repeated cycles of this process, the junior’s skills in requirements analysis, design, and implementation all grow together.
The Key Principles of This Structure
| Principle |
Explanation |
| The AI Agent does not build things for you |
The junior implements; the AI Agent reviews and advises |
| Decisions are made by the human |
The AI Agent provides options and rationale; final judgment is the junior’s |
| Ask “why?” immediately when something is unclear |
Asking the AI Agent like you would a senior accelerates learning |
| Document the process |
Accumulated design reviews and code reviews become the team’s knowledge assets |
A junior who was stagnating because there was no senior
uses the AI Agent in a senior role to receive design and review feedback and build their skills.
Not “a tool that does things for you” — but “a partner you grow with.”
0.5 How to Introduce AI Agent Collaboration
Both examples have different role arrangements, but share a common structure:
whether for an individual or an organization, the pattern is filling gaps with the AI Agent and validating through mutual feedback.
To put this into practice, follow these four steps.
| Step |
Phase |
Key Question |
Output |
| 1 |
Diagnose what is lacking |
What are we missing? |
The role to assign to the AI Agent |
| 2 |
Define how the role should be performed |
How does that role work? |
A guidelines document (CLAUDE.md, etc.) |
| 3 |
Apply to small tasks and refine |
Is it working as intended? |
Refined role definitions and guidelines |
| 4 |
Confirm results and expand scope |
Does it hold up for broader work? |
Expansion criteria and team-wide guidelines |
Step 1. Diagnose What Is Lacking
Start by identifying where the bottlenecks are for the individual or organization.
This diagnosis determines what role to assign to the AI Agent.
| Diagnostic Question |
Senior Team Example |
Junior Startup Example |
| What work is backed up? |
Implementation, documentation, testing |
Design reviews, code reviews |
| Why is it backed up? |
No juniors, so seniors do everything |
No senior, so work proceeds without validation |
| What role should the AI Agent fill? |
Junior developer (delegate execution) |
Senior developer (reviews and mentoring) |
The key is not to start with “what should we have the AI Agent do?” —
but to start with “what are we missing?”
Step 2. Define How the AI Agent Should Perform the Role
Once the role is established, document the way the person currently in that role (or who should be in that role) actually works.
If you tell an AI Agent “act like a junior,” it will interpret that in its own way.
For the AI Agent to perform as intended, the person who actually holds that role needs to document their working methods in concrete detail.
[Example — Senior defining the working method for the "junior role"]
■ When implementing code
- Read the design document first; do not make any judgment calls not covered by the design
- After implementation, always write an execution report
- The report must include: scope of implementation, list of changed files, test results, unresolved issues
■ When writing tests
- Write unit tests using Jest
- Achieve at least 80% code coverage
- If existing tests break, report immediately
→ This content goes into CLAUDE.md or a separate guidelines file.
[Example — Junior defining the working method for the "senior role"]
■ When reviewing requirements
- Organize missing items, contradictions, and decisions needed as questions
- Use "have you considered this?" rather than "do it this way"
■ When reviewing code
- Check alignment against the design document
- Point out security vulnerabilities and performance issues
- Present improvements with explanations (for learning purposes)
→ The more clearly the working method is defined, the better the AI Agent's feedback quality will be.
Step 3. Apply to Small Tasks and Refine
Do not apply this to all work at once.
Apply it to one small, low-risk task first, then adjust the role definition and working method.
[Apply → Feedback → Improve Cycle]
┌──────────────────────────────────────┐
│ Apply to a small task │
│ (e.g., implement one API, │
│ review one document) │
└──────────────┬───────────────────────┘
▼
┌──────────────────────────────────────┐
│ Review results — mutual feedback │
│ · Did it perform as intended? │
│ · Where were the instructions weak? │
│ · Where did the AI Agent go wrong? │
└──────────────┬───────────────────────┘
▼
┌──────────────────────────────────────┐
│ Improve role definition & method │
│ · Update the guidelines file │
│ · Refine instruction templates │
│ · Clarify verification criteria │
└──────────────┬───────────────────────┘
│
└──→ Apply again to the next task
After 2–3 cycles of this, the role definition and guidelines will stabilize for that type of work.
Step 4. Confirm Results and Expand Scope
Once results are confirmed at a small scale, gradually expand the scope of work and the number of people involved.
| Phase |
Scope |
Checkpoint |
| 1st |
Implement 1 API |
Does the instruct → perform → verify cycle function? |
| 2nd |
Module-level development |
Is consistency maintained across work spanning multiple files? |
| 3rd |
Feature-level development |
Is the full flow — design → implementation → testing → documentation — stable? |
| 4th |
Full team adoption |
Can other team members use the AI Agent effectively with the same guidelines? |
Starting with a large task because you are in a hurry
will result in the AI Agent generating large amounts of code in the wrong direction before the role is even properly defined.
Start small, verify, then expand — this is the fastest path.
0.6 Structure of This Guide
| Section |
Chapter |
Content |
| Overview |
Chapter 0 |
Framing the AI Agent as a collaboration partner ← you are here |
| Fundamentals |
Chapter 1 |
Installing the Claude Code CLI |
|
Chapter 2 |
Project setup and configuration (CLAUDE.md, Memory) |
|
Chapter 3 |
Using MCP servers |
|
Chapter 4 |
Using Sub Agents |
| Advanced |
Introduction |
The four structural limitations of AI Agents |
|
Advanced 1 |
Caveats for using AI Agents — clear instructions, file saving, task management |
|
Advanced 2 |
Context management and token optimization |
The Fundamentals section focuses on getting up and running.
The Advanced section focuses on using AI Agents correctly and reducing mistakes.
