AGENTS.md

What Is AGENTS.md?

AGENTS.md is a plain Markdown instruction file that tells AI coding agents how to work within a software project. It is not executable configuration. Instead, it gives agents context that source code and a human-facing README may not fully explain, such as safe commands, local conventions, and areas not to change.

What AGENTS.md Is Used For

It gives an agent a reliable starting point before it edits code.

• Explain the project structure and its main components.
• Specify install, run, test, and validation commands.
• Set coding, naming, and architecture conventions.
• Mark security-sensitive or generated files as protected.
• Define review expectations, such as updating tests or documentation.

How AI Coding Agents Find and Apply Instructions

Discovery differs between tools, so teams should verify the behavior in their chosen agent.

1. The agent starts a task and scans for supported instruction files.
2. It reads applicable project-level guidance, usually near the repository root.
3. Where supported, it adds more specific folder-level instructions for files being changed.
4. It applies the relevant commands and rules while planning, editing, and checking work.

What to Put in an AGENTS.md File

Keep the file specific enough to guide work and short enough to stay relevant.

• A one-line description of the application and a small repository map.
• The package manager and focused commands, such as pnpm test --filter api.
• Important conventions, integration boundaries, and completion checks.
• Explicit guardrails, such as: “Do not change database migrations without approval.”
• A generated draft is acceptable, but a maintainer should verify every command and rule.

AGENTS.md vs CLAUDE.md and Tool-Specific Instruction Files

These files can serve similar purposes, but support and precedence are tool-dependent.

Benefits of a Focused AGENTS.md

A focused file makes AI-assisted work more predictable.

• Reduces repeated prompts about routine project rules.
• Helps agents run the right checks before proposing changes.
• Preserves local patterns, making changes easier to review.

Practical Limits and Risks

AGENTS.md is guidance, not a control system.

• Stale, lengthy, or conflicting instructions can distract an agent.
• Never include secrets, access tokens, or unsafe production commands.
• Tests, code review, access controls, and human judgment still matter.

Where to Place and Maintain AGENTS.md

Place a shared AGENTS.md at the repository root and commit it to Git. In a monorepo, add smaller folder-level files only where packages need genuinely different rules. Update the file whenever commands, architecture, or guardrails change.

Using AGENTS.md with Emergent

Clear requirements and validation boundaries help autonomous coding agents build consistently. The same discipline supports principles for building AI agents and practical app design and development in Emergent, where agents can build, test, and refine full-stack applications from natural-language requirements.