Ada → What is CLAUDE.md

CLAUDE.md: the file Claude Code reads on every turn

Not at session start. On every message turn. Whatever is in this file shapes every decision Claude Code makes, for the entire session.

What CLAUDE.md actually is

CLAUDE.md is a plain markdown file that lives in your project root. Claude Code detects it and reads it on every message turn — injecting its contents into the context window before processing your request.

That last part is worth repeating: on every message turn, not just once at the start of the session. Every time you send a message, the contents of CLAUDE.md are included in what Claude Code reads before it responds.

This means CLAUDE.md is not a note to yourself. It is an active constraint layer — present at every decision point, shaping every action Claude Code takes.

A common misconception: "Claude Code reads CLAUDE.md at session start." The reality: CLAUDE.md is injected on every context window — throughout the entire session, for every message. Its weight in your token budget is paid repeatedly, which is why what you put in it matters.

What should go in CLAUDE.md

Because CLAUDE.md is read on every turn, it should contain only what needs to be true on every turn. That means structural facts — not implementation details.

Include

  • What the project is — and what it is not
  • Architectural decisions that have been made
  • Technology constraints (what you won't use)
  • Scope boundaries (what is out of scope)
  • Bounded context definitions
  • Naming conventions and vocabulary
  • Invariants that must always hold

Do not include

  • Current task lists or in-progress work
  • Implementation details that change
  • Generic instructions ("be helpful")
  • Session-specific context
  • Anything that should live in an agent file instead
  • Descriptions of what you're working on right now

The token cost of CLAUDE.md is paid on every turn. Keep it dense with signal — not padded with content that's only relevant sometimes.

What a good CLAUDE.md looks like

The defining quality of a well-written CLAUDE.md is that every line constrains something. If a line could be removed without changing Claude Code's behavior, it shouldn't be there.

CLAUDE.md — example
# Analytics Dashboard
What this project is:
A self-hosted web analytics dashboard. Privacy-first.
No cookies. Tracks pageviews, unique visitors, referrers.
What it is not:
Not a marketing platform. Not a cookie-based tracker.
Not a SaaS product — single-tenant only.
Constraints that apply:
No third-party analytics scripts.
Data stays on the server. No external egress.
SQLite only. No managed database services.
Architecture decisions (final):
Server-rendered. No client-side framework.
File-based routing. Minimal JavaScript.

Every line here is a constraint. None of it is aspirational. Claude Code reads it on every turn and cannot build outside it.

The problem: writing CLAUDE.md by hand

Writing CLAUDE.md manually has a structural problem: you're writing constraints from memory, not from an explicit formalization of your intent.

You'll include what you thought of. You'll miss what you assumed was obvious. The "what it is not" section — the most important one — is the hardest to write without a structured process to surface it.

And when Claude Code builds something wrong, you update CLAUDE.md reactively. You're capturing drift after it happened, not preventing it before building starts.

Ada solves this by running structured elicitation before compilation. The questions Ada asks are specifically designed to surface the constraints, scope boundaries, and "what it is not" decisions that are hardest to write without a process. The resulting CLAUDE.md traces every constraint back to something you explicitly stated.

How Ada produces CLAUDE.md →
$ git clone https://github.com/alexrozex/ada

Ada produces CLAUDE.md from structured elicitation — every constraint traced to intent.

Get started →