10 Lessons for Writing a Good AGENTS.md for Codex and Claude Code

By @Voxyz_ai · 2026-05-30T16:02:30.000Z

One markdown file plus a famous name, 162K stars (andrej-karpathy-skills). I stared at that number for a while. The name did a lot of the lifting. The same file from an unknown account would mostly get ignored. But it caught fire because it hit a real need: everyone's handing their code to AI now, and the thing that trips everyone up is the same. The model can write. It just doesn't know your project's rules. This file was the first to turn "how do I keep the agent in line" into something you can copy. And the slice that caught on is narrow. It's about behavior, how the model should act while it codes: ask when unsure, make the smallest change, don't refactor for fun.

This isn't a post about AGENTS.md formatting. It's 10 lessons from actually shipping with these tools: which counterintuitive moves work better, and which traps you only need to hit once. I run both Codex and Claude Code, and everything below works for both.

You'd think more information means the tool understands you better. The opposite is true: the more you write, the easier it is for the tool to miss the few lines that actually matter.

The entry file loads in full at the start of every session. Every wasted line there pushes out something the tool actually needs. Two numbers worth knowing. Codex has a project_doc_max_bytes limit, 32 KiB by default, but it's not that one oversized file gets truncated. Codex concatenates from global to project root down to your current directory, and once the combined size hits the cap it stops adding more. Write too much up front and the rules closest to the task can get squeezed out of context. Claude Code's official guidance is to target under 200 lines, and CLAUDE.md loads in full no matter how long it is, so longer means worse adherence.

Working rule: keep the root file between 100 and 200 lines. Past that, split it into docs/ or subdirectories.

# ❌ don't do this
## Founding Story
Back in 2024 I tossed out this idea on a livestream, and then...
(300 lines of startup story + vision + why we're different)

# ✅ do this
## Project Overview
A web app that drafts X posts in a creator's own voice and schedules them.

Goal:
- turn a rough idea into a publish-ready post in under a minute

Priority:
1. draft sounds like the user
2. no fake stats, no broken links
3. speed
4. polish

Stack:
- Next.js App Router + TypeScript
- Tailwind + shadcn/ui
- Supabase (auth + Postgres)
- a background worker for scheduled posts

An engineer who's never seen your project should be able to answer, within 30 seconds of reading it: what is this, how do I run it, where does code go, how do I verify a change?

You list your stack and assume the tool won't go rogue. But it doesn't know your project's baggage. It'll helpfully reach for the "best" option it knows, and that option may collide with your migrations and conventions.

Codex and Claude Code both run commands, edit files, and ask for permissions on their own. In Codex's default Auto preset, local work is usually workspace-write plus on-request: reads and writes inside the workspace and routine commands run freely, but writing outside it or hitting the network asks first. A file that only lists your stack won't stop any of that. So the do-not list has two layers: what to never introduce, and what it isn't allowed to decide alone.

## Tech Stack
- Next.js 15 App Router + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase Auth + Postgres
- Zustand for client state

## Do NOT introduce unless asked
- Redux
  Reason: state moved to Zustand + server components
  Revisit: only if we need offline sync
- styled-components
  Reason: styling is Tailwind-only
  Revisit: never, unless the design system is replaced
- a second ORM or database
  Reason: data layer is Supabase + Postgres
  Revisit: only for separate event/log storage, not the product DB

## Stop and ask before
- changing public API contracts
- editing auth / billing / permissions logic
- changing database schema or running a migration
- adding a production dependency
- editing a test just to make it pass
- a diff over 500 lines, or touching files outside the asked scope
- any command that hits production, billing, users, or external services

A do-not list isn't a mood. It's a compressed record of decisions. With a Reason and a Revisit, the tool knows why a rule exists and when it can loosen. The Stop-and-ask column matters more. It isn't a ban. It says: this call isn't yours to make alone.

"Write clean code" sounds like a good rule. To the tool it says nothing.

The tool can't read "clean," "simple," or "performant." It can read "use named exports," "components under 200 lines," "async/await instead of .then() chains."

# ❌ vague, the tool can't act on it
## Coding Rules
- write clean code
- keep it simple
- make it fast

# ✅ concrete, the tool can follow it directly
## Coding Rules
- Server components by default; add "use client" only for state or effects
- Validate every API input with zod before it touches the DB
- No `any`; model it with a type or `unknown`
- Money is integer cents, never a float
- One exported component per file
- Add a test when behavior changes, not only for new features

Codex and Claude Code both run commands to check their own work, so "what done means" has to be written down too:

## Definition of Done
Before finishing:
1. run `pnpm typecheck`
2. run `pnpm lint`
3. run tests for changed files

## Final response format
When done, report in this order:
1. files changed
2. what changed and why
3. verification run, with results
4. verification NOT run, with the reason
5. remaining risks or follow-ups

Quick test: after reading a rule, can you judge in five seconds whether a piece of code follows it? If yes, the rule's good. If not, rewrite it.

You assume the thing to write down is project knowledge. But where the tool actually goes off the rails is its behavior, not its knowledge.

It doesn't ask when it's unsure; it picks one reading and barrels ahead. It doesn't stop when it should; it "improves" the code next door while it's at it. That 162K repo from the intro took off for exactly this layer. It describes no specific project. It just turns a few of Karpathy's observed failure modes into behavior rules. Worth stealing into your own file.

## How to work
- Restate the goal in one line before coding; if it is ambiguous, ask
- Make the smallest change that satisfies the task
- Do not refactor nearby code unless asked
- Surface tradeoffs and inconsistencies instead of silently picking one
- No new abstraction unless it is used in 3+ places

Hand it a vague task and watch the first move. If it restates the goal or asks a question instead of charging in, this layer is doing its job.

The temptation is to cram every architecture doc into this one file. But its job isn't storage. It points the tool to where the information actually lives.

A regular user's entry file is a knowledge dump. A power user's is a router.

## Project Context
Read these only when relevant:
- Architecture overview: `docs/architecture.md`
- API contracts: `docs/api.md`
- Database schema notes: `docs/database.md`
- Deployment runbook: `docs/deploy.md`
- Long task planning: `.agent/PLANS.md`

I added a PLANS.md there, and it's one of the highest-leverage moves. AGENTS.md doesn't hold the plan itself. It carries one line: for anything complex, go write a plan in .agent/PLANS.md, split it into phases, wait for my sign-off. The template lives in the repo. OpenAI's cookbook has a whole piece on using PLANS.md to carry multi-hour, multi-step work.

## Long-running work
For complex features, migrations, or large refactors:
1. read `.agent/PLANS.md`
2. write an execution plan first, split into phases
3. wait for approval before implementation
4. keep the plan updated as work progresses

A goal is just the top-level objective you hand it. Paired with the phases laid out in PLANS.md, that's what lets it carry a task that runs for hours. My setup is simple: I run these in an isolated worktree (a worktree is just a separate checkout of your code for this one task, so a blowup doesn't touch your main branch), drop a clear goal before bed, and check a string of commits and verification notes in the morning. The longest single run I've had was 36 hours, where it took a full architecture problem from start to finish, and it came out decent. I've seen people run 6-day ones; I just haven't hit a task that needs that long. The premise comes first: tests run, the sandbox caps what it can touch, every phase is reversible, and there are no production credentials or prod write access on the machine. Without that, it isn't automation. It's locking an intern on the production box overnight.

It can run that long only because the goal is written tight and the phases are cut fine. The template I reach for looks like this:

Goal: <one sentence, one outcome you can verify>

Break it into phases. Run each phase through this loop, no skipping:
1. write the test first
2. write the code
3. code review
4. simplify, cut anything not needed
5. run tests, fix until green
6. (UI work) run the real flow with a test admin account, take screenshots,
   judge whether any button, dialog, or copy adds cognitive load or blocks the user
7. commit

Run all phases end to end in one dedicated worktree; don't switch context midway.
Stop for me on anything irreversible: production data, migrations, external writes.

At every step, ask yourself:
- "You overengineered this, there is a simpler way"
- "There is a smaller delta that buys us most of the benefits"
- "There is a more elegant way"
- "This is not architecturally coherent"

Those four prompts are just lesson 4's behavior rules pressed into a single task. One more thing: don't write a big goal as one big plan. Break it into stages, one plan per phase, and run each plan through an adversarial pass to confirm it's coherent and buildable before you let it go. Then even after an overnight run, what you wake up to is a clean string of commits, not a pile to roll back.

The pointer mechanics differ slightly between the two. Codex loads referenced docs on demand, only when it needs them. Claude Code's import pulls the whole file in at launch, so don't hang big docs off it; use skills or path-scoped .claude/rules/ instead.

If the root file shows no big blocks of doc text, only "when you need X, go read Y," you've got it right.

That goal from the last lesson, the one you can leave running all night? You don't let go of it because you trust the model. You let go because of the few layers of guardrail that start here.

Some modules carry ten times the risk of the rest. Give them their own file.

Both tools walk from the project root down to your current directory. The closer a file is to the task, the more it counts. But the two handle "priority" differently. Codex is closer to an override: one file per level, the nearer one beats the farther one, and in the same directory AGENTS.override.md beats AGENTS.md. Claude Code is more like concatenation: every CLAUDE.md gets stitched into context in order, the later ones carry more weight, and if rules contradict, the model can still waver. Subdirectory CLAUDE.md loads on demand, and you can scope it with paths in .claude/rules/. Drop a local file in each high-risk directory and you've put a railing around the danger zone.

AGENTS.md
src/
  auth/
    AGENTS.md
  billing/
    AGENTS.md
infra/
  AGENTS.override.md

# src/auth/AGENTS.md
## Security boundaries
- Don't touch the X OAuth token refresh flow without asking
- Never log access or refresh tokens, not even at debug level
- Any change here must run `pnpm test src/auth`

## Known traps
- Tokens are encrypted at rest; write through `tokenStore`, never the table
- Token refresh holds a one-at-a-time lock; do not parallelize it
- The session cookie is httpOnly + SameSite=Lax; changing it breaks popup OAuth

A subdirectory file should carry only that directory's local risks, not a copy of the root.

You write a red line into the file and assume the tool holds it. It won't always remember. Don't keep red lines in the file alone.

Anthropic says it plainly: to actually block an action regardless of what the model decides, use a PreToolUse hook; writing it into CLAUDE.md doesn't count. The two tools line up roughly, but the hardness differs.

intent      AGENTS.md / CLAUDE.md           tells the tool how it should act
intercept   PreToolUse hook                 runs your check before an action fires
permission  Codex rules / permissions.deny  which commands may run, which are blocked
boundary    sandbox_mode / sandbox.enabled  what the tool can actually reach

Below are two concrete Codex configs. Copy them if they help, skip them if not. The point stands either way. These layers enforce the red lines. Don't count on the model to remember them.

Codex hooks load from ~/.codex/hooks.json, <repo>/.codex/hooks.json, or the [hooks] table in config.toml, and support lifecycle events like PreToolUse, PostToolUse, and Stop.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

Codex also has rules, which control which commands can run outside the sandbox, with allow, prompt, and forbidden as the actions. A good replacement for "hope the model remembers not to run the dangerous thing." One heads-up: rules are still marked experimental, so don't sell them as a forever-stable standard, but they're the best place right now for command-level policy.

# ~/.codex/rules/default.rules
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing code needs human confirmation",
)

prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
    justification = "Use a safer cleanup script instead of raw rm -rf",
)

On the Claude Code side, the PreToolUse hook plus permissions.deny and sandbox.enabled in managed settings are the harder enforcement layer. On Codex, keep one thing in mind: the PreToolUse hook can intercept Bash, apply_patch, and MCP calls, which is useful, but OpenAI itself calls it a guardrail, not a complete enforcement boundary, and not every command gets caught. The real hard edges still come from the sandbox, permission profiles, rules, CI, an isolated worktree, and withholding production credentials.

What you put in the file is a "please remember." Intercept what you can with hooks, govern what you can with rules, isolate what you can with the sandbox, and stop trusting the model to comply. The more dangerous and irreversible the action, the further down these layers it belongs.

Every new session, the tool meets your project fresh, like it has amnesia. You don't need a vector database for this, and you shouldn't hand memory entirely to the tool's built-in system either.

The two tools' auto-memory sits in opposite states. Codex's Memories is off by default and not yet available in some regions. Claude Code's auto memory is on by default (since v2.1.59), with Claude writing what it learns into MEMORY.md, the first 200 lines or 25KB of which load every session. But both vendors flag the same thing: mandatory team rules belong in the file, in Git, and auto-memory is only a backup.

## Memory
`MEMORY.md` records durable project learnings:
- decisions that changed future implementation
- recurring traps
- patterns the agent previously got wrong
- commands that fixed real issues

At the start of a non-trivial task, read `MEMORY.md`.
At the end, suggest updates if a durable lesson was learned.
Do not store secrets, credentials, or customer data.

Set one bar for what's worth saving, and most of the junk never lands:

## Memory update rule
Only update `MEMORY.md` when the lesson is likely to matter again in 30 days.
Skip one-off bugs, temporary TODOs, secrets, and speculative preferences.

If your memory is auditable, deletable, and shows up in a git diff, it's healthy. Otherwise long-term memory slowly turns into long-term pollution.

Mix personal preferences, team conventions, and machine permissions into one file to save effort, and what you're really building is a drawer nobody dares clean out.

personal style   ~/.codex/AGENTS.md   or   ~/.claude/CLAUDE.md
team convention  <repo>/AGENTS.md     and  <repo>/CLAUDE.md
machine perms    .codex/config.toml   or   .claude/settings.json

Personal preferences go global, shared across every project:

# ~/.codex/AGENTS.md  (or ~/.claude/CLAUDE.md)
## My working style
- Show the diff and your reasoning before anything destructive
- When unsure, give me 2 options with tradeoffs; don't guess
- Match the file's existing style; don't reformat code you didn't change
- Lead with the answer, keep it short, paste exact file paths
- Reply in Chinese; keep code and comments in English
- Skip the "you're absolutely right" preamble

The file in the project skips personal taste and carries only this repo's conventions:

# <repo>/AGENTS.md
## Repository expectations
- Use pnpm
- Run `pnpm lint` before finishing
- Run tests for modified packages
- Document public utilities in `docs/`
- Do not modify billing or auth flows without confirmation

You use both Codex and Claude Code, so the natural move is to write a file for each. But two files will drift, and in two months nobody can say which one is right.

Anthropic is explicit: Claude Code reads CLAUDE.md, not AGENTS.md. The fix is simple. Make AGENTS.md the single source of truth and let CLAUDE.md hold one line, an import:

# CLAUDE.md
@AGENTS.md

## Claude Code only
Use plan mode for changes under `src/billing/`.

Claude Code pulls the whole imported file in at launch, then appends its own lines. If you don't need Claude-specific content, a symlink works too:

ln -s AGENTS.md CLAUDE.md

Don't maintain two full sets of rules. AGENTS.md is the source, CLAUDE.md keeps just the import plus the rare Claude-only addition. Write them separately and in two months they won't match.

Don't want to think it through from scratch? Paste this into AGENTS.md and adjust. Ten lessons, compressed into one file:

# AGENTS.md

## Project Overview
<one paragraph: what it is, who it's for, the top priority>

## How to work
- Restate the goal in one line before coding; if unclear, ask
- Make the smallest change that does the job; don't refactor nearby code
- Surface the tradeoffs; don't silently pick one

## Coding Rules
- <one rule you can judge in five seconds>

## Definition of Done
- run typecheck / lint / the tests for what changed
- report: files changed, what and why, what you verified, what risks remain

## Do NOT introduce unless asked
- <library> — Reason: <why> / Revisit: <when it's worth reconsidering>

## Stop and ask before
- auth / billing / DB schema / production / any change over 500 lines

## Project context (read when relevant)
- docs/architecture.md, .agent/PLANS.md, MEMORY.md

Don't let this file carry the dangerous stuff alone, back it with hooks / rules / sandbox. On Claude Code, add a CLAUDE.md whose single line imports it, plus a few Claude-only notes. One source, both tools read it.

1. Run /init for a first draft: Codex produces AGENTS.md, Claude Code produces CLAUDE.md (and reads an existing AGENTS.md).
2. Cut the root file under 200 lines / 32 KiB, and move big docs into docs/ and PLANS.md.
3. Add Do NOT introduce and Stop and ask, and hand dangerous actions to rules / hooks / sandbox instead of just writing them down.
4. Make AGENTS.md the source of truth and import it into CLAUDE.md with a one-line import. Don't maintain two.

The entry file isn't write-once-and-forget. It should grow like a test suite, every time the tool gets something wrong.

Each time the tool repeats a mistake, turn that mistake into a more specific rule. Each process you have to explain by hand, turn into a doc pointer, a hook, a rule, or a test command.

The entry file isn't the agent's knowledge base. It's the agent's working contract.

It answers four questions for you: where am I and how does the code run, how should I act when I'm unsure, how do I prove I'm done, and which calls aren't mine to make? AGENTS.md and CLAUDE.md answer the first three. The fourth goes to config, rules, hooks, sandbox, and CI.

In a month, Codex and Claude Code won't have gotten smarter. You'll just have turned your project's implicit knowledge into something they read, run, and verify before every job.

If this helped:

→ Repost it to someone whose AGENTS.md is already too stuffed to touch → Bookmark the skeleton above and copy it next time you write an AGENTS.md

Everything I'm writing as I build: voxyz.ai/insights.

• andrej-karpathy-skills (the 162K-star CLAUDE.md repo from the intro): github.com/multica-ai/andrej-karpathy-skills
• AGENTS.md (Codex official guide): developers.openai.com/codex/guides/agents-md
• Codex Best Practices: developers.openai.com/codex/learn/best-practices
• Codex Hooks: developers.openai.com/codex/hooks
• Codex Rules: developers.openai.com/codex/rules
• Codex Agent Approvals & Security (sandbox / approval): developers.openai.com/codex/agent-approvals-security
• Codex Memories: developers.openai.com/codex/memories
• PLANS.md (OpenAI Cookbook): developers.openai.com/cookbook/articles/codex_exec_plans
• Claude Code Memory (CLAUDE.md / AGENTS.md import / auto memory): code.claude.com/docs/en/memory