Standing instructions: AGENTS.md and CLAUDE.md

What to understand

• Standing instructions are the project's long-term memory; a task brief is its short-term memory. The brief from Lesson 5 is per-job and disposable. AGENTS.md / CLAUDE.md are durable: they encode the facts that are true for every task in this repo, how to build, how to test, where things live, what 'done' means here. Together they form a two-tier system: durable house rules in the file, job-specific detail in the brief. The file stops you re-typing the same context; the brief stays lean because it can assume the file.
• AGENTS.md is now a cross-tool open standard, not a Codex-only file. The same AGENTS.md is read by Codex, and increasingly by other agents (Cursor, Jules, and others have converged on it). Claude Code is the deliberate exception: it reads CLAUDE.md, not AGENTS.md, but it can import AGENTS.md in one line, so you still keep a single source of truth. Treat AGENTS.md as the shared base and CLAUDE.md as a thin Claude-specific wrapper around it.
• Codex resolves AGENTS.md by walking the tree and concatenating root-down. It reads global scope from ~/.codex first (AGENTS.override.md before AGENTS.md), then walks from the Git root down to your current directory, joining files with blank lines. At every level it checks AGENTS.override.md before AGENTS.md, and the override wins if both exist. Files closer to your current directory appear LAST in the combined prompt, so they override earlier guidance. Codex reads at most one file per directory, skips empty files, and stops once the combined size hits project_doc_max_bytes (32 KiB default), and crucially, if it truncates, you get no warning in the TUI, so an over-stuffed chain can silently drop your most specific rules.
• Claude Code loads CLAUDE.md by walking UP the tree, then ordering content root-down. Files in the directory hierarchy above your working directory load in full at launch; within each directory CLAUDE.local.md is appended after CLAUDE.md (so your private notes are read last at that level), and across the tree content is ordered from the filesystem root down to where you launched, so the file closest to your launch point is read last and effectively wins. Subdirectory CLAUDE.md files are NOT loaded at launch; they load on demand when Claude reads a file in that subdirectory. This is the load-order detail people get wrong: 'closer = read later = higher precedence' for ancestors, and 'deeper = lazy-loaded' for descendants.
• Claude Code has four scopes, ordered broad-to-specific. Managed policy (org-wide, e.g. C:\Program Files\ClaudeCode\CLAUDE.md on Windows, cannot be excluded by individual settings) → user (~/.claude/CLAUDE.md, your personal defaults across all projects) → project (./CLAUDE.md or ./.claude/CLAUDE.md, team-shared via source control) → local (./CLAUDE.local.md, gitignored, your private per-project notes). They load in that order, so project rules appear after user rules and take precedence on conflicts. Put each rule at the level whose audience matches it.
• What goes in these files is exactly the stuff you'd otherwise re-explain: build/test/lint commands, coding standards, project layout ('API handlers live in src/api/handlers/'), naming conventions, and 'always do X' rules. The signal-to-noise rule from the official docs is brutal and correct: vague entries actively hurt. 'Use 2-space indentation' beats 'Format code properly'; 'Run npm test before committing' beats 'Test your changes'; 'API handlers live in src/api/handlers/' beats 'Keep files organized'. A rule the agent can't verify it followed is a rule it will quietly ignore.
• Keep them short, length is a cost, not a feature. Claude Code targets under 200 lines per CLAUDE.md because longer files consume more context and measurably reduce adherence; Codex hard-caps at 32 KiB and truncates silently past it. For larger projects, split topics into .claude/rules/ files (one topic per file) that can be path-scoped with YAML frontmatter (paths: ["src/api/**/*.ts"]) so a rule only loads into context when Claude touches matching files, keeping the always-on root file lean while still having deep coverage where it's needed.
• These files are context, not enforcement, know the line. Claude's docs are explicit: CLAUDE.md is delivered as a user message after the system prompt, so there is no guarantee of strict compliance, especially for vague or conflicting rules. For anything that MUST happen at a fixed point (run lint before every commit, block writes to a path), use a PreToolUse hook, it executes as a shell command regardless of what the model decides. The mental model: file = strong suggestion the agent reads every time; hook = hard gate the harness enforces.
• Auto memory is the newer second layer, and it is separate from CLAUDE.md. Claude Code (v2.1.59+) now writes its own notes as it works, build commands, debugging insights, preferences it infers from your corrections, into ~/.claude/projects/<project>/memory/. The first 200 lines (or 25 KB) of that MEMORY.md load every session. The split that matters: CLAUDE.md is what YOU write (instructions); auto memory is what CLAUDE writes (learnings). The '#' quick-add shortcut in the REPL now saves to auto memory, not to CLAUDE.md, to change CLAUDE.md, edit it or tell Claude 'add this to CLAUDE.md'.

Deeper dive

Step by step

1

Generate a starting CLAUDE.md with /init

12

In Claude Code, run /init in your project root. Claude explores the codebase with a subagent and drafts a CLAUDE.md with the build commands, test instructions, and conventions it discovers; if a CLAUDE.md already exists it suggests improvements rather than overwriting. If the repo already has an AGENTS.md (or .cursorrules / .windsurfrules), /init reads them and incorporates the relevant parts. Set CLAUDE_CODE_NEW_INIT=1 first if you want the newer interactive multi-phase flow that also offers to scaffold skills and hooks.

Hint/init gives you a ~70% draft from what's inferable. Your job is the 30% Claude can't discover, house rules, architectural invariants, and gotchas.

On this screen

1. 1Generated build/test section. Auto-discovered commands, run each one yourself once to confirm it's correct before trusting it in every future session.
2. 2Conventions section. A starting point; refine it into concrete, verifiable rules Claude could never infer from a cold read (money-as-cents, no-DB-from-routes).

2

Trim it to the essentials and make every rule verifiable

12

Edit the generated file toward 200 lines or fewer. Delete anything Claude can rediscover cheaply; keep only durable facts: build/test/lint commands, naming conventions, project layout, and 'always do X' rules. Then rewrite every vague line into one the agent can check it followed, turn 'format properly' into '2-space indentation, no semicolons', and 'test your changes' into 'run pnpm test before reporting done'. Use markdown headers and bullets, never dense paragraphs. Done when the file is at or under ~200 lines and every remaining rule names something the agent could check it followed.

HintEvery line costs context tokens every session and dilutes adherence. If a rule only matters in one folder, it belongs in a path-scoped .claude/rules/ file, not the always-on root.

On this screen

1. 1Headed, scannable structure. Keep the ## headers and bullets, the agent scans for the section it needs the way you scan a form; walls of prose get skimmed and lost.
2. 2Specific rule example. Concrete and verifiable ('2-space indentation') reliably outperforms vague guidance ('format properly'), which the docs say is silently ignored.

3

Choose the right scope for each instruction

12

Place each rule at the level whose audience matches it. Personal preferences that follow you everywhere go in ~/.claude/CLAUDE.md (all your projects). Team-shared standards go in the committed ./CLAUDE.md (or ./.claude/CLAUDE.md). Private per-project notes, sandbox URLs, your test data, go in ./CLAUDE.local.md, which you add to .gitignore (choosing the personal option in /init does this for you). Org-wide policy lives in the managed-policy CLAUDE.md and cannot be excluded by individual settings. Remember the order: managed → user → project → local, so project rules load after user rules and win on conflict. Done when each rule lives at exactly one scope and you can say in one line who its audience is.

HintIf a rule is just yours, keep it out of the committed file, your teammates don't need your sandbox URL, and it adds noise to their context.

On this screen

1. 1Official memory docs. The page this step paraphrases. How Claude remembers your project. Keep it open while sorting rules; the scopes (managed, user, project, local) and their load order are documented here.
2. 2CLAUDE.md vs auto memory table. The visible table splits what YOU write (instructions) from what CLAUDE writes (learnings), check it before placing a rule, so instructions go in CLAUDE.md and not in auto memory's lane.

4

Set up AGENTS.md for Codex (and every other AGENTS-aware tool)

12

In your repository root, create an AGENTS.md (use the production example above as a template) with sections for the stack, exact build/test/lint commands, project layout, conventions, an always/never block, and security rules. For a subservice with different rules, add a nested file like services/payments/AGENTS.md. Codex merges from the Git root down and the deeper file wins. Use services/payments/AGENTS.override.md when you need to supersede the base file in that directory, or ~/.codex/AGENTS.override.md for a temporary global override. Keep the whole chain well under 32 KiB. Verify it is read: start a fresh Codex session and ask what this repo's build commands are, a correct answer without searching means AGENTS.md loaded.

HintCodex reads at most one file per directory, skips empty ones, and truncates silently at 32 KiB, so put each service's rules in that service's folder and don't let an over-stuffed root starve the deeper files.

On this screen

1. 1Discovery order. The visible How Codex discovers guidance section: global ~/.codex first, then Git root down to your directory, deeper files are appended later and win.
2. 2Override behaviour. The page documents AGENTS.override.md: checked before AGENTS.md at every level, the mechanism for service-specific or temporary overrides.

5

Make one file the source of truth

To avoid maintaining two near-identical files, put all shared content in AGENTS.md and create a CLAUDE.md whose first line is @AGENTS.md, then add only Claude-specific notes below it (see the wrapper example above). The first time Claude encounters the import it shows a one-time approval dialog listing the file. On Windows, prefer this @-import over a symlink, since symlinks need Administrator or Developer Mode.

HintOne source of truth means a single rule change updates both Codex and Claude at once, no silent drift, which is the classic two-file failure.

6

Verify what actually loaded, then decide file vs hook

12

In Claude Code, run /memory to list every CLAUDE.md, CLAUDE.local.md, and .claude/rules file loaded in the current session, and to toggle auto memory. If a file you expected isn't listed, Claude can't see it, check its location against the load order before assuming it was ignored. For deeper debugging, the InstructionsLoaded hook logs exactly which instruction files loaded, when, and why. Finally, audit your rules: any rule that MUST happen at a fixed point (lint before every commit, block writes to a path) should be moved out of CLAUDE.md and into a PreToolUse hook, because a file is guidance, not a guarantee.

HintWhen an instruction 'isn't working', first confirm it loaded at all, half the time the file is simply in the wrong place; the other half it's a must-happen rule that belongs in a hook.

On this screen

1. 1Loaded files list. Shows exactly which memory files are active this session, your first debugging stop when a rule seems ignored.
2. 2Auto memory toggle. Separate from CLAUDE.md; this controls the notes Claude writes for itself (build commands, learnings) across sessions.

Production prompt examples

# AGENTS.md

> Standing instructions for AI coding agents in this repository.
> Read at the start of every session. Keep under 200 lines. Concrete over vague.

## Project
- Name: payments-api. TypeScript service handling Stripe + ledger.
- Stack: Node 20, TypeScript (strict), Fastify, Prisma, PostgreSQL, Vitest.
- Package manager: pnpm. NEVER use npm or yarn in this repo.

## Build, test, lint (run these exact commands)
- Install: pnpm install
- Dev server: pnpm dev # http://localhost:3000
- Typecheck: pnpm typecheck
- Lint (must pass): pnpm lint
- Unit tests: pnpm test
- One test file: pnpm test src/ledger/posting.test.ts
- Before you say a task is done: pnpm lint && pnpm typecheck && pnpm test must all pass.

## Project layout (where things live)
- HTTP routes: src/routes/
- Business logic: src/services/
- DB access only in: src/repositories/ (never query the DB from a route)
- Shared types: src/types/
- Tests sit next to source as *.test.ts (co-located, not in a /tests dir).

## Conventions (verifiable, not vibes)
- 2-space indentation; no semicolons (Prettier config is the source of truth).
- Money is ALWAYS integer cents (bigint), never floats. No exceptions.
- Use the existing logger in src/lib/logger.ts, no console.log in committed code.
- New env vars: add to src/config/env.ts (zod schema) AND .env.example.
- Prefer immutable updates ({...obj}); do not mutate function arguments.

## Always do / never do
- ALWAYS read the file you're editing before proposing a diff.
- ALWAYS add or update a test when you change behaviour in src/services/ or src/ledger/.
- NEVER edit anything under prisma/migrations/ by hand, generate with `pnpm prisma migrate`.
- NEVER commit secrets; if you spot one, stop and flag it.
- If a task is ambiguous, ask ONE tight question instead of guessing.

## Security
- All external input is validated with zod at the route boundary before use.
- Ledger writes go through src/ledger/post.ts only, it enforces double-entry invariants.

@AGENTS.md

## Claude Code specific

- Use plan mode for any change under src/billing/ or src/ledger/, show the plan and wait for approval before editing.
- When you finish a task, run /memory mentally: did you violate any rule above? If so, fix it before reporting done.
- For multi-step refactors, prefer creating a short checklist and working through it rather than one giant diff.

<!-- maintainer note: keep this wrapper tiny. All real rules live in AGENTS.md so Codex and Claude never diverge. This comment is stripped before it reaches Claude's context. -->

Common mistakes to avoid

• Letting the file grow past a couple hundred lines (or past 32 KiB on Codex, where it truncates with no warning), both burn context and lower how reliably the agent follows any single rule.
• Writing vague rules ('write clean code', 'handle money carefully') instead of concrete, verifiable ones ('integer cents only', 'run pnpm lint before finishing'), the docs say vague rules are silently ignored.
• Expecting CLAUDE.md / AGENTS.md to enforce a must-happen step, it's guidance delivered as a user message, not a guarantee; use a PreToolUse hook for hard enforcement.
• Maintaining separate AGENTS.md and CLAUDE.md by hand until they silently drift apart, instead of importing one from the other with @AGENTS.md.
• Getting precedence backwards, assuming the root file wins when in fact the file closest to your working directory is read last and effectively overrides it.
• Putting a multi-step procedure in CLAUDE.md when it should be a skill (loads on demand), or a personal sandbox URL in the committed project file when it should be in gitignored CLAUDE.local.md.
• Assuming a rule is loaded without checking, when it 'isn't working', forgetting to run /memory first to confirm the file was even seen.

Source conflicts to review

• Codex's AGENTS.md guide and third-party 2026 write-ups agree on the 32 KiB project_doc_max_bytes default and silent truncation, but community reports (e.g. openai/codex issue #7138) note the truncation gives no TUI warning, verify the current cap and any warning behaviour in your installed Codex version's config (config.toml).
• Claude Code's '#' quick-add shortcut historically wrote to CLAUDE.md in older guidance; current official docs route it to AUTO MEMORY, not CLAUDE.md. Behaviour depends on version (auto memory needs v2.1.59+), confirm in /memory which store received your note.