How AGENTS.md Works

Knowing what AGENTS.md is isn't enough.

To use it effectively, you need to understand three concepts:

1. Discovery — how an agent finds instructions.
2. Scope — where those instructions apply.
3. Precedence — what happens when multiple instructions exist.

1. Discovery

A coding agent looks for applicable instruction files when working inside a repository.

The simplest setup is:

my-project/
├── AGENTS.md
├── package.json
├── src/
└── tests/

The root AGENTS.md contains instructions intended for the repository.

For example:

# Project Guidelines

- Use TypeScript.
- Use `pnpm` for package management.
- Run `pnpm test` before completing changes.

These instructions establish the project's general working rules.

Exact discovery behavior can vary between coding-agent tools. Always check the documentation for the tool you're using.

2. Scope

Large repositories often contain areas with different requirements.

Consider:

my-project/
├── AGENTS.md
│
├── frontend/
│   ├── AGENTS.md
│   └── src/
│
└── backend/
    ├── AGENTS.md
    └── src/

The root file can contain repository-wide instructions:

# Repository Guidelines

- Use `pnpm`.
- Run linting before completing changes.
- Never commit secrets.

The frontend file can contain frontend-specific instructions:

# Frontend Guidelines

- Use React functional components.
- Use Tailwind CSS for styling.
- Add `"use client"` only when required.

The backend file can contain different instructions:

# Backend Guidelines

- Validate API input using Zod.
- Keep business logic inside services.
- Add tests for new endpoints.

This allows instructions to live close to the code they describe.

3. Why Scope Matters

Without scoped instructions, the root AGENTS.md can become huge:

# Frontend Rules

...

# Backend Rules

...

# Mobile Rules

...

# Infrastructure Rules

...

# Database Rules

...

Most of those instructions may be irrelevant to the agent's current task.

Instead:

AGENTS.md

frontend/
└── AGENTS.md

backend/
└── AGENTS.md

mobile/
└── AGENTS.md

Each area can contain focused instructions.

This reduces unnecessary context and makes instructions easier to maintain.

4. General vs Specific Instructions

Think of instructions as moving from:

General
   ↓
More specific
   ↓
Task-specific

For example, the root might say:

- Add tests for new business logic.

The backend might be more specific:

- Use Vitest for service-layer unit tests.

These instructions don't conflict.

Together they tell the agent:

Add tests, and for backend service tests use Vitest.

5. What Happens When Instructions Conflict?

Consider:

Root AGENTS.md

- Use npm for package management.

frontend/AGENTS.md

- Use pnpm for package management.

Now the instructions conflict.

In systems supporting hierarchical AGENTS.md instructions, the more specific applicable instruction generally takes precedence.

For work inside frontend/, that would mean using:

pnpm

However, exact precedence behavior is ultimately determined by the coding agent being used.

This is why you should avoid unnecessary conflicting instructions.

6. Example: Monorepo

Consider a repository containing:

commerce-platform/
│
├── AGENTS.md
│
├── apps/
│   ├── web/
│   │   ├── AGENTS.md
│   │   └── src/
│   │
│   └── api/
│       ├── AGENTS.md
│       └── src/
│
└── packages/
    └── shared/

Root AGENTS.md

# Repository Guidelines

- Use `pnpm`.
- Run `pnpm lint` before completing changes.
- Do not modify generated files.

apps/web/AGENTS.md

# Web Application

- Use Next.js App Router.
- Prefer Server Components.
- Use Tailwind CSS for styling.

apps/api/AGENTS.md

# API

- Validate request payloads with Zod.
- Keep database access inside repositories.
- Add tests for new API endpoints.

Now an agent modifying:

apps/web/src/app/page.tsx

receives repository-wide guidance plus the relevant web-app guidance.

An agent modifying:

apps/api/src/users/service.ts

instead works with the repository guidance plus API-specific instructions.

7. Don't Create Nested Files Without a Reason

This doesn't mean every directory needs an AGENTS.md.

❌ Avoid:

src/
├── AGENTS.md
├── components/
│   ├── AGENTS.md
│   ├── buttons/
│   │   └── AGENTS.md
│   └── forms/
│       └── AGENTS.md

unless those directories genuinely have different working rules.

Too many instruction files make the repository harder to understand and maintain.

Create a nested AGENTS.md when an area has meaningfully different instructions.

8. Codex Example

Codex supports hierarchical project instructions.

At a high level, Codex builds its applicable instruction set from broader instructions toward more specific repository instructions.

This makes a structure such as:

AGENTS.md
        ↓
apps/
        ↓
apps/web/AGENTS.md

useful for giving Codex increasingly specific guidance.

Codex also supports additional instruction-file behavior and configuration beyond the basic open AGENTS.md convention.

Those details are Codex-specific, not universal AGENTS.md behavior.

9. A Useful Mental Model

Think of AGENTS.md like instructions attached to areas of your codebase.

Repository
│
│  "Rules for everything"
│
├── Frontend
│      "Additional frontend rules"
│
├── Backend
│      "Additional backend rules"
│
└── Mobile
       "Additional mobile rules"

The closer the instruction is to the code being changed, the more specific it can be.

Good Practice

Keep root instructions broad:

- Use `pnpm`.
- Never commit secrets.
- Run linting before completing changes.

Keep specialized instructions close to their relevant code:

# Backend

- Validate incoming API payloads using Zod.
- Use repository classes for database access.

Common Mistake

Don't copy the same instructions into every nested file.

❌

Root:
Run pnpm lint.

Frontend:
Run pnpm lint.

Backend:
Run pnpm lint.

Mobile:
Run pnpm lint.

If a rule applies everywhere, keep it at the appropriate higher scope.

Key Takeaway

When working with AGENTS.md, think in terms of:

Discovery → Scope → Specificity

Use the root AGENTS.md for repository-wide guidance.

Use nested AGENTS.md files only when parts of the repository genuinely need more specific instructions.

And remember:

AGENTS.md is an open convention, but the exact discovery and precedence behavior is implemented by the coding agent.

Always distinguish general AGENTS.md practices from tool-specific behavior.

Up Next

What Belongs in AGENTS.md

Next we'll decide which instructions are actually useful enough to include—and which information should live somewhere else.