How to Write a CLAUDE.md for Your Project (2026 Guide)

If you let an AI agent edit your codebase, the single highest-leverage file you can add is a CLAUDE.md (or AGENTS.md, .cursorrules, GEMINI.md). It tells the agent your stack, your conventions, and the lines it must not cross — so it stops guessing and starts shipping the right thing. This guide shows you how to write one, and you can generate a starter in seconds with our CLAUDE.md Generator.

Why it matters

Agents are stateless between tasks. Without a rule file they re-derive your conventions every time, and they will happily "tidy up" working code or pull in a dependency you did not ask for. A CLAUDE.md removes that ambiguity. Teams report it pays for itself within a week of daily use.

The four sections every CLAUDE.md needs

• Stack — list the languages, frameworks, and key libraries so the agent targets the right APIs.
• Conventions — TypeScript strict mode, tests required, no console.log in prod, commit style.
• Workflow — read before editing, prefer diffs over rewrites, run checks before reporting done.
• Guardrails — the things it must NOT do (add deps, rewrite working code, skip tests).

A starter template

You can hand-write this, or use the generator. A minimal version looks like:

# My App

## Stack
- TypeScript, React, Node.js, PostgreSQL

## Conventions
- TypeScript strict mode; no <code>any</code>
- Write tests for new logic

## Guardrails
- Don't add dependencies without asking
- Don't rewrite working code "to clean it up"

Keep it in sync

When your stack changes, update the file. Agents trust it more than they trust inference, so a stale CLAUDE.md is worse than none. If you use multiple tools, keep CLAUDE.md, AGENTS.md, and .cursorrules pointing at the same rules.

Want the polished version with copy-ready formatting? Open the CLAUDE.md Generator and export it in seconds.

Tools we recommend