Root AGENTS.md

Scenario

You have a repository containing one application.

Most development rules apply everywhere:

• pnpm is the package manager;
• TypeScript is used for source code;
• tests should accompany behavioral changes;
• lint, typecheck, and tests are expected before completion.

The repository has several directories, but none require substantially different instructions.

A single root AGENTS.md is enough.

Repository Structure

task-manager/
├── AGENTS.md
├── src/
│   ├── api/
│   ├── features/
│   ├── shared/
│   └── index.ts
├── tests/
├── package.json
└── tsconfig.json

AGENTS.md

# Project Instructions

## Development

- Use `pnpm`.
- Write new application code in TypeScript.
- Follow the existing organization under `src/`.

## Architecture

- Keep feature-specific behavior under `src/features`.
- Keep reusable application utilities under `src/shared`.
- Follow existing patterns before introducing a new top-level source directory.

## Testing

- Add or update tests when behavior changes.
- Add a regression test when fixing a reproducible bug.
- Run tests relevant to the changed area.

## Validation

Before completing substantial source changes, run:

- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`

What This Does

The root file establishes repository-wide instructions.

Conceptually:

AGENTS.md
    ↓
src/
tests/
configuration
other repository files

The instructions are broad enough to apply throughout the project.

An agent working on:

src/features/tasks/

and an agent working on:

src/shared/

both need the same package-manager, testing, and validation guidance.

There is therefore no reason to duplicate those instructions in narrower files.

What This Does NOT Do

A repository does not need nested AGENTS.md files simply because it has multiple directories.

For example:

src/
├── api/
├── features/
├── shared/
└── utils/

does not automatically justify:

src/api/AGENTS.md
src/features/AGENTS.md
src/shared/AGENTS.md
src/utils/AGENTS.md

If those files would mostly repeat the root instructions, they create maintenance overhead without providing useful additional context.

Why These Instructions Matter

It is easy to over-engineer agent instructions.

Suppose the repository creates five scoped files containing variations of:

- Use `pnpm`.
- Run `pnpm lint`.
- Run `pnpm test`.

Now a future workflow change may require updating all five files.

Duplicated instructions can also drift.

One file might eventually say:

pnpm test

while another still references an obsolete command.

A single root file avoids this problem when the rules are genuinely repository-wide.

Key Decisions

Start at the root

A useful default is:

Begin with one root AGENTS.md.

Add narrower files only when a real scope requires additional guidance.

Put universal instructions at the broadest useful scope

Rules such as:

package manager
repository-wide validation
general source organization

usually belong at the root.

Avoid premature nesting

Do not create scoped instruction files in anticipation of complexity that does not yet exist.

Let the repository's actual differences justify additional scopes.

Keep the root useful

A root file should contain instructions that are broadly relevant.

If it becomes filled with rules for one specialized package, that is a signal that some instructions may belong in a narrower scope.

When to Use This Pattern

Use a single root AGENTS.md when:

• the repository contains one application or closely related codebase;
• most development rules apply everywhere;
• validation commands are largely shared;
• architectural differences between directories are small;
• nested files would mostly repeat the same instructions.

Start simple.

Introduce scoped instructions when the repository gives you a concrete reason.