I read 64 CLAUDE.md files. The most useful section was missing from all of them.

On Saturday morning, May 30, seven people opened a vibe coding tool in my workshop. Five of them were stuck before lunch. The one person who wasn’t had something the other six didn’t, and it had nothing to do with knowing how to code.

She had a file. One page of markdown at the root of her project. The model read it before it touched a line of her app. The file told the model what her product was, who used it, which decisions were locked, and how she would verify any change.

The rest of us were trying to do that work inside the prompt window. One frustrated retry at a time.

The wall

You know the wall already.

You’re 200 prompts deep. The app was supposed to take a Sunday. It has been four days. The signup form still does not email anyone. You paste the error into the chat. The tool apologizes and changes three files you did not ask about. You ask what it changed. It tells you what it usually tells you, which is not what changed.

Stack Overflow surveyed 49,000 developers in 2025. 33% said they trust the accuracy of AI-generated code. 46% actively distrust it. The number is bleak among the people who should be the easiest to convince.

You don’t have a model problem. You have a memory problem.

The rename, then the data

In April, Andrej Karpathy went on stage at Sequoia and renamed the category. He coined the phrase “vibe coding” eighteen months earlier and has stopped using it. He calls the thing “agentic engineering” now. The talk has 1.18 million views as I write this.

The line that made the rounds was about what programming actually is in 2026:

“What is the piece of text to copy-paste to your agent? That’s the programming paradigm now.”

A talk about programming where the headline move is “what’s in the text file.” I read that and wanted to know what the text file actually looks like in the wild.

So I pulled 64 of them. Every well-known project on GitHub that has a CLAUDE.md at the root of its repo. Next.js, bun, deno, zed, langchain, airflow, Anthropic’s own cookbook, the official Model Context Protocol SDKs, Supabase, DuckDB, plus a random sample of smaller repos. 64 files in total. The median is 6 KB and 168 lines.

The empirical canonical structure

Five sections appear in more than 40% of the files.

Project overview: 42% of files
Architecture: 64%
Commands you run: 66%
Code style and conventions: 41%
Workflow, meaning branches and PRs and deploys: 42%

Add two more bands and you get the de-facto seven: Testing (27%) and Tech stack (27%).

Anthropic’s own three-minute video on the file uses the same shape. Their worked example, verbatim:

This is a Next.js 15 app using the app router, Tailwind, and Drizzle ORM. Command: dev server, run tests, lint, code style, use two-space indentation, prefer named exports.

That paragraph is fine. It is also the part of the file most non-engineers cannot write. Tailwind, Drizzle ORM, named exports, two-space indentation. Each one is gatekeeping vocabulary. You either know what those words mean or the example is unusable as a model.

Of the seven canonical sections, exactly one is something a non-engineer can write with authority.

The objection

There is an objection waiting in the comment section under Karpathy’s talk and every “stop vibe coding” video orbiting it. The most-liked one, under the most-watched of them:

“Vibe coding is not for users without programming experience. The experienced programmer becomes the software architect.”

137 likes. The argument is that you have to already know how to code to direct an agent through anything serious.

That argument is mostly right and entirely the wrong move to make from it.

The seven sections don’t require programming experience equally. Five of them do. Two are mixed. The mistake the comment makes is treating the seven sections as one indivisible block.

If you are not an engineer, the answer is not to pretend you can write all seven. The answer is to skip the five engineers write better than you, and write the four sections engineers, by the empirical record, leave out.

The subtraction

The math, section by section.

You should write the project overview yourself. Engineers consistently under-write it, and the overview is what your product does, who uses it, and the one job it must do well. You know that better than the engineer ever will.

You should skip architecture, commands, code style, and workflow. Architecture defers to the engineer or to whatever the tool can infer from the code. Commands are shell knowledge. The style guide either exists already or does not need to. The workflow lives wherever your team’s PR conventions live. Four sections out, no loss.

Testing sits in the middle. You cannot write pnpm test, but you can describe what should be true of the product after any change, and the version of testing written that way is more useful than the engineer’s ## Testing block anyway.

Tech stack does not matter. The model can read your package.json.

One section of seven. The reason your prompts have been reading like apologies is that you have been trying to write all seven.

Stop. The file has another name in our workshops. We call it 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. A standing brief is a permanent product document, not a programmer’s checklist. From here this essay uses “standing brief,” because the framing change matters more than what Anthropic named the file.

What engineers leave out

I read 64 CLAUDE.md files. None of them had a glossary.

Not one. Even Zed’s CLAUDE.md, which talks for paragraphs about internal abstractions called Entities, Actions, Elements, and Notify, never defines what any of them mean. (I tried to figure out what Notify is from context. I still can’t tell you.) The reader is presumed to already know.

That is the cleanest finding in the corpus and the cleanest opening for the non-engineer. Four sections appear in essentially zero of the 64 files. They are the sections engineers leave open. They are also the sections a non-engineer can authoritatively own.

Vocabulary. The product-specific words that mean something specific. What “lead” means in your 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.

Decisions we’ve made. Product calls that are already settled. Things you tried and abandoned. Tools you chose for reasons that aren’t in the code. The engineer’s version of this is an “Architecture Decision Record.” Only one file in the 64 (vercel/ai) has one. The non-engineer’s version is shorter and harder: do not relitigate.

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 in real time.

The standing check. A short list the model runs through before it tells you a change is done. Two of the 64 files I read had something like this. oven-sh/bun calls it “Code Review Self-Check.” zed-industries/zed calls it “After any agentic session.” Neither has a shared name. We can give it one and use it everywhere.

Engineers tend to write the parts they can verify with a test or a build. The four sections above are the ones a non-engineer is in the best position to write, because you are the one who knows what the words mean, which decisions are settled, what the product is not, and how you intend to check the result.

The worked example

A standing brief written by someone who cannot code looks like this. The example is a composite, drawn from the half-dozen real ones I have watched workshop attendees write.

# CLAUDE.md (Outbound sales follow-up app)

## Project overview
A WhatsApp follow-up tracker for our outbound sales team.
Five users: me (Anna), three reps, one manager (Jordan). Internal.
Clients never see it.

We built it to replace a Google Sheet that drifted out of sync between
the reps. The one thing this product must do well is make sure no lead
is forgotten between Monday and Friday.

## What this product is not
- Not a CRM. We will not migrate Salesforce data into it.
- Not a sender. Reps message manually. The app only reminds.
- Not a dashboard. Jordan has one screen, not a BI tool.
- Not multi-team. If marketing wants something similar, they build their own.

## Vocabulary (these words mean specific things here)
- **Lead**: a row in Airtable "Sales Pipeline 2026" with status
  "Open" or "Following up". A name in a Slack message is not a lead.
- **Open**: pasted this week, no message sent yet.
- **Following up**: one message sent, no reply.
- **Done**: reply received OR 14 days since last message.
- **Rep**: Marcus, Sarah, or Devon. Each only sees their own leads.
- **Reminder**: a Thursday or Friday notification inside the app.
  Never email. Never WhatsApp.

## Decisions we've made (don't relitigate)
- We tried auto-sending WhatsApp. One message went out twice. Reps
  stopped trusting it. Do not bring this back even if it would
  "save time."
- We tried Slack instead of WhatsApp. The team uses WhatsApp on phones.
  Stay with WhatsApp.
- We pay for Airtable. Do not migrate to "save money." The cost of a
  data move is higher than the subscription.
- Jordan is the only one with the dashboard view. Don't build a shared one.

## What should be true after any change
I cannot read code. I check by doing this:
1. I add a fake lead labeled "Test entry for today".
2. I set its reminder to 2 minutes from now.
3. I verify Jordan sees it on her dashboard.
4. I verify Marcus does not see it under Sarah's name.
If any of those four fail, the change is not done.

## Before you finish (the standing check)
Before you say a change is done, verify:
1. Did you change anything not strictly needed for the request?
   If yes, list it.
2. Did you read this file before editing? If no, read it now.
3. Which of the four checks above does this change affect?
4. Did you violate anything in "Decisions we've made"?
   If yes, stop and ask before continuing.

## When something is broken
1. I write one sentence describing what was wrong.
2. I screenshot it.
3. I paste both, with: "Read CLAUDE.md first. Ask me one question
   before changing any code."

A few things to notice about that file.

No mention of frameworks, libraries, test runners, or anything you would find in a package.json. Every line is something Anna can answer with authority.

The “Vocabulary” section is doing most of the work. Without it the model would interpret “Open” three different ways across three different sessions.

“Decisions we’ve made” is the section that prevents the model from helpfully un-doing your last hard call. The auto-WhatsApp item is the most common shape: a thing we tried, it failed, do not bring it back even if it would seem to save time later.

The standing check at the bottom is the model talking to itself before it talks to you.

The pattern, in one sentence

Write the standing brief before you write the prompt.

Not before each prompt. Before the project. The brief is the truth the model can’t infer. Every prompt after the brief is a request inside a context that already knows the rules.

That’s the move.

One more pattern worth a name

The 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, the short self-audit at the bottom of the worked example, is something we’ve watched bun and zed invent in the wild without naming. Two repos out of 64. No name in any guidance doc. It is a list the model walks through before it claims a change is done: did I change anything not asked for, did I read the brief, which checks does this affect, did I break any standing decisions. Five lines. The standing brief and the standing check pair up. One tells the model what’s true. The other tells the model what to verify.

Near the end of his Sequoia talk Karpathy says:

“You can outsource your thinking, but you can’t outsource your understanding.”

The standing brief is where your understanding goes. The standing check is the model’s promise to read it. The thinking can leave the room. The understanding stays with you, in markdown, at the root of the project.