289 Agentic coding basics [2d]

Posted . Visible to the public.

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 builder mode.

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.

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.

Then skim, and come back to when you need them:

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.

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.

Profile picture of Henning Koch
Henning Koch
makandra.de
Say thanks
License
Source code in this card is licensed under the MIT License.
Posted by Henning Koch to makandra Curriculum (2026-08-31 15:28)
This website uses short-lived cookies to improve usability.
or learn more