Put Guidance in the Right Layer

Lesson 3 · Customization · ~12 minutes

Codex behavior comes from several layers. Reliability improves when each instruction lives at the narrowest scope that genuinely needs it.

One task only               → prompt
Every task in one repo      → AGENTS.md
Codex settings for one repo → .codex/config.toml
Your defaults everywhere   → ~/.codex/config.toml
Repeatable procedure        → skill

How Precedence Works

Codex reads global guidance, then walks from the repository root toward the current directory. Guidance closer to the working directory wins. Configuration follows a similar layering model, with one-off CLI flags taking highest precedence.

Feedback loop

Do not pre-populate a huge AGENTS.md. Add build commands, verification criteria, and conventions; then add a rule only after repeated friction demonstrates its value.

A Useful Starter

# AGENTS.md
## Verification
- Run `make test` after changing application code.
- Run `make lint` before reporting completion.

## Constraints
- Ask before adding production dependencies.
- Keep unrelated refactors out of bug fixes.

Follow the Instruction Chain

Suppose you launch Codex from services/payments/. Codex reads global guidance first, then the repository root, then each directory down to the current one. The closest applicable instruction wins.

~/.codex/AGENTS.md                 personal defaults
repo/AGENTS.md                    team-wide rules
repo/services/AGENTS.md           service conventions
repo/services/payments/AGENTS.md  payment-specific rules

This lets broad rules stay broad while specialized commands remain close to the code they govern. An override file is useful for a genuine replacement, but ordinary nested guidance is easier to reason about.

Separate Instructions from Enforcement

Statement	Best home
“Run `make test-payments` here.”	Nested `AGENTS.md`
“Formatting must pass.”	Formatter or CI, referenced by guidance
“Use workspace-write by default.”	`config.toml`
“Prepare releases using these eight steps.”	Skill

Instruction debt

Vague rules such as “write clean code” consume context without changing behavior. Keep commands, constraints, routing guidance, and verification criteria; delete slogans.

Check Your Understanding

Where should a rule that applies to every task in one repository live?

Repository instructions in AGENTS.md
Personal defaults in config.toml
Reusable workflow in skill

Correct. Repository-wide working agreements belong in the root AGENTS.md.

Use AGENTS.md for durable repository guidance; settings and workflows have different jobs.

Do This Now

In one active repository, draft five lines covering the real test command, lint command, dependency policy, scope constraint, and definition of done. Then launch Codex from the root and a nested directory and ask it to list the active instruction sources in precedence order.

Primary Sources

Custom instructions with AGENTS.md and Config basics.

Questions? Paste an existing Kiro or Claude instruction file and ask me to classify each line by Codex layer.

← Previous Next →