CLAUDE.md と .cursorrules に書く「アーキテクチャルール」完全ガイド——AIに設計を守らせる具体的な書き方 CLAUDE.md と .cursorrules に書く「アーキテクチャルール」完全ガイド——AIに設計を守らせる具体的な書き方

When developers begin using AI coding assistants such as Cursor, Claude Code, or GitHub Copilot, a common pattern emerges quickly: the generated code runs, but the underlying design becomes chaotic. Functions sprawl, naming conventions drift, layering collapses, and dependencies cross boundaries that a human reviewer would normally guard. Because these tools optimize for producing a working result, architecture often suffers unless the project explicitly constrains them. Configuration files like CLAUDE.md and .cursorrules are the practical mechanism for imposing those constraints, and understanding how to write them well has become an important skill for teams that ship AI-assisted code.

The core reason AI writes inconsistent code is that, by default, it lacks persistent context about a project's conventions. Each request is interpreted largely in isolation, so the model fills gaps with statistically common patterns rather than your repository's specific rules. CLAUDE.md, read by Claude Code, and .cursorrules, read by Cursor, act as standing instructions that the assistant loads alongside the prompt. They serve a similar purpose to a contributor guide, except the audience is a machine that will follow literal, well-scoped directives more reliably than vague aspirations.

Effective architecture rules tend to be concrete and testable rather than abstract. Instead of writing "keep the code clean," a rule should specify the layering model, such as separating domain logic, application services, and infrastructure, and state which directions dependencies may flow. Naming conventions, file organization, and module boundaries belong here too. Many teams document where new code should live, which patterns are mandatory, and which are forbidden. For example, a rule might forbid direct database calls from UI components, require repository interfaces, or insist that external API clients are wrapped behind an adapter. The more a rule reads like an enforceable constraint, the more consistently an assistant honors it.

Specificity in technical detail matters because AI generalizes. Stating preferred libraries, error-handling style, and testing expectations reduces drift. It helps to include short, canonical examples of "good" and "bad" code, since models follow demonstrated patterns closely. Some teams add explicit prohibitions, like avoiding global state, limiting file length, or banning certain dependencies, and pair each rule with a brief rationale so the assistant can apply judgment in edge cases. Keeping the file focused appears to work better than overloading it, because very long instruction sets can dilute attention and lead to inconsistent compliance.

These files fit into a broader ecosystem of agent configuration. .cursorrules has been Cursor's established convention, while the editor has been moving toward a structured .cursor/rules directory that allows scoped, multiple rule files. CLAUDE.md plays an equivalent role for Anthropic's command-line agent. GitHub Copilot offers repository custom instructions through its own configuration, and the industry is gradually converging on README-like, machine-readable guidance files. Although formats differ, the principle is shared: provide persistent project context so the assistant does not reinvent conventions on every request. Treating these files as living documents, versioned in the repository and reviewed like code, helps keep them aligned with the actual codebase.

There are limits worth acknowledging. Rules guide behavior but do not guarantee it, so they are best combined with conventional enforcement such as linters, type checkers, formatters, and CI checks that fail when boundaries are violated. Architecture tests that assert dependency directions can catch what an assistant misses. In this sense, CLAUDE.md and .cursorrules reduce the frequency of design problems rather than eliminate them, and human review remains the final safeguard. Overly rigid rules can also slow legitimate changes, so periodic pruning is advisable.

For teams adopting these practices, a reasonable starting point is documenting the existing architecture explicitly, codifying a handful of high-value constraints, and expanding only when recurring problems justify it. As AI tools take on more of the routine writing, the human contribution shifts toward defining and maintaining the rules that preserve coherence. The payoff is code that not only works but remains readable, modular, and maintainable, which is ultimately what keeps AI-assisted development sustainable over time.