CLAUDE.md and AGENTS.md are the highest-leverage files in an AI-assisted repo
Jovan Chan argues that a well-crafted `CLAUDE.md`, `AGENTS.md`, or `.cursorrules` file is the single cheapest change developers can make to stop AI agents from wasting tokens and start matching project conventions.
Score breakdown
A concise, well-structured rules file gives AI coding agents standing instructions that prevent repeated mistakes and enforce project conventions across every session, making it a compounding productivity asset as described in the post.
- 01CLAUDE.md is read automatically by Claude Code; AGENTS.md is an emerging cross-agent convention; .cursorrules is Cursor's equivalent.
- 02The post warns that an agent given 2,000 lines of rules follows none of them — keep the file short and high-signal.
- 03Four recommended sections: tech stack, key commands, working conventions, and explicit guardrails (what NOT to do).
Jovan Chan argues that `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` — small Markdown files placed at the repo root — are the single cheapest change that makes AI coding agents stop wasting tokens, stop reinventing existing utilities, and start matching a project's conventions. `CLAUDE.md` is read automatically by Claude Code; `AGENTS.md` is described as an emerging cross-agent convention that several tools now respect; `.cursorrules` is Cursor's equivalent. Many teams, the post notes, keep all three with near-identical content.
The post also lists what to leave out: non-actionable philosophy, things the agent can infer from the code itself, and secrets or internal URLs.
The post outlines four categories of content that belong in the file: (1) the tech stack stated plainly — languages, framework, package manager, and test tooling — so the agent doesn't suggest `npm install` in a `pnpm` repo or class components in a hooks codebase; (2) the key commands for install, dev, test, and typecheck so the agent can verify its own work; (3) working conventions such as reading relevant files before editing, making the smallest change that solves the task, and preferring existing utilities over new dependencies; and (4) explicit guardrails — don't invent APIs or file paths, don't commit secrets, don't leave commented-out code or console spam. The post also lists what to leave out: non-actionable philosophy, things the agent can infer from the code itself, and secrets or internal URLs.
Chan recommends treating the rules file like code — adding one line whenever the agent does something annoying twice — so it compounds in value over weeks. To lower the barrier to creating the first version, Chan describes a free, open-source VS Code/Cursor extension called Agent Rules that detects the stack and scaffolds all three files. A paid Agentic Coding Starter Kit with role-specific presets, framework configs, MCP server setups, sub-agent definitions, and review checklists is also mentioned.
Key facts
- 01CLAUDE.md is read automatically by Claude Code; AGENTS.md is an emerging cross-agent convention; .cursorrules is Cursor's equivalent.
- 02The post warns that an agent given 2,000 lines of rules follows none of them — keep the file short and high-signal.
- 03Four recommended sections: tech stack, key commands, working conventions, and explicit guardrails (what NOT to do).
- 04Stating the package manager (e.g., pnpm) prevents the agent from suggesting npm install in the wrong repo.
- 05The post recommends treating the file like code: add one line whenever the agent does something annoying twice.
- 06Chan describes a free, open-source VS Code/Cursor extension called Agent Rules that scaffolds all three files automatically.
- 07A paid Agentic Coding Starter Kit with framework configs, MCP server setups, sub-agent definitions, and review checklists is also mentioned.
Topics
Summary and scoring are generated automatically from the original article. We always link back to the publisher and never republish images or paywalled content. Last processed Jun 9, 2026 · 17:05 UTC. How this works →