The AGENTS.md Hierarchy

How agents inherit context at the right level of detail

The problem: context is expensive

  • Every token in an agent's context window has a cost - latency, accuracy, money
  • A backend agent doesn't need frontend conventions. A frontend agent doesn't need database schemas.
  • Loading everything everywhere wastes the window on irrelevant detail
  • Loading nothing means every session starts from scratch - rediscovering the same decisions
  • The solution: a layered hierarchy where each level adds detail only when relevant
The hierarchy gives agents the right context at the right time - broad rules globally, project decisions at the root, deep detail only in the directories that need it.

AGENTS.md: the cross-tool standard

AGENTS.md is the single source of project instructions - the cross-tool standard supported natively by OpenAI Codex CLI and readable by Claude Code via @-import lines in CLAUDE.md.

Claude Code users

Create CLAUDE.md at the repo root containing two import lines:
@AGENTS.md
@MEMORY.md

Claude Code imports both AGENTS.md and MEMORY.md transparently. No duplication needed.
Codex CLI users

Codex reads AGENTS.md natively. No extra setup required - just create AGENTS.md and it loads automatically.
Sources: Anthropic import-syntax docs · OpenAI AGENTS.md guide · agents.md

Three tiers of AGENTS.md

Global
~/.claude/CLAUDE.md
Always loaded in every Claude Code session. Behavioral rules, skill-loading triggers, universal preferences. Under ~30 lines.
Project root
[repo]/AGENTS.md
One-paragraph summary, resolved architecture decisions, repo structure, tools, conventions. Under ~40 lines.
Subdirectory
[repo]/[track]/AGENTS.md
Stack details, track-specific patterns, gotchas, schemas. Loaded only when working in that directory. Can be as detailed as needed.
Each tier inherits from the one above. An agent working in api/ sees: global rules + project root + api/AGENTS.md. The root ~40-line limit prevents context bloat; subdirectory files are loaded only in context and can be as detailed as the track requires.

What goes where

Level Contains Example
Global Behavioral rules, skill triggers, em-dash ban, commit style "Never use em dashes"
Project root Project name, decisions (brief), repo map, tools, tracker config "Base branch: main"
Subdirectory Stack, key conventions, commands, schemas, gotchas "All API routes use Zod validation"

The intent layer extends beyond AGENTS.md - each file has a distinct role (see next slide).

The intent layer

File Purpose
docs/overview/vision.md + requirements.md Operator-owned product intent - agents read, never write
decisions.md Architecture decisions with full rationale
.agentic/context.md Ephemeral session state - auto-written by the Stop hook
MEMORY.md Stable facts learned across sessions
.agentic/learnings.md Fix-pattern learnings from resolved Skeptic cycles
.agentic/findings.md Curated recurring Skeptic-finding patterns
glossary.md Ubiquitous Language - agents prefer these terms
qa.md QA triggers and accumulated runtime knowledge
Drift between code and these files is intent debt - distinct from technical debt in the code (module manifests embed the same file-level intent in the source). A stale entry is worse than a missing one because readers trust it.

How /ds-init-project scaffolds it

  1. Discovery phase - auto-detects project name, description, tracks, database, web UI, tracker
  2. Creates root AGENTS.md - one-paragraph summary, decisions section, repo structure map, tools
  3. Creates track AGENTS.md files - one per detected subdirectory (e.g. api/AGENTS.md, web/AGENTS.md)
  4. Creates supporting files - .claude/settings.json, docs structure, MEMORY.md stub
myproject/
  AGENTS.md              ← root (under 40 lines)
  CLAUDE.md              ← imports: @AGENTS.md + @MEMORY.md  (Claude Code loader)
  api/AGENTS.md          ← backend track detail
  web/AGENTS.md          ← frontend track detail
  .claude/settings.json  ← MCP servers, shared config
Running /ds-init-project is idempotent - it updates existing files and adds new tracks without overwriting what's already there.

How /ds-wrap keeps it current

What /ds-wrap reads
  • Files touched this session
  • Git diff and commit history
  • Existing AGENTS.md content
  • Current .agentic/context.md
What /ds-wrap writes
  • Updates root AGENTS.md with new decisions
  • Creates/updates track AGENTS.md files
  • Enriches .agentic/context.md with session summary
  • Adds stable facts to MEMORY.md
  • Promotes recurring or high-blast-radius Skeptic findings to .agentic/findings.md
  • If you touched a new subdirectory, /ds-wrap creates its track AGENTS.md automatically
  • Stable facts (architecture, gotchas, setup commands) get extracted and persisted
  • Ephemeral details (current task, next steps) stay in .agentic/context.md where they belong
The hierarchy grows organically. You don't plan it upfront - /ds-wrap builds it from what actually happened in each session.

Right context. Right level. Right time.

Lean roots, detailed tracks, nothing wasted.

github.com/Space-Dinosaurs/DinoStack