AGENTS.md Hierarchy Design - Global, Project, and Subdirectory Guidance

AGENTS.md is the repository contract Codex reads before starting work. It can define coding conventions, required specifications, protected areas, verification commands, and operations that require approval.

Discovery order

Codex builds an instruction chain when a session starts.

1. ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md
2. AGENTS.override.md or AGENTS.md files from the Git root down to the current directory
3. Guidance is combined from root to current directory, so closer files appear later and take precedence

~/.codex/AGENTS.md
project/AGENTS.md
project/apps/web/AGENTS.md

Starting Codex inside apps/web loads all three levels. An AGENTS.override.md file takes priority over AGENTS.md at the same level.

What belongs in the root file

The root file should contain repository-wide contracts only.

# AGENTS.md

## Read Order
1. Read this file.
2. Read applicable rules in `shared/rules/`.
3. Read the task-specific skill.

## Non-Negotiable Rules
- Do not deploy without explicit approval.
- Keep Japanese content as the source of truth.

## Verification
- Run `npm run harness:check` after harness changes.

Move long procedures into shared/rules/, shared/skills/, or specifications. Treat AGENTS.md as a concise map of reading order, ownership, and critical boundaries.

When to add nested guidance

Add a nested AGENTS.md only when an area has distinct requirements.

Area	Local guidance
apps/web/	UI tests, accessibility, browser checks
packages/database/	Migration policy and destructive-change approval
src/content/docs/	i18n, frontmatter, and link validation

Verification Method

Ask Codex to list the active instruction files and precedence to verify discovery. Next, config.toml design covers executable configuration rather than prose guidance.