Claude Code Best Practices: CLAUDE.md, Subagents, Hooks and Reviews

Claude Code is easy to start with and surprisingly deep once you configure it. Most disappointing results trace back to the same few causes: no project context, tasks that are too large, missing verification, or permissions left wide open. The practices below are organized by layer, from the repository outward, and reflect how the tool works as of November 2026. Check the official documentation at docs.anthropic.com for current details.

Layer 1: CLAUDE.md as the project's briefing

CLAUDE.md is loaded into context at the start of each session. Claude Code reads it hierarchically: a user-level file in your home directory, a project file at the repository root, and files in subdirectories when the agent works there. Treat it like a briefing for a capable new colleague, not like a wiki.

A lean, effective project file covers:

• Commands: how to install, build, run tests (including a single test), lint and type-check.
• Architecture in a few lines: main directories, where business logic lives, what not to touch.
• Conventions that differ from defaults: naming, error handling, state management, preferred libraries.
• Hard rules: “Never edit generated files in src/gen/”, “All database changes need a migration.”
• Definition of done: “Tests pass, types check, no new lint warnings.”

Keep it short. Every line costs context on every request, and long files dilute the rules that matter. If you also use other agents, keep shared rules in AGENTS.md and import it; see AGENTS.md and CLAUDE.md explained.

Layer 2: How you give tasks

1. Plan first for anything non-trivial. Use plan mode so Claude explores and proposes an approach without editing. Correcting a plan costs seconds; correcting an implementation costs much more.
2. State acceptance criteria. “Done when the new endpoint returns 429 after five failed logins within a minute, with a test proving it.”
3. Point to examples. “Follow the pattern in services/billing.ts” beats paragraphs of description.
4. Keep tasks reviewable. If the diff would be too large to read carefully, split the task.
5. Reset when stuck. If the agent loops on the same error, clear the context and restart with what you learned, rather than piling on corrections.

Managing context in long sessions

Context is a budget. Long sessions accumulate file contents, logs and abandoned approaches that crowd out what matters. Start a fresh session for each new task, delegate searches to subagents so their findings return as summaries, and avoid pasting full log files when the relevant twenty lines will do. When a session must continue, compacting it with a summary of decisions made keeps the agent on track.

Layer 3: Subagents for focus

Subagents are specialized agents with their own instructions, tool access and separate context window. Project subagents live in .claude/agents/ and are shared via version control. They help in two ways: the main session's context stays clean, and each subagent can be tuned for a job.

Restricting tools per subagent is both a quality and a safety measure: a reviewer that cannot edit cannot “fix” things silently.

Layer 4: Hooks for guarantees

Instructions in CLAUDE.md are requests; hooks are enforcement. Hooks are commands configured in Claude Code's settings that run at defined points, for example before a tool is used or after a file is edited. Useful patterns:

• Format after every edit: run the formatter on changed files so style never appears in reviews.
• Block sensitive paths: reject edits to .env files, lockfiles or infrastructure definitions.
• Guard dangerous commands: stop commands such as force pushes or production database access before they run.
• Run checks before finishing: require type checks or a fast test subset to pass before the agent reports completion.

Keep hooks fast and their error messages clear, because the agent reads the output and adjusts.

Layer 5: Permissions and integrations

• Use allow and deny rules in project settings rather than approving everything interactively or skipping permissions entirely.
• Pre-approve safe, frequent commands (tests, linters) to reduce friction; keep network, deployment and destructive commands behind confirmation.
• Add MCP servers deliberately, with the narrowest scopes. Each one widens what the agent can do and what untrusted content can reach it.
• Commit shared settings; keep personal preferences in local, ignored settings files.

Layer 6: Review and automation

Agent output still needs a human reviewer who understands the change. Make that efficient: ask Claude to summarize what changed and why, run a reviewer subagent before opening the pull request, and require the same CI checks as for human code. For routine jobs, headless mode lets you run Claude Code in CI, for instance for nightly dependency updates or first-pass pull request reviews. Pair this with AI code review tooling where it helps, and with release automation such as the setup in mobile CI/CD for Claude Code projects.

Anti-patterns to retire

• A 600-line CLAUDE.md copied from the internet.
• Running with all permissions skipped on a machine that holds production credentials.
• Merging diffs nobody read because “the tests passed.”
• Every developer maintaining private configuration instead of a shared, versioned setup.

Teams that want to adopt these practices together often benefit from a structured session on their own codebase. A Claude Code workshop from neooutput covers exactly this setup, from the first CLAUDE.md to hooks and CI.