Claude Code Best Practices for Large Codebases

1. Keep the root CLAUDE.md lean

Everything in your root CLAUDE.md is loaded into every session. Anthropic recommends staying under about 200 lines per file. Put only what applies everywhere: build and test commands, the overall layout, and hard rules.

Imports with @path help organise a long file but don't save context — imported files load too. To save context, scope instead.

2. Scope rules to where they apply

Put a CLAUDE.md inside a package or folder — it loads only when Claude works on files there. Or use .claude/rules/ with path-scoped rules, which load only for matching files.

---
paths:
  - "services/api/**"
---

# API rules
- Every endpoint validates input with the shared schema helpers
- Return errors in the standard { code, message } shape
- Add an integration test for every new route

3. Plan before you edit

For anything non-trivial, start in plan mode (/plan or Shift+Tab). Claude researches the codebase and proposes an approach without touching files. Correcting a plan is cheap; correcting a 20-file change is not.

4. Delegate exploration to subagents

Searching a big repo fills context fast. Ask Claude to use a subagent to investigate — "use a subagent to find every place we call the billing API and summarise how" — so the reading happens in a separate context and only the summary comes back.

For independent pieces of work, subagents with isolation: worktree can each work in their own temporary git worktree without stepping on each other's edits.

5. Manage context deliberately

• /context — see what's taking up space
• /compact — summarise the session when it gets long, optionally with focus instructions
• /clear — start fresh between unrelated tasks
• Point Claude at specific files and folders instead of asking it to "look at everything"

6. Make verification automatic

Tell Claude how to check its work — the exact test command, the type checker, the linter — and expect it to run them. For rules that must never be broken, use hooks: a PostToolUse hook to format files after edits, or a PreToolUse hook that blocks writes to generated or protected folders.

7. Control permissions

Use /permissions to allow safe, frequent commands (your test runner, read-only git commands) and deny risky ones. Fewer prompts keep you in flow; firm denies keep you safe. Commit shared rules to .claude/settings.json so the whole team works the same way.

8. Review before you merge

Use /diff to see everything that changed and /code-review on your branch before opening a pull request. For security-sensitive changes, run /security-review too.

9. Build a team of specialists

As patterns emerge, capture them: a migration subagent, a test-writing subagent, a release skill. claudeagents gives you 120+ of these ready-made, all reading from one CLAUDE.md, so your large-codebase conventions apply to every agent at once.