Claude Code in Action

1 · Steering beats prompting essential

Here's a moment you'll recognize the first time you use Claude Code seriously. You type a request, hit Enter, and instead of one tidy answer the thing starts moving — reading files, running a command, editing something, running another command. It isn't replying to you; it's working. And the instinct most people bring from chatbots — "craft the perfect prompt, then wait" — is exactly the wrong one here. The engineers who get great results out of Claude Code aren't better prompt-writers. They're better drivers.

Think of the difference between ordering a meal and cooking alongside someone in your kitchen. With a chat model you place an order: one clear request, one dish comes back. With Claude Code you're at the stove together — you say "start the sauce," watch them reach for the wrong pan, say "no, the heavy one," taste as you go, and adjust. You're not composing one flawless instruction up front; you're giving direction continuously, correcting cheaply and often. That ongoing course-correction is what we mean by steering, and it is the single skill this whole chapter is built around.

The common mistake — and it's an expensive one — is to treat plan approval and the interrupt key as optional friction, let the agent run unattended for twenty minutes, and judge it only at the very end. That isn't delegating; it's gambling. When it drifts (and on a long task it will), you've burned the twenty minutes and now have to untangle a large wrong diff instead of nudging a small one. Steering is cheap precisely because you do it early and often — a sentence now beats a revert later.

With a chat model you write one good prompt. With Claude Code you run a loop you influence: approve a plan, narrow scope, interrupt when it drifts, rewind when it goes wrong. The skill is steering, not one-shot prompting.

2 · The extended-session problem essential

Picture a brilliant new colleague who has no long-term memory. For the first hour they're extraordinary — sharp, fast, exactly on brief. But they can only hold so much in their head at once, and as the day fills up, the earliest things you told them quietly fall out. By hour two they've forgotten you said "don't touch the auth module," and they're confidently editing it, sure they're helping. That colleague is Claude Code on a long task, and the disappearing memory is the context window filling up.

This matters because agentic coding feels most powerful exactly where it's most fragile — the big, sprawling, multi-file jobs you'd most love to hand off. A one-line fix almost never drifts; there's nothing to forget. It's the two-hour, twenty-file refactor where early constraints scroll out of memory, the model loses the thread of its own half-finished plan, and small wrong turns compound into a diff you no longer recognize. The failure isn't that the model got dumber; it's that the relevant facts got crowded out by everything that happened since.

The mistake beginners make is to blame the model ("it ignored me!") when the real cause is structural — you asked one context window to hold more than it can. Naming this drift and understanding why it happens is what turns it from a mystery into something you can manage: break the work into scoped chunks, restate constraints as you go, keep a CLAUDE.md the agent re-reads (§4), and verify at each stage rather than at the bitter end. Understanding the loop's lifecycle is what lets you steer a long task without it going sideways.

A one-line prompt is easy. A two-hour refactor across twenty files is where it drifts: the context window fills, early decisions get forgotten, the agent wanders. Understanding the loop's lifecycle is what lets you steer a long task without it going sideways.

3 · Plan first, then act essential

Every carpenter you've ever heard quoted the same rule: measure twice, cut once. The reason isn't fussiness — it's arithmetic. A wrong measurement costs you a pencil mark to fix; a wrong cut costs you the board. Claude Code has exactly the same asymmetry, and plan-first is how you exploit it. A wrong idea in a plan costs one sentence to correct. That same wrong idea, discovered after it's been turned into twelve edits across five files, costs you a revert, a re-explanation, and your afternoon.

Here's why this feels counterintuitive at first. The whole appeal of an agent is that it just does the thing — asking it to stop and describe its approach feels like putting a leash on the very speed you paid for. But the plan is where the cheap thinking happens. When Claude says "I'll extract the retry logic into a new decorator and update the three call sites," you can catch in five seconds that it missed a fourth call site, or that your team already has a retry helper it should reuse instead. Neither of those is obvious from the outside once the code is written — they're buried in a diff. On the plan, they're one line each.

The mistake to avoid is treating "make a plan" as a vague ritual — asking for a plan and then rubber-stamping it without reading. A plan you don't scrutinize is worse than no plan, because it lulls you into trusting a direction you never actually checked. Read it like a code reviewer: which files, in what order, what's the risky step, what could this break? Correct the approach before the first edit, when redirection is free. For anything non-trivial, get a plan before code — it catches wrong assumptions when they're cheap to fix.

A well-steered task

1. State the goal and constraints ("add pagination; don't touch auth").
2. Ask for a plan; read it. Correct a wrong step now, not after 12 edits.
3. Approve; let it work in a scoped area. Watch the first tool calls to confirm direction.
4. Interrupt (Esc) and re-steer if it drifts: "stop — wrong file."
5. Verify yourself (run tests, read the diff). Only then move on.

steering.md> Plan a refactor that extracts the retry logic from api.py into a reusable
> decorator. List the files you'll touch and the risks. Do NOT write code yet —
> I'll approve the plan first.

# Claude explores, proposes an approach, and waits. You approve or correct
# BEFORE any edits. Enter plan mode explicitly, or just ask for a plan.

4 · Configure the project — CLAUDE.md intermediate

Think about the onboarding doc a good team hands a new hire — the one-pager that says "we use pnpm, not npm; tests live next to the source; never touch the generated folder." Without it, the new engineer is competent but keeps tripping the same invisible wires: running the wrong command, editing a file that gets overwritten on build, adding a dependency the team spent a meeting deciding against. You could explain all of it out loud every morning. Or you could write it down once. CLAUDE.md is that written-down onboarding doc — except your new colleague reads it fresh at the start of every session, and never forgets to.

This is the highest-leverage file in the whole chapter, and the reason is the drift problem from §2. A chat instruction lives only in the current conversation; when the context window fills, it's gone. A fact in CLAUDE.md is re-supplied every session, so it survives the memory churn that erodes everything else. That's the difference between a rule you have to keep repeating and a rule that just holds. Put your commands there and Claude runs your real pytest -q instead of guessing at a test command; put your guardrails there and "don't push without asking" becomes a standing constraint rather than a hope.

The classic mistake pulls in the opposite direction: treating CLAUDE.md as a wiki and dumping the entire architecture, a history of the project, and three paragraphs of prose into it. That backfires, because every line you add is read into the context window every session — a bloated file spends your budget and dilutes the signal, burying the load-bearing "never edit vendor/" under noise. The skill is editorial: include only the stable facts Claude otherwise rediscovers or gets wrong, and cut everything else. CLAUDE.md is project memory Claude reads every session: conventions, commands, and constraints. It's the single highest-leverage file for quality — it stops you re-explaining context every time and makes the whole team's Claude behave consistently.

CLAUDE.md# CLAUDE.md — read at the start of every session

## Commands
- Test:  `pytest -q`
- Lint:  `ruff check .`
- Run:   `python -m app`

## Conventions
- Python 3.12, type hints on public functions.
- Never edit files under `vendor/` — generated.
- Prefer stdlib; a new dependency needs a note in the PR.

## Guardrails
- Do NOT commit or push unless I explicitly ask.
- Ask before deleting files or changing the DB schema.

5 · Permissions — control what it can do intermediate

Imagine giving a new intern the keys to the office. You don't hand over the master key that opens the server room, the safe, and the CEO's desk — you give them a badge that opens the doors they actually need, and leave the rest to require a manager's swipe. Claude Code's permission system is exactly that badge. By default it's cautious: it stops and asks before running a command or editing a file. Permissions are how you say "these doors are always fine, walk right through — but these ones, never, and anything else, come find me."

Why bother tuning it? Because the default "ask every time" is safe but slow, and constant interruptions train you to stop reading the prompts and just mash "yes" — which is less safe than a thoughtful allowlist. The goal is to make the frequent, harmless actions frictionless (running your tests, reading files, editing your own source) so that when a prompt does appear, it's rare enough that you actually pay attention. You're spending a few minutes of setup to buy back both speed and vigilance. It's the same trade an ops team makes with least-privilege IAM: grant exactly what's needed, deny the irreversible, review the unusual.

The mistake here is understandable and dangerous: opening the allowlist too wide because the prompts are annoying — Edit(*), Bash(*), allow-everything. That hands the intern the master key to stop them knocking. The discipline is to be generous with the reversible and read-only (reads, tests, lint, scoped edits) and stingy with the irreversible (force-deletes, pushes, schema changes) — and let everything you haven't thought about fall through to "ask." Claude Code asks before running commands or editing, governed by a permission mode + an allow/deny list in settings.json. Tightening this lets it move fast on safe actions while gating dangerous ones.

settings.json{
  "permissions": {
    "allow": ["Bash(pytest:*)", "Bash(ruff:*)", "Read(*)", "Edit(src/**)"],
    "deny":  ["Bash(rm -rf:*)", "Bash(git push:*)", "Edit(vendor/**)"]
  }
}

6 · Advanced — model the permission decision advanced

You've written the allow and deny lists. But have you noticed you're trusting them without knowing exactly how they combine? Here's the question that catches people out: what happens when an action matches both lists — say Edit(vendor/x.py) when your allow-list has Edit(src/*) but your deny-list has Edit(vendor/*)? Or when it matches neither? "It'll probably do the safe thing" is not an answer you want to be guessing at when the action is rm -rf. The only way to trust a security rule is to be able to state precisely what it does in every case — so we're going to build the decision as a few lines of Python you can actually run.

Writing the rule out as code does two things. First, it removes ambiguity: the order of the checks is the policy, and once it's code there's no room for "I think it works like…". Second, it reveals that this isn't some Claude-specific quirk — it's the same pattern every serious access-control system uses. A firewall checks its deny rules before its allow rules; a cloud IAM policy lets an explicit Deny override any Allow; a good bouncer's list of who's barred beats the list of who's invited. Modeling Claude's permission check teaches you a principle you'll reuse far beyond this tool.

The trap this section defends against is the seductive-but-wrong ordering: "check allow first, and if it's allowed, let it through." Do that and a broad Edit(src/*) could green-light something you meant to forbid, because you never gave the deny-list a chance to speak. Deny must be checked first, and unmatched actions must default to ASK — those two decisions are the entire difference between a safe gate and a leaky one, which is exactly why they're worth making explicit in code. How does an allow/deny list actually decide? Modeling it makes the rules unambiguous — and it's the logic a policy check would run.

permission_model.pyimport fnmatch

def decide(action, allow, deny):
    """deny wins over allow; unmatched -> ask the human."""
    if any(fnmatch.fnmatch(action, d) for d in deny):
        return "DENY"
    if any(fnmatch.fnmatch(action, a) for a in allow):
        return "ALLOW"
    return "ASK"

allow = ["Bash(pytest*)", "Read(*)", "Edit(src/*)"]
deny  = ["Bash(rm -rf*)", "Bash(git push*)", "Edit(vendor/*)"]
for act in ["Bash(pytest -q)", "Edit(src/app.py)", "Edit(vendor/x.py)",
            "Bash(rm -rf /)", "Bash(curl evil.com)"]:
    print(f"{decide(act, allow, deny):5}  {act}")

ALLOW  Bash(pytest -q)
ALLOW  Edit(src/app.py)
DENY   Edit(vendor/x.py)
DENY   Bash(rm -rf /)
ASK    Bash(curl evil.com)

7 · Advanced — verify, don't trust advanced

There's a specific sinking feeling you only get once, and then never forget. The agent has been working for a while, it announces "Done — all tests pass, the refactor is complete," and you, relieved, commit it and move on. An hour later something is broken that has nothing to do with what you asked for, and when you finally read the diff you find it quietly rewrote a file you never mentioned. It didn't lie to you. It genuinely believed it was done. "Done" from an agent is a claim, and a claim is not evidence.

This is the habit that separates people who ship agentic work reliably from people who occasionally get burned by it: verify the work with something the agent didn't author. The reason is subtle. The agent's summary is generated by the same process that did the work, so if its understanding was wrong, its report will be confidently wrong in exactly the same way — the narration inherits the bug. Green output from an independent test run, and your own eyes on the diff, come from outside that loop. That's why "I ran the tests and they pass" (from the agent) and "the tests pass" (from you watching the exit code) are completely different levels of trust.

The failure mode to name is verification theater: glancing at the agent's cheerful summary, seeing the word "passed," and calling it checked. That's not verification, it's reassurance. Real verification is boringly concrete — run the suite yourself and read the exit code, run git diff --stat to confirm only the files you expected changed (this is where silent scope-creep shows up), and read anything security- or data-sensitive by hand. The single habit that makes agentic coding reliable: verify the work. An agent that says "done" has proven nothing until you see green tests and a clean diff.

verify_gate.pydef accept_change(tests_pass, diff_reviewed, touched_forbidden):
    reasons = []
    if not tests_pass:        reasons.append("tests not green")
    if not diff_reviewed:     reasons.append("diff not reviewed")
    if touched_forbidden:     reasons.append("touched a forbidden path")
    return (not reasons), reasons

print("accept?", accept_change(True, True, False))
print("accept?", accept_change(True, False, True))

accept? (True, [])
accept? (False, ['diff not reviewed', 'touched a forbidden path'])

8 · Professional — a repeatable session workflow professional

Watch a surgeon and an airline pilot and you'll notice the same strange thing: highly skilled experts running checklists. Not because they've forgotten how to do their jobs — because under pressure, tired, or distracted, everyone skips the "obvious" step, and the obvious step is the one that bites. Everything in this chapter so far has been a technique; this section is about turning those techniques into a habit you run the same way every time, so that a good session isn't something you have to feel inspired to produce.

The reason a fixed loop matters more with Claude Code than with ordinary coding is that the agent moves fast and the temptation to skip steps is constant. On the tenth easy task of the day you'll want to skip the plan, skip reading the diff, let it push. Nine times you'll get away with it; the tenth is the story you tell in the incident review. A repeatable workflow makes the safe path the default path — you pull latest, state the goal and constraints, plan the non-trivial stuff, watch the early tool calls, verify with tests and a full diff read, and commit by hand — so correctness doesn't depend on your discipline holding up at 5pm on a Friday.

The mistake is thinking a workflow is only for beginners and that you'll "just know" when to be careful. Expertise doesn't remove the failure modes; it just makes you faster at hitting them. The loop below is deliberately short enough to actually follow every time — that's the point. Your per-task Claude Code loop

1. Pull latest; state the goal + constraints.
2. Plan-first for anything non-trivial; approve/correct the plan.
3. Let it work scoped; watch early tool calls.
4. Verify: run tests, read the full diff, check no forbidden paths.
5. Commit yourself with a clear message (DF2); never auto-push.

9 · Tech-lead — standardize steering across the team tech-lead

Everything up to now made you good at Claude Code. But a team where quality depends on each person's personal discipline is a team with a quality problem waiting to happen. One engineer has a tight CLAUDE.md and always reads the diff; the next has an empty allow-everything config and trusts "done." Their output looks fine right up until the day the second engineer's unattended agent force-pushes over main. The tech-lead's job is to stop relying on virtue and start relying on defaults.

The move that makes this scale is committing a shared .claude/ tree — CLAUDE.md, settings.json, hooks — into the repo itself, so the conventions, guardrails, and permissions arrive automatically the moment someone clones it. Nobody has to remember to set them up, and nobody can drift from them by accident. It's the same insight as linting or CI: you don't ask people to remember to format their code, you make the formatter run on save. Good steering discipline stops being folklore passed between engineers and becomes a property of the repository, which means it holds even as the team grows and turns over.

The trap a lead falls into is assuming the config, once committed, stays healthy — that nobody quietly widened an allow-list or dropped the test hook to unblock themselves on a Friday. Standards decay silently. That's why the payoff of modeling the config as something you can audit in code (the lab below) is so high: a check that fails loudly when a repo is missing its deny-list or its verification hook is what keeps the standard honest long after you wrote it. A lead commits a shared CLAUDE.md + settings.json so every engineer's Claude follows the same conventions, guardrails, and permissions. Consistency scales quality — and a config check keeps it honest.

config_audit.pydef audit_config(cfg):
    problems = []
    if "deny" not in cfg.get("permissions", {}):
        problems.append("no deny-list -> risky actions ungated")
    if "Bash(git push*)" not in cfg.get("permissions", {}).get("deny", []):
        problems.append("push not denied -> agent could push unreviewed")
    if not cfg.get("has_claude_md"):
        problems.append("no CLAUDE.md -> conventions not shared")
    if not cfg.get("stop_hook_tests"):
        problems.append("no test-on-stop hook -> verification is manual")
    return problems

weak = {"permissions": {"allow": ["Edit(*)"]}, "has_claude_md": False}
strong = {"permissions": {"allow":["Edit(src/*)"], "deny":["Bash(git push*)"]},
          "has_claude_md": True, "stop_hook_tests": True}
print("weak repo:", audit_config(weak))
print("strong repo:", audit_config(strong) or "compliant")

weak repo: ['push not denied -> agent could push unreviewed', 'no CLAUDE.md -> conventions not shared', 'no test-on-stop hook -> verification is manual']
strong repo: compliant

Vague:   "make the tests better"

Steered: "In tests/test_auth.py, add cases for the expired-token and
          missing-header paths. Use the existing pytest fixtures; don't
          touch the production code or add new dependencies."

1. Enter plan mode (Shift+Tab to cycle to "plan", or start with a
   "plan only, don't edit yet" instruction).
2. Ask: "Plan how to add rate limiting to the API layer. List the files
   you'd change and the approach — do not edit yet."
3. Read the plan. Correct the approach BEFORE code exists
   ("use the existing middleware, not a new decorator").
4. Approve; Claude executes the agreed plan.

# CLAUDE.md

## Conventions
- Package manager is `pnpm`, never `npm`.
- Tests live next to source as `*.test.ts`; run with `pnpm test`.
- Use the existing `Result<T>` type for fallible functions; don't throw.

## Do not
- Don't add dependencies without asking.
- Don't edit `generated/` — it's built from the schema.

def decide(tool, allow, deny, default_mode):
    # denylist always wins
    if tool in deny:
        return "deny"
    if tool in allow:
        return "allow"
    # otherwise fall back to the session's default mode
    return default_mode          # "ask" (default) | "allow" | "deny"

allow = {"Read", "Grep", "Bash(pnpm test)"}
deny  = {"Bash(rm -rf *)", "Bash(git push)"}
print(decide("Read", allow, deny, "ask"))            # allow
print(decide("Bash(git push)", allow, deny, "ask"))  # deny
print(decide("Edit", allow, deny, "ask"))            # ask (default)

# 1. Run the checks yourself (or make Claude run them and show raw output):
pnpm test            # exit code + real output, not a summary
pnpm lint
git diff --stat      # confirm ONLY the files you expected changed

# 2. Read the diff of anything security- or data-sensitive by hand.
# 3. If green: commit. If not: feed the failing output back and steer.

Team Claude Code workflow (per task)
  1. Branch first (never work on the default branch).          [enforced: hook]
  2. Steer: state file(s), goal, and constraints up front.     [advisory]
  3. Plan mode for any change touching >1 file; approve plan.   [advisory]
  4. Let it work; keep read tools on the allowlist,            [enforced: settings.json]
     push/delete on the denylist.
  5. Verify: run tests + lint + `git diff --stat` yourself.    [enforced: PreToolUse hook on commit]
  6. Commit with a real message; open a PR for review.         [enforced: branch protection]

Knowledge check check yourself