You have used a coding agent for months, mostly to learn and to get advice. From here on the agent writes most of your code while you direct and review. This lesson covers how to do that well: how to align on a plan before code is written, how to shape the agent's behavior, how to make it verify its own work, and how to keep a session productive.
Important
Work on this lesson in
buildermode.
Learning goals
- You can explain when planning with an agent pays off and when it is overhead, and align on a plan before implementation.
- You can work in both collaboration styles — small steps with a review after each, or full upfront alignment with one review at the end — and say which one fits a task.
- You can shape an agent's behavior with project instructions (e.g.
CLAUDE.md) and know what belongs there and what doesn't. - You can explain what model choice and permission modes (manual, auto, plan) trade off.
- You can give the agent a way to verify its own work (e.g. tests, a build, a screenshot) and explain why "looks done" is not done.
- You can get an independent review from a fresh context, e.g. a subagent or a second session.
- You can explain what skills and MCP connectors are, and write a small skill.
- You can keep a session productive: clear context between tasks, correct early, rewind when needed.
Resources
Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.
Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.
- 📄
Best practices for Claude Code
Show archive.org snapshot
— the one document to read for this card: verification, explore-plan-code, specific prompts,
CLAUDE.md, session management, failure patterns - 📄 How Claude Code works Show archive.org snapshot — the agentic loop and the context window
- 📄 Permission modes Show archive.org snapshot — manual, auto, plan
- 📄 Skills Show archive.org snapshot and Subagents Show archive.org snapshot — reusable workflows, and fresh contexts for investigation and review
- 📄 MCP Show archive.org snapshot — connecting external tools like Linear or a database
- 📄 No Meat Proxy Show archive.org snapshot — why forwarding agent output without understanding it adds no value, and what to do instead
- 📄 Comprehension Debt Show archive.org snapshot — Addy Osmani on the gap between the code that exists and the code anyone actually understands, and why it breeds false confidence
Learn
Read Best practices for Claude Code Show archive.org snapshot . It is long, but it is the one document to read for this card. Pay special attention to:
- Give Claude a way to verify its work — the single most important habit.
- Explore first, then plan, then code — and the note on when planning is overhead.
- Provide specific context in your prompts — compare the before/after examples.
- Write an effective CLAUDE.md — the include/exclude table.
- Manage your session and Avoid common failure patterns.
Two collaboration styles
Small steps. You describe one small change, the agent implements it, you review, repeat. Fast feedback, easy to steer, easy to understand each step. The risk: you lose the big picture, and the result is a sequence of local decisions.
Align everything upfront. You and the agent work out the whole plan first — files involved, approach, edge cases, tests, what's out of scope — for example with the /agree-on-everything skill or by letting the agent interview you. Then the agent implements the plan in one go and you do one thorough review at the end. Good for larger changes and when you know what you want. The risk: a long review of a big diff, and mistakes in the plan propagate.
In practice you'll mix both. The exercise below makes you try each in its pure form so you can feel the difference.
Shaping behavior
CLAUDE.md is read at the start of every session. It is the place for things the agent can't infer from the code: the test command, conventions that differ from Rails defaults, gotchas. It is not the place for things the agent already does right, or for tutorials. Keep it short — a long CLAUDE.md gets ignored.
Skills (.claude/skills/*/SKILL.md) hold workflows and knowledge that are only relevant sometimes. They load on demand. The trainee skills you have been using are skills like this.
Verification and honesty
An agent stops when the work looks done. Give it a check it can run — the spec, a build, a screenshot compared against a design — and ask it to show you the evidence: the test output, the command and its result. If you can't verify a change, don't ship it.
For a real second opinion, use a fresh context: a subagent that reviews the diff, or a second session that never saw the implementation reasoning. An agent reviewing its own work in the same session is biased toward it.
Verifying the change is not the same as understanding it. In a 2026 study Show archive.org snapshot , novice programmers built the same feature three ways: by hand, with an agent, and with an agent that made them explain each block before they were allowed to use it. The two agent groups produced work you could not tell apart.
Then the agent was taken away and they had to fix a bug in what they had built. The group that had explained as they went fixed it 62% of the time; the group that hadn't, 23%. The group that worked by hand fixed it most reliably of all — and never finished the feature.
What you add
From this card on, the agent writes most of your code, and the failure mode changes with it. Until now the risk was not learning. From here the risk is shipping something you don't understand — and it will not feel risky at all, because agent output is well formatted, it has tests, it runs, and it is usually right. Looking right is not the same as being right, and neither one is the same as you being able to answer for it.
Here is the uncomfortable part. Your project lead has the same agent you have. If your contribution is passing their request to it and passing its output back, you have added nothing they couldn't have got in the time it took to ask you. There is a name for that role — a meat proxy — and it isn't a job.
So the question you should be able to answer about every change you hand over is: what did I add that the agent wouldn't have? There are real answers, and most of them are things this curriculum teaches you:
- What the change is actually for. An agent optimizes the request it was given. Noticing that the request is wrong, incomplete, or solves the wrong problem is yours (Requirements analysis and minimum viable UIs).
- What the codebase already has. Agents rebuild what they can't see, and will cheerfully add a third way of doing something (Exploring code bases with agents).
- How we do things here. Our stack isn't the default one, and an agent reaches for the default (Our Rails stack, and why it isn't Omakase).
- Judging the design. Whether this is simple, whether it belongs here, whether the names are any good (Software design basics, More Software design).
- Catching a confident wrong answer. The tone is identical whether it is right or not (Asking your agent about APIs and libraries).
- Deciding what not to build. An agent will gold-plate happily. Saying no is a judgment call.
None of this means using the agent less. Use it for everything it's good at, which is most of the typing. It means the value you add moves from producing the change to being answerable for it — which is exactly what your mentor review, and later every code review, is checking.
Exercises
All exercises in MovieDB. Commit agent-implemented changes and your own follow-up edits separately, so the review trail is readable.
1. A CLAUDE.md for MovieDB
Write a CLAUDE.md for your MovieDB: how to run tests, which conventions you follow (Haml, RSpec style, factories, BEM), known gotchas. Keep it under 30 lines.
Test that it works: ask the agent for a small change in a fresh session, once with and once without the file (move it away temporarily). What changed in the agent's behavior? Cut every line that didn't make a difference.
2. Two features, two styles
Implement two comparable features, one per style:
- Small steps: Users can rate a movie from 1 to 5 stars; the movie page shows the average rating. Give the agent one small step at a time (migration, model, form, view, tests, …). Review each step before the next.
-
Align upfront: Users can write a short review text for a movie; reviews are listed on the movie page, newest first, and can be deleted by their author. First align on everything — use
/agree-on-everything, or ask the agent to interview you and write a spec. Then let it implement the whole plan, then do one thorough review.
For both features the agent must verify its work with specs and show you the output.
Afterwards, write down for each style: how long did it take, how many corrections did you make, how well do you understand the result, how good is the code. Discuss with your mentor which style you'd pick for which kind of task.
3. Fresh-context review
Take the diff of one of the features from exercise 2. Ask the agent to have a subagent review it against the original requirement and report gaps only, not style. Then do the same in a completely fresh session.
Compare the findings with your own review. What did the fresh context catch that the original session missed? What did it report that you consider noise?
4. Verify in the browser
Ask the agent to make a visual change to MovieDB (e.g. restyle the movie list) and to verify the result with a screenshot before reporting back. Look at the screenshot and at the page yourself. Did the agent's verification match reality?
5. Write a skill
Write a project skill for MovieDB that encodes a recurring workflow, for example /new-model <name> that creates a model with migration, factory and model spec following your conventions. Use it once. What did you have to put into the skill that you'd otherwise explain every time?
6. Course-correct
Give the agent a deliberately vague prompt ("make the movie page better"). Watch what it does. Stop it with Esc when it goes in a direction you don't want, redirect it, and if that doesn't work, rewind with /rewind and write a better prompt. Note how many corrections it took and what the better prompt looked like.
Discuss with your mentor
- Which model did you use, and when would you switch? What does it cost in quota?
- When did planning pay off, and when was it overhead?
- Which of your review findings from exercise 2 would the mentor's explain-it-cold check have caught?
Note
Agent security — what happens when an agent reads content that tries to instruct it — has its own card later in the curriculum: LLM and agent security.
