> practices
Practices
Atomic, versioned best-practices — each a when X → do Y (because Z)
unit tied to a guide section, with how to verify it still holds. This is
the corpus agents query through the
guide MCP; machines read it at
/practices.json.
- When
- A task will run 30+ minutes largely unattended (an overnight migration, a big multi-file refactor, a workflow fleet).
- Do
- Switch the session to Fable before you kick it off.
- Why
- Fable is Opus-class reasoning with faster output, so a long autonomous run finishes sooner without dropping quality. Keep Opus/Sonnet for short interactive work where latency matters less than the marginal reasoning.
Fable is the ceiling, not the default — reach for it when a task’s wall-clock time, not its difficulty, is the constraint.
- When
- You're running an overnight or unattended job that might hit an AskUserQuestion.
- Do
- Leave the default (since 2.1.200 it no longer auto-continues). Only re-enable the idle timeout via /config for tasks scoped so any default is harmless.
- Why
- A stalled question is a safer failure mode than Claude silently picking an answer and building a hundred commits on a guess you never saw.
- Since
- Claude Code 2.1.200
- Verify
- /config → the AskUserQuestion idle timeout should be off by default.
Come back to a paused session, not to work built on an invisible assumption.
- When
- You're starting a long or unattended run and don't want to approve 200 prompts.
- Do
- Use auto mode and scope what "trusted" means (your repos, buckets, internal domains). Reserve bypass mode for disposable sandboxes only.
- Why
- Auto mode's classifier screens each action and tool output, blocking the genuinely dangerous while letting routine work flow — safety without babysitting. Bypass turns that off entirely.
- Since
- Claude Code 2.1.205
- Verify
- Docs — permission modes; 2.1.205 changelog entries on auto-mode hardening (transcript-tamper block, rm -rf confirmation).
Since 2.1.205 auto mode also blocks transcript tampering and asks before rm -rf on an unresolved variable — the screen keeps hardening.
- When
- Claude has tried to fix the same thing twice and is still wrong.
- Do
- Clear or compact the context and restate the problem fresh, rather than adding a third correction on top.
- Why
- A context full of failed attempts biases the next attempt toward the same wrong path. A clean slate with a crisp restatement beats piling on.
Poisoned context compounds errors. Resetting is cheaper than it feels.
- When
- Your checked-in CLAUDE.md has grown past a screen, or /doctor flags it as bloated.
- Do
- Cut anything Claude could derive from the codebase itself (project structure, commands visible in package.json, obvious conventions) and keep only durable constraints and non-obvious decisions. Since 2.1.206, /doctor proposes these trims for you.
- Why
- Every session pays CLAUDE.md's tokens before any work starts — a bloated file is a permanent tax on the context budget with no marginal signal.
- Since
- Claude Code 2.1.206
- Verify
- Run /doctor — a bloated checked-in CLAUDE.md shows up as a check with proposed trims.
CLAUDE.md is for what the repo can’t say — the moment a line restates the codebase, delete it.
- When
- An MCP server does long-running calls (a heavy search, a build, a remote job) and they die at ~60 seconds in fresh sessions.
- Do
- Set request_timeout_ms for that server in .mcp.json (or --mcp-config). Since 2.1.206 the setting is actually honored — before, fresh sessions silently fell back to the 60s default.
- Why
- The failure looks like a flaky remote server but is a client-side default; one config line makes the timeout intentional instead of accidental.
- Since
- Claude Code 2.1.206
- Verify
- Configure request_timeout_ms above 60000 for a slow server and confirm a long call survives in a brand-new session.
If long MCP calls still time out after 2.1.206, the limit you set is now real — raise it in config, not by retrying.
- When
- You're about to make an ultracode / multi-agent request whose scale you're unsure about.
- Do
- Set Dynamic workflow size to small in /config AND scope the prompt down. Watch the count in /workflows.
- Why
- The size setting is advice to the model, not an enforced ceiling (the 16-concurrent / 1,000-per-run hard caps still apply), and a broad prompt can still talk Claude past a small setting. Bounding spend takes both the knob and a tight prompt.
- Since
- Claude Code 2.1.202
- Verify
- /config → Dynamic workflow size shows unrestricted/small/medium/large; /workflows shows the live agent count.
Find out the agent count from /workflows, not from the bill.
- When
- A multi-file task has a lot of mechanical coding (boilerplate, edits, wiring) around a few real decisions.
- Do
- Tell Claude to run the routine coding in a subagent on an appropriate lower-power model, and keep judgment, review, and synthesis in the lead model. Drop the instruction in the session or your CLAUDE.md.
- Why
- You get more throughput while the lead model's allowance drains slower — the expensive model only spends on decisions, not typing.
A one-line habit, not a config change: “for all coding tasks use your judgement to pick an appropriate lower-power model and run it in a subagent.”
- When
- Claude Code acts oddly after an update — hooks not firing, an MCP server missing, settings seemingly ignored — or you inherit a machine you didn't configure.
- Do
- Run /doctor (alias /checkup) before hand-debugging config files. Since 2.1.205 it diagnoses AND fixes setup issues, and since 2.1.206 it also flags bloated checked-in CLAUDE.md files.
- Why
- A full checkup finds the broken hook, stale binary, or misconfigured server in seconds; spelunking through settings.json and ~/.claude by hand takes an afternoon and misses the same things.
- Since
- Claude Code 2.1.205
- Verify
- Run /doctor — it should walk a checklist of setup checks and offer fixes; /checkup is an alias.
The habit is “checkup first, spelunk second” — the tool now knows more failure modes than you remember.
- When
- You have a long PR walkthrough, investigation, or dashboard-like result you'd otherwise paste into Slack or Notes.
- Do
- Ask for an artifact ("make an artifact that walks through this PR with the diff annotated"). Reopen the latest from any session with Ctrl+].
- Why
- An artifact is a live, reopenable page instead of a wall of text — a second screen that updates while a long task runs, and on Pro/Max it stays private to you.
Artifacts are open to Pro and Max now, not just Team/Enterprise.
- When
- A session just built a feature or made a nontrivial change.
- Do
- Run /code-review, or spin a fresh subagent that sees only the diff, to grade the work before you accept it.
- Why
- A fresh context isn't biased toward code it just wrote, so it catches what the author missed. It's the cheapest way to raise the floor on autonomous output.
Writer/reviewer separation is the single highest-leverage habit for unattended work.