Use CLAUDE.md for concise, scoped instructions about working in the repository and for a clear protocol to retrieve architecture decisions. Keep each decision's status, rationale, alternatives and consequences in a separate reviewed record so Claude Code receives current authority rather than a copied summary.
Separate working memory from decision history
Claude Code reads project memory to understand recurring instructions. That makes CLAUDE.md suitable for commands, conventions and a discovery protocol. It is less suitable as a growing archive of every architectural choice, because copied rules can become stale and lack explicit supersession.
An architecture-aware example
This pattern makes the decision check part of planning while preserving the common record as authority.
# Architecture workflow
Before proposing changes to data ownership, API compatibility, authentication or deletion:
- Search the repository decision record.
- Include matching decision IDs and statuses in the plan.
- Preserve accepted constraints unless the task explicitly includes superseding them.
- If records conflict or coverage is missing, stop and ask for a decision.Give rules observable consequences
If an architecture rule has a canonical test, name the command. If it is judgement-based, say that human review remains required. Do not imply that reading CLAUDE.md makes a constraint enforced; instruction following and deterministic verification are different controls.
- State the affected scope and exceptions.
- Link or query the authoritative decision instead of paraphrasing it.
- Name the validation command for objective constraints.
- Treat missing or superseded records explicitly.
Check for stale memory
Review CLAUDE.md whenever repository structure or canonical commands change. Architecture decisions should be maintained through their own lifecycle; the memory file usually needs only a stable route to them. Test the arrangement from a clean session rather than relying on an existing conversation.