Agentic Coding, done properly

AI can write code faster than you can read it. That is the opportunity and the danger. Point an agent (an AI that doesn't just chat but actually reads files, runs commands, and fixes its own errors in a loop) at a task with no structure, and you get a tangled mess you can't ship. Wrap it in the right workflow — plan, test, review, release — and the same agent ships features to production while you sleep. That directed way of working is agentic coding.

This guide teaches that workflow from zero. It is built on the methods of Matt Pocock (creator of the widely-used skills for real engineers) and the published engineering practice of Anthropic, Thoughtworks, GitHub, Simon Willison, Addy Osmani and others — all from 2025–2026.

The whole method is one repeating loop. Six moves take an idea to a shipped, safe feature. The rest of this guide is these moves in detail, then the production, scaling and judgment layers around them.

Section 1Mindset & the maturity ladder

Before any tools, one idea decides everything: most of your results come from the harness, not the model. The harness — the software around the AI that lets it read files, run commands, and loop until a task is done — is where quality is won. Claude Code is one such harness. A great model in a weak harness produces slop. An ordinary model in a strong harness ships real features.

Where you sit today is a rung on a ladder. The goal of this guide is to move you up it.

Rungs 3 and 4 are where professional work happens — and where this guide takes you. The shift is from being in the loop (typing every line) to being on the loop (setting direction, checking evidence). You stop being the person who writes the code and become the person who is accountable for it.

Section 2Setup

This is a READ-DO checklist: read each item, do it, move on. Budget twenty minutes. At the end you'll run your first agent and see it work.

Before you start (prerequisites)

Three things must exist first. Each links out to a proper installer — set them up, then come back:

• Node.js v20 or newer — the runtime that Claude Code and the tools run on. Installing it also gives you npm (a package manager, used below). Get it from nodejs.org.
• Git — the version-control tool that saves snapshots ("commits") of your code and lets agents work on separate copies. The whole workflow assumes a git project. Get it from git-scm.com, then run git init in your project folder.
• A Claude account — Claude Code signs in to Anthropic's service, which needs a paid plan or API credits (you pay per token). Create one at claude.com.

npm install -g @anthropic-ai/claude-code
claude   # first run walks you through login

npm install -g pnpm
pnpm --version

npx @mattpocock/skills install

- Use pnpm, never npm.
- Type-check with `pnpm tsc --noEmit` before claiming a task is done.

if echo "$CLAUDE_TOOL_INPUT" | grep -qE '\bnpm (install|run|i)\b'; then
  echo "Use pnpm, not npm." >&2
  exit 2   # a non-zero exit blocks the command
fi

chmod +x .claude/hooks/pre-bash.sh
# then add it under "hooks" in .claude/settings.json —
# see the hooks guide for the exact PreToolUse block

Section 3Align — grill before you code

The oldest failure in software is building the wrong thing because nobody was aligned. Agents make it worse: they're eager, so they start coding your first vague sentence immediately. The fix is grilling — you make the agent interview you, one question at a time, until every fuzzy decision is nailed down. Only then does anyone write code.

Run /grill-me (or /grill-with-docs, which also reads your existing docs). The agent asks one sharp question, waits, asks the next. It hunts for the decisions you skipped.

Ubiquitous language — one word, one meaning

As you grill, capture your project's real terms in a context.md file. This shared glossary is your ubiquitous language (an idea from Domain-Driven Design). Once "standalone video" has one agreed meaning, the agent names variables consistently, stops re-explaining itself, and even spends fewer tokens thinking. It's documentation and a token-saver at once.

Record decisions as ADRs

When grilling settles a real decision, write it down as an Architecture Decision Record (ADR). That's one small file in docs/adr/ — the choice, and why you made it. ADRs are how you steer a system without holding all of it in your head; Section 10 leans on them heavily.

Section 4Plan — PRD to tracer-bullet issues

Grilling produces a shared understanding. Now freeze it. Run /to-prd to turn the interview into a PRD — the "destination document" that states exactly what the finished feature does, who it's for, the user stories, and how you'll know it's done. This is what the agent builds toward and what you review against.

Then run /to-issues to break the PRD into small, independent tickets. The rule that makes this work: every ticket is a tracer bullet — a vertical slice that cuts through all layers (database → backend → screen) instead of building one horizontal layer at a time.

The tickets form a small board with clear blocking relationships. That map is what later lets you run several agents at once (Section 11) — each grabs an unblocked ticket.

Section 5Build — TDD with agents

Left alone, an agent writes ninety messy tests and a huge block of code at once, then declares victory. The cure is TDD as automated discipline: red-green-refactor, run by the /tdd skill, one test at a time.

Don't let the AI mark its own homework

Pocock's key move: the agent that writes the implementation is not the agent that wrote the test. One agent writes a single failing test and is forbidden from writing production code. A second agent writes just enough code to pass it. The tester can't quietly weaken the test to make its own code look good.

Test behaviour, not internals

Because agents refactor constantly, tests bound to internal file structure break every time code moves — "death by a thousand false alarms." Instead force blackbox behaviour tests: launch the real app, press the button, see the status change. They survive refactors and double as a readable spec of the feature. This choice is what makes review-by-watching possible in Section 6.

Section 6Verify — review without reading every line

Agents produce more code than you can read. So don't review by reading — review by watching and by evidence. This is the single technique that makes the whole workflow scale.

The flipped testing pyramid

Classic advice: mostly fast unit tests, few slow end-to-end tests. Pocock flips it — a heavy base of blackbox behaviour tests. Those are historically expensive for humans to debug, but an agent has infinite patience: it reruns, instruments, and resolves failures at no cost to you.

Demo reels — watch the feature work

Configure the behaviour tests to record as they run — a screen recording for a web app, a terminal "cinema cast" for a CLI. Each test drives a real user scenario end to end. When the work is done, the agent opens a pull request (a "PR" — a proposal to merge its branch, where teammates and automated checks review the change), confirms all checks are green, and embeds the recording. Your review becomes watching a short clip to confirm the behaviour with your own eyes.

You can also run /review to spawn adversarial reviewer agents that check the diff (the exact lines added and removed) against the spec and your standards — a second opinion before you even watch the reel.

Section 7Production-ready — the quality gates

"The tests pass" is not "it's ready for millions of users." Between them sits a definition of done the agent must clear every time. Encode it once; enforce it with CI so nothing merges without it. Treat the list below as a DO-CONFIRM checklist: do the build, then confirm each item before you ship.

• Type-check is strict and green — including noUncheckedIndexedAccess: true, which forces the agent to handle "this array slot might be empty."
• Behaviour tests cover the feature's real paths, not just the happy one (the case where nothing goes wrong).
• Lint (an automated style-and-error checker) and formatting pass; no suppressed warnings snuck in.
• The non-functionals below are addressed, not skipped.

Coverage that means something

A high coverage number can be a lie — code executed but nothing actually asserted. Sanity-check it with mutation testing: a tool deliberately introduces bugs and checks your tests catch them. Tests that survive mutations are theatre. This matters more with agents, which are skilled at writing tests that run but prove nothing.

The non-functionals agents quietly skip

Agents optimise for the happy path and the visible feature. Left unprompted, they routinely omit the things that decide whether real users have a good time. Make these explicit gates (Thoughtworks' "sensors" idea — automated checks that watch for exactly these):

Section 8Ship without breaking prod

Passing gates earns a merge, not a release. Shipping safely to millions is its own discipline — the agent writes the code, but the pipeline protects the users. Build it once; every change flows through it.

Database changes need special care

You can roll back code instantly; you cannot un-drop a column. Use expand-contract migrations: first add the new shape and write to both (expand), deploy, backfill, then remove the old shape later (contract). Never let an agent write a destructive, one-shot migration into a release.

See what production is doing

Ship observability with the feature: error tracking, and real-user performance monitoring (Core Web Vitals from real sessions). Set an error budget — a threshold that, when breached, automatically pauses rollout. When something slips through, feed it back as a new ticket into the loop (Section 5). That incident-to-ticket loop is how the system gets stronger over time.

Section 9Security & compliance

Agentic coding adds two security surfaces at once: the code the agent writes, and the agent itself as a running program with tools. Both need guarding for anything real.

Securing the agent

• Prompt injection. Content the agent reads — a web page, an issue, a dependency's README — can contain instructions that hijack it. Treat everything the agent ingests as untrusted input, and never wire it to act on unreviewed content.
• Least privilege. Give the agent and its MCP tools the narrowest access that works — read-only where possible, scoped tokens, no standing production credentials.
• Secrets. Keep keys out of the context window and out of the repo. Use a secrets manager; add a hook or scanner that blocks a commit containing a credential.

Securing the generated code

• Scan it automatically. Run SAST (static analysis) and DAST (running-app scans) in CI. Agent code has average-of-the-internet security habits; assume it needs checking.
• Supply chain. Agents add dependencies casually. Pin versions, audit new packages, and watch for hallucinated or typo-squatted package names.
• Licences & IP. Generated code can echo licensed source. Keep a licence scanner in the pipeline for anything you ship commercially.

Section 10Steering architecture you don't fully understand

Agents write more code than any one person can hold in their head. The question stops being "do I understand every line?" and becomes "am I steering the shape?" You can, without reading it all — by owning interfaces, not internals.

Own the interfaces; let the agent own the insides

Build around deep modules (John Ousterhout's idea): a lot of complexity hidden behind a small, stable interface — the public functions and types other code calls, also called its API. You are the strategic programmer — you design that public interface and the boundaries. The agent is the tactical programmer — it fills the implementations. As long as the interface holds, you can steer a system whose insides you didn't write.

Make big decisions reviewable

For consequential choices, ask the agent to design it twice — present two or three options with trade-offs, not one. Record the choice as an ADR. Run a second, adversarial agent to argue against the design. You're reviewing decisions, which are few and high-leverage, instead of lines, which are many and low.

Triage by reversibility

Match your involvement to blast radius. A change that's easy to undo (a component, behind a flag) can run with light oversight. A one-way door — a schema change, a public API, an auth model — gets your full attention and a prototype to de-risk it first. Fight software entropy here: agents accelerate the drift toward a "ball of mud," so architecture review is active maintenance, not a nicety.

Section 11Ship faster — parallel execution

One agent is useful. The leap in throughput comes from running several at once — but only on top of everything so far, because parallelism multiplies output and needs review capacity to match.

Give each agent its own workspace

Agents in the same folder trip over each other's changes. A git worktree gives each agent a separate copy of the repo on its own branch, so several run in parallel without collision. An orchestrator agent hands each one an unblocked ticket from your board (Section 4) and assembles the results.

Running unattended — the AFK loop

You can let agents run while you sleep: pull a ticket, implement, commit, repeat. Pocock's open-source tool Sand Castle automates this — the Ralph loop. It needs three guardrails, no exceptions:

Section 12Context, tokens & determinism

Everything the agent knows lives in its context window. Treat it as a scarce budget you curate — not a bucket you fill. This is context engineering, and it's the modern replacement for prompt engineering.

Avoid the dumb zone

As a conversation grows, it fills with "sediment" — old context, dead ends, wrong turns — and quality drops well before the advertised limit. Pocock puts this dumb zone around 100k tokens. The cure is not a bigger window; it's a fresh one. Treat each task as a clean session: spin up, do the ticket, commit, kill it. To carry only what matters across the gap, run /handoff — it compresses the state into a small file a fresh agent reads cleanly. Compaction (auto-summarising) buys time, but a fresh session beats a compacted one.

Spend fewer tokens, keep more quality

• Keep CLAUDE.md lean — don't pay to re-read facts the agent can look up.
• Use your ubiquitous language so the agent thinks in short, shared terms.
• Lean on prompt caching: put the stable stuff (system prompt, CLAUDE.md, tool defs) first so it's charged once, then cheaply reused.
• Load MCP tools on demand rather than all upfront; fan out heavy reading to subagents that return a short summary and keep the main context clean.

Determinism — reliable outcomes from a random model

The model is stochastic; you will never make it repeatable. So don't try. Instead wrap it in deterministic machinery that only accepts correct output: hooks that block wrong actions every time, tests that must pass, CI that must be green, sandboxes that bound what's possible. You don't get a deterministic model; you get deterministic outcomes. That distinction is the quiet engine under this whole guide.

Section 13Systematise — the repeatable system & a PWA template

Everything so far is a workflow you run by hand. The final move turns it into a system, so every new project starts at rung 4 instead of climbing from zero. Two layers, and inheritance between them.

The point of the template: inheritance guarantees coverage. The non-functionals from Section 7 and the pipeline from Section 8 become impossible to forget — they're already there before the agent writes a line. A concrete golden-path template for a PWA (Progressive Web App — a website that installs and works offline like a native app) at scale:

• Build: Vite + TypeScript in strict mode (noUncheckedIndexedAccess); Workbox for offline/PWA.
• Tests: Vitest for logic, Playwright for behaviour — with video recording on, so every run produces a demo reel (Section 6).
• Pipeline: CI to Cloudflare Pages, where each preview deploy is your staging; Lighthouse performance budgets and security scans are merge gates.
• Operate: feature flags, error tracking, and Core Web Vitals RUM wired from the start.
• Steer: a lean CLAUDE.md, the pnpm-not-npm hook, the skills, docs/adr/, context.md, and a PR template that encodes the definition of done.

Measure the system, not vibes

Track whether the system actually helps, using DORA metrics: deploy frequency, lead time, change-fail rate, restore time. And run evals — repeatable test suites for your agents and prompts — so you improve on evidence, not gut feel.

Section 14Judgment — and when NOT to use agents

The last skill is knowing when to close the laptop. Agentic coding amplifies judgment; it doesn't replace it. Four things stay yours.

Sometimes the right call is to write it yourself: a tiny change where setup costs more than doing it; a novel core algorithm that is the product; a domain with life-or-safety stakes and no room for a plausible-but-wrong answer. Reaching for an agent is a choice, not a reflex — and choosing well is the real skill this guide is training.

ReferenceGlossary for the novice agentic coder

Plain-language definitions for every key term in the guide. Dotted-underlined words above link here. The last group covers everyday engineering words a newcomer may not know yet.

Foundations — how the model works

LLM (Large Language Model)

The AI that reads and writes text, like Claude. It predicts the next piece of text one step at a time. It has no memory of its own between sessions; everything it "knows" in a session is the text you have given it.

Token

The unit an LLM reads and writes in — a chunk of text, roughly ¾ of a word (about 4 characters). "Agentic coding" is ~4 tokens. You pay per token, and the model's limits are measured in tokens, so tokens are the currency of everything here.

Context (context window)

All the text the model can see right now: your instructions, the files it has read, the conversation so far, and its own replies. Measured in tokens, with a maximum size (the newest Claude models hold from hundreds of thousands up to 1 million tokens). The model's short-term working memory for this one session.

Prompt

The message you send the model. In agentic coding a good prompt is less "write me X" and more "here is the goal, the constraints, and how to check you got it right."

Inference

One run of the model turning input into output. "The agent made 40 inferences" means it took 40 turns of thinking and acting.

Temperature

A dial from 0 to 1 for how random the model's output is. Low temperature = more repeatable and focused; high = more varied and creative. For coding you usually want it low.

Hallucination

When the model states something confidently that is wrong or invented (a function that doesn't exist, a fact it made up). The whole workflow exists to catch these before they reach production.

The harness — what turns a chatbot into a coder

Harness

The software scaffolding around the model that lets it actually do work: read and write files, run commands and tests, use tools, and loop until a task is done. Claude Code is a harness. The key insight of modern agentic coding: most of your results come from the harness, not the model.

Agent

An LLM running inside a harness in a loop: it looks at the goal, takes an action (edit a file, run a test), sees the result, and decides the next action — repeating until done.

Agentic coding

Building software by directing agents that plan, write, test, and fix code themselves, while you stay "on the loop" — setting direction and checking evidence — rather than typing every line.

Subagent

A separate agent the main agent spawns to do one focused job (e.g. "explore these 40 files") in its own context window. It returns a short summary, keeping the main agent's context clean. Subagents are how you fan work out in parallel.

Orchestrator

The main agent that plans the work and hands pieces to subagents, then assembles their results. An orchestrator-plus-subagents setup is the standard shape for larger or parallel tasks.

Tool

A capability you give the agent to reach outside its own text: run a shell command, search the web, query a database. The agent calls tools the way a person clicks buttons.

MCP (Model Context Protocol)

An open standard for plugging external tools and data (GitHub, a database, a browser) into an agent. If a tool speaks MCP, your agent can use it without custom glue code.

Hook

A script that fires automatically at a fixed point in the agent's lifecycle — for example, before it runs any shell command. Hooks are deterministic (they run every single time, no matter what the model decides), which makes them the reliable way to enforce rules like "never use npm, use pnpm."

Skill

A small reusable instruction file (a SKILL.md) that teaches the agent how to do one kind of task well, loaded only when needed. Matt Pocock's grill-me, tdd, and diagnose are skills. Skills keep expertise out of the always-on context until the moment it's relevant.

CLAUDE.md

A file of standing instructions the agent reads at the start of every session: your project's conventions and environment quirks. Keep it lean — the model has a limited instruction budget, so don't fill it with facts it can discover elsewhere.

Plan mode

A setting where the agent proposes a plan and waits for your approval before touching any files. It separates "decide what to do" from "do it," which is where most quality is won or lost.

Headless mode

Running the agent non-interactively from a script or CI (e.g. claude -p "..."), with no chat window. This is how agents run inside automated pipelines.

The workflow — planning to shipping

Grilling

Having the agent interview you — one question at a time — about your plan until every fuzzy decision is resolved, before it writes code. Matt Pocock's grill-me / grill-with-docs skills do this. It fixes the oldest failure in software: building the wrong thing because nobody was aligned.

Ubiquitous language

A shared glossary of your project's real terms (kept in a context.md file) used by you, the code, and the agent alike. An idea from Domain-Driven Design. Once a term has one agreed meaning, the agent stops over-explaining, names things consistently, and even uses fewer tokens to think.

PRD (Product Requirements Document)

The "destination document": exactly what the finished feature should do, who it's for, and how you'll know it's done. The grilling session becomes the PRD.

Tracer bullet / vertical slice

A thin slice of work that goes all the way through the system (database → backend → screen) instead of one horizontal layer at a time. Each slice runs and can be tested on its own, which gives fast feedback and lets slices be built in parallel.

TDD (Test-Driven Development)

Write a failing test first, then write just enough code to make it pass, then clean up. The test defines "done" before the code exists.

Red-green-refactor

The three beats of TDD: red = a failing test, green = make it pass, refactor = tidy the code without breaking the test. With agents, a separate agent writes the test so the coding agent can't "mark its own homework."

Blackbox / behaviour test

A test that checks what the software does from the outside (open the app, click the button, see the status change) rather than how it's built inside. These survive refactors and double as a readable spec of the feature.

Diagnose

A disciplined debugging loop (reproduce → minimize → hypothesise → instrument → fix → regression-test) that stops the agent from guessing at bug fixes.

Handoff

Compressing the important state of a session into a small file so a fresh agent can pick up cleanly, instead of dragging a bloated, tired context along. Prevents the "dumb zone."

Review

Checking the agent's output before merge. State of the art: watch a recorded demo reel of the behaviour tests and read the evidence, rather than reading every line; scrutinise harder when the change is risky.

Scaling & production

Git worktree

A feature of git that gives each agent its own separate copy of the project on its own branch. Agents in different worktrees never overwrite each other, so you can run several at once safely.

AFK ("Away From Keyboard") / Ralph loop

Letting agents run unattended — pulling tickets from a backlog, implementing, committing — while you're not watching. Needs guardrails: a sandbox, a hard iteration cap, and a "done" signal.

Sandbox

An isolated environment (often a Docker container) where the agent can run freely without being able to damage your real machine. Essential before letting agents run unattended.

CI (Continuous Integration)

The automated pipeline that runs on every change: type-check, lint, and the full test suite. A change that fails CI never merges. CI is where "deterministic" quality is enforced.

Staging environment

A production-like copy of your app where changes are deployed and tested before real users see them. Your safety net between "tests pass" and "customers use it."

Context engineering

The craft of deciding exactly what goes into the context window — and what to leave out — so the model performs at its best. The modern replacement for "prompt engineering": curate, don't cram.

Compaction

Automatically summarising an overgrown conversation to reclaim context space while keeping the essentials. A tool for staying out of the dumb zone.

Prompt caching

Reusing the model's processing of an unchanged prefix (system prompt, CLAUDE.md, tool definitions) across calls, so you pay full price once and a fraction thereafter. Order context static-first to benefit.

The "dumb zone"

The point where a context window has grown so large and cluttered that the model's quality drops — often well before the advertised limit (Pocock cites ~100k tokens). The cure is fresh sessions and handoffs, not a bigger window.

Instruction budget

The practical limit (~300–500 rules) on how many instructions the model can reliably follow at once. Spend it on things it can't infer; don't waste it restating the obvious.

Deep module

A component that hides a lot of complexity behind a small, simple interface (idea from John Ousterhout). Deep modules are what keep an AI-built codebase navigable; you design the interfaces, the agent fills the insides.

Software entropy / "ball of mud"

The natural drift of a codebase toward tangled mess. AI writes code so fast it accelerates entropy, so you actively fight it (with architecture reviews and deep modules) or drown in it.

Determinism

Getting reliable, repeatable outcomes even though the model itself is random. You don't make the model deterministic; you wrap it in deterministic machinery — hooks, tests, CI, sandboxes — that accepts only correct output.

Everyday engineering terms (for newcomers)

Git & repository

Git is the tool that tracks your code's history. A "repository" (repo) is one project under git. A "commit" is a saved snapshot; a "branch" is a parallel line of work you can develop and later merge back. Agents lean on all of these.

Pull request (PR)

A proposal to merge one branch into another. It shows the exact changes (the "diff"), runs automated checks, and is where a human — or another agent — reviews the work before it lands. On some tools it's called a merge request.

CLI (command-line interface)

A program you drive by typing commands in a terminal, rather than clicking buttons. Claude Code is a CLI; so are git and pnpm.

API / interface

The public "front door" of a piece of code: the functions and types other code is allowed to call, without knowing what happens inside. You steer a system by owning its interfaces (Section 10).

Feature flag

A switch that turns a feature on or off in a running app without shipping new code. Lets you merge work early but reveal it gradually, and switch it off instantly if it misbehaves.

PWA (Progressive Web App)

A website built to behave like an installed app — it can load offline, be added to the home screen, and feel native — while still being served from the web.

ReferenceCurated resources

The sources this guide is built on — all from 2025–2026, the practitioners defining agentic coding as it's actually done. Grouped so you can go deeper on any section.