CLAUDE.md examples for architecture rules

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.