Your First Verified Fix
Make one tiny change and watch a test prove that it works
One request, one check A request says what to change. A check says how to tell whether the change worked.
- You started with a visible failing test.
- You asked for one change and named `npm test` as the check.
- You used the passing command output as evidence that the fix worked.
The project has a function that returns Hello Ada, while its test expects Hello, Ada!. Here is an abridged representative terminal transcript with annotations. Lines beginning with ← are lesson annotations, not terminal output.
Why it matters: Your first reusable Claude Code workflow is small: show a failure, request a change, and name the check.In the transcript, which output is the clearest evidence that the requested change worked?
What Fills the Context Window
Almost every best practice in this course exists because of one constraint
Startup cost, then everything you add Loaded before your first message: the system prompt, CLAUDE. md files from your working directory and its parents, the first 200 lines or 25KB of auto memory's MEMORY.
- The window holds configuration, conversation, file reads, and command output together.
- Startup cost is fixed and prunable; working cost is unbounded and must be scoped.
- Subagent work does not land in your window — only its summary does.
The formatting rule is being ignored. You want evidence before changing anything.
Why it matters: Context problems have a receipt. Read it before changing your prompt.You have eight MCP servers connected but use only one. A colleague says that is why your context fills so fast. Are they right?
The Permission Model
Enforced by Claude Code, not by the model — and that distinction is the whole safety story
Three tiers, two persistence behaviors Read-only tools — file reads, grep, glob — need no approval inside the working directory or any additional directories you have granted. Bash commands need approval, except the built-in read-only set.
- Read-only work is free inside the working directory; Bash, edits, and network calls ask.
- Bash approvals persist per repository; edit approvals last one session.
- Compound commands are split, so each subcommand must match a rule on its own.
You want to see the difference between the persisted Bash rule and the session-only edit approval.
Why it matters: Approvals you click are invisible; approvals you write are reviewable. Prefer writing the ones that matter.Your CLAUDE.md says "you may run any git command without asking." Claude still prompts for `git push`. Is something broken?
Choose the Right Extension
Six mechanisms, six triggers — most setups fail by picking the familiar one
Route by trigger, then check the cost CLAUDE. md — loads every session, full content, in every request.
- Six mechanisms, each with a recognizable trigger.
- CLAUDE.md costs every request; skills cost on demand; subagents cost a separate window; hooks cost nothing unless they return output.
- Instruction versus enforcement is the sharpest distinction: must-always-happen means hook.
You have the team's four complaints and their current (wrong) homes.
Why it matters: Misrouting is the default failure. The trigger tells you the mechanism faster than the feature comparison does.Your team's API style guide is 400 lines. Where does it belong, and what happens if you put it in CLAUDE.md?
Subagents and Context Isolation
Send the reading somewhere else and get back only what you need
A separate window with a one-way door Why it helps. The subagent's reads, greps, and command output live in its window, not yours.
- Subagents run in their own window and return only a summary.
- Explore is read-only and skips CLAUDE.md and git status; general-purpose has full tools and loads them.
- Conversation history and main-session auto memory do not cross the boundary.
You need to understand token refresh before changing expiry behavior, and you want to keep your window clean for the change itself.
Why it matters: Delegate the reading, keep the deciding — and write the prompt as though the subagent has never met you, because it hasn't.You delegate to a subagent: "apply the naming convention we agreed on to all the new modules." The result uses a different convention. Why?
Non-Interactive Mode
claude -p turns the agent into a Unix command — with all that implies
Bound the actions, then the turns, then parse the result Enumerate the tools. --allowedTools "Edit(src/)" "Bash(pnpm test )" states exactly what the job may do.
- `claude -p` composes like a Unix command; formats are text, `json`, and `stream-json`.
- No prompts and no trust verification under `-p`; the allow list is the boundary.
- `dontAsk` plus `--max-turns` gives fail-closed, bounded runs.
Same job, same repository. You want it to fix tests or fail loudly, never to delete them.
Why it matters: Unattended safety comes from an enumerated allow list plus an external check — not from a more carefully worded prompt.Your `-p` job hangs for an hour and then times out in CI. The transcript shows Claude trying to run a command it had not been allowed. What mode was it in, and what should it be?