Vol. X · Field Operations · X.1
AGENTS.md as Constitution
AGENTS.md (and CLAUDE.md, and the Cursor rules file) is the repo's standing prompt. It is owned policy: how to build, test, and stop. Keep it short, imperative, and true, or the agent will ignore it and invent a culture.
7 min read
Doctrine
- One constitution at the repo root. Nested files override locally, they do not contradict globally.
- Say what to run, where to look, and what never to do. Do not write a novel about the company mission.
- The constitution is source: diff it, review it, test that agents still follow it.
What belongs in the constitution
Build and test commands. Package manager. Branch and PR rules. Secrets and prod boundaries. Links to skills for depth. Codex, Claude Code, Gemini CLI, Goose, and Aider all read a standing file. agents.md is the cross-vendor name. Treat it as Factor 2 at repo scale.
Push depth to skills. The constitution points; the skill teaches.
Anti-patterns
- A 4,000-line AGENTS.md that restates every style nit.
- Six overlapping rule files that fight (Cursor, Copilot, Claude, Codex) with no source of truth.
- Instructions the repo itself does not follow.