AGENTS.md
also called Project instructions file
A plain file in the repo that tells agents how this project works.
A convention for a checked-in file at the repo root (and in subdirectories) that gives agents project context: build commands, conventions, gotchas, what not to touch. Agents read it automatically.
It is onboarding documentation for a very literal new teammate. The best ones are short, concrete and command-focused — "run pnpm test, never edit generated/, use the Result type" — not aspirational prose.
The value scales with the cost of being wrong. Commands the agent must type, conventions that would otherwise be guessed, and files it must not touch are all worth writing down once rather than correcting repeatedly. Keep it short: everything in it competes for attention on every task.
The file that stops the same mistake twice
Every new session generates migrations the wrong way.
Add one line naming the migration command and the rule that generated files are never edited by hand. Two lines in the repository replace an untold number of corrections, and they apply to every future session and every teammate.
- docsClaude Code overview ↗
A first-party description of the surfaces an agentic coding tool ships on, including parallel sessions and long-running tasks. Not evidence that it improves productivity.
- docsBest practices for using GitHub Copilot to work on tasks ↗
Recommends bounded tasks with explicit acceptance criteria, and names what is a bad fit for unattended delegation: ambiguous, security-sensitive, production-critical or deeply domain-specific work.
Skill · Capability
A packaged procedure the agent can load when the task calls for it.
Context Pointer · Reference
A cheap reference to something the agent can fetch if needed.
Progressive Disclosure
Reveal detail only when it becomes relevant.
Spec · Specification
A written description of the intended outcome, before the work starts.