Information Architecture for Rules

A CLAUDE.md file is not a README. It is not a knowledge dump. It is a set of operating instructions for an AI agent that reads top-to-bottom, assigns decreasing priority as it goes, and has a finite attention budget. Treating it like documentation — long, thorough, comprehensive — is the single most common mistake teams make.

The correct mental model is progressive disclosure. The first section answers: what is this project and what are the absolute rules? The second section answers: what does the tech stack look like and how do we build? The third section answers: what are the patterns, conventions, and gotchas that prevent recurring mistakes? Each section assumes the reader has absorbed everything above it. Each section is less critical than the one before it.

Structure your CLAUDE.md into five canonical sections, in this exact order. First: Project Identity — one paragraph describing what this project is, who it serves, and what makes it unusual. Second: Hard Rules — the NEVER and ALWAYS constraints that override all other behavior. Third: Build and Validation — the commands Claude needs to verify its own work. Fourth: Architecture — file structure, key systems, routing, data flow. Fifth: Gotchas — the recurring mistakes, edge cases, and traps that have bitten the team before.

This ordering is not arbitrary. Identity gives Claude the mental model it needs to make judgment calls. Hard rules set the boundaries. Build commands enable self-verification. Architecture provides navigational context. Gotchas prevent known failure modes. Each section builds on the foundation laid by the sections above it.

Progressive disclosure applies within sections too. Inside your Architecture section, lead with the routing table — the single most referenced piece of information in any web project. Follow it with key files. Then data flow. Then edge cases. Inside your Gotchas section, lead with the gotcha that has burned the team most recently. Recency correlates with relevance.

The test for whether your information architecture is correct: if Claude only reads the first 30 lines, does it have enough to avoid catastrophic mistakes? If it reads the first 100 lines, does it have enough to produce correct code for the most common tasks? If it reads the full file, does it have enough to handle edge cases? If the answer to any of these is no, your ordering is wrong.