← mobang.fr

· Vibecoding

CLAUDE.md: The Rules File That Makes Your AI a Reliable Teammate

CLAUDE.md is a plain text file you drop at the root of your project, and your AI assistant reads it automatically at the start of every session. It holds your project's rules: the exact stack and versions, the commands to run and test, the code conventions, the known traps, and your definition of "done." The result: the AI shows up briefed instead of starting from zero in every conversation.

It solves a problem everyone coding with AI runs into: you re-explain your project every session, and the assistant still breaks your conventions, upgrades a library you had pinned, or touches a folder it should never touch. The rules file works as permanent working memory.

The golden rule fits in four words: short and dense. Every line consumes context budget on every exchange. A well-chosen one-page file beats ten exhaustive pages.

This guide shows you what belongs in the file, what to leave out, and gives you a complete example ready to copy. CLAUDE.md, AGENTS.md, Cursor rules — the file name changes with the tool, the principles don't.

The problem: your AI forgets everything between sessions

By default, an AI assistant keeps no memory from one conversation to the next. Every new session, it rediscovers your project like an intern who shows up each morning with no memory of yesterday.

You probably know the symptoms already:

  • you type the same stack explanation at the start of every session;
  • the AI suggests a library you ruled out three weeks ago;
  • it writes code in a style that doesn't match the rest of the project;
  • it "fixes" things that were working fine.

That's not a bug — the model only sees what's in its context window. A rules file solves the problem at the source: your briefing gets injected at the start of every session, automatically.

What goes in it: five blocks that change everything

A good rules file covers five topics, and nothing else.

1. The stack, with exact versions. Not "React," but "Next.js 15, strict TypeScript, Tailwind 4." Without versions, the AI falls back on its training memories and may hand you syntax from a different version than yours.

2. The commands. How to start the project, run the tests, build. This lets the AI check its own work instead of handing you untested code.

3. The project's conventions. Where components live, how files are named, which language user-facing text uses. Everything a new developer would need to know to write code that looks like yours.

4. The known traps. The highest-value lines in the file: "never edit migrations by hand," "the Stripe lib is pinned to 14.x, do not upgrade." Every documented trap is a mistake the AI won't make again.

5. The definition of "done." Tests pass, lint is clean, the build compiles. Without this block, the AI treats code that merely looks right as finished. With it, it knows what it has to prove before handing back.

The golden rule: short and dense

Your rules file gets loaded into context on every exchange. Every line carries a permanent cost: it takes up room the model can no longer spend on your actual code. Keep it lean:

  • aim for one page max — fifteen to twenty lines is a great start;
  • no general documentation, no project history, no tutorials;
  • one rule per line, phrased as an instruction: "do X," "never touch Y";
  • if a line has never prevented a mistake, delete it.

By 2026, this pattern has become a de facto industry standard. The community of developers coding with AI sums it up as "structured skills > heroic prompting": structured, permanent rules beat heroic prompts rewritten from scratch every session.

A complete example: a minimal CLAUDE.md for a web project

Here's a full file for a typical web project. Copy it, adapt every line to your own project, delete what doesn't apply.

# Online store — project rules

## Stack
- Next.js 15 (App Router), strict TypeScript
- Tailwind CSS 4, Prisma + PostgreSQL

## Commands
- Dev: `npm run dev`
- Tests: `npm test` (Vitest)
- Build: `npm run build`

## Conventions
- Components live in `src/components/`, one file per component
- No `any` — use an explicit type or `unknown`
- User-facing text lives in `src/locales/en.json`

## Known traps
- Never edit `prisma/migrations/` by hand
- `stripe` is pinned to 14.x: do not upgrade

## Definition of done
- `npm test` and `npm run lint` pass, the build compiles

Twenty useful lines. Each one prevents a specific category of mistakes. That's exactly the density you're aiming for.

CLAUDE.md, AGENTS.md, Cursor rules: same family

The file name depends on your tool, not the principle:

  • CLAUDE.md — read by Claude Code at the project root;
  • AGENTS.md — the same role, adopted by several other tools;
  • Cursor rules — the same content, in Cursor's rules format.

The good news: the content is portable. Write your rules once, in plain markdown, and adapt them per tool. Switch assistants tomorrow and your investment travels with you. Some people keep a single source file and make the others plain copies or links.

One last thing: commit this file to git. It's part of the project just like the README, and everyone who joins — human or AI — benefits from it.

Where to start today

Thirty minutes is enough for a first version.

  1. Create the file at the root of your project (CLAUDE.md or your tool's equivalent).
  2. Fill in the five blocks: stack and versions, commands, conventions, known traps, definition of done. Fifteen to twenty lines, no more.
  3. Start from real annoyances: think of the last three times the AI frustrated you — what rule would have prevented each one? Write those rules.
  4. Test it immediately: open a fresh session and give it a small task. If the AI follows your conventions without being reminded, it's working.
  5. Keep it alive: every new recurring mistake becomes a line; every line that stops earning its place gets cut. A once-a-month re-read is plenty.

The perfect file doesn't exist, and it's not the goal. An imperfect one-page file, kept alive, already turns your assistant into a teammate who knows the project — everything you used to re-explain by hand, written down once, for good.