If you use Claude Code, Cursor, or Copilot daily and don't have a rules file in your repo, you're leaving a lot on the table. A good CLAUDE.md / AGENTS.md / .cursorrules is the single cheapest change that makes an AI agent stop wasting tokens, stop reinventing your utilities, and start matching your conventions.
Here's what actually belongs in one — and what to leave out.
What these files are
They're a small Markdown file at your repo root that the agent reads as standing instructions:
- CLAUDE.md — read automatically by Claude Code.
- AGENTS.md — an emerging cross-agent convention several tools now respect.
- .cursorrules — Cursor's equivalent.
Same idea, different filename. Many teams keep all three with near-identical content.
What to put in it
Keep it short and high-signal. An agent that gets 2,000 lines of rules follows none of them.
1. The stack, stated plainly.
- Languages: TypeScript, Python
- Framework: Next.js (App Router)
- Package manager: pnpm
- Tests: Vitest + Playwright
This alone stops the agent from suggesting npm install in a pnpm repo or class components in a hooks codebase.
2. The commands that matter.
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Typecheck: pnpm typecheck
Now the agent can verify its own work instead of guessing.
3. How to work here — the conventions.
- Read relevant files before editing; match existing style.
- Make the smallest change that solves the task; don't refactor unrelated code.
- Prefer existing utilities over new dependencies.
4. The guardrails — what NOT to do.
- Don't invent APIs or file paths — verify they exist.
- Don't commit secrets.
- Don't leave commented-out code or console spam.
What to leave out
- Novel-length philosophy. If it's not actionable, it's noise.
- Things the agent can read from the code. Don't restate every folder's purpose; point it to where to look.
- Secrets, internal URLs, anything you wouldn't commit.
Keep it alive
Treat it like code. When the agent does something annoying twice, add one line forbidding it. Over a few weeks your rules file becomes a compounding asset — every future session starts smarter.
Generate a first draft in two seconds
Writing the first version by hand is tedious. I made a free VS Code / Cursor extension that detects your stack and scaffolds all three files for you: Agent Rules (open source). Run one command, pick the files, edit to taste.
If you want deeper, role-specific presets (framework configs, MCP server setups, sub-agent definitions, review checklists), there's a paid Agentic Coding Starter Kit — but the extension plus the outline above gets most people a solid rules file for free.
What's in your CLAUDE.md? I'm collecting good patterns — share your best rule.
Top comments (0)