AGENTS.md: Designing the Repository Contract for AI Coding Tools

AI coding tools can now inspect a repository, modify multiple files, run tests, and open pull requests with limited supervision. Their biggest limitation is not code generation. It is context.

An agent may produce syntactically correct code while violating local conventions, changing the wrong abstraction, skipping required checks, or misunderstanding how a service is deployed. The repository often contains the information needed to prevent these mistakes, but that information is scattered across README files, scripts, issue history, team habits, and tribal knowledge.

AGENTS.md addresses this problem by giving the repository an explicit operating contract for AI coding tools.

It is more than a prompt stored in a file. When designed well, it becomes a maintainable interface between human engineering intent and machine execution. It tells agents how to orient themselves, which constraints matter, how to validate changes, and when to stop and ask for clarification.

This guide explains how to create that contract, where to place it, what to include, and how to keep it useful as the codebase evolves.

What Is AGENTS.md?

AGENTS.md is a Markdown instruction file that provides repository-specific guidance to coding agents. It can describe:

• The architecture and boundaries of the project
• Commands for installing dependencies, running tests, linting, and building
• Coding and naming conventions
• Rules for modifying generated files, migrations, APIs, or infrastructure
• Security, privacy, and compliance requirements
• Expectations for pull requests and commit-ready changes
• Directory-specific instructions for complex areas of the repository

The exact behavior depends on the AI coding tool. Some tools automatically look for AGENTS.md. Others support similar files with different names, locations, or precedence rules. Therefore, treat the filename as an emerging convention rather than a universal technical standard.

The important idea is the repository instruction layer.

A typical project might begin with a root-level file:

repository/
├── AGENTS.md
├── README.md
├── package.json
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   └── api/
│       └── AGENTS.md
├── packages/
│   └── design-system/
│       └── AGENTS.md
└── scripts/

The root file establishes global expectations. Nested files can refine those expectations for a specific application, package, or subsystem.

For example, the root file might say that all changes must pass the repository test suite. An apps/api/AGENTS.md file might add that database schema changes require a migration, a rollback plan, and a specific integration test.

Key Insight: An AI coding tool does not need more instructions by default. It needs the right instructions at the right scope, expressed as verifiable repository behavior.

Why Repository Instructions Matter

Without a repository contract, agents tend to infer intent from incomplete evidence. They may prioritize the most visible README, follow outdated examples, or choose a familiar framework pattern that conflicts with local architecture.

This creates several predictable failure modes.

1. Correct code in the wrong place

An agent may introduce a new utility when an established shared package already exists. It may add business logic to a controller instead of the domain layer, or bypass a service boundary because the shortest implementation appears locally reasonable.

2. Incomplete validation

An agent may run a fast unit test and report success even though the project requires type checking, database tests, generated client updates, or an end-to-end suite.

3. Unsafe changes

An agent may edit authentication middleware, deployment configuration, secrets handling, or database schemas without understanding the consequences. A clear instruction file can require human approval for high-risk areas.

4. Inconsistent collaboration

If every developer gives an agent different instructions, the codebase becomes dependent on individual prompting habits. A repository contract moves important guidance into a shared, reviewable artifact.

5. Context waste

Agents spend tokens and execution time searching for information that the maintainers already know. A concise map of the repository improves both speed and accuracy.

The goal is not to eliminate agent judgment. The goal is to constrain judgment where the project has already made a decision.

How to Write an Effective AGENTS.md

A useful AGENTS.md should be operational rather than aspirational. “Write clean, maintainable code” is difficult for an agent to apply consistently. “Run pnpm lint, pnpm typecheck, and the affected package tests before proposing completion” is actionable.

Use the following structure as a practical starting point.

1. Define the project in a few lines

Start with a compact orientation section:

# Repository Guide

## Purpose

This repository contains the customer billing platform. It includes a TypeScript API,
a React dashboard, background workers, and shared packages.

## Primary stack

- Node.js 22
- TypeScript with strict mode enabled
- PostgreSQL
- React and Vite
- pnpm workspaces

This context helps an agent form an initial model before it explores individual files.

Avoid turning the opening into a long company history. The first section should answer:

• What does this repository do?
• What are its major components?
• Which languages and tools are central?
• Is it a monorepo, service, library, or application?

2. Explain the repository map

Agents need to know where responsibilities belong.

## Repository layout

- `apps/web`: Customer-facing dashboard
- `apps/api`: HTTP API and request handlers
- `apps/worker`: Asynchronous job processing
- `packages/domain`: Shared business rules
- `packages/ui`: Reusable interface components
- `db/migrations`: Versioned database migrations
- `scripts`: Local development and CI utilities

Include architectural boundaries that are not obvious from directory names. For example:

Business rules belong in `packages/domain`. Do not place billing calculations
inside HTTP handlers or React components.

This is more valuable than a generic statement about clean architecture because it identifies the actual decision the agent must preserve.

3. Document the command contract

One of the most valuable sections is a reliable command reference.

## Development commands

Install dependencies:

    pnpm install

Start the local application:

    pnpm dev

Run unit tests:

    pnpm test

Run tests for one package:

    pnpm  - filter @company/domain test

Run linting:

    pnpm lint

Run type checking:

    pnpm typecheck

Build all packages:

    pnpm build

Also explain prerequisites and known limitations:

- Use Node.js 22 and pnpm 9.
- Local integration tests require Docker.
- Do not run production migration commands against local development databases.
- If a command fails because a service is unavailable, report the failure instead of
  claiming validation succeeded.

Agents frequently confuse “the command ran” with “the repository is valid.” Your instructions should distinguish:

• Commands that are required for every change
• Commands that are required only for certain directories
• Commands that are expensive or environment-dependent
• Commands that cannot be run by an agent and require human verification

4. State coding and design conventions

Focus on conventions that affect implementation decisions.

## Coding conventions

- Use named exports for shared modules.
- Prefer immutable data transformations.
- Validate external input at the API boundary.
- Do not introduce a new dependency when an existing package provides the capability.
- Use the repository error types instead of throwing ad hoc strings.
- Add tests for new business behavior and regression cases.

Avoid copying a complete style guide into AGENTS.md. Link to authoritative documents when they exist, and reserve this file for rules an agent must know while working.

5. Define change-specific safety rules

Some paths deserve explicit caution.

## High-risk areas

Changes to the following require focused tests and a clear explanation in the pull request:

- `db/migrations`
- Authentication and authorization middleware
- Payment provider integrations
- Infrastructure and deployment files
- Public API schemas
- Personal data processing

Do not edit generated files directly. Update the source schema or generator,
then run the appropriate generation command.

This section can also define when an agent should stop:

Ask for clarification before proceeding if:

- The requested change conflicts with an existing architectural boundary.
- A database migration may delete or transform production data.
- A new secret, permission, or external service is required.
- The expected behavior is ambiguous and cannot be resolved from tests or documentation.

A strong repository contract gives the agent permission to pause. That is a feature, not a failure.

Repository Instructions and Instruction Precedence

Large codebases need more than one level of guidance. A practical hierarchy usually looks like this:

1. Organization or platform policies
2. Repository-level AGENTS.md
3. Nested AGENTS.md files in the relevant directory
4. Task-specific instructions from the issue or user
5. Existing code, tests, and configuration

The exact precedence varies between tools, so document your expected behavior and verify it with the tools your team uses.

Nested instructions should add local detail, not repeat the entire root document. For example:

AGENTS.md
apps/api/AGENTS.md
apps/api/src/payments/AGENTS.md

The root file might establish general TypeScript and testing rules. The API file can describe request validation and response conventions. The payments file can specify idempotency, provider mocks, audit logging, and approval requirements.

Scope instructions carefully

A directory-level file should apply only to the code it governs. Avoid placing a broad instruction in a deeply nested directory if agents may edit files outside that scope.

A useful rule is:

• Put universal rules at the root
• Put subsystem rules near the subsystem
• Put temporary task guidance in the issue or pull request, not in permanent repository instructions

Watch for conflicting rules

Conflicting instructions create unpredictable agent behavior and confuse human contributors. Review nested files for contradictions involving:

• Package managers
• Test commands
• Formatting tools
• API design
• Generated artifacts
• Dependency policies
• Security approvals

When a local exception exists, state it explicitly:

The general repository rule prefers pnpm. This package is published independently
and must use npm for release verification.

The AGENTS.md Quality Framework

A repository contract should be evaluated like an engineering interface. Use this five-part framework.

Discoverable

Can a new contributor or coding agent find it immediately?

• Place the primary file at the repository root.
• Link to nested guides.
• Mention the file in the main README when appropriate.
• Use clear headings and predictable terminology.

Specific

Does each instruction describe an actual decision?

Weak:

Keep the code high quality.

Strong:

All API input must be parsed with the schemas in `packages/validation`.
Do not access request body fields before schema validation.

Verifiable

Can the instruction be checked through a command, test, file location, or review criterion?

Weak:

Make the service reliable.

Strong:

Changes to retry behavior must include a test covering timeout, retry exhaustion,
and duplicate request handling.

Minimal

Does the file contain the smallest amount of context needed to guide work?

Long instructions are not automatically better. Excessive prose increases the chance that the most important rules will be overlooked. Prefer concise bullets, examples, and links to source documentation.

Maintained

Is the document reviewed when the repository changes?

Treat stale instructions as a defect. A command that no longer works can be worse than no command because it creates false confidence.

A Step-by-Step Rollout Plan for Teams

Introducing repository instructions does not require a large governance project. Use a staged rollout.

Step 1: Observe agent failures

Review recent AI-assisted changes and identify recurring issues:

• Repeatedly incorrect test commands
• Misplaced files
• Duplicate utilities
• Broken generated code
• Unsafe configuration edits
• Missing migration or API documentation

These failures reveal what the repository contract needs to state.

Step 2: Draft the smallest useful root file

Start with:

• Project purpose
• Repository map
• Development commands
• Required validation
• High-risk paths
• Stop conditions

Do not attempt to document every convention in the first version.

Step 3: Test the instructions against real tasks

Give an agent representative work:

• A small bug fix
• A new endpoint
• A refactor
• A test-only change
• A dependency update

Observe whether it finds the correct directories, chooses the correct commands, and respects the stated boundaries.

Step 4: Add local instruction files selectively

Create nested AGENTS.md files only where the local rules are materially different. Good candidates include:

• Monorepo applications
• Public libraries
• Infrastructure code
• Database systems
• Security-sensitive integrations
• Generated SDKs or clients

Step 5: Make validation enforceable

An instruction file cannot replace CI. Pair it with automated checks for rules that must never be skipped.

| Contract area | Human-readable guidance | Automated enforcement | | - - | - - | - - | | Formatting | Use the repository formatter | CI formatting check | | Types | Keep strict type checking enabled | Type-check job | | Tests | Run affected tests before completion | CI test suites | | Dependencies | Avoid unapproved packages | Lockfile and policy checks | | Security | Do not expose secrets or sensitive data | Secret scanning and security review | | Database changes | Add reversible, reviewed migrations | Migration validation |

Step 6: Review the file like production code

Assign ownership and include changes to AGENTS.md in normal code review. Ask:

• Is this instruction still true?
• Is it precise enough to act on?
• Can it be verified?
• Does it duplicate another source of truth?
• Could it create a security or maintenance risk?

Common Mistakes to Avoid

Turning AGENTS.md into a universal prompt

The file should describe the repository, not attempt to define an agent’s entire personality or reasoning process. Avoid generic instructions such as “be intelligent,” “think deeply,” or “always produce perfect code.”

Listing commands without explaining when to use them

A large command catalog creates noise. Categorize commands by purpose and scope, and identify required checks.

Duplicating documentation

If the architecture is documented in a dedicated design document, link to it. Duplicated content will drift.

Encoding temporary preferences as permanent rules

A one-week migration constraint does not belong in a durable repository contract unless it is clearly marked with an owner and expiration date.

Trusting the agent’s report without independent validation

An agent can misunderstand a command result or fail to run a required check. CI, code review, and branch protection remain essential.

Treating AGENTS.md as a security boundary

The file is guidance, not an authorization system. It cannot prevent a malicious prompt, compromised tool, unsafe dependency, or unauthorized access. Apply least-privilege permissions, protect secrets, isolate execution environments, and review changes to sensitive code.

A Practical Starter Template

The following template is intentionally compact:

# Repository Guide

## Purpose

Briefly describe what this repository contains and who uses it.

## Structure

- `path/`: responsibility
- `path/`: responsibility
- `path/`: responsibility

## Stack and prerequisites

- Runtime:
- Package manager:
- Required services:
- Environment setup:

## Development commands

- Install:
- Run locally:
- Test:
- Lint:
- Type check:
- Build:

## Implementation rules

- Rule with a concrete location or example
- Rule with a concrete location or example
- Rule describing how to reuse existing abstractions

## Validation

Before proposing completion:

1. Run the relevant tests.
2. Run linting and type checks for affected packages.
3. Update generated artifacts when their sources change.
4. Report any checks that could not run and explain why.

## High-risk changes

List files or systems requiring additional testing, approval, or clarification.

## Stop conditions

Ask for clarification when requirements conflict, data loss is possible,
or the change requires new access, secrets, or external infrastructure.

## Further documentation

- Link to architecture documentation
- Link to contribution guidelines
- Link to deployment or security guidance

The New Repository Contract

The emergence of AGENTS.md signals a broader shift in software development. Repositories are no longer written only for human readers. They are becoming operational environments in which AI coding tools inspect structure, infer intent, execute commands, and propose changes.

That creates a new responsibility for engineering teams: make important decisions legible.

A repository contract should not attempt to predict every future task. It should establish the stable facts that agents must respect:

• Where code belongs
• Which abstractions already exist
• How changes are validated
• Which areas require caution
• When uncertainty requires a human decision

The best result is not an agent that acts autonomously at all costs. It is an agent that can move quickly within known boundaries and reliably surface the moments that demand expertise.

Start with a small, precise AGENTS.md. Test it against real work. Connect it to CI and review practices. Then evolve it as the repository and its AI tooling mature.

Conclusion

AGENTS.md is becoming a practical foundation for AI coding tools because it turns implicit engineering knowledge into an explicit repository contract.

Its value comes from precision, scope, and maintenance. A concise guide that names the correct commands, architectural boundaries, validation rules, and stop conditions can prevent more mistakes than a long generic prompt.

For teams adopting agentic development, the next step is straightforward: document how the repository should be understood before asking an agent to change it.

Related Reading

• Terminal Agents vs. AI IDEs: Architecting the Ultimate 2026 Developer Workflow

• From Vibe Coding to Production: Guardrailing Agentic Workflows Against Architectural Decay

• Why Git Is the Best Database for Multi-Agent AI