Claude Code & Agentic Development with Claude
You've built the agent loop by hand. Claude Code is that loop, productionized into a coding agent that lives in your terminal, reads and edits your repo, runs commands, and asks before doing anything risky. This chapter is how to drive it well — and what to steal for your own agents.
- an Anthropic API key (
ANTHROPIC_API_KEY) +pip install anthropic
Learning objectives
- Install Claude Code and run it against a real repository.
- Explain its agent loop and how permissions gate risky actions.
- Use
CLAUDE.md, slash commands, and subagents to steer it. - Write effective prompts for an agent that can read, edit, and run code.
- Map every Claude Code feature back to a pattern in your own agents.
What Claude Code is intermediate
Claude Code is Anthropic's official agentic coding tool. It's the Chapter 4 agent loop, hardened and given a real tool surface: it can read files, edit them, run shell commands, search the codebase, call the web, and spawn subagents — all under a permission system that stops before anything destructive. Under the hood it's the same Messages API and the same tool-use loop you just wrote in C2, running against a frontier model at high effort.
claude.ai/code, and IDE extensions (VS Code, JetBrains). This chapter uses the CLI — the concepts carry across all of them.The agent loop, productionized intermediate
You already know this shape from C2. Claude Code is the same round-trip, with a real file/shell tool surface and a permission gate wrapped around every action.
This picture is the whole idea of Claude Code in four boxes: it is the same send-request / get-reply loop you built in C2, but now the model can act on your computer — and a permission gate sits in the middle so nothing dangerous happens without your say-so.
- Top box — Claude (the model): it looks at your request and proposes a single action, called a tool call (for example "edit this file" or "run this command"). At this point nothing has actually happened yet.
- Arrow down → permission gate: every proposed action passes through this gate first. The gate decides: run it automatically (safe, read-only things) or pause and ask you (anything that changes files or runs commands).
- Arrow down → tool runs (edit/bash/…): only after it's allowed does the tool actually execute — editing a file, running a shell command, and so on.
- The long curved arrow back up (labelled "result back to model") carries the outcome — the new file contents, the command's output — back to Claude, which reads it and decides the next step. Then the whole loop repeats until the job is done.
In short: The one box to remember is the permission gate. It is the difference between an assistant that suggests and one that acts — and the safety idea you'll rebuild in every agent of your own.
Lab C3.1 · Install & first session intermediate
- Install & launch. Follow the current install instructions from Anthropic's docs, then in any project directory run:
shell
claudeIt starts an interactive session scoped to the current directory.
- Ask it to orient itself. A good first prompt is exploratory, not a change:
prompt
Explain what this project does and how it's structured. Don't change anything yet.Watch it read files, search, and summarize — read-only tools run without prompting you.
- Ask for a small, concrete change.
prompt
Add a --version flag to the CLI that prints the version from pyproject.toml. Show me the diff before applying.Now it proposes an edit — a state-changing action — and pauses for your approval.
This lab is your first real session. You install Claude Code, launch it in a project, and give it two prompts — first a harmless "look around" one, then a small change. The point is to see the permission gate in action: read-only work just happens, but a change waits for you.
- Launch: running
claudein a project folder starts an interactive session scoped to that directory — it can see and work with the files there, and nowhere else. Think of it as opening a chat that also has hands. - Prompt 1 (orient):
"Explain what this project does… Don't change anything yet."asks it only to read and summarise. Reading files and searching are read-only tools, so they run without asking you — you'll watch it explore on its own. - Prompt 2 (change): asking it to
Add a --version flagandShow me the diff before applyingrequests an edit — an action that changes state. Now the gate kicks in: Claude proposes the edit and pauses for your approval before touching anything. - The habit this teaches — explore first, change second — is called read-only-first, and it's the same discipline you'll see again in the FDE method (Chapter 7).
What the output means: Prompt 1 prints a plain-English summary of the repo (no changes). Prompt 2 shows you a diff — the exact lines it wants to add or remove — and then stops and asks "apply this?" instead of silently editing.
Try this: On your very first prompt in any unfamiliar repo, add "don't change anything yet." You build trust in what the agent understands before you let it write a single line.
Permissions: the trust ladder intermediate
Claude Code classifies actions by risk and asks before the risky ones. This is the productionized version of the human-in-the-loop gate from Chapter 4.
| Action class | Examples | Default behavior |
|---|---|---|
| Read-only | read file, grep, glob, list | Runs automatically |
| Reversible-ish writes | edit a file, create a file | Asks (or auto-approves once you allow it) |
| Shell / external | run a command, install a package, push to git | Asks — you approve each, or allowlist a pattern |
npm test once doesn't mean npm publish is fine. Approve deliberately. For outward-facing or hard-to-reverse actions (push, deploy, delete), confirm first — this is a habit the tool enforces and one you should build into every agent you write.Lab C3.2 · Steering with CLAUDE.md & slash commands advanced
Two mechanisms turn Claude Code from generic to your project's agent:
CLAUDE.md— persistent project context. A file at the repo root that's loaded into every session. Put conventions, build/test commands, and gotchas here.CLAUDE.md
# Project conventions - Run tests with `pytest -q`; lint with `ruff check`. - All API code targets the Anthropic Python SDK, model `claude-opus-4-8`. - Never edit files under `generated/` by hand — they're built by `make gen`.Now every session already knows how to test, what model to use, and what not to touch — you stop repeating yourself.
- Slash commands — reusable prompts. Type
/to see built-ins (and any you define). They're saved prompts for tasks you do often:.claude/commands/review.md
Review the current git diff for correctness bugs and security issues. Report findings with severity; don't fix yet.Invoke it with
/review. This is exactly the "prompts as versioned artifacts" idea from Chapter 2, applied to your workflow.
This lab shows the two ways you turn a generic agent into your project's agent: a CLAUDE.md file (standing context it always reads) and slash commands (saved prompts you can re-run). Both save you from re-typing the same instructions every session.
CLAUDE.mdis a plain text/Markdown file at the top of your repo. Claude Code loads it into every session automatically, so whatever you write here is context it always has — like a sticky note the agent reads before starting.- The example lines state conventions: how to run tests (
pytest -q), which model to use, and a hard rule —Never edit files under generated/ by hand. Now you never have to repeat any of this; the agent just knows. - Slash commands are reusable prompts saved as files under
.claude/commands/. The filename becomes the command:review.md→ you type/reviewto run it. - The
review.mdbody is just a prompt: "Review the current git diff for correctness bugs and security issues… don't fix yet." Saving it as a file means the whole team gets the same review prompt, and it's version-controlled like any other code.
What the output means: After adding these two files, a fresh session already knows your test command and coding rules without being told, and typing /review runs your saved review prompt in one keystroke.
Try this: Write a CLAUDE.md for a project you know with just four lines: the test command, one build/lint command, one convention, and one "never touch this" rule. That's Exercise C3.1 — the smallest useful version.
bit-bucket-repo this course lives in has nested CLAUDE.md files that tell the agent how each sub-project deploys. Good CLAUDE.md hygiene is the difference between an agent that guesses and one that follows your conventions.Subagents & parallelism advanced
For big tasks, Claude Code can spawn subagents — separate agent instances that work in parallel on independent pieces, then report back. This is the same "fan out, then synthesize" pattern you'd build with concurrency in your own systems.
This diagram shows how Claude Code handles a big task by splitting it into pieces that run at the same time. It's the "fan out, then converge" pattern: hand independent chunks of work to helpers, then combine what they find.
- Top box — main agent: the session you're talking to. When a task naturally breaks into independent parts, it doesn't do them one-by-one — it delegates.
- Three arrows fanning out → explore A / B / C: each is a subagent, a separate agent instance working on its own piece in parallel (e.g. searching three different subsystems, or reviewing five files at once).
- The line at the bottom — "results synthesized back into one answer": each subagent reports what it found, and the main agent merges those findings into a single coherent result for you.
- When to use it: only when the work truly fans out into independent items. For a single sequential edit, spinning up subagents just adds delay and cost — the main agent should just do it.
In short: Fan out for breadth (many independent things at once), converge for the answer. Reach for subagents when a task is wide, not when it's a single step.
Prompting a coding agent well advanced
An agent that can act needs sharper prompts than a chatbot. The habits that work:
| Habit | Why |
|---|---|
| Give the goal up front, fully specified | Modern Claude does best with the whole task stated once, not dripped over many turns. State intent, constraints, and "done" criteria. |
| Say what NOT to do | "Don't refactor unrelated code. Don't add error handling for cases that can't happen." Bounds prevent scope creep. |
| Ask to plan before big changes | "Show me a plan and the files you'll touch before editing." Cheaper to redirect a plan than a diff. |
| Point at verification | "Run the tests after each change and fix failures before moving on." An agent that checks its own work is far more reliable. |
/login endpoint 500s on empty passwords — reproduce it with a test, then fix it" is a task an agent can actually close.What to steal for your own agents expert
Claude Code is a reference implementation of everything this course teaches. Map its features to the patterns you build:
| Claude Code feature | Your agent's equivalent |
|---|---|
| Permission gate on risky tools | Human-in-the-loop approval + risk classification (Ch 4, capstone safety gate) |
CLAUDE.md project context | System prompt + retrieved conventions (Ch 2, Ch 3 RAG) |
| Slash commands | Versioned, reusable prompts (Ch 2) |
| Subagents | Parallel fan-out with a synthesis step (Ch 4) |
| Read-only-first workflow | The autonomy ladder — earn trust before acting (Ch 7 FDE) |
Common pitfalls expert
| Pitfall | Fix |
|---|---|
| Letting it edit before you trust its understanding | Start with read-only "explain/find" prompts |
| Blanket-approving shell commands | Approve deliberately; allowlist narrow patterns only |
| Repeating conventions every session | Put them in CLAUDE.md once |
| Vague prompts ("make it better") | State goal, constraints, and done-criteria explicitly |
| No verification step | Tell it to run tests/lint and fix failures before finishing |
Exercises expert
Exercise C3.1 — Write a CLAUDE.md
Context: The fastest way to feel the value of standing context is to write one for a project you know and watch the agent honour it unprompted.
Your task: For a project you know, write a CLAUDE.md with how to run tests, the one build/lint command, two conventions, and one "never touch this" rule, then start a session and confirm the agent respects it without being told.
Requirements:
- Include the test command and one build/lint command
- Include two real conventions the repo follows
- Include one hard "never touch this" rule
- Start a session and confirm the agent follows it without a reminder
- This is a context file, not executed code
💡 Hint: Pick conventions you'd otherwise have to repeat every session — the win is watching the agent already know them on turn one.
Exercise C3.2 — Plan-first refactor
Context: Running one real refactor under the plan-first protocol is how the difference from a one-shot "just do it" becomes obvious rather than theoretical.
Your task: Give Claude Code a real refactor task, but require: show a plan and the files first, wait for approval, then make one change at a time and run the tests between each — and note how the flow changes the outcome versus one-shot.
Requirements:
- Require a plan and the file list before any edit
- Wait for approval, then change one thing at a time with tests between each
- Observe that assumptions surface before code changes
- Observe that diffs stay small and reviewable and redirection is cheap
- This is a workflow, not executed code
💡 Hint: Watch specifically for the moment the plan reveals a wrong assumption — that's the redirect you'd otherwise have paid for in a finished diff.
Show what to watch for
Plan-first surfaces wrong assumptions before any code changes, keeps diffs small and reviewable, and lets you redirect cheaply. It mirrors the capstone's "thin vertical slice" discipline.
Exercise C3.3 — Map the features
Context: The check that you see Claude Code as an example rather than magic is being able to trace each feature back to the course chapter that teaches its underlying pattern.
Your task: Without looking, redraw the "steal for your own agents" table from memory: for each Claude Code feature, name the course chapter that teaches the underlying pattern.
Requirements:
- Permission gate → the agents chapter / capstone safety gate
CLAUDE.mdcontext → prompting and RAG- Slash commands → prompting (reusable artifacts)
- Subagents → the agents chapter (parallelism)
- Read-only-first → the FDE chapter (autonomy ladder)
- This is a recall/design exercise, not executed code
💡 Hint: If you can name the chapter behind each feature, you've internalised that Claude Code is assembled from patterns you already know.
🪜 Practice ladder beginner → industry
Six graded exercises, easy to real-world. Try each before opening its solution.
Context: Claude Code is the manual tool-use loop, hardened into a coding agent with a permission gate. Your first move in an unfamiliar repo is to let it orient without changing anything.
Your task: Launch Claude Code in a project and write your first prompt so it only orients itself without changing anything, then explain why read-only tools run without prompting you.
Requirements:
- Start a session scoped to the project directory
- First prompt asks it to explain the project and structure and to change nothing yet
- Explain that read-only tools (read/grep/glob) run automatically because the permission gate classifies them as safe
- Frame this as read-only-first discipline — build trust before letting it write
- This is a workflow, not executed code
💡 Hint: The permission gate's whole design is that safe reads don't interrupt you while writes do — leaning into that is how you stay in control cheaply.
Show solution
shell:
claude
prompt:
Explain what this project does and how it's structured.
Don't change anything yet.Running claude starts an interactive session scoped to the current directory — it can see and work with files there and nowhere else. Reading files, grep, and glob are read-only tools, so the permission gate lets them run automatically without asking you. Adding "don't change anything yet" on the first prompt in an unfamiliar repo is the read-only-first discipline: you build trust in what the agent understands before you let it write a single line. This solution is a workflow, not executed code.
Context: CLAUDE.md is standing context loaded into every session, so the agent stops needing the same reminders. The minimal useful version is just four lines.
Your task: Write a CLAUDE.md at the repo root with the four smallest useful things: the test command, one build/lint command, one convention, and one "never touch this" rule.
Requirements:
- Plain Markdown at the repo root, loaded into every session automatically
- The test command (e.g.
pytest -q) - One build or lint command (e.g.
ruff check) - One convention the agent should follow
- One hard "never touch this" rule (e.g. never hand-edit generated files)
- This is configuration/context, not executed code
💡 Hint: Put in the things you'd otherwise retype every session — the test command and the one rule you never want violated earn their place first.
Show solution
# Project conventions
- Run tests with `pytest -q`; lint with `ruff check`.
- All API code targets the Anthropic Python SDK, model `claude-opus-4-8`.
- Never edit files under `generated/` by hand — they're built by `make gen`.CLAUDE.md is a plain Markdown file at the repo root that Claude Code loads into every session automatically, so it is standing context the agent always has — like a sticky note it reads before starting. Stating the test command, the model to use, and a hard "never touch this" rule means you stop repeating yourself each session; a fresh session already knows how to test and what not to break. This file is configuration/context, not executed code.
Context: A slash command is a saved, version-controlled prompt the whole team shares — "prompts as versioned artifacts" made concrete. A /review command standardises code review.
Your task: Create a /review slash command as a saved prompt under .claude/commands/ that reviews the current git diff for correctness bugs and security issues but does not fix them yet.
Requirements:
- Save it as
.claude/commands/review.md— the filename becomes the command - The body is prompt text asking for a diff review of correctness and security
- It reports findings with severity but does not fix anything yet
- It's reusable and identical for everyone on the team
- It's version-controlled like code; this is a workflow artifact, not executed code
💡 Hint: The filename is the command name, and the body is just the prompt you'd otherwise paste every time — committing it makes the whole team review the same way.
Show solution
.claude/commands/review.md:
Review the current git diff for correctness bugs and
security issues. Report findings with severity; don't fix yet.Slash commands are reusable prompts saved as files under .claude/commands/; the filename becomes the command, so review.md is invoked by typing /review. The body is just a prompt. Saving it as a file means the whole team gets the identical review prompt and it is version-controlled like any other code — this is the "prompts as versioned artifacts" idea from Chapter 2 applied to your workflow. Not executed code; it is a workflow artifact.
Context: "Fix the bug" is a weak prompt. The lesson's four habits — specified goal, explicit non-goals, plan-first, and a verification step — turn it into one a coding agent can execute reliably.
Your task: Rewrite the weak prompt "Fix the bug" into a strong, actionable one using the four habits: a fully specified goal, what NOT to do, plan-first, and a verification step.
Requirements:
- State the goal precisely (the symptom, the expected behaviour, a reproducing test)
- Say what NOT to do (no unrelated refactors, no handling impossible cases)
- Require a short plan and the files it will touch before editing, and wait for approval
- Require verification: one change at a time, run the tests after each
- This is workflow design, not executed code
💡 Hint: Bounding the work ("don't do X") and demanding a plan first are what keep the agent from confidently solving the wrong, larger problem.
Show solution
prompt:
The /login endpoint 500s on empty passwords.
Goal: reproduce it with a failing test, then fix it so an empty
password returns a 400 with a clear error.
Do NOT: refactor unrelated code, or add error handling for cases
that can't happen.
First: show me a short plan and the files you'll touch — wait for
my OK before editing.
Then: make one change at a time and run `pytest -q` after each
change; fix any failures before moving on.An agent that can act needs sharper prompts than a chatbot. "Fix the bug" is vague and gets literal-but-wrong results; a strong prompt states intent, constraints, and "done" criteria up front (modern Claude does best with the whole task stated once). Saying what not to do bounds scope creep; asking for a plan first is cheaper to redirect than a diff; and pointing at verification ("run the tests after each change") makes the agent check its own work. This is a workflow, not executed code.
Context: On a real refactor, a strict plan-first, one-change-at-a-time protocol surfaces wrong assumptions before code changes and keeps diffs small — the same discipline as a thin vertical slice.
Your task: Give Claude Code a real refactor task under a strict plan-first, one-change-at-a-time protocol, and describe what the plan-first flow buys you versus a one-shot "just do it".
Requirements:
- State the refactor, then require a plan plus the exact files before any edit
- Wait for approval; then make one change at a time and run the tests between each
- Stop and report if any test fails; don't proceed
- Bound scope (e.g. don't change public signatures or unrelated modules)
- Explain the payoff: assumptions surfaced early, small reviewable diffs, cheap redirection
- This is workflow design, not executed code
💡 Hint: Plan-first is cheaper to redirect than a finished diff — you catch the wrong approach at the plan, not after the code is written.
Show solution
prompt:
Refactor payments/charge.py to extract the retry logic into a
reusable helper.
1. Show a plan and the exact files you'll touch first.
2. Wait for my OK.
3. Then make ONE change at a time and run `pytest -q` between each.
4. Stop and report if any test fails; do not proceed.
Don't change public function signatures or unrelated modules.Plan-first surfaces wrong assumptions before any code changes, keeps diffs small and reviewable, and lets you redirect cheaply — it mirrors the capstone's "thin vertical slice" discipline. The per-step verification ("run tests between each") means an agent that checks its own work, which is far more reliable, and the explicit bounds prevent scope creep. This maps directly to the human-in-the-loop and read-only-first patterns the FDE method (Chapter 7) uses. Workflow design, not executed code.
Context: Claude Code is a reference implementation, not magic. Mapping each of its features to the pattern you'd build yourself proves you can steal the ideas for your own agents.
Your task: Reproduce the "steal for your own agents" table: for each Claude Code feature, name the equivalent pattern you build into your own agents.
Requirements:
- Permission gate on risky tools → human-in-the-loop + risk classification
CLAUDE.mdproject context → system prompt + retrieved conventions (RAG)- Slash commands → versioned, reusable prompts
- Subagents → parallel fan-out with a synthesis step (only when work is genuinely wide)
- Read-only-first workflow → the autonomy ladder, earning trust before acting
- This is a knowledge/design exercise, not executed code
💡 Hint: The permission gate is the single most important idea to carry across — classify by risk so safe reads run free and writes ask.
Show solution
Claude Code feature -> Your agent's equivalent
-----------------------------------------------------------------
Permission gate on risky tools -> Human-in-the-loop approval +
risk classification (Ch 4 /
capstone safety gate)
CLAUDE.md project context -> System prompt + retrieved
conventions (Ch 2, Ch 3 RAG)
Slash commands -> Versioned, reusable prompts (Ch 2)
Subagents -> Parallel fan-out with a
synthesis step (Ch 4)
Read-only-first workflow -> The autonomy ladder — earn trust
before acting (Ch 7 FDE)Claude Code is a hardened, productionized version of the same Messages API and manual tool-use loop from C2, running against a frontier model. Its permission gate is the single most important safety idea to carry into your own agents — it classifies actions by risk (read-only runs automatically; writes and shell/external commands pause and ask). Subagents are the "fan out, then converge" pattern used only when work is genuinely wide, not for a single sequential edit. This is a knowledge/design exercise, not executed code.
✓ Checkpoint — you can move on when you can…
- Install Claude Code and run a read-only orientation session.
- Explain its agent loop and how the permission gate classifies actions.
- Write a
CLAUDE.mdand a slash command that steer its behavior. - Say when to use subagents and when not to.
- Prompt a coding agent with goal, bounds, and verification.
- Map each Claude Code feature to the course pattern it implements.
terraform plan, kubectl, and AWS calls, and the permission gate is a hard safety policy that never touches prod unapproved. Everything you learned here about read-only-first, approval gates, and project context maps straight onto it. See the capstone design →Knowledge check check yourself
What is the single most important safety idea in Claude Code's productionized agent loop, and how does it treat read-only vs state-changing actions?
Show answer
What does a CLAUDE.md file do, and how does it differ from a slash command?
Show answer
CLAUDE.md is persistent project context loaded into every session (conventions, build/test commands, gotchas); a slash command is a reusable saved prompt under .claude/commands/ that you invoke on demand.