AGENTS.md
AGENTS.md is an instruction file for agents placed at the root of the repository, which has become the closest thing to a universal standard for telling an agent how to work on a project. It is the usual vehicle for the project constitution and for project boundaries in spec-driven development.
Where agent instructions live is no longer up to each individual tool. AGENTS.md is read natively by some 20 coding tools, has been adopted by more than 60,000 projects, and its specification has been stewarded since December 2025 by the Agentic AI Foundation, under the Linux Foundation. For the team, the practical consequence is that the constitution and the project boundaries have a home that any agent understands, regardless of vendor: writing them once in that format avoids maintaining separate versions for each tool.
The boundaries system: Always / Ask First / Never
The most distinctive content of an AGENTS.md file is the boundaries system, a three-level delegation framework that goes beyond a flat list of prohibitions:
| Level | Meaning | Examples |
|---|---|---|
| Always (always do) | Actions the agent carries out without asking. | Running the tests before a commit, following naming conventions, logging errors. |
| Ask First (ask before acting) | Actions that might be correct but require approval because of their impact. | Modifying the database schema, adding new dependencies, changing the public API. |
| Never (never do) | Absolute red lines. | Committing secrets, editing dependency directories, modifying the production configuration. |
The system grants autonomy where it is safe (Always), creates checkpoints where they are needed (Ask First), and sets unambiguous red lines (Never). It is not static: as the team gains trust, something that is Ask First today may move to Always, and something once thought harmless may be raised to Ask First after an incident. It is gradual autonomy, much like how we delegate more and more to a professional who demonstrates sound judgement.
Two scopes: project and task
Boundaries operate at two levels. In the constitution, they set the general rules that apply to everything that gets built. In each task, they add the specific constraints of that implementation (the third field of the four-field prompt; see Atomic tasks and atomic commits). The combination provides global consistency and local precision. "Never commit secrets" is a project-level boundary; "don't touch the existing entry points" belongs to the specific task.
Common mistake
A flat list of prohibitions. Without levels, the agent doesn't know what it can do on its own, what to ask about, and what to avoid. Nor is it advisable to keep everything in Ask First indefinitely—it wastes the trust already earned and floods the team with queries—or to confuse project scope with task scope. And the fact that the file exists and every tool reads it says nothing about whether its rules are the right ones: the team decides the content and reviews it with the same deliberation as the constitution.
Resources
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
🏦 SDD en equipos ágiles [SDD in Agile Teams, in Spanish]Skill Arena · Scrum Manager
References
- AGENTS.md (format specification).
- Agentic AI Foundation / Linux Foundation. (2025). Stewardship of the AGENTS.md specification.
- Osmani, Addy. (2025). "How to write a good spec for AI agents."
See also
Want to advance in agility? You can search for course and exam calls or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.