CLAUDE.md Best Practices: A Practical Template for Real Claude Code Projects

CLAUDE.md is the file that prevents you from explaining the same project facts in every Claude Code session. It is not magic, and it is not a policy engine.

The useful mental model is simple: CLAUDE.md is persistent guidance loaded into context. It helps Claude behave consistently, but it does not enforce security boundaries. Enforced behavior belongs in settings, permissions, and hooks.

This guide gives you a copy-paste template, a small team workflow, three practical use cases, and the failure cases that make many CLAUDE.md files quietly harmful.

First Principle: CLAUDE.md Is Guidance, Not Enforcement

The official docs separate CLAUDE.md from auto memory, settings, and hooks. CLAUDE.md contains human-written instructions. Auto memory stores local learnings. Settings and permissions configure client behavior. Hooks execute commands at lifecycle events. Mixing these layers is the fastest way to create a file that looks helpful but fails under pressure.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to Put CLAUDE.md Files

Claude Code reads CLAUDE.md and CLAUDE.local.md files from the working directory upward. Project-root files are available from the start of the session. Nested files are added when Claude reads files in that subtree. Put team rules at the repo root, personal preferences in CLAUDE.local.md, and package-specific details close to the code they affect.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What Belongs in Always-Loaded Memory

Keep only facts that are valuable in almost every session: build commands, test commands, architectural boundaries, naming rules, forbidden patterns, and review gates. Keep long debates, historical logs, secrets, one-off task plans, and full specification dumps out of always-loaded memory.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-Paste CLAUDE.md Template

The following template is deliberately short. It gives Claude enough structure to act well without turning startup context into a knowledge landfill.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use Imports and .claude/rules/ Carefully

Imports with @path/to/file are useful for organization, not for token savings. Imported files still enter context at launch. When instructions grow, first delete stale content; then move path-specific instructions into .claude/rules/ so they load only when relevant.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three Real Use Cases

1. For onboarding, document the project map and verification commands rather than every setup detail. A new teammate needs the shape of the system and the safety checks.
2. For bug fixing, include reproduction commands, log locations, and the minimum test command. Claude spends less context on wandering and more on narrowing the defect.
3. For content and knowledge workflows, keep publishing rules, tone, internal-link requirements, and quality gates in CLAUDE.md. Keep long research notes in Obsidian or regular docs.

Failure Cases and Pitfalls

1. Failure 1: importing every README and meeting note. Fix it by keeping five always-needed lines in CLAUDE.md and letting Claude read details on demand.
2. Failure 2: writing vague rules such as “write good code.” Fix it with verifiable rules such as npm run lint, src/api/**, or “no default exports.”
3. Failure 3: placing hard security rules only in CLAUDE.md. Fix it with permissions and PreToolUse hooks, because CLAUDE.md guidance is not an enforcement layer.

Team Maintenance Rule

Treat CLAUDE.md as a living project contract. Update it when Claude repeats the same mistake, when reviews repeat the same comment, when a command changes, or when a new architectural boundary matters to every future task.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

What to Read Next

For the knowledge-workflow side, read Claude Code and Obsidian integration. For daily operating habits, use Claude Code productivity tips. For safer automation, pair this with Claude Code permissions guide. Team rollout help is available on the training and consultation page.

What I Verified for This Article

For this update I checked the current Claude Code memory, context window, settings, and commands docs. The article now treats CLAUDE.md as guidance rather than enforcement and keeps the template short enough to be useful in real repositories. Official references: memory, context window, settings, and commands.