architecture-understanding — Claude Code rule: what it does
The architecture-understanding rule has the agent read docs/architecture.md and check code changes against its architecture. Use it when a project documents its design in a Mermaid diagram.
no license ★ 1,054 updated 2025-07-17
.cursor/rules/architecture-understanding.mdcWhat architecture-understanding does
The agent parses the Mermaid diagram in docs/architecture.md to identify module boundaries, relationships, data flows, interfaces, and dependencies. It then checks proposed changes against the documented constraints and separation of concerns.
If the file is missing, the agent stops and alerts the user. A diagram it cannot parse prompts a request for clarification; an architectural violation triggers a warning. The rule’s core check depends on docs/architecture.md being present.
For Claude Code, put the rule at .claude/rules/architecture-understanding.md. Cline uses .clinerules/architecture-understanding.md.
What it helps with
- parse a project’s Mermaid architecture diagram
- identify module boundaries and dependencies
- trace data flows and system interfaces
- check code changes against architecture constraints
- keep new code within defined component boundaries
Example prompts for the agent
- Read
docs/architecture.mdand explain how the project modules relate to one another. - Check this change against the architecture documented in
docs/architecture.md. - Review whether the new code preserves the separation of concerns in the architecture.
How to install architecture-understanding
Manually: put the files in place
.cursor/rules/architecture-understanding.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.claude/rules/architecture-understanding.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/architecture-understanding.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/architecture-understanding.mdManually: put the files in place
.clinerules/architecture-understanding.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about architecture-understanding
How do I install architecture-understanding in Claude Code?
Save the rule at .claude/rules/architecture-understanding.md.
What does architecture-understanding do?
It guides the agent through the Mermaid diagram in docs/architecture.md and checks changes against the documented architecture.
What happens if the Mermaid diagram cannot be parsed?
The agent asks for clarification. If docs/architecture.md is missing, it stops and notifies the user.