The Project Brief Every AI Coding Session Should Read First

Every AI coding assistant starts a session with the same handicap: it knows nothing about your project except what you tell it, and it has to be told again every single time. The usual fix is to keep typing the same three paragraphs into chat — "we use Postgres, not Mongo," "don't touch the payment module," "the docs are out of date, trust the code" — until, a few sessions in, you write it down instead. That written-down version is the project brief, and how you structure it decides whether it actually gets read or just becomes one more stale file in the repo.

This isn't the same problem as remembering what happened last Tuesday. A brief answers "what is this project and what are its rules," and that answer barely changes week to week. A decision log or a current-state file answers "what's true right now," and that changes constantly. Conflating the two is why so many of these files rot — the stable parts get buried under status updates, or the status updates never get written because editing the stable document feels like too much ceremony. Keep the brief to what's actually fixed, and it stays short enough that an assistant — and a new teammate — will actually read the whole thing.

What a Brief Is For, and What It Isn't

Think of the brief as the answer to a question a new hire would ask on day one, before they've read a line of code: what is this, what can't change, what will get someone fired if they do it, and what should I believe when the code and the docs disagree. That's a small, stable set of facts. It is not a running journal, and it is not a place to record that you migrated from Redis to Postgres-backed sessions last month — that belongs in an append-only decision log that changes with the project, not in a document meant to be read cold at the start of every session.

Anthropic's own guidance for CLAUDE.md, the file Claude Code loads automatically at the start of every session, makes the same point from the tooling side: instructions delivered as a user message compete for attention with everything else in the context window, and "the more specific and concise your instructions, the more consistently Claude follows them." Anthropic recommends keeping a single CLAUDE.md under roughly 200 lines for this reason — past that point, adherence measurably drops. The open, tool-agnostic AGENTS.md convention lands on a similar number from the opposite direction, with community guidance suggesting 150 lines or fewer and a rule of thumb that if your context file is longer than your README, it's already too long. A one-page brief isn't a stylistic preference — it's close to the practical ceiling for how much an assistant reliably absorbs before it starts skimming.

Note: A brief and a project's ongoing memory system aren't competitors — they're two different documents doing two different jobs. If you're building both, our companion piece on project memory for AI coding assistants covers the append-only decision log and status-marker system that the brief deliberately leaves out.

The Five Things a Good Brief Actually Needs

Every brief we've built that survived more than a month has the same five sections, in roughly this order. Skip a section if it genuinely doesn't apply — don't pad it out to look complete.

1. What This Is

Three sentences, no more: what the project does, who uses it, and what stage it's at. This exists to stop an assistant from guessing scope. A prototype and a production billing system need very different levels of caution around the same kind of change, and nothing else in the brief communicates that if this section doesn't.

Internal tool for the claims team to reconcile daily payment
batches against the processor's settlement file. Used by ~12
people, three times a day. In active development — expect
schema changes weekly until the Q4 freeze.

2. Fixed Constraints

The settled decisions: framework, database, language version, deployment target — the things that would require a real conversation to change, not a pull request. A table works better here than prose, because an assistant (and a skimming teammate) can scan it in seconds instead of parsing sentences for the one fact they need.

The "why" column earns its place. A rule without a reason invites someone — human or AI — to "fix" it the first time it looks inconvenient. A rule with a reason attached at least gets argued with on the merits.

3. Absolute Rules

Not style preferences — prohibitions, usually written after something already went wrong once. Keep this list short enough to actually be absolute; a rule that's really "prefer X" doesn't belong next to "never commit secrets."

- Never commit anything under /secrets or matching *.pem
- Never run a destructive migration without a fresh backup first
- Never modify /vendor — it's a pinned third-party checkout
- Never touch the payment reconciliation logic without a
  second human review, even if tests pass

Tip: If you're maintaining both a brief and an AGENTS.md, the community convention there calls this the "Do Not Modify" section and treats it as one of the highest-value parts of the whole file. It's worth keeping that exact framing — "never modify these paths" reads unambiguously in a way "be careful with these paths" doesn't.

4. Truth Verification

One short, blunt statement: when the code and the documentation disagree, which one wins. This sounds obvious until you watch an assistant "fix" perfectly working code to match a comment or a README section that was aspirational the day someone wrote it and never touched again. That's not a hypothetical failure mode — it's the single most common way a stale document turns into a broken build, because the resulting diff looks intentional and confident, which is exactly what makes it slip through review.

Running code and passing tests outrank this document and every
comment in the codebase. If something here is wrong, fix this
file — do not change working code to match a stale description.

If your project also maintains a status-tracked state file — the kind covered in our companion piece — this is the section that says so, in one line, rather than trying to duplicate that file's content here.

5. Conventions

Only the patterns an assistant can't infer by reading the code — naming schemes, folder boundaries, or house rules that go against a framework's own defaults. Don't restate what's already obvious from the directory structure; that's exactly the kind of padding that pushes a one-page brief past the length where anyone still reads the whole thing.

- API handlers live in src/api/handlers/, one file per resource
- Error responses always use the shared ApiError shape, never
  a raw thrown Error
- Test files sit next to the code they test, not in a separate
  /tests tree

A Complete One-Page Example

Put together, the five sections read like this — short enough to fit on one screen, specific enough to actually change what an assistant does.

markdown

# Project Brief — Claims Reconciliation Tool

## What This Is
Internal tool for the claims team to reconcile daily payment
batches against the processor's settlement file. Used by ~12
people, three times a day. In active development.

## Fixed Constraints
| Constraint | Value | Why |
|---|---|---|
| Backend | Node 20, Express | Org-supported runtime |
| Database | Postgres 15 (RDS) | Existing backup tooling |
| Auth | Azure AD SSO | Compliance requirement |

## Absolute Rules
- Never commit anything under /secrets or *.pem
- Never run a migration without a fresh backup
- Never modify /vendor
- Never touch reconciliation logic without human review

## Truth Verification
Running code and passing tests outrank this document. Fix this
file if it's wrong — never change working code to match it.

## Conventions
- API handlers: src/api/handlers/, one file per resource
- Errors always use the shared ApiError shape
- Tests live next to the code they test

That's roughly 40 lines. It fits comfortably inside the length budget both Anthropic's CLAUDE.md guidance and the AGENTS.md convention recommend, with room to spare for whatever's genuinely specific to your project.

Where the Brief Actually Lives

The brief doesn't need a bespoke filename or a new convention to invent. In Claude Code, it's the natural content of a project's CLAUDE.md — the file every session loads automatically, which you can bootstrap by running /init against your codebase and then trimming to just what the tool couldn't infer on its own. Anthropic's current guidance is explicit that /init should generate a starting point, not the final document: refine it down to instructions "Claude wouldn't discover on its own," since anything derivable from the code itself is exactly the padding that makes a brief too long to be read reliably.

If you're supporting more than one assistant — Cursor, Copilot, Codex, Gemini CLI — put the brief in AGENTS.md instead, since that's the closest thing this space has to a shared convention, and have CLAUDE.md import it with a single @AGENTS.md line rather than maintaining two copies that will drift apart. Claude Code reads that import automatically and lets you append anything Claude-specific below it. The mechanics of exactly which file loads for which tool, and in what order, are covered in more depth in our companion article on project memory — this piece is deliberately about what goes inside the file, not the plumbing that loads it.

Common Mistakes

Writing a README instead of a brief. A README explains the project to a new human joining once. A brief exists to change what an assistant does on every single session — narrower job, and it shows in what belongs in each.

Letting the brief absorb the decision log. The moment "what's fixed" starts including "we tried Redis and reverted it in July," the document stops being something anyone reads end to end. Decisions belong in a separate, append-only file.

Skipping the "why" on fixed constraints. An unexplained rule reads as arbitrary, and arbitrary rules are the ones that get quietly worked around the first time they're inconvenient.

Treating "absolute rules" as a style guide. If a rule is really a preference — "prefer async/await over .then() chains" — it dilutes the rules that actually matter. Keep this section for things that are genuinely never acceptable.

Never updating it. A brief that says "in active development" eighteen months after shipping to production is actively misleading, not just outdated. Update it as part of finishing whatever changed the constraint — not as a separate cleanup task nobody schedules.

Keeping It Honest

A brief only earns the "read this first" position if it stays short and stays current — the two properties pull against each other unless updating it is cheap. The way to keep it cheap is the same discipline good comments follow: change the brief in the same commit or pull request that changes the fact it describes. If a migration to a new database is what made "Postgres 15" true, that line updates in the same review, not in a follow-up ticket that may or may not get picked up. Treat the brief as part of the change, not documentation about the change, and it stops being the thing that's always six weeks behind reality.

Frequently Asked Questions

How is this different from a CLAUDE.md or AGENTS.md file?

It isn't a different file — it's what should be inside one. CLAUDE.md and AGENTS.md are the delivery mechanism a given tool loads automatically; the brief is the content strategy for what you put there so the file stays short and gets followed.

Should the brief include setup or installation instructions?

Only if an assistant genuinely can't derive them from package.json, a Makefile, or an existing setup script. If a human would run npm install && npm run dev, an assistant can usually find that too — spend the brief's limited space on what isn't already discoverable.

What if fixed constraints change?

Update the brief in the same change that makes the new constraint true, and treat the old row as gone, not struck through. Unlike a decision log, the brief isn't a historical record — it describes today, and the history of how you got there belongs in the append-only file instead.

Is one page really enough for a large, complex system?

For the brief, yes — deliberately. A large system needs more context overall, but that context belongs in path-scoped rules, a decision log, or a state file loaded only when relevant, not stuffed into the one document every session reads unconditionally. If the brief is growing past a page, that's usually a sign something in it belongs in a more targeted file instead.

The One Document Worth Getting Right

Most of what makes AI-assisted work reliable is unglamorous: write down the handful of things that are actually fixed, say plainly which source of truth wins when two documents disagree, and keep the whole thing short enough that it gets read instead of skimmed. None of that requires new tooling — it requires treating the brief as a first-class part of the codebase, updated in the same breath as whatever it describes, rather than a one-time onboarding artifact nobody revisits. An hour spent writing it is the cheapest fix available for the specific, expensive mistake of an assistant confidently building on something that stopped being true months ago.

Sources referenced:

• How Claude remembers your project — Claude Code documentation

• AGENTS.md — agents.md

• AGENTS.md Guide — AddyOsmani.com