Guide · October 2026
What to put in a team CLAUDE.md, with a real example
Four things: your terms, your standards, when to ask before acting, and what never to do. Write each as a short rule that a person could check, and keep the file to about a page.
A CLAUDE.md is a plain Markdown file in the folder your team works in. Claude Code reads it at the start of every session (opens in a new tab). The documentation's own examples are about code: build commands, indentation, where files live. This guide is for a product or data team, whose work is answers, specs and reviews.
The example is the sample file from this site's demo: 46 lines, written for a demo company called Chinook. Each part is shown beside what Claude wrote in a recorded run that followed it. They are the runs the home page shows. Every excerpt is copied from that file or from the record of a run.
1. Your terms
Start with the words your team argues about. Revenue, customer, market: each has two or three honest readings, and an AI that is asked a question will pick one without saying so. Write down the one you mean.
## Our terms
- Revenue: the sum of invoice totals, in USD.
- Market: the billing country on the invoice.
- Customer: anyone with at least one invoice.
- Business customer: a customer with a company on the account.
- Year: the calendar year of the invoice date.
- Catalog: tracks, albums and artists. Genre belongs to the track.
A teammate then asks: "Which five markets brought in the most revenue in 2025, and how many customers bought in each?" This is the whole reply.
The five markets with the most revenue in 2025 were USA ($85.14, 11 customers), Canada ($72.27, 7), France ($40.59, 4), Brazil ($37.62, 4) and Czech Republic ($36.75, 2).
Query: SELECT billing_country AS market, SUM(total) AS revenue_usd, COUNT(DISTINCT customer_id) AS customers FROM invoice WHERE EXTRACT(YEAR FROM invoice_date) = 2025 GROUP BY billing_country ORDER BY revenue_usd DESC, market LIMIT 5;
Row count: 5
Assumption: "customers" means anyone with at least one 2025 invoice billed to that market.
The latest invoice in the warehouse is dated 22 December 2025. I don't know if later sales are missing or if there were none.
Three of the terms are in that query. Market is the billing country, revenue is the sum of invoice totals, and the year is the calendar year of the invoice date. The fourth, customer, can still be read two ways when the question is about one year, so the reply says which way it was read.
2. Your standards
Next, what the work should look like when it is handed over. A standard earns a line in the file when you can check it by looking at the result. "Lead with the answer" passes that test. "Write well" does not. The documentation asks for the same thing: instructions concrete enough to verify (opens in a new tab).
## Writing
- Lead with the answer. Plain words, short sentences.
- No em dashes or en dashes. No exclamation marks.
- Say what you don't know. Label every assumption as one.
## Data
- Query the warehouse with psql. You connect as ai_readonly.
- That role can read and nothing else. Never ask for more access.
- Show the query you ran and the row count with every answer.
- In a terminal, reply in plain text: the answer in one sentence, the query on one line, then the row count.
Now read the reply above against those lines. It leads with the answer. The query and the row count are there. One assumption is labeled, and one thing it does not know is said. The record of that run shows one thing more: before it finished, Claude searched its own files for dashes and exclamation marks.
The last data rule is for a terminal. This is Claude Code answering a question from the command line, in the demo's project folder:
$ claude -p "How much revenue did we make in 2025, and from how many customers?" --allowedTools "Bash(psql *)"
In 2025 we made $450.58 in revenue from 46 customers, across 80 invoices.
Query: select sum(total) as revenue_usd, count(distinct customer_id) as customers, count(*) as invoices, min(invoice_date), max(invoice_date) from invoice where extract(year from invoice_date) = 2025
Row count: 1
One sentence, the query on one line, the row count. Nothing in the command mentions the file. Claude Code was started in the folder that holds it, and read it without being told. The other runs in this guide were started another way, and the instruction they were given said to read the file first.
A standard can also fix the shape of a document your team writes often. The sample does that for a spec:
## Specs
A first draft is an outline that fits one screen. Four parts, each under its own Markdown heading, in this order:
1. Problem: two sentences, in the customer's words where you can.
2. Requirements: up to four, numbered, one short sentence each.
3. Open questions: up to three, each with who should answer it.
4. Acceptance criteria: up to three, as "Given, when, then".
Keep list items short enough to scan: about 15 words.
Given the transcript of a customer call and the request "Draft a spec from calls/2026-10-06-monthly-invoices.txt", Claude wrote this:
## Problem
"Every purchase is its own invoice, in its own email", so a video studio builds its monthly statement by hand.
Its accountant rejects invoices that "show my name, not the studio or our tax number", and the studio "would shop elsewhere" after its books close in December.
## Requirements
1. Offer one monthly statement per account, listing that month's invoices (assumption: calendar month).
2. Save a company name and tax number once, then print both on every later invoice.
3. Let buyers type a free text reference at checkout that prints on the invoice.
4. Let customers get old invoices on the site, not only by email.
## Open questions
1. Should the statement be a PDF, a spreadsheet or both? Owner: the customer's accountant.
2. Must we check the tax number, or is typing it in enough? Owner: Finance.
3. How many of our 10 business customers have this problem? Owner: Dana.
## Acceptance criteria
1. Given several invoices in one calendar month, when the month ends, then one statement lists them all.
2. Given a saved company name and tax number, when the next invoice is issued, then it shows both.
3. Given a reference typed at checkout, when the invoice is issued, then it shows that reference.
Four headings in the order asked for, four requirements, three open questions with an owner each, and three criteria as "Given, when, then". The one assumption in it is labeled.
3. When to ask before acting
## Ask before acting
- Before anything that writes, sends or deletes.
- When a request needs a customer's personal details.
- When a term above could be read two ways.
These are the moments when a wrong guess costs more than a question. Keep the list short. An AI that asks about everything is as much trouble as one that never asks.
None of the recorded runs could ask. Each was given one request and had no one to answer back. Look at what the run in section 1 did when a term could be read two ways: it answered, and labeled its reading as an assumption. The Writing rules ask for that label, and for a job that runs unattended it is the right fallback.
4. What never to do
## Never
- Never run a query that changes data.
- Never put customer names or emails in a spec or a ticket.
- Never present an estimate as a measured number.
The second line can be checked against the record. The call transcript has the customer's name in it 17 times. The spec draft above says "a video studio" and never names the customer.
The third is in the same draft. Nobody asked for the next part: the call ends with a promise to find out how many business customers there are, so Claude counted them. It kept what it had measured apart from what it could not know:
Measured in the warehouse for question 3: 10 of our 59 customers are business customers, and no customer has more than one invoice in any calendar month.
Rows: 1.
Not known: whether these counts are current, or whether this customer is one of the 10. The warehouse has no invoices after 22 December 2025, so I could not check the customer's estimate of "thirty or forty" purchases a month.
The first line is different in kind. "Never run a query that changes data" is a request, and Claude Code's documentation is plain that the file is context, not enforced configuration (opens in a new tab). In the demo that rule cannot be broken either, because the role Claude connects as has no right to write. Put the rule in the file so that the AI does not try, and the limit in the database so that it cannot. The guide to read-only access shows how.
5. Keep it short, and let the work correct it
The sample is 46 lines. The documentation says to stay under 200 (opens in a new tab), because a longer file takes up more of the context and is followed less closely. For a team file, aim for a page: people have to read it too.
Leave out what is true of one task only. A long procedure belongs in a skill (opens in a new tab), and a personal preference in your own file.
Then run real work through it and read what comes back. The design audit in the demo said twice that the file had not told it something:
Assumption: property names start with a capital letter, as in every other variant in the file. Assumption: every Type should have every State. Our guidelines spell out neither.
- `Input` has Default, Focus and Error. It has no Hover or Disabled. Our guidelines do not list required states, so I don't know if those are missing.
Each is a line the file is missing: how property names are written, and which states every component must have. Add the rule and run the audit again. The documentation gives the same test (opens in a new tab) for when to add a line: when you would otherwise explain the same thing a second time.
6. Where the file goes
For a team, the file is CLAUDE.md at the top of the project folder, kept in version control with the work (opens in a new tab), so that every session reads the same text. Personal preferences go in ~/.claude/CLAUDE.md and stay out of the team's file. To see whether a session has loaded it, run /context and look under Memory files.
If the team also uses other AI coding tools, the shared name is AGENTS.md. Recent versions of Claude Code read that file (opens in a new tab) when the folder has no CLAUDE.md. If it has both, a first line of @AGENTS.md in the CLAUDE.md pulls the shared file in.
In Claude's chat apps there is no file. The same text goes into a project's instructions (opens in a new tab), and on the Team and Enterprise plans a project can be shared with the people who need it.
Questions
How long should a CLAUDE.md be?
As short as it can be and still change what the AI does. The sample in this guide is 46 lines. Claude Code's documentation says to stay under 200, because a longer file is followed less closely.
Will Claude always follow it?
No. The documentation says so: Claude reads the file and tries to follow it, with no guarantee (opens in a new tab), and a specific rule is followed more reliably than a vague one. For anything that must not happen, put the limit outside the model: a hook in Claude Code, or a database role that cannot write.
CLAUDE.md or AGENTS.md?
If Claude Code is the only tool, CLAUDE.md. If the team uses several, keep the rules in AGENTS.md. Recent versions of Claude Code read it when there is no CLAUDE.md in the folder.
Is this only for engineers?
No. Nothing in the sample is about writing code. It defines the team's terms, sets a writing standard, fixes the shape of a spec and of an audit, and says when to ask. That is a product and data team's file.
Do you write this for teams?
Yes. A team guidelines file is one of the four things in the Two-Week AI Setup: one shared file that tells your AI how your team works. See what is included.
Sources
- Claude Code documentation. How Claude remembers your project (opens in a new tab)
- Claude Code documentation. Write effective instructions (opens in a new tab)
- Claude Code documentation. When to add to CLAUDE.md (opens in a new tab)
- Claude Code documentation. Choose where to put CLAUDE.md files (opens in a new tab)
- Claude Code documentation. AGENTS.md (opens in a new tab)
- Claude Code documentation. Troubleshoot memory issues (opens in a new tab)
- Claude Help Center. What are projects? (opens in a new tab)