---
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:

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.

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:

Claude reads these files *when it needs them*. Your root context stays lean.

### 5. Place local CLAUDE.md files in sensitive directories

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:

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

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.