Design CLAUDE.md, Scoped Rules, and Memory That Improve Every Session
Create concise CLAUDE.md instructions, path-scoped rules, imports, and durable memory without bloating Claude Code's context.
Design CLAUDE.md, Scoped Rules, and Memory That Improve Every Session
Quick answer
CLAUDE.md is durable project context loaded into Claude Code sessions. Keep it short, concrete, and testable: commands, architecture boundaries, non-obvious conventions, and safety rules. Move specialized workflows into skills and path-specific instructions into .claude/rules/. The official memory guide documents the hierarchy and imports.
A production-ready starting point
# Project contract
## Commands
- Install: `pnpm install --frozen-lockfile`
- Focused test: `pnpm test -- <path>`
- Full verification: `pnpm lint && pnpm typecheck && pnpm test`
## Architecture
- `apps/web` may depend on `packages/domain`; the domain package must not import UI code.
- Database access goes through `packages/data`. Do not query from route handlers.
## Working rules
- Preserve public API compatibility unless the task explicitly changes it.
- Add a regression test before fixing a reported defect.
- Never edit generated files under `src/generated`; run `pnpm generate`.
- Never commit `.env*`, credentials, production data, or local debug artifacts.
## Handoff
- Report changed files, verification commands/results, and unresolved risk.
Every line should change behavior. “Write high-quality code” wastes context because it is not actionable.
Scope instructions instead of growing one file
Use .claude/rules/ for topic or path-specific policy. For example, a frontend rule can apply to apps/web/**/*, while migration instructions apply only to db/migrations/**/*. This prevents backend tasks from paying the context cost of UI rules.
Use imports when a maintained document already contains the source of truth:
@README.md
@docs/architecture/decision-records.md
Import selectively. A 200-page handbook is not a good always-on dependency.
CLAUDE.md vs memory vs skill
| Mechanism | Use it for | Avoid |
|---|---|---|
CLAUDE.md | Always-relevant project contract | Tutorials and large references |
| Scoped rule | Instructions for certain paths | Global commands |
| Auto memory | Useful learned facts/preferences | Security policy or changing release state |
| Skill | Repeatable workflow or reference | Mandatory rule that must always apply |
| Hook | Deterministic enforcement | Nuanced engineering judgment |
Auto memory is helpful but should not be the sole home for critical rules. Review saved memory and remove stale facts.
Test the instruction file
Open a fresh session and ask:
Without editing, tell me the correct focused-test command, which files are
generated, and the dependency boundary for the domain package. Cite the
instruction source for each answer.
Then give a small task that crosses a rule. If Claude violates it, make the rule more specific—not more emphatic.
Maintenance discipline
- Delete rules the code or tooling now makes obvious.
- Replace prose with a command or link to the canonical source.
- Add the reason for surprising constraints.
- Review after architecture or tooling changes.
- Keep secrets and personal data out of instruction files.
FAQ
Where should CLAUDE.md live?
Repository-level instructions belong at the project root. Claude Code also supports user and managed instruction scopes; choose the narrowest scope that matches ownership.
Why is my CLAUDE.md ignored?
The rule may be vague, contradicted by a higher-priority instruction, outside the active scope, or lost in excessive context. Ask Claude which instruction sources loaded.
How long should CLAUDE.md be?
There is no universal line limit. Optimize for behavior-changing density. If a section is not relevant to most sessions, move it to a rule or skill.