CLAUDE.md and agent briefs

A CLAUDE.md CLAUDE.md A CLAUDE.md file is a project instruction file that tells Claude Code how the codebase works, what rules to preserve, and how to verify changes. Open full term file is the first durable artifact most non-engineers need when they start building with Claude Code. It is also the artifact that gets the most attention right now and the least useful guidance.

This page is the reference version. The narrative version is at /blog/non-coders-claude-md, where we walk through 64 real CLAUDE.md files from public repos and the four sections engineers leave out across almost all of them. This page is what to look at when you are sitting down to write or revise yours.

We use the term standing brief Standing brief A standing brief is the permanent product document that sits at the root of an AI-assisted project. It tells the model what the product is, what it must never do, what specific words mean, and how to verify any change. Open full term through the rest of this page in place of “CLAUDE.md.” Mechanically the file is the same: markdown at the root of your project, read by the model at the start of each session. The framing is different. A standing brief is a permanent product document, not a programmer’s checklist.

The seven canonical sections

Across 64 real CLAUDE.md files we read in May 2026 (the corpus included Next.js, bun, deno, zed, Apache Airflow, Anthropic’s own cookbook, the official Model Context Protocol SDKs, plus a random sample of smaller projects), seven sections emerge as the de-facto template.

• Project overview: what the product is. Present in 42% of files.
• Architecture: how the code is laid out. 64%.
• Commands you run: build, test, lint, dev server. 66%.
• Code style and conventions: 41%.
• Workflow: branches, PRs, deploys. 42%.
• Testing: 27% as a named section, referenced in 72% of files somewhere.
• Tech stack: 27%.

If you have an engineer on the team, those seven sections are the file. If you are writing one yourself as a non-engineer, the math is harder.

Which sections you can author

Of the seven, only one is something a non-engineer can write with full authority.

Project overview. Yes. Engineers consistently under-write this section. The overview is what the product does, who uses it, and the one job it must do well. If you decided what the product is, you are the right author of this section.

Architecture. Not authoritatively. Defer to an engineer or let the model infer from the codebase. If you do write a version, keep it conceptual: how the pieces fit at a product level, not what each folder contains.

Commands. No. This is shell knowledge. Skip the section or let the engineer fill it in.

Code style. No. Defer to an existing style guide. Most projects don’t need a custom one.

Workflow. No. Same.

Testing. Partial. You cannot write a pytest invocation. You can write what should be true of the product after a change. That non-engineer version is often more useful than the engineer’s ## Testing block, because it captures product-level expectations the test suite alone wouldn’t catch.

Tech stack. No, and it does not matter. The model can read your package.json.

One section out of seven. The reason non-engineer CLAUDE.md files often read like apologies is that the writer tried to fill all seven and ran out of authority at section three.

The four sections engineers leave out

The four sections below were missing from essentially all 64 of the files we read. They are also the sections a non-engineer can author with the most authority.

1. Vocabulary

Zero of the 64 files we read had a vocabulary section.

This is the cleanest gap in the corpus. Even repositories that name internal abstractions (Zed talks about “Entities,” “Actions,” “Elements,” and “Notify” without defining them; bun talks about a custom runtime model) never write down what these words mean inside the project.

A vocabulary section names the product-specific words that mean something specific inside this codebase. What “lead” means in this CRM. What “open” means versus “in progress.” What counts as “done.” The engineer wrote the code that handles a Lead. You decided what makes a Lead a Lead. Write that down. The model would otherwise invent it across sessions.

A useful vocabulary section is 6 to 12 entries. Each is one line: the term in bold, then the specific meaning. Cross-reference where the term lives (Airtable column, status flag, screen name).

2. Decisions we’ve made

The “decisions” section captures product calls that are already settled. Things you tried and abandoned. Tools you chose for reasons that aren’t in the code.

Engineers do have a version of this: the “Architecture Decision Record.” Only one of the 64 files we read carries one (vercel/ai). The engineer’s version focuses on stack and architecture choices. The non-engineer’s version focuses on product decisions and is harder to write because it requires admitting things that didn’t work.

The shape: bullet list, 4 to 10 entries. Each one names a thing you tried, why it failed, and the instruction to not bring it back. The instruction matters. Without it the model will helpfully suggest the thing you already ruled out.

3. What this product is not

The scope-defending section. Engineers don’t write it because they’re inside the system. You should write it because you’re the one who watches scope drift week to week.

This is where the standing brief stops feature creep. Each bullet starts with “Not.” Not a CRM. Not a dashboard. Not multi-team. Not a sender. The negative space defines the product as clearly as any positive description, and the model can read it before it suggests an unrelated feature.

A useful “what this is not” section is 3 to 6 lines. Resist longer.

4. The standing check

The standing check Standing check A standing check is a short self-audit list a coding agent runs through before claiming a change is done. It pairs with the standing brief: the brief tells the model what's true, the check tells the model what to verify before reporting back. Open full term is a self-audit list the model runs through before it claims a change is done.

Two repos out of 64 carry something like it. oven-sh/bun calls it “Code Review Self-Check.” zed-industries/zed calls it “After any agentic session.” Neither has a shared name. We use “standing check” so the pair (standing brief, standing check) is easy to remember.

The structure is four to six numbered questions:

1. Did you change anything not strictly needed for the request? If yes, list it.
2. Did you read the standing brief before editing? If no, read it now.
3. Which of the product-level checks does this change affect?
4. Did you violate anything in “Decisions we’ve made”? If yes, stop and ask.

The standing check goes at the end of the file so the model encounters it last, sitting in context as it starts writing back to you.

The smallest useful version

If you write only four sections, write these:

# CLAUDE.md

## Project overview
One paragraph: what this is, who uses it, the one job it must do well.

## Vocabulary
- **Term**: what it specifically means inside this product.
- ...

## Decisions we've made
- We tried X. It failed because Y. Don't bring it back.
- ...

## What this product is not
- Not a Z.
- ...

## Before you finish (the standing check)
1. Did you change anything not asked for?
2. Did you read this file before editing?
3. Which of the product-level checks does this change affect?
4. Did you violate "Decisions we've made"?

Add a “Commands” section when you have an engineer who can fill it. Add a “Testing” section when you can describe what should be true of the product after a change. Skip the rest until the project needs them.

What to read next

• The narrative essay version of this page: /blog/non-coders-claude-md. Read this first if you have not.
• The companion pillar on agent direction: /learn/directing-ai-agents.
• The companion essay on verifying the work after any change: /blog/non-coders-verification-ladder.

If you want a workshop instructor in the room while you write your first standing brief, the Saturday workshop covers exactly this.