Best Practices for Claude Code

1A good prompt says what stays put

First family: limit what Claude is allowed to do, starting with the request itself. Faced with a vague request, Claude adds intermediate code, files and features nobody asked for (ch. 6). A verb like "refactor" makes it worse. Refactoring means reorganizing code without changing what it does. Yet, according to the book, such terms "are not neutral. They signal permission" (ch. 8).

Against this overreach, the book sums up a good prompt in four elements (ch. 7):

• what must change;
• what must not change;
• which tradeoffs matter;
• which tradeoffs do not matter.

The book applies these four elements in a rewriting exercise, on the slides app (ch. 8):

✗ "Add usage statistics to track slide generation."

✓ "Add lightweight, production-ready usage statistics to track slide generation.
   The logic should live in a dedicated, isolated module or service, and must not
   change the existing generation logic, the data models or the APIs. Introduce no
   new dependency and no architectural change. Runtime overhead must be negligible.
   If that is impossible without breaking these constraints, stop and explain why."

In the ✓ version, each piece has a job:

• The isolated module and the prohibitions say what stays put. A module is a piece of code kept separate.
• The negligible overhead is the tradeoff that matters.
• The last sentence gives Claude an honest way out: stop and explain, instead of hacking something together.

Why so much care? The book answers with a warning: Claude Code "will not protect your architecture for you" (ch. 8). Architecture is the way the code is split up and organized. Nor will Claude reliably stop you from making a risky change. It is "a multiplier" (ch. 8), so sloppy instructions produce damage faster than doing it by hand.

2CLAUDE.md prevents, it doesn't repair

A tight prompt only covers one request. To limit every session at once, the book turns to a file. CLAUDE.md is a Markdown file at the root of the project. Claude reads it at the start of every session, "before your prompt, before your code" (ch. 10). Its rules therefore weigh on every answer.

CLAUDE.md doesn't have to be written by hand. The /init command writes a first draft: it analyzes the repository, that is, the project folder (ch. 10). You then add what Claude can't guess:

• the project's boundaries: here no database, no accounts, no pages built by the server (ch. 12);
• the tool versions: Node, Python, Docker and PowerShell, which Claude reads off the machine (ch. 13).

Two of these tools come back later. Node runs JavaScript outside the browser, and PowerShell is the Windows terminal. Here is an example of my own, not from the book, in the spirit of the course:

# CLAUDE.md
## Scope
- Out of scope: database, user accounts, server-side rendering
## Environment
- Windows, PowerShell only; Node 18 or higher
## Learned rules
- Do not refactor the layout logic
- No new file for a layout change

The "Learned rules" section of this example follows the book's maintenance rule. As soon as you correct Claude twice on the same point, the correction goes into the file (ch. 13). From it the book draws its formula. CLAUDE.md is not where you solve problems: it is where you prevent bad ones from happening in the first place (ch. 13).

3Plan mode: no code before a reviewed plan

Second family: make Claude think in writing before it codes. A scratchpad is a Markdown file where Claude writes its analysis before touching the code. Plan mode is a Claude Code setting that helps it do so. In this mode, Claude reads files freely. Its edits and commands stay blocked until you approve a plan (ch. 18).

The book chains the two in four steps (ch. 18):

1. you enter plan mode;
2. Claude fills the scratchpad;
3. you review it;
4. you switch to a mode that allows edits.

The second step starts from a prompt, shown here (ch. 15):

"Create a scratchpad.md file. Use it to reason about the next change before writing
any code. Include the goal, the constraints, a step-by-step plan and what must not
change. Do not modify any code yet."

On the slides app, Claude comes back with three architecture options, with their pros and cons (ch. 17). It also flags edge cases, those extreme situations where the code risks breaking:

• an empty Markdown file;
• slide separators hidden inside a code block;
• a giant PDF export.

The scratchpad has a second job. According to the book, Claude Code is "effectively stateless across sessions" (ch. 15): it keeps no memory of the previous session's reasoning. The scratchpad keeps that reasoning in its place. This has changed since, see "Still relevant in 2026?".

Since the next session relies on it, the scratchpad has to stay up to date. Stale planning documents are often worse than none, because they create false confidence (ch. 18).

4Three constraints settle it better than an opinion

The scratchpad doesn't settle everything. It leaves one choice open: where to store the statistics (ch. 17)?

• option A: in-memory counters, written to a JSON file, a text data format;
• option B: an event system, code that reacts to messages sent by the rest of the app;
• option C: a SQLite database, a database kept in a single file.

To settle it, the book doesn't ask "what do you think?". It names the decision in an ADR (Architecture Decision Record). An ADR is a numbered note that records an architecture decision. This one is called ADR-001. The prompt then sets three constraints, which a solution either meets or doesn't (ch. 20):

"Resolve the open decisions in SCRATCHPAD.md related to usage tracking, in particular
ADR-001. Let's aim for a simpler approach than the full event system.
Produce an implementation plan with all file changes.
Constraints:
- No external database
- Only Node.js built-in modules
- Data must survive restarts"

With these constraints, Claude picks a simplified variant of option A (ch. 21). A single object, shared by the whole codebase, accumulates the counters in memory. That one-of-a-kind object is called a "singleton". It only writes to the file after a short pause (ch. 21). Without the constraints, Claude might reasonably have chosen a more elaborate architecture (ch. 21).

The resulting plan is reviewed before approval, and it is short. It comes to one file created, three modified, no dependency and eight checks (ch. 21 and 22). A dependency is an external library added to the project. The plan also copies the structure of the services already there. The new code thus fits the existing style instead of importing another one (ch. 21). The module's lesson: "Existing codebases reward discipline" (ch. 25).

5A recovery prompt also says what not to redo

Third family: catch what goes wrong, starting with the most brutal accident. While implementing the usage tracking, Claude runs Get-Process node | Stop-Process -Force. This PowerShell command force-kills every Node process, meaning every running Node program. A child process is a program launched by another one. According to the book, force-killing a child Node process can close the terminal, and the assistant with it (ch. 23).

The session dies, but the files are intact. The interruption hits the session, not necessarily the code (ch. 23). So you have to give Claude back its context, meaning what it knew about the task. The book does it with a recovery prompt of four elements (ch. 23):

• what is already done;
• read the code first;
• non-destructive tasks;
• things to avoid.

These four elements fit in a few lines. Here is a reconstruction of that prompt, written by me from the book's description:

"Usage tracking (option A) is implemented and the server tests pass. The session
stopped before SCRATCHPAD.md was updated. First re-read usageTracker.js, slides.js
and index.js. Then update SCRATCHPAD.md. Do not restart the server and do not
run any test."

The last sentence of this prompt carries the book's rule. A recovery prompt should not only say what to do, it should also say what to avoid repeating (ch. 23).

6Code that works can still drift

Like a cut-off session, a crash is obvious right away. Silent drift is not: the code works, but it slowly moves away from the project's structure. The book gives three forms of it (ch. 31):

• duplicated logic;
• a shared utility bypassed, meaning a project-wide function that doesn't get called;
• behavior placed at the wrong level.

A concrete case, made up to illustrate the first form: Claude rewrites a duration formatter inside the new module. Yet the project already has one. Everything works, and technical debt has moved in. Technical debt is a shortcut you'll have to pay back later.

Against this drift, the book proposes six steps (ch. 33):

1. map the code involved;
2. pick "the narrowest place to extend the system" (ch. 32);
3. set minimal-change rules;
4. implement in small, verifiable steps;
5. ask Claude to audit its own technical debt;
6. validate what has not changed.

The sixth step, validating what has not changed, leans on a prompt. That prompt forces Claude to prove it understood the existing code (ch. 33):

"List all the behaviors that should remain unchanged after this modification.
Explain how the current implementation preserves them."

Claude's answer reads like a test. A vague answer means the change isn't safe. Compiling proves nothing either: code without a syntax error can still drift. The book sums it up in four words: "compilation is not review" (ch. 34).

Finally, drift often starts with a sentence. The book warns that three innocent-sounding phrases open the door to it (ch. 33):

• "Just add it quickly."
• "Refactor while we are here."
• "We'll clean it up later."