AI-Native Development, Part 1: A CLAUDE.md for Every Module

In short: CLAUDE.md is the standing brief Claude Code reads before it touches your code. One file at the root isn't enough. Put a short one in every module or feature folder, so the right rules appear at the right time.

Why It Matters

Without a brief, the AI guesses your conventions, your business rules and which code is dangerous, and it guesses confidently. CLAUDE.md turns those guesses into written instructions.

That is what makes AI-native development both efficient and effective. It gets faster because you stop re-explaining the same rules in every prompt. It gets safer because the rules sit in front of the model every time.

One caveat: CLAUDE.md is context, and nothing enforces it. Claude reads it and usually follows it, but nothing blocks a violation. Critical rules still need tests behind them, which is a later part of this series.

How Claude Uses It

• At session start, it loads every CLAUDE.md from the folder you launched in, up through its parent folders to the root.
• When it reads or edits files in a subfolder, it also loads that folder's CLAUDE.md.

Broad rules are always loaded. Narrow rules load only when the work reaches them. That keeps the context small, and the context is what you are paying for in both speed and accuracy.

A Three-Level Layout

I work on a multi-repo travel platform: a backend API, an internal staff console and a public-facing website. Each repo has its own CLAUDE.md, and the folders inside have more:

workspace/
  CLAUDE.md                      how the projects connect
  backend-api/
    CLAUDE.md                    stack, auth, conventions
    src/modules/
      payment/CLAUDE.md          one per domain
      upload/CLAUDE.md
  staff-console/
    CLAUDE.md
    src/features/
      bookings/CLAUDE.md
  public-website/
    CLAUDE.md
    src/features/...

The workspace file is the one that no single repo can write. It says which service is the real backend, which flows deliberately bypass it, and where a stale duplicate implementation is sitting. A model that only sees one folder will confidently assume the wrong thing is the current one. A CLAUDE.md can say "ignore this" as usefully as it says "do this".

What Goes in a Module File

The headings are the same in every API module, so both people and Claude know where to look:

# modules/payment
## Purpose                        what this module owns
## Key Files                      where things live
## Business Rules                 what the code can't tell you
## Patterns Claude Must Follow    hard rules
## Known Issues / Notes           weak spots, stated honestly

The API files also carry sections for the database models a module owns, its external dependencies, its endpoints and its error handling.

Business Rules and the hard-rules section matter most, because the code shows what happens and never why. In the payment module, for instance, cancelling a certain kind of payment reverses one running total but deliberately leaves a related status field alone. That is an intentional asymmetry the business depends on. Without the word "intentional" written next to it, a helpful model will quietly "fix" it.

Why One File Per Module

Relevance. Context is finite, and payment rules are noise while you work on uploads. Module files load only when the work reaches that module.

Same diff as the code. The payment file's history reads as a list of feature commits, not documentation commits. A reviewer sees the code and the rules change together, instead of finding out later that the docs drifted.

Both sides of a contract. A frontend feature file can point to the API module it maps to and say that the backend is the source of truth. When Claude works on a screen, it knows which side makes the real decision.

The Payoff

The payment file says never to change a payment's status outside the webhook service or the manual confirm path. A model asked to "mark it paid when the customer returns to the site" would otherwise write a status update in a controller. That works in a demo and breaks accounting in production. With the rule in the file, it is the one specific thing the model already knows not to do.

The upload file says to add any new upload reference to a central list, or a nightly cleanup job deletes files that are still in use. A rule in a markdown file is still only guidance, so a unit test compares that list with the database schema and fails CI when they differ. The rule helps Claude get it right the first time. The test catches the miss when someone, human or AI, ignores it.

Keeping It Healthy

• Keep files short. Claude Code's own guidance is to aim for under about 200 lines per file. Longer files cost more context every session and make individual rules easier to lose. Some of ours grew past that, so we moved the detailed coding conventions into skills that load on demand and left CLAUDE.md as a short index.
• Review changes in pull requests, like code. A stale line is worse than a missing one, because the AI plans around it with full confidence. While writing this post I found a line describing a git hook that no longer matched what the hook does.
• After every AI mistake, add the rule that would have prevented it. That is where most of our hard-rules sections came from.

If You Want to Try This

• Start with one root file: the stack, how to run things, a handful of real rules.
• Add module files as you actually touch each module, not all of them on day one.
• Use the same headings in every module file.
• Back every genuinely dangerous rule with a test or a hook.

The takeaway: put the rule next to the code it protects, and back the dangerous ones with a test.