## Definition **`AGENTS.md`** is a project-owned system prompt that the agentic CLI loads into every session started in the repo. It is where the team's *standing rules* live — conventions that apply to every task, not procedures invoked on demand. A cross-tool convention (Claude Code, OpenCode, Cursor agent mode, Continue). ## Companion File **`CLAUDE.md`** holds Claude Code-specific additions only (skills, sub-agent routing, MCP). Portable rules go in `AGENTS.md`; tool-specific instructions in `CLAUDE.md`. Duplication between the two is a smell. ## What Belongs High signal-to-token ratio. Things the agent cannot infer from the code: - Stack and commands (one line each). - Non-obvious rules with rationale. - How the team works with agents on this repo. ## What Does NOT Belong - Anything inferable from 2–3 source files ("we use TypeScript"). - Stale war stories — use git history. - Long lists of "important files" — the agent can search. - Prompts. This file holds standing rules, not the current task. ## Heuristic > If a fact would be true tomorrow even if half the code changed today, it probably belongs in `AGENTS.md`. If it would be stale by Friday, it doesn't. ## Keeping It Honest - Treat as code: review, version, audit. - Run an audit quarterly: have an agent read `AGENTS.md` and list rules it believes are no longer applied. Delete what's dead. - Aim for **under 80 lines**. ## Related - [[Agentic CLI]] - [[Skill]] - [[Hook]] - [[Architecture Decision Record]]