CLAUDE.md and AGENTS.md: What to Actually Put in Your Agent Config Files

First, the naming. CLAUDE.md is what Claude Code reads from your repo; AGENTS.md is the same convention for Codex. They serve the identical purpose, so don't maintain two of them — put your rules in one and make the other a single line that points at it. (More on running both tools together in this guide to sharing one repo.)

Keep it short on purpose

The agent re-reads this file on every run, and everything you add dilutes everything else. A three-page manifesto gets treated like terms of service — technically present, functionally skipped. Aim for one scannable screen. If a line isn't load-bearing, cut it. The goal is a file the agent can actually hold in its head, not a policy document.

The five things worth including

A one-paragraph project map. What this is, the stack, where it runs, where the source and the build output live. This orients the agent before it opens a single file.

The commands. Install, dev, build, test — verbatim. And the rule that goes with them: run build and tests before claiming something is done. This one line prevents most "it works" claims that don't.

The house rules that actually matter. Not a style-guide dump — the two or three habits you keep having to correct. "Smallest change that solves it." "Don't reformat files you didn't touch." "Commit only when asked." Three sharp rules beat thirty vague ones.

A do-not-touch list. Generated files, hand-managed configs, vendored code. Agents love to "helpfully" rewrite exactly the files that must not change; naming them explicitly is the cheapest insurance you'll ever write.

Gotchas. The non-obvious traps: the env var the tests need, the casing the API returns, the size limit the build enforces. This section should grow every time the agent gets bitten — which is why it pairs with a lessons.md the agent appends to itself.

A starter you can paste

Here's a skeleton that has everything above and nothing it doesn't. Fill in the angle brackets and delete what you don't need:

# CLAUDE.md  (AGENTS.md is identical — or make one a pointer to the other)

## What this project is
One or two lines. What it does, the stack, where the app runs.
"Astro static site, deploys to <host>. Source in /src, output in /dist."

## Commands
- install:  <your install command>
- dev:      <your dev command>
- build:    <your build command>
- test:     <your test command>
Run the test + build commands before saying anything is done.

## House rules (only the ones that matter)
- Simplicity first. Smallest change that solves it. No drive-by refactors.
- Match the surrounding code's style; don't reformat files you didn't touch.
- Commit only when asked. Never push without asking.

## Do NOT touch
- /src/data/*.generated.json  — rebuilt by the export script
- prod.config.*               — hand-managed
- anything under /vendor

## Gotchas (grows over time — see lessons.md)
- Tests hang without NODE_ENV=test.
- The API returns snake_case, not camelCase.
- Image assets must stay under 200kb or the build fails.

## When you finish
Update lessons.md with anything I had to correct.
Leave a one-line note in STATUS.md: what changed and what's next.

Global vs per-repo

Keep a global config for your personal defaults — how you like commits written, that you always want a plan before big changes, your safety habits — and a per-repo file for what's specific to that codebase. The repo file wins where they overlap. That split means you don't repeat yourself on every project, and each project still gets its own do-not-touch list and gotchas.

Treat it as living, not fixed

The best config files are the ones that get edited constantly. Every time you correct the agent, that correction should land somewhere it will read next time — a new gotcha here, a line in lessons.md there. A config you wrote once and never touched is a config that's already out of date. Make updating it part of the definition of "done," and the agent gets measurably better at your codebase week over week.