Claude Code best practices: a setup that scales

Claude Code reads your CLAUDE.md files at the start of every session. They are how it learns who you are, how you like to work, and how your projects fit together. Most setups start as one file and grow into a junk drawer: personal preferences mixed with build commands, stale instructions nobody trusts, the same rule stated three slightly different ways.

There is a better shape. This guide explains it, and at the end there is a prompt you can copy that makes Claude audit your setup against it, ask you what is missing, and fix the files with you.

Three layers, one job each

Claude documentation works best in three layers. Each layer has one job, and no guidance is duplicated across layers.

Layer 1: the global ~/.claude/CLAUDE.md. How Claude should behave. This file is personal and travels with you across every project. It answers "how does this user want Claude to interact", never "how does this project work". It holds your interaction preferences (response length, languages, how sessions should be titled), your execution model (when to orchestrate multiple agents, when to work inline), which model tiers to use for which kind of work, your verification bar (what must actually pass before Claude may say "done"), and safety rails like secrets handling.

Layer 2: the repo CLAUDE.md. A router, plus conventions. This file is loaded at the start of every session in the repo, so every token in it is paid on every session. Keep it thin. It routes; it does not explain. It holds the repo layout in a few lines, a pointer map (for each concern, the path of the doc that owns it), the verify commands, the release entry point, the genuinely non-negotiable rules stated in one or two lines each, and the repo's naming conventions. If a section grows past a short paragraph, its content belongs in a topic doc with a one-line pointer left behind.

Layer 3: topic docs. The how-to. docs/ARCHITECTURE.md, DESIGN.md, docs/RELEASING.md and friends. These hold the deep detail and are loaded on demand, only when Claude works in that area. They can be long. Every topic doc should be reachable from the Layer 2 pointer map, and no two docs should own the same concern.

Why this shape works:

Token economy. Layers 1 and 2 are paid on every session; Layer 3 only when relevant. A fat repo file silently taxes every conversation.
Single source of truth. Duplicated guidance drifts. A router that points instead of restating has far less surface to contradict or go stale.
Portability. Your behavior preferences follow you to new projects without copying anything.

Equip agents with knowledge, not job titles

When Claude orchestrates subagents, what measurably helps is giving each agent the knowledge its slice of work needs: an objective, scope boundaries, the relevant current best practices, and an output contract. "You are an expert in X" on its own does little; "here are X's current best practices" does a lot. Whether an agent should be a specialist or a generalist is a per-task call: specialize deep, separable slices, and keep sequential or cross-cutting work with one strong generalist.

One more habit worth encoding: before implementing, have Claude look up the current best practices of whatever the task touches (frameworks, libraries, SDKs, concepts) from live sources instead of trusting its training data. And have it rediscover every time rather than writing the findings down: written-down best practices go stale, while the code plus a fresh lookup stays true.

Let Claude fix your setup

Copy the prompt at the top of this page into any Claude Code session. Claude will fetch this page, read the audit procedure below, and work through it with you: it inventories your files, asks you what is missing, and rewrites them with your approval.

The audit prompt

You are auditing and improving this user's Claude Code setup against the three-layer architecture described above. Work interactively: never rewrite anything before the user has answered your questions.

Step 1: inventory. Read every always-loaded source: ~/.claude/CLAUDE.md, the repo CLAUDE.md, any nested or CLAUDE.local.md files, anything they import, and the auto-memory index if one exists. Then list the markdown docs in the repo. Note which topic docs exist and which are referenced from the repo CLAUDE.md. (Other configuration surfaces exist: settings.json, hooks, skills. They are out of scope for the rewrite, but inventory the always-loaded ones so the token accounting is honest.)

Step 2: classify. Tag every instruction found in Step 1: behavior (belongs in Layer 1), routing/convention (belongs in Layer 2), how-to (belongs in a Layer 3 topic doc), other-surface (belongs in settings, a hook, a skill, or memory), or stale (contradicts the current code, refers to files that no longer exist, or duplicates another layer). Build a short table of misplaced and stale items.

Step 3: interview. Ask the user about every gap, in small batches, concrete and answerable, proposing a sensible default with each question. Cover at minimum whichever of these the existing files do not already answer: response shape (length, tone, language); session titling; subagent display preferences if their terminal has options; when to orchestrate multiple agents and how big a fan-out may get; which model tiers for which roles; the definition of done (which commands must pass); secrets rules; and, per repo, the real non-negotiables and which doc owns each concern. If the files already answer everything, show the classification table for confirmation and move on.

Step 4: propose, then rewrite. Present a short plan: what moves out of each CLAUDE.md, what gets added, which topic docs are created or merged. After approval, apply it. A block moved from the repo CLAUDE.md into a topic doc leaves a one-line pointer behind; a block moved into the global file is simply removed (a checked-in file must never point into one user's private config).

Step 5: verify. Re-read the finished files and check: the repo CLAUDE.md is a genuine router (aim for under 80 lines); every topic doc is referenced; nothing appears in two layers; router one-liners still match the docs they point to; every interview answer landed somewhere. Report the before and after size in lines of each always-loaded file.

Anti-patterns to flag along the way: the fat router (a repo CLAUDE.md that explains architecture and release mechanics inline); behavior rules in a repo file; the orphan doc no file points to; the same rule stated in two places; stale instructions that erode trust in the whole file; a setup with no stated verification bar, letting "should work" pass as "works"; and workflows that go straight to code on remembered APIs instead of looking up current best practices first.

Where Orb fits

Orb keeps every one of those Claude Code sessions one keystroke away: each session is a bubble in a Liquid Glass dock, so the maker, the checker, and the session auditing your setup all stay visible and reachable. If you are reading this from Orb's onboarding: welcome, your first session is already running this audit.