How to write a CLAUDE.md (or AGENTS.md) that makes AI better at your project

A CLAUDE.md or AGENTS.md file is a plain text note at the top of your project that an AI coding assistant reads before it does anything. It holds the things you’d tell a new teammate on day one: what the project is, how you like to work, and what must never happen. A good one saves you from repeating yourself and stops the most common AI mistakes before they start.

What these files are

Different tools look for different names. Claude Code reads CLAUDE.md. Many other tools read AGENTS.md. The idea is the same: a Markdown file in your project folder that gets loaded into the AI’s context at the start of every session.

AI assistants don’t remember your last conversation. Every session starts from zero. This file is how the project remembers for them.

What to put in it

After writing these for several projects, I’ve settled on six sections. None of them needs to be long.

1. How to work with me

This is the section most people skip, and it’s the one that matters most. Tell the AI how you want to collaborate.

From the brief for TARA, my 3D driving game:

## How to work with me

- I make the important decisions. Before any choice that changes
  scope, look, story, controls or architecture, stop and ask me
  with 2–4 options and your recommendation.
- Work one phase at a time. At the end of each phase: run it,
  take screenshots, tell me what's done in 5 lines or less,
  then wait for my "go".
- Commit after every working step with a clear message.
- Never claim something works without running it in the browser
  and checking the console for errors.
- If something is unclear in this brief, ask. Don't guess.

Those five lines changed how every session went. The AI stopped making big decisions silently, and it stopped telling me things worked when they didn’t.

2. The project in one paragraph

What is this thing, for whom, and what’s the tone? One paragraph is enough. If the AI knows the point of the project, its small decisions get better.

3. Hard rules

A short numbered list of things that are never negotiable. For TARA, the rules included that every asset must be made in code with no downloaded models, and a performance target of 60 frames per second on a mid-range laptop. Rules work best when they can be checked.

4. The tech stack, locked

List what you’ve chosen: language, framework, libraries, where it deploys. Say that it’s locked. Otherwise an AI will happily add a new library to solve a problem your existing ones already handle.

5. Project structure

A small map of the folders and what lives in each. It doesn’t need every file. It needs enough that new code lands in the right place.

6. Commands

How to run the project, run the tests and build it. If the AI can run your checks, it can verify its own work.

What to leave out

• Things the code already says. Don’t describe every function. The AI can read the code.
• Anything secret. No passwords, API keys or tokens. This file usually gets committed to GitHub.
• Vague wishes. “Write clean code” changes nothing. “Functions under 40 lines, no new dependencies without asking” changes behaviour.
• A history of the project. Keep the file about how to work now.

Shorter is better. A file the AI reads every session should be a page or two. If it grows past that, move the detail into separate documents and link to them.

Keep a handoff file next to it

A brief describes the plan. Plans change. On longer projects I keep a second file, HANDOFF.md, that records:

• every decision that overrides or extends the brief, with the reason
• what exists in the code, phase by phase
• how to verify it
• what’s next

When a session ends, the AI updates the handoff. When a new one starts, it reads the brief and the handoff, and it’s caught up in a minute. On TARA, that file is what lets a brand-new session carry on without me re-explaining anything.

A template to copy

# Project name

## How to work with me
- Ask before changing scope, design or architecture.
- One step at a time. Show me the result, then wait.
- Commit after every working step.
- Never say it works without running it.

## What this is
One paragraph: what it does, who it's for, the tone.

## Hard rules
1. ...
2. ...

## Tech stack (locked)
- Language / framework:
- Hosting:
- Tests:

## Structure
src/        what lives here
tests/      what lives here

## Commands
- Run:
- Test:
- Build:

How to tell if it’s working

You’ll notice three things. You stop typing the same instructions. The AI asks you a question at the moments you’d want it to. And when you open a fresh session, it behaves like it’s been on the project for weeks.

If the AI keeps making the same mistake, don’t correct it in chat for the fifth time. Add one line to the file. That’s the whole maintenance routine.

This file is one of the twelve habits I use to keep AI from breaking my projects. It’s also the reason my release pipeline can run with me only saying “ok”.