This is the CLAUDE.md workshop I built and taught to 500+ engineers at The New York Times, rebuilt for YouTube. Part one, eighteen minutes:
Your auto-generated CLAUDE.md is worse than no file at all
If you'd rather read than watch, the cut-down version is below. Everything I built in the video (the fifteen-line template, the prompt, the repo, the grading skill) is linked from the video's description, so go watch it on YouTube.
I built a fake news syndication service called Bulldog. You know when the same article shows up on twenty different websites, word for word the same dang article? Bulldog is the thing that pushes one story out to all of those partners.
Then I baked four traps into it. The kind of trap a coworker who's been at the company for a year catches instantly but a new hire on day one would never guess.
After that I opened a fresh Claude Code session and handed it three tasks.
Claude did all three. It wrote tests for them too. Every single test passed.
And it walked into all four traps.
I did the exact same thing again. Same repo, same prompt, brand new session. The only difference was that this copy of the repo had a fifteen-line CLAUDE.md in it.
Zero traps were triggered.
Why fifteen lines did that
Every Claude session has a hard ceiling on how much it can hold at once. Your files, your prompts, everything it reads. That ceiling is the context window, and the easiest way to picture it is a sponge. It soaks up everything around it, it can only hold so much, and when you overfill it, the OLDEST stuff falls out first.
Every new session is a brand new dry sponge. CLAUDE.md is the first liquid that goes in, automatically, before you type a single word. Think of it like the house rules pinned up in a professional kitchen. Every chef who starts there reads them on day one.
Which is why what you put in it matters way way more than how much.
The one principle
Every line in your CLAUDE.md must earn its place. Full stop!
Claude already knows how to code. It can read your whole repo. So don't repeat anything it can figure out on its own. Compare these:
"Run
npm testto run the tests." Claude knows this, delete it."
npm run checkexits 1 on a clean checkout on purpose. That's the sample data, not a broken build." THAT earns its place. Claude might work it out after a few turns, but it'd burn valuable tokens figuring it out every single session."You are an expert senior engineer. Be thorough." It's already trying its best, I promise. Role prompts like this can be helpful but not when they're this general.
"Our fiscal Q3 starts in February. Every date I give you is fiscal, not calendar." Earns its place.
Thariq at Anthropic put it better than I can: focus on information that pushes Claude out of its normal way of thinking.
The test I use: could Claude have figured this out on its own? If no, it goes in. If yes, but it would take a substantial amount of time or tokens to get there, it also goes in. And expensive doesn't just mean tokens. Four minutes of watching Claude dig around your computer is four minutes every time you start a new session.
The five things
1. Name and define your systems. Bulldog talks to another make believe service called Lily. That repo isn't on my machine. Unless I tell Claude what Lily does, it's going to go scan GitHub to find out, every single conversation that touches Lily. One line with the name and a concise description ends that. This applies outside engineering too. If you're a lawyer or a real estate agent with internal jargon only your firm uses, define it.
2. State your non-obvious defaults. Every repo has at least one thing that looks totally standard and isn't. Maybe your tests live somewhere nobody expects, or your main branch isn't really production. Claude makes very calculated guesses based on what the majority of the internet does, so anything your team does differently is a guess it will get wrong.
3. Document the gotchas, and say why. These are the ones you add after somebody gets burned. And most people skip telling Claude the reason. "Never add a field to version one" is fine. "Never add a field to version one, because a partner parses it by position and one extra key crashes their overnight import" is way better, because now Claude knows what it's protecting. Would you hand a junior engineer a rule and not explain it? Don't do it to Claude either.
4. Set behavioral guardrails. These are about how Claude goes about the work. "Never spend more than three attempts per issue, because retry loops waste tokens." Notice the why here again.
5. Define your decision frameworks. When two approaches are both valid, Claude tie-breaks with whatever the internet upvoted. Give it your rubric instead. Mine for Bulldog, most important first: reversibility, testability, readability, consistency.
You don't have to be an engineer for this one. If you use Claude for accounting, yours might be something like: audit defensibility, consistency with last year's return, the client's risk tolerance, and then total tax saved. Look at that last one. Tax saved is DEAD last. When two treatments are both valid I'm picking the one I can defend in an audit, not the biggest refund. But Claude doesn't know that unless I write it down, so it's going to optimize for the refund because it assumes that's what I want.
Remember, Claude is a gambler. A compulsive one. It's gambling with statistics, and your CLAUDE.md is how you can fix the odds.
So why not just run /init
Claude Code ships a /init command that writes a CLAUDE.md for you. A group at ETH Zurich actually tested this. They ran the real /init for every major coding agent against 138 real GitHub issues, and Claude Code's best score was with NO auto-generated file at all.
Hence the title. A file full of things Claude already knows is dirty water the sponge didn't need.
The catch
Everything in CLAUDE.md is advisory. It's not enforced. In a long enough session Claude will drift off from it. Write it anyway, tonight, by hand or with Claude. Give it the five categories and run every line through the one filter.
▶️ Watch the full thing here: Your auto-generated CLAUDE.md is worse than no file at all
Every resource from the video is free inside The AI Kitchen, my Skool community: the fifteen-line CLAUDE.md as a fill-in-the-blank template, the exact prompt I gave Claude, the Bulldog repo with both branches, my one-page digest of the ETH Zurich paper, the five-things checklist, the terminal statusline script from the video, and the skill that grades your CLAUDE.md line by line.
Join my Skool for free: alextong.me/kitchen
One ask. Reply to this email and tell me one thing you never wrote down but probably should have for your team. Give me context, because I have no idea what y'all do all day. That's a line that belongs in your file, and I genuinely want to read yours!
Upwards and onwards, thanks for reading!