---
title: "CLAUDE.md Best Practices: 8 Patterns That Actually Work"
published: true
description: "A hands-on guide to structuring CLAUDE.md files so Claude Code understands your codebase — from skills and hooks to progressive disclosure via ADRs."
tags: architecture, devops, api, security
canonical_url: https://blog.mvpfactory.co/claude-md-best-practices-8-patterns-that-work
---
## What we are building
By the end of this tutorial, you will have a production-grade CLAUDE.md setup across your repository — a concise root file, scoped local context, reusable skills, deterministic hooks, and ADR-backed architectural documentation. Let me show you the 8 patterns I use in every project.
## Prerequisites
- A repository with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) initialized
- Basic familiarity with how Claude Code reads `CLAUDE.md` files
- A `.claude/settings.json` in your project (we will create one below)
## Step by step
### 1. Keep your root CLAUDE.md short and high-signal
Your root `CLAUDE.md` is not onboarding docs. It is a cheat sheet — build commands, critical invariants, the one thing that breaks if you forget it. Keep it under 200 lines.
| Approach | Token cost | Signal quality | Result |
|---|---|---|---|
| Full knowledge dump (2,000+ lines) | High | Low — buried in noise | Claude ignores critical rules |
| Concise repo memory (50–150 lines) | Low | High — every line matters | Claude follows conventions reliably |
### 2. Encapsulate repeated workflows as skills
Instead of re-explaining your release process every session, define it once:
markdown
Example skill: /release
- Run
./scripts/version-bump.sh - Update CHANGELOG.md with conventional commits since last tag
- Create PR targeting main with title "release: vX.Y.Z"
Short, declarative skills outperform verbose ones. A 10-line skill that says *what* to do beats a 50-line skill that explains *how* each step works internally.
### 3. Use hooks for deterministic actions — not memory
If an action must *always* happen, do not rely on `CLAUDE.md`. Use hooks. Memory is probabilistic; hooks are deterministic.
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"command": "echo 'Editing file: $CLAUDE_FILE'"
}
],
"PostToolUse": [
{
"matcher": "Write",
"command": "npx prettier --write $CLAUDE_FILE"
}
]
}
}
A line in `CLAUDE.md` saying "always run prettier" will be forgotten halfway through a long session. A hook will not. Here is the minimal setup to get this working — drop that JSON into `.claude/settings.json` and you are done.
### 4. Progressive disclosure — point, don't dump
Instead of inlining your entire auth architecture, point to it:
markdown
Architecture decisions
- Auth flow: see docs/adr/003-auth-strategy.md
- Database sharding: see docs/adr/007-sharding.md
- API versioning: see docs/adr/012-api-versions.md
Claude reads these files *when it needs them*. Your root context stays lean.
### 5. Place local CLAUDE.md files in sensitive directories
markdown
infra/CLAUDE.md
- NEVER modify terraform state files directly
- All changes require plan output review before apply
- Cost tags are mandatory on every resource
The auth module almost always needs stricter guardrails than the rest of the app. Scope your rules accordingly.
### 6. Keep context lean and navigable
Clear folder names help Claude the same way they help a new hire:
plaintext
After: navigable structure
src/
payments/
payment-validator.ts
payment-service.ts
payment-utils.ts
notifications/
notification-sender.ts
When Claude sees `payments/payment-service.ts`, it already knows scope and responsibility before reading a single line.
### 7. Version your CLAUDE.md alongside code
Add "update CLAUDE.md" to your PR checklist, right next to "update tests." A stale `CLAUDE.md` is worse than none — it actively misleads. The docs do not mention this, but drift between your architecture and your `CLAUDE.md` is the single fastest way to get Claude fighting your patterns instead of extending them.
### 8. Document the WHY in ADRs
markdown
ADR-005: gRPC for internal services
Status: Accepted
Context: Inter-service latency exceeded 200ms p99 under load
Decision: Migrate internal APIs from REST to gRPC
Consequence: Significant throughput improvement, but added protobuf compilation step
Without this, Claude sees gRPC and may suggest REST "for simplicity." With the ADR in place, it respects the decision and works within the constraint.
## Gotchas
- **"Always do X" in CLAUDE.md is unreliable.** If it must happen every time, it belongs in a hook, not in memory. Convert your top 3 "always" instructions to hooks today.
- **Over-stuffing the root file.** Once you cross 200 lines, signal degrades fast. Extract detail into ADRs and local context files.
- **Forgetting local CLAUDE.md scope.** Local files override or extend the root — they do not replace it. Make sure your root invariants still apply.
- **Stale CLAUDE.md after refactors.** This one will save you hours: if you rename a module or change a convention, update `CLAUDE.md` in the same PR. Not later. Not in a follow-up ticket. The same PR.
## Conclusion
Here is the gotcha that will save you hours: Claude Code does not need to know everything about your codebase. It needs the *right things at the right time*. These 8 patterns — concise root files, skills, hooks, progressive disclosure, local context, lean structure, versioned config, and ADRs — give you exactly that.
Start by auditing your root `CLAUDE.md`, converting your top 3 repeated workflows into skills, and replacing every "always do X" instruction with a hook. Speaking of good habits — I keep [HealthyDesk](https://play.google.com/store/apps/details?id=com.healthydesk) running during long pairing sessions with Claude Code because it is easy to lose two hours without moving; the break reminders and desk exercises are a small thing that compounds.
Check the [official Claude Code docs](https://docs.anthropic.com/en/docs/claude-code) for the latest hook schema and configuration format. Now go make your repo memory work *for* you.
Top comments (0)