UC Jung

Posted on Apr 1

Chapter 6. Best Practices for Working with an AI Agent

#ai #productivity #agents #programming

1.1 Why Clear Instructions Matter

An AI Agent "reasons" — but it also "guesses"

When an instruction is vague, an AI Agent fills in the gaps itself and proceeds with the task.
A person would ask "how should I handle this?" — but an AI Agent decides on the most plausible interpretation and executes it.

This is both its strength and its risk.

[Vague instruction]
> Build a login feature

[AI Agent's interpretation — the user has no idea]
  • Framework? → assumes React + Express
  • Authentication? → assumes JWT
  • DB? → assumes SQLite
  • Password encryption? → assumes bcrypt
  • Social login? → assumes none

→ Result: works, but built on a tech stack you didn't intend

[Clear instruction]
> Build a login API using NestJS + Passport.js.
> - Auth: JWT-based, with refresh token
> - DB: PostgreSQL + Prisma
> - Password: argon2 hashing
> - Social login excluded from this stage

→ Result: built exactly as intended

"Make it good" is not an instruction

Telling an AI Agent to "do it well," "do it appropriately," or "figure it out" provides zero actionable information.

Vague instruction	Problem	Clear instruction
"Make an API"	Stack, structure, and auth are all guessed	"NestJS REST API, JWT auth, Prisma ORM"
"Add tests"	Scope and framework are unclear	"Write unit tests for UserService using Jest"
"Fix this"	What the problem is is unclear	"Return 409 instead of 500 on duplicate email at POST /users"
"Improve performance"	What and by how much?	"getUsers query takes 3 seconds. Check for N+1 and bring it under 1 second"
"Refactor this"	No criteria	"Split the auth module into 3 layers: controller/service/repository"

Real problems that vague instructions create

1. Rollback cost

If an AI Agent modifies dozens of files in the wrong direction and you say "that's not right," rolling back takes more time than the original task. One line of clear instruction saves 30 minutes of cleanup.

2. Wasted context

When an AI Agent reads unnecessary files to figure out what direction to take, the context window is consumed. If half of the 200K tokens are spent "getting oriented," there's not enough space left to do the actual implementation.

3. Compounding errors

If the first instruction is vague, every subsequent task builds on the wrong premise. If you discover the problem three steps later, you have to start over from step one.

7 Elements of a Good Instruction

Element	Description	Example
Why	The purpose and intent behind the task	"We're improving the profile-editing UX to reduce user churn"
What	What is to be done	"Implement a user profile update API"
How	What technology or approach to use	"NestJS, Prisma, class-validator"
Scope	Boundaries of the task	"Email and nickname only. Exclude password changes"
Reference	Materials to consult or investigate	"See Prisma docs at prisma.io/docs", "Refer to src/auth/README.md"
Constraint	Restrictions that must be respected	"Existing tests must not break"
Verify	How to confirm it's done	"Pass npm test + manually test PUT /users/:id"

Why "Why" matters

Without knowing the purpose, an AI Agent will produce code that "works" technically but may not align with business intent. When the AI Agent knows the purpose and intent, it has a better chance of reasoning in the right direction when faced with ambiguous judgment calls.

Without Why	With Why
"Build a profile update API" → mechanical CRUD implementation	"Improving UX to reduce churn" → input validation made user-friendly, error messages written from the user's perspective
Implemented with defaults, no guiding criteria	Decisions made to serve the purpose (prioritize response speed, detailed error messages, etc.)

Why "Reference" matters

An AI Agent responds based on its training data, which may differ from the latest versions or project-specific conventions.
Providing references means the work is grounded in evidence rather than guesswork.

Situation	Reference instruction example
Latest API usage	"Implement this by referring to https://docs.nestjs.com/security/authentication"
Based on internal docs	"Follow the conventions in docs/api-convention.md"
Following existing code patterns	"Use the same structure as src/auth/auth.service.ts"
External library	"Read the README at https://github.com/oraios/serena and configure accordingly"
Design system	"Implement the component by referencing the Figma link"

💡 Claude Code can search the web and read files directly —
give it a URL and it will look it up; give it a file path and it will read it.
"Check here" produces far more accurate results than "figure it out yourself."

Not every instruction needs all 7 elements.
But making a habit of always including Why, What, and Scope — and adding Reference whenever the latest technology or project-specific conventions are involved — makes a meaningful difference.

Practical Pattern: Step-by-Step Instructions

For complex tasks, break them into stages rather than issuing everything at once.

# ❌ Everything at once
> Build a user management system. Include registration, login,
> profile editing, permission management, and email verification.

# ✅ Step by step
> [Step 1] First, design the DB schema for the user management system.
>   - User, Role, Permission tables
>   - Written as a Prisma schema
>   → Review, then proceed to the next step

> [Step 2] Implement the User CRUD API in NestJS.
>   - POST /users (registration)
>   - GET /users/:id (profile lookup)
>   - Input validation with class-validator
>   → Confirm tests pass before the next step

> [Step 3] Add JWT authentication.
>   - Passport.js + JWT Strategy
>   - Access token: 15 min, refresh token: 7 days
>   → Verify that existing tests still pass

Using Plan Mode

Claude Code's Plan Mode lets you have the AI Agent plan first and then proceed only after your approval.

# Enter Plan Mode
> /plan

# Or include it in the instruction
> Plan the migration of the auth system to OAuth2 first.
> Don't execute yet — just show me the plan. I'll approve before we proceed.

In Plan Mode, a Sub Agent (Plan) analyzes the codebase and presents a plan.
Reviewing and refining the plan before approving execution reduces the risk of heading in the wrong direction.

1.2 Instruction Checklist

Before giving a work instruction, quickly run through the following.

□ Is the purpose and intent stated? (Why)
□ Is it clear what is to be done? (What)
□ Is the scope defined? (Scope) — is there an "exclude X"?
□ Is the tech stack / approach specified? (How)
□ Are reference materials provided? (Reference) — URLs, file paths
□ Is there a completion criterion? (Verify) — tests, commands, expected result
□ Is this asking for too much at once?

1.3 Save and Update Outputs as Files

An AI Agent does not physically preserve memory

Decisions made during an AI Agent conversation — design directions, architecture choices, API specs, and so on — exist only within the session's context window. Think of it like RAM: when the session ends, it's gone.

[During the session]
  User: "Let's use JWT for auth"
  AI Agent: "Got it, proceeding with JWT"
  User: "PostgreSQL for the DB"
  AI Agent: "Understood, designing with PostgreSQL"
  ... (10 decisions over an hour)

[Session ends — terminal accidentally closed]
  → All 10 decisions lost
  → Must explain everything from scratch in a new session

Problems this causes in practice

Situation	Outcome
Terminal accidentally closed	All decisions made so far are lost
Auto-compaction (`/compact`)	Earlier decisions may be dropped during summarization
Continuing the next day	New session — no prior context
Handing off to a teammate	Hard to reconstruct the decision-making process from chat history alone

The solution — save decisions to files immediately

Decisions made during a work session should be written to physical files as they happen.
Files persist after the session ends, so you can pick up wherever you left off at any time.

Instruction example ①: During planning

> We're going to plan out the user authentication system.
> Update the decisions to ./todo/Plan_Draft_Auth_System.md as they're made.
> Ask me for approval before making any updates.

Instruction example ②: During design

> Design the API spec.
> Reflect decisions in ./docs/API_Spec_v1.md.
> Update the file whenever something changes, and get confirmation before each update.

Instruction example ③: For long-running work

> This refactoring will span multiple sessions.
> Track progress in ./PROGRESS.md.
> - Completed items: ✅
> - In progress: 🔄
> - Not started: ⬜
> Update this file at the end of each work segment.

Recommended File Structure

my-project/
├── todo/                              ← Plans and decision records
│   ├── Plan_Draft_Auth_System.md
│   ├── Plan_Draft_DB_Migration.md
│   └── Decision_Log.md               ← Key decisions and their rationale
├── docs/                              ← Output documents
│   ├── API_Spec_v1.md
│   └── Architecture_Overview.md
├── PROGRESS.md                        ← Overall progress status
└── CLAUDE.md                          ← Project context

3 Core Principles for Saving Files

Principle	Description	Instruction example
Save immediately	Reflect decisions in the file as soon as they're made	"Update the file each time something is decided"
Approve before applying	Confirm before changing files	"Ask for my approval before updating"
Specify the path	State exactly where to save	"Save to ./todo/Plan_Draft_Title.md"

⚠️ Key point: Telling an AI Agent to "remember this" is far less reliable than saying "save it to a file."
Memory in a conversation disappears when the session ends — files persist permanently.

1.4 Starting and Ending Work — Context Management Procedure

When starting a new task

Even within a single session, tasks change multiple times.
When switching tasks — say from "DB design → API implementation → writing tests" — if you don't clear out the previous task's context, the AI Agent gets buried under previously read files and conversation history, which degrades accuracy on the new task.

Switching tasks within the same session is the primary application of this procedure.
It applies equally when you close a session and open a fresh one.

STEP 1. Define the task overview and the AI Agent's role

In the first instruction of a new task, clearly declare "what will be done" and "what role the AI Agent plays."

> We're going to design the user authentication system now.
> Your role is backend architect.
> Design using NestJS + Passport.js,
> and record decisions in ./todo/Plan_Draft_Auth.md.

STEP 2. Remove or compact unnecessary context

Leftover context from a previous task can interfere with the new one.

Situation	Action	Command
Completely new task unrelated to previous work	Full context reset	`/clear`
New task partially related to previous work	Direct instruction for selective compaction	`/compact keep only auth-related decisions`
Low-stakes simple task switch	Stating the new task overview and role in STEP 1 guides auto-compaction appropriately	(no additional action needed after STEP 1)

⚠️ Claude's auto-compact doesn't know what's important.
For important work, use /compact <what to preserve> to control it directly.
Trust auto-compact only for low-stakes tasks.

STEP 3. When continuing from previous work — restoring context

When you need to pick up from where a prior task left off, restore context using the saved output files.
This applies both when continuing within the same session after a /clear, and when resuming previous work in a new session.

> We were working on the authentication system design in the previous session.
> Read the following files and get up to speed:
> - ./todo/Plan_Draft_Auth.md (design plan)
> - ./PROGRESS.md (progress status)
> - ./docs/API_Spec_v1.md (API spec)
>
> Summarize what you've learned,
> and tell me what we should pick up next.

The key here is to explicitly instruct what to keep and what to discard.

> Once you've read the previous work files:
> - The DB schema design is finalized — you can drop it from context
> - The JWT token design is still undecided — keep that
> - Use the "Outstanding Items" section of ./todo/Plan_Draft_Auth.md as the goals for this session

Task Start Instruction Template

> [Task overview] (what is being done)
> [AI role] (what kind of expert to act as)
> [Reference files] (previous outputs, context to restore)
> [Context cleanup] (what to keep / what to remove)
> [Output storage] (path, filename, approval process)

When a task ends (on session close or extended break)

This is the supplementary procedure for when you close a session or wrap up for the day and plan to continue tomorrow.
For task switches within the same session, STEP 1–3 above are sufficient —
but when you're ending the session itself, complete the steps below so the next session can pick up seamlessly.

STEP 1. Preserve outputs as records

> Wrap up today's work:
> - Completed code is already committed (confirmed)
> - Add design decisions to ./todo/Decision_Log.md
> - Update ./PROGRESS.md with the current status

STEP 2. Update reference materials

Update the reference materials the AI Agent will read in the next session to reflect the current state.
Without this step, the next session's AI Agent will read outdated materials and work from stale assumptions.

> Update the following files to reflect today's changes:
> - ./docs/API_Spec_v1.md → include newly added endpoints
> - ./CLAUDE.md → reflect updated architecture information
> - ./todo/Plan_Draft_Auth.md → check off completed items, update outstanding items
> Get approval before making changes.

⚠️ If reference materials are left in a past state, the next session's AI Agent will work without knowing what has already changed.
This is the primary cause of the "I already fixed that, but it went back to the original" problem.

STEP 3. Record TODOs — handoff for the next session

Explicitly document what's left to do so that the next session (or another person) can pick up right away.

> Record the work to continue in the next session in ./todo/TODO_Next.md:
> - Remaining tasks (in priority order)
> - Prerequisites for each task
> - File paths to reference
> - Caveats or unresolved issues

TODO file example

# TODO — Next Session Work List

## Priority 1: Refresh Token Implementation
- Prerequisite: Access token issuance complete (✅)
- Reference: ./docs/API_Spec_v1.md > POST /auth/refresh
- Note: Token expiry confirmed at 7 days (Decision_Log.md #12)

## Priority 2: Social Login (Google OAuth)
- Prerequisite: After Refresh Token is complete
- Reference: https://docs.nestjs.com/security/authentication#oauth2
- Unresolved: Callback URL domain not yet confirmed (needs team lead sign-off)

## Notes
- No direct commits to main — use feature/auth-* branches
- All 186 existing tests must pass

Task Start/End Checklist

[Starting a task]
□ Declared the task overview and AI Agent's role?
□ Cleared previous context? (/clear or /compact)
□ For continuing work: instructed the AI Agent to read previous output files?
□ Explicitly specified what context to keep and what to remove?
□ Specified the output save path and approval process?

[Ending a task]
□ Outputs preserved as files? (code committed, documents saved)
□ Reference materials updated to reflect the current state? (API spec, CLAUDE.md, etc.)
□ TODOs recorded for the next session? (remaining tasks, prerequisites, unresolved issues)

1.5 Instruction Checklist (Comprehensive)