Writing CLAUDE.md and AGENTS.md Files That Actually Work

Every coding agent starts a session with no memory of your project. Before it does anything, it reads a file at the repository root: CLAUDE.md for Claude Code, AGENTS.md as the cross-tool convention, .cursor/rules for Cursor. What is in that file determines whether the agent behaves like a senior engineer who joined last month or a contractor who has never seen the codebase. Most teams either do not have one or have a bad one, and the difference in agent output is dramatic.

What It Is For

The context file is not documentation for humans; the README is that. It is operating instructions for a capable, fast, well-read contractor who will forget everything at the end of the session. It should answer, in order: what is this, how do I run and test it, what must I never do, what conventions do you have that I could not infer, and where are the things I will otherwise search for.

What Belongs

Commands. How to build, test, lint, typecheck, and run. Exact commands. If a command is dangerous to run casually (starting a server, running migrations), say so.

Invariants. Rules the codebase depends on that are not enforced by tooling. "Schema changes go in a new Flyway migration; never edit an applied one." "Post content must not start with an H1." "No em dashes in content." These are the rules the agent will break without being told, because nothing in the code stops it.

Conventions the code does not reveal. "We use the v2 client; the v1 client is still in the repo for one legacy job." "Tests live next to source, not in a tests folder." "Prefer explicit transactions; open-in-view is off."

Locations. Where controllers, API clients, migrations, and config live. Saves a search per session and prevents the agent from creating a second copy of something that exists.

Working preferences. "Match existing style; do not add comments that restate the code." "Ask before adding a dependency." "Run the tests yourself before reporting done."

What Does Not Belong

• Anything the agent can read from the code. Do not describe the architecture in prose the agent could get from the directory listing.
• Long explanations. Agents weight everything in the file; a bloated file dilutes the rules that matter.
• Aspirational architecture. Describe what is, not what you wish.
• Secrets, obviously.
• Rules that should be hooks. "Never run rm -rf" in the file is a strong suggestion; a hook that blocks the command is a guarantee. Anything you would never want done goes in a hook.

A Template

markdownCopy
# CLAUDE.md

## What this is
Spring Boot 3 API + React/Vite frontend for a learning platform. Postgres via Flyway.

## Commands
- Backend tests: `cd backend && mvn -q test`
- Frontend typecheck: `cd frontend && npx tsc -b`
- Frontend dev server: ask me; do not start it yourself.

## Never
- Edit an applied Flyway migration. New schema or content changes go in a new Vnn file.
- Start post content with an H1.
- Use em dashes in content.
- Add a dependency without asking.

## Conventions
- Controller -> Service -> Repository -> Entity. All responses wrapped in ApiResponse<T>.
- Content migrations use dollar-quoted strings ($MD$ ... $MD$) so Markdown needs no escaping.
- Reading time = GREATEST(3, ROUND(words / 200)).

## Where
- Controllers: backend/src/main/java/.../controller
- API client: frontend/src/api/blogApi.ts
- Migrations: backend/src/main/resources/db/migration

## How to work
- For changes touching more than two files, propose a plan first and wait.
- Run tests before reporting done. Report what you ran.
- Do not modify tests to make them pass; tell me if a test looks wrong.

Under a hundred lines. Every line earns its place.

Scoping and Layering

Most agents read context files hierarchically: a global file in your home directory for personal preferences, the repository root file for the project, and subdirectory files for areas with their own rules (a CLAUDE.md in frontend/ that says "this is a Vite app; use the existing hooks in src/hooks"). Put rules at the narrowest scope where they apply, so the root file stays short.

The Maintenance Loop

The file is version controlled and it evolves, and the loop that improves it is the same one that improves any agent harness: when the agent makes a mistake that a rule would have prevented, the rule goes in the file. Reviewed a PR and found the agent used the deprecated client? Add "we use the v2 client". Agent created a duplicate utility? Add its location. Over a few weeks the file becomes the distilled, enforced tribal knowledge of the codebase, which is worth having even if you never used an agent.

The inverse loop matters too: when the agent consistently ignores a rule, the rule is probably buried. Move it up, shorten it, or turn it into a hook.

Skills: The Same Idea for Recurring Tasks

For a task you do repeatedly (write a migration, add an API endpoint, generate a component), a skill file spells out the steps, conventions, and verification for that task, and the agent loads it when the task matches. Skills keep the root context file short and make recurring work consistent. Same rules: exact commands, invariants, small.

What to Practice Next

Write a context file for one repository using the template. Delegate one task to an agent, review it, and record every correction you made. Turn each correction into a line in the file (or a hook, if it is a "never"). Repeat for a week. The module agentic-coding-working-with-claude-code-codex-and-cursor covers skills, subagents, permissions, and review in depth.