Skip to main content
AGENTS.md works especially well in monorepos. You can place one file at the root for project-wide conventions and additional files inside individual packages for package-specific instructions. Agents automatically read the nearest file in the directory tree.

​
How precedence works

The closest AGENTS.md to the file being edited takes effect. Explicit user chat prompts override everything.
When an agent edits a file, it walks up the directory tree and reads the nearest AGENTS.md it finds. This means:
  • A file in packages/api/src/routes/users.ts will use packages/api/AGENTS.md if it exists, otherwise fall back to the root AGENTS.md.
  • A root AGENTS.md sets defaults for the whole repo.
  • A package-level AGENTS.md overrides or extends those defaults for that package.
  • User chat prompts always take the highest priority — they override any AGENTS.md instructions.

​
Directory tree resolution

Agents resolve instructions by walking from the edited file upward: 
repo-root/
├── AGENTS.md              ← 3. Root fallback
├── packages/
│   ├── api/
│   │   ├── AGENTS.md      ← 1. Closest — used when editing files here
│   │   └── src/
│   │       └── routes/
│   │           └── users.ts
│   └── web/
│       ├── AGENTS.md      ← Used when editing files in packages/web/
│       └── src/
└── tools/
    └── scripts/           ← 2. No AGENTS.md here, walks up to root
Every subproject can ship its own tailored instructions. The OpenAI main repository had 88 AGENTS.md files at the time of writing.

​
What to put in the root AGENTS.md

The root file should cover conventions that apply across the entire repo:
  • How the monorepo is structured (where apps and packages live)
  • Top-level install and bootstrap commands
  • Shared tooling (linter, formatter, CI)
  • Commit and PR conventions
  • Security policies
# AGENTS.md (root)

## Monorepo structure
Apps live under `apps/`. Shared packages live under `packages/`.
Use `pnpm install` from the root to install all dependencies.

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
  instead of scanning with `ls`.
- Check the `name` field inside each package's `package.json` to confirm
  the right name — skip the top-level one.

## Shared tooling
- Lint everything: `pnpm lint`
- Test everything: `pnpm test`
- CI config lives in `.github/workflows/`.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

​
What to put in package-level AGENTS.md files

Package files should cover what’s specific to that package — and avoid repeating what the root already says:
  • How to run that package’s dev server
  • Package-specific test commands
  • Local code style or architectural constraints
  • Gotchas unique to that package
# AGENTS.md (packages/api)

## Setup
- Run from repo root: `pnpm install --filter api`
- Start dev server: `pnpm --filter api dev`

## Testing
- Run tests: `pnpm turbo run test --filter api`
- Or from this directory: `pnpm test`
- Run one test: `pnpm vitest run -t "<test name>"`

## Architecture notes
- Routes live in `src/routes/`. One file per resource.
- Middleware is in `src/middleware/`. Do not add business logic there.
- Database access goes through the repository layer in `src/repositories/`.

​
When to add a nested AGENTS.md

Add a package-level AGENTS.md when:
  • The package uses a different language or framework than the rest of the repo
  • The test command is different from the root-level command
  • There are architectural rules or gotchas specific to that package
  • The package is large enough that its own context would get lost in the root file

​
Best practices

  • Don’t repeat yourself. If a rule is in the root AGENTS.md, don’t copy it into every package file. Only override what’s different.
  • Keep commands accurate. An agent that runs the wrong command wastes time. Verify commands match what’s actually in package.json.
  • Update files when workflows change. If you change the test runner or rename a script, update the relevant AGENTS.md at the same time.
  • Co-locate with the code. Commit AGENTS.md files alongside the code they describe. They’re part of the project, not meta-documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us