Emerging Patterns
The field guide/Pattern 03
Living draft v0.1

PATTERN 03 / CONTEXT

Keep instructions close to the code

A small root guide, local instructions, and one source of truth across agents.

2 min readWorking draftAGENTS.md
IN ONE SENTENCE

Put durable project knowledge where the next agent can find it.

The idea

Use a root AGENTS.md for the essentials: how to start the project, which checks matter, and the constraints that are easy to miss. Add a nested file when a directory has genuinely different rules. The format supports local guidance, but discovery and precedence depend on the agent.

Think of these files as a compact orientation for a capable new teammate.

When it helps

This is useful when agents repeatedly miss the same repository convention, or when different packages have distinct build and test workflows. Avoid creating a file in every directory by habit.

Put it into practice

Keep shared instructions at the root and explain only the local differences below it. Check which files your agent actually loads, especially when starting from a subdirectory.

A small instruction hierarchy
repository/
├── AGENTS.md          # Setup, shared constraints, checks
├── CLAUDE.md          # Optional compatibility symlink
├── apps/
│   └── web/
│       └── AGENTS.md  # Browser checks and UI conventions
└── packages/
    └── engine/
        └── AGENTS.md # Engine invariants and focused tests

One source of truth

For Claude setups that need a compatibility file, a relative symlink avoids maintaining two copies. Run this only when CLAUDE.md does not already exist; merge any existing instructions first.

From the repository root
ln -s AGENTS.md CLAUDE.md

# Alternative: a CLAUDE.md file containing this import
@AGENTS.md

Current Claude Code documentation describes direct AGENTS.md support from v2.1.277, subject to settings and other instruction files. The symlink is a compatibility technique, not a universal requirement. An import is more portable for Windows teams. Check the current loading rules ↗

Where it breaks down

Instructions drift. Remove obsolete commands and duplicated rules during ordinary maintenance. Do not rely on prose as enforcement for a critical invariant: encode it in a check where possible.

Nested instructions need deliberate discovery. Verify your agent’s behavior rather than assuming every tool interprets the hierarchy identically.

Further reading