Write the file you keep wishing the agent had read.

This guide walks through a few ways to build CLAUDE.md and AGENTS.md files. Start with session history, a research set, a repo scan, or a conversation with the people who do the work. Then test the file on a real task.

Start with a path

synthetic examplesresearch links included

active layer01 / 05

CLAUDE.md

A short map of the repo: what to read, which commands to run, and what the team expects.

# start with the map
## Project shape
- Read docs/architecture.md before editing
- Keep the change small and local
- Run the named checks before handoff

01 / choose a route

Start with the evidence you have.

There are a few good ways to build an instruction file. Pick the route that matches your situation, then use the output as raw material for the file.

SESSION LOGS01 / 05

Mine the work you already did.

Give Claude or Codex a batch of recent session logs. Ask it to mark repeated corrections, failure cases, successful fixes, and rules you had to restate. Keep the patterns that show up more than once, then check them on a fresh task.

Collect 10-20 logsMark repeatsDraft rulesTest on a fresh task

WHAT YOU GET

You leave with candidate rules backed by examples. A human still decides what belongs in the file.

STARTING PROMPT

Review these session logs for repeated corrections, failure cases, successful fixes, and rules I had to restate.

Return:
- the pattern
- the evidence
- a proposed rule
- where the rule belongs
- a way to test it on a new task

Use the result in the file builder

The session-log route follows the same idea as a compound engineering review: use your real work to find repeated patterns, then turn only the patterns with evidence into shared instructions.

02 / mental model

Give each instruction a home.

Your repo, session history, and team research hold the raw material. Sort it, shorten it, and decide what deserves a check.

Keep the map short.

01Put each idea in the smallest layer that can hold it. Keep project memory readable. Move repeatable procedures into skills. Use checks when prose cannot hold the line.

CLAUDE.md
AGENTS.md

A short project map, commands, conventions, and links to detail.

start

rules

Rules that apply only under a path.

path

SKILL.md

A repeatable procedure with triggers, steps, references, and stop conditions.

hooks / settings

Settings and hooks for permissions and checks that prose cannot guarantee.

guard

tests / review

A fresh task, test run, or UI check that tells you whether the rule helped.

check

03 / newer context rules

Let the model do more of the choosing.

The old playbook added rules, examples, and repetition. The newer playbook keeps the useful context and leaves room for judgment.

MODEL SHIFT01 / 09

Leave room for judgment.

THEN

Add a rule for every edge case.

NOW

State the outcome and keep guardrails for real risks.

When system prompts, skills, files, and requests disagree, the agent has to sort the messages before it can work. Keep a clear boundary for risky actions. Drop rules that only repeat the obvious.

TRY THIS

Review these rules for conflict and unnecessary guardrails.

Return:
- conflicting lines
- rules that only repeat the obvious
- rules that still protect a real risk
- a keep, soften, or delete decision
- a test for each change

The goal is not fewer rules at any cost. The goal is fewer rules that compete with the task.

This section translates Anthropic's newer context-engineering guidance into a working review. Keep explicit checks for high-risk actions. Check current Claude Code behavior before making a product-specific command a team rule.

04 / context budget

Keep the root file short enough to use.

Put the first few decisions in the root file. Link to the longer procedure. If the agent has to read 200 lines before it finds the test command, the file is doing too much.

One rule, two homes

Too much in one file

# CLAUDE.md

- 78 lines of history
- edge cases we have seen
- full API reference
- package commands
- five copies of the same warning
- instructions for unrelated folders
- a giant testing manifesto
- a long list of preferences

You make the agent read all of it before the task.

Short map, linked detail

# CLAUDE.md

## Start here
- Read docs/architecture.md
- Run npm test before handoff
- Keep changes local and explain tradeoffs

## Deeper guides
- Testing: .claude/skills/testing/
- UI rules: .claude/rules/ui.md
- Release: docs/release.md

The longer example is hidden until you ask for it.

05 / scope & precedence

Scope rules to the work they affect.

A root file cannot explain each folder. Pick the file you are changing, then check which instructions apply.

Choose the file being edited

editing: apps/reporting/src/query.ts

Start here: start at the file, inspect the hierarchy, then confirm the current Claude Code or Codex rules.

04apps/reporting/AGENTS.md

Rules for this product area.

03AGENTS.md

Shared repo commands and conventions.

02~/.claude/CLAUDE.md

Your cross-project defaults.

01.claude/rules/ui.md

This UI rule sits outside a data query.

This is a teaching model. Check current docs before you make it a team rule.

06 / choose the shape

Use the setup that matches the work.

Each team needs a different file tree. Choose who needs the rule, where the work lives, and which tool must read it.

TEAM REPOSITORY01 / 05

Give the team one starting point.

Keep shared commands and conventions in the repository file. Add path rules for local work. Move longer procedures into skills.

03AGENTS.md

Shared repo rules and commands.

02apps/reporting/AGENTS.md

Rules for one product area.

01.claude/skills/

Procedures the team can load when needed.

00CI / tests

Checks that support the written rules.

Ownership: the team owns the root file. The product-area owner maintains the local rules.

Use this as a planning map. Check current Claude Code and Codex docs before you standardize discovery or precedence.

07 / file hierarchy

See which context follows the file.

A global file travels with you. A project file travels with the repo. A nested file waits for work in its directory.

global / personalproject / sharednested / on demand

For this file: the global and project files are part of the starting context. The nested file joins when work enters apps/reporting/.

NESTED FILE03 / 03

FILE TREEworking directory: apps/reporting/

├─~/.claude/global

│CLAUDE.mdall projects

├─project/repo

│CLAUDE.mdshared

└─apps/reporting/package

├─CLAUDE.mdnested

└─src/query.tsactive file

ACTIVE CONTEXTquery.ts

~/.claude/CLAUDE.mdpersonal defaults across projects

project/CLAUDE.mdshared repo context

apps/reporting/CLAUDE.mdloaded when this area is read

Local detail, inside a shared map.

Keep repo-wide commands in the project file. Add reporting rules beside the reporting code. The deeper file can stay out of unrelated tasks.

Current Claude Code docs describe ~/.claude/CLAUDE.md as user scope, ./CLAUDE.md or ./.claude/CLAUDE.md as project scope, and nested CLAUDE.md files as directory-specific context. Check the loading rules before standardizing this for Codex or another tool.

08 / skills & tools

Use the right workflow for the unknown.

These five workflows help you map decisions, surface tacit knowledge, collect current evidence, and turn repeated lessons into better instructions.

DECISION MAP01 / 05

Turn a big goal into a map of decisions.

Use Wayfinder when the work is too large for one session. It creates a low-resolution map and child decision tickets. The map stays an index. Detail lives in the ticket.

Name the destinationMap open decisionsResolve one ticketUpdate the index

WHAT IT ADDS

A short map of decisions, owners, blockers, and links. Use the map as a table of contents for the work.

STARTING PROMPT

Use Wayfinder to plan the work of creating or improving CLAUDE.md and AGENTS.md.

Define the destination. Separate decisions from tasks. Create tickets for open decisions. Keep the map as an index, not a second copy of each decision.

Use the result in the file builder

Watch for: Wayfinder plans by default. It should not turn an unresolved decision map into implementation.

Pick the workflow by uncertainty: decisions - Wayfinder, tacit knowledge - grilling, repeated learning - compound, current evidence - Last30Days, unknown territory - Scout.

table of contents pattern

Keep the root file as a registry, not a junk drawer.

A short CLAUDE.md or AGENTS.md can point to deeper files, skills, tools, and checks. That makes the starting point easy to scan. It also creates a maintenance job: rename the target, and the registry can lie.

AGENTS.md

01- Read docs/architecture.md

02- Load .claude/skills/verify-report/SKILL.md

03- Apply .claude/rules/ui.md for UI work

04- Use scripts/refresh-data.ts for data refresh

05- Check npm test before handoff

registry check5 / 5 live

docs/architecture.mdlinked

.claude/skills/verify-report/SKILL.mdlinked

.claude/rules/ui.mdlinked

scripts/refresh-data.tsexists

npm testruns

Everything points somewhere. The root file stays short because the detail has a home.

Drift watch: the registry only works while its names stay true. Rename a skill, move a document, or change a command and the short file can point nowhere. Recheck links when you prune or migrate.

This is a synthetic map. In a real repo, resolve the paths and commands with a small check. Keep the registry short, current, and owned by someone.

09 / write the file

Write down the work your team repeats.

Choose the facts and checks that belong in a durable file. Copy the example, then edit it for your repo.

Start with one file.

Good instructions name the action, the reason, and the check. “Write clean code” gives the agent nothing it can test.

Use a line when it prevents a repeated mistake. Drop it when it only sounds wise.

Choose what to keep

Project mapwhere to look first
Commandshow to run checks
Conventionshow to change code
Definition of donewhat proves completion

If you cannot name the mistake a line prevents, leave it out.

AGENTS.md / starter example

10 / improve what you have

Start with an audit when a file already exists.

Give the model the current file, a few recent tasks, and the failures that still repeat. Review the evidence before you add another line.

EXISTING FILE REVIEW01 / 04

Inspect the file and the work around it.

Read the file beside three to five recent tasks. Mark lines that repeat a fact, point to the wrong path, give a vague preference, or lack a check.

BRING THESE ALONG

current filerecent diffssession notesfailed checks

ASK THE MODEL

Review this instruction file against the attached tasks and diffs.

For each line, mark:
- keep
- move
- rewrite
- delete

Point to the evidence for each choice. Flag any line that no one can test.

Start with evidence from the repo. Do not ask for a prettier file before you know which lines caused trouble.

This path turns maintenance into a small review cycle: inspect the evidence, sort the rules, rewrite the useful ones, and try the file again.

11 / verify the loop

Pair each rule with a way to check it.

Write down the loop: read the map, make a plan, change the smallest thing, then run the checks and look at the result.

01Orient

Read the map and inspect the paths you will touch.

02Plan

State the smallest change and the tradeoff.

03Change

Edit the files the task needs.

04Verify

Run the checks and inspect the result.

Use prose for direction. Use hooks, permissions, tests, or CI when a rule must hold even if someone forgets it.

handoff console

$ run the loop
waiting for evidence...

12 / maintain the manual

Review the file after the repo changes.

A rule can help at first and become noise after a migration. Review the file with recent tasks and choose whether each line stays, moves, or goes.

“Explain the files before editing.”

It makes the agent reread the repo. Point to the architecture note instead.

“Run the reporting checks before handoff.”

It names a concrete action. Keep it in the shared project file.

“Use the old folder name from the 2024 migration.”

The path changed. Delete the line and add the current path only if the task needs it.

“For data work, read the source contract first.”

It helps people start in the right place. Keep it short and link to the contract.

13 / research layer

Keep the evidence with the rule.

The source trail includes local Last30Days runs, recent X bookmarks, primary repos, and a few web guides. Use the links as starting points, then check current docs before you copy a rule into a real repo.

Use the method on the next repo.

Make a map. Name the commands. Ask who owns each rule. Run a check that can catch the failure. Revisit the file after the next change.

Return to the beginning

primaryAnthropic / Claude Coderepo primaryClaude Code directory mapscope primaryOpenAI / Codexrepo primaryThe new rules of context engineeringAnthropic X bookmarkThe four-layer systemcontext X bookmarkThe re-reading problemmemory X bookmarkFive files, one stacksystem webStructure CLAUDE.md, skills, and agentsguide webWhere decisions should liveguide

Research note: the Last30Days runs included GitHub, web, Hacker News, Reddit, X, and video sources. Some Reddit and media results were partial. Treat social posts as signals, then verify the rule in current product docs.

Take one path into the next repo.

Pick a route above and use it on a real project. Bring back the file, the evidence behind it, and one check that tells you whether it helped.

Then show the team what you kept, what you moved, and what you cut.

Choose a path