AGENTS.md

AGENTS.md is a universal standard with two distinct jobs: a global file of personal preferences injected into every session at harness level, and a repo-level file that serves as an agent’s entry point into a codebase. The rules for each are almost opposite.

Global: every line earns its place

Your global AGENTS.md is injected into all new sessions, so it must never be specific to a repo, language, or task. The heuristic that has won out as models have improved: less is more. Keep it minimal, ideally hand-written, and limited to two categories:

• Universally relevant preferences - how you like to be communicated with, conventions that apply everywhere.
• Corrections for failure modes you have actually observed - not ones you imagine.

Lengthy global files used to be common. The consensus has moved: if your AGENTS.md includes lines like “don’t commit secrets”, you’re behind the curve - frontier models already know, and every wasted line is context spent before the session starts.

Repo-level: an entry point, not a manual

At repo level, AGENTS.md is a powerful tool. Most harnesses inject it directly into context, making it the first thing an agent reads. It should:

• Give a high-level overview of the repo’s purpose and structure.
• Point to the most relevant files, docs, and path roots - pointers, not prose.

For larger codebases and monorepos, nested AGENTS.md files can serve distinct modules or services - but use the fewest possible, and add one to correct an observed failure mode, not for the sake of coverage. Frontier models are now very good at reasoning over large repos: they dispatch explorer subagents, gather context about specific areas, and synthesise. Trust that machinery; write the map, not the territory.