CLAUDE.md provides persistent project instructions. Anthropic’s current documentation explicitly describes these instructions as context, not enforced configuration. Use them for stable facts and workflow; use settings, hooks, OS controls, and service authorization for hard boundaries.
Write Only Durable Context
Include:
- project purpose and architecture map;
- authoritative commands for test, lint, build, and formatting;
- file ownership and generated-file rules;
- coding conventions that are not discoverable;
- data/security constraints and prohibited areas;
- definition of done and escalation conditions.
Avoid secrets, long tutorials, temporary task notes, contradictory rules, and facts already obvious from the repository. Anthropic recommends concise, specific instructions; path-scoped rules or skills suit narrower procedures.
Make Rules Verifiable
Weak: Write good secure code.
Better:
- Validate API request bodies with schemas in src/schemas.
- Never log Authorization, cookies, OTPs, or payment payloads.
- Run npm test and npm run lint for src/** changes.
- Do not edit generated/**; run npm run generate after schema changes.
- Ask before database migrations or new dependencies.
If a repository uses AGENTS.md, current Claude documentation explains that CLAUDE.md can import it. Review imports so an untrusted repository cannot silently load unrelated local files.
Worked Example
A Karachi SaaS team’s 400-line instruction file contains outdated commands and style essays. They replace it with an 80-line root file: architecture, exact gates, generated boundaries, secrets, and migration policy. Frontend-specific rules move into a path-scoped file.
The team tests three representative tasks and uses /context or current equivalent to verify loading. A command-deny requirement is placed in enforced settings rather than relying on prose.
Failure Cases to Diagnose
- Instructions contain API keys: remove and rotate exposed values.
- Two nested files conflict: define ownership and remove drift.
- Every task procedure loads globally: move it to a skill or scoped rule.
- Hard prohibition exists only in Markdown: enforce it technically.
- File grows after every session: schedule pruning and source review.
- Imported path is outside trusted workspace: require explicit approval.
🇵🇰 Pakistan Angle
Document actual local commands, Windows/WSL differences, and PKT operational expectations if they affect development. Do not encode stereotypes such as assuming every Pakistani user prefers Roman Urdu; specify tested localization requirements.
Agency repositories should name client data boundaries and forbid copying production exports into prompts or fixtures. Keep client-specific rules in the client repository, not a personal global file that can leak context elsewhere.
Hands-On Exercise
- Draft a CLAUDE.md under 100 useful lines.
- Convert vague instructions into testable rules.
- Move one narrow procedure to scoped guidance.
- Enforce one hard boundary outside the file.
- Test loading and prune contradictions.
Completion Rubric
- Context is concise, stable, and repository-specific.
- Commands and boundaries are verifiable.
- Secrets and temporary notes are absent.
- Narrow rules load only when relevant.
- Hard restrictions have technical enforcement.
- Imports and nested instructions are reviewed.
Sources
Key takeaway: CLAUDE.md should be a concise project operating contract; it shapes behavior, while enforceable controls remain outside model context.