Scope & Nested AGENTS.md

A single AGENTS.md at the repository root is enough for many projects.

But as a codebase grows, different areas may need different instructions.

A frontend application might use React and Playwright.

A backend service might use Node.js, Zod, and Vitest.

A mobile application might use React Native and Expo.

Putting every rule into one huge root file can create unnecessary context.

That's where scoped and nested AGENTS.md files become useful.

1. Start With One Root AGENTS.md

For a small application:

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

the root file may be all you need.

# Project Guidelines

## Development

- Use TypeScript.
- Use `pnpm`.

## Testing

- Add tests for new business logic.
- Run `pnpm test` before completing changes.

## Validation

- Run `pnpm lint`.
- Run `pnpm typecheck`.

Don't create nested files simply because the feature exists.

Start simple.

Add scope only when the repository actually needs it.

2. When Does a Nested AGENTS.md Make Sense?

Consider a monorepo:

platform/
├── AGENTS.md
│
├── apps/
│   ├── web/
│   ├── api/
│   └── mobile/
│
└── packages/
    ├── ui/
    └── database/

These areas may have very different development rules.

The web application might require:

- Prefer React Server Components.
- Use Tailwind CSS.

The API might require:

- Validate request payloads using Zod.
- Keep business logic inside services.

The mobile application might require:

- Use React Native components.
- Follow Expo-compatible APIs.

Putting all of these in the root file means an agent working on the API receives frontend and mobile instructions it doesn't need.

A better structure may be:

platform/
├── AGENTS.md
│
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   │
│   ├── api/
│   │   └── AGENTS.md
│   │
│   └── mobile/
│       └── AGENTS.md
│
└── packages/

Now instructions can live closer to the code they affect.

3. Root Instructions Should Be Broad

The root AGENTS.md should contain rules that apply across the repository.

For example:

# Repository Guidelines

## Package Management

- Use `pnpm`.
- Do not manually modify `pnpm-lock.yaml`.

## Security

- Never commit secrets or `.env` files.

## Workflow

- Follow existing patterns before introducing new abstractions.
- Run relevant validation before completing changes.

These rules make sense regardless of which application is being modified.

4. Nested Instructions Should Be Specific

Now consider:

apps/web/AGENTS.md

It could contain:

# Web Application Guidelines

## React

- Prefer Server Components.
- Add `"use client"` only when client-side interactivity is required.

## Styling

- Use Tailwind CSS.
- Reuse components from `src/components/ui`.

## Testing

- Use Playwright for end-to-end tests.

These instructions are relevant to the web application.

They don't need to appear in:

apps/api/AGENTS.md

5. Think General → Specific

A useful mental model is:

Repository
    ↓
Application
    ↓
Feature / specialized area

Instructions become more specific as you move deeper into the repository.

For example:

platform/
│
├── AGENTS.md
│      Repository-wide rules
│
└── apps/
    └── api/
        ├── AGENTS.md
        │      API-specific rules
        │
        └── payments/
            └── AGENTS.md
                   Payment-specific rules

But this doesn't mean you should automatically create all three levels.

Only add another level when there are meaningfully different instructions.

6. Avoid Repeating Parent Instructions

Suppose the root file says:

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

Don't copy those instructions into every nested file.

❌ Avoid

# apps/web/AGENTS.md

- Use `pnpm`.
- Never commit secrets.
- Run `pnpm lint`.
- Use Tailwind CSS.

✅ Better

# apps/web/AGENTS.md

- Use Tailwind CSS for styling.
- Reuse existing components from `src/components/ui`.

The nested file should primarily contain what is different or additional for that scope.

This keeps the instruction hierarchy easier to maintain.

7. Scope Can Prevent Irrelevant Instructions

Imagine the root file contains:

- Every API endpoint must validate requests using Zod.

But your repository also contains:

mobile/

The rule isn't relevant there.

Instead, put it where it belongs:

api/
└── AGENTS.md

- Validate incoming API request payloads using Zod.

This makes the intended scope explicit.

8. Example: Full-Stack Monorepo

Consider:

commerce/
│
├── AGENTS.md
│
├── apps/
│   │
│   ├── storefront/
│   │   ├── AGENTS.md
│   │   └── src/
│   │
│   └── api/
│       ├── AGENTS.md
│       └── src/
│
└── packages/
    │
    ├── ui/
    │   ├── AGENTS.md
    │   └── src/
    │
    └── database/
        └── src/

Root

# Repository Guidelines

- Use `pnpm`.
- Use TypeScript.
- Never commit secrets.
- Run relevant tests before completing changes.

Storefront

# Storefront Guidelines

- Use Next.js App Router.
- Prefer Server Components.
- Use components from `packages/ui` before creating app-specific equivalents.

API

# API Guidelines

- Validate request payloads using Zod.
- Keep business logic inside services.
- Access the database through repositories.

UI Package

# UI Package Guidelines

- Components must not depend on application-specific business logic.
- Maintain keyboard accessibility for interactive components.
- Add Storybook stories for new reusable components.

Each instruction has a clear home.

9. Nested Files Can Add Instructions

Nested instructions don't always need to replace something.

Suppose the root says:

- Add tests for new business logic.

The API file says:

- Use Vitest for service-layer unit tests.

Together, they provide more detail:

Root
"Add tests"
      +
API
"Use Vitest for service tests"
      ↓
Complete guidance

The nested file adds specificity without contradicting the root.

This is usually the easiest hierarchy to maintain.

10. Nested Files Can Also Override Guidance

Sometimes different parts of a repository genuinely use different tooling.

For example:

Root

- Use Vitest for JavaScript unit tests.

legacy/AGENTS.md

- Tests in this package still use Jest.
- Do not migrate the test framework unless the task explicitly requires it.

The exception exists for a legitimate reason.

A scoped instruction lets you express that without making the root guidance complicated.

However, frequent overrides may indicate that your root instruction is too broad.

11. Avoid Deep Instruction Trees

Technically, you might create:

src/
└── features/
    └── payments/
        └── checkout/
            └── components/
                └── AGENTS.md

But should you?

Probably not unless those components genuinely have special working requirements.

Deep hierarchies create maintenance problems:

Which instructions apply?

Where is this rule defined?

Which file should I update?

Is this rule duplicated somewhere else?

Prefer the shallowest structure that accurately represents your repository.

12. A Practical Decision Test

Before creating a nested AGENTS.md, ask:

Question 1

Does this area have different commands?

Yes → nested file may help.

Question 2

Does it use different frameworks or testing tools?

Yes → nested file may help.

Question 3

Does it have important architecture boundaries?

Yes → nested file may help.

Question 4

Would putting these instructions in the root create irrelevant guidance for most tasks?

Yes → nested file may help.

Question 5

Am I creating the file just because I can?

Yes → don't.

13. Example: When NOT to Nest

Suppose you have:

src/
├── components/
├── hooks/
├── utils/
└── types/

and every directory follows the same project conventions.

You probably don't need:

components/AGENTS.md
hooks/AGENTS.md
utils/AGENTS.md
types/AGENTS.md

A single root file is simpler.

14. Example: When Nesting Helps

Now consider:

company-platform/
├── web-nextjs/
├── api-node/
├── mobile-expo/
└── infrastructure-terraform/

These areas have substantially different:

• Frameworks.
• Commands.
• Testing strategies.
• Architecture.
• Deployment concerns.

Scoped instruction files make much more sense here.

company-platform/
├── AGENTS.md
├── web-nextjs/
│   └── AGENTS.md
├── api-node/
│   └── AGENTS.md
├── mobile-expo/
│   └── AGENTS.md
└── infrastructure-terraform/
    └── AGENTS.md

15. Codex: How Scope Works

Codex supports hierarchical project instructions.

For repository instructions, Codex builds an instruction chain based on the working directory.

Conceptually:

Repository root
       ↓
Intermediate directories
       ↓
Current working directory

Instructions closer to the working directory can provide more specific guidance.

When instructions conflict, more specific applicable instructions can override broader ones.

This makes nested files useful for monorepos and repositories containing applications with different development conventions.

This describes Codex behavior. Other coding agents may implement discovery and precedence differently.

16. Codex Also Has User-Level Instructions

Codex can also use instructions outside the repository for personal/default guidance.

Conceptually:

User-level guidance
        +
Repository guidance
        +
Scoped repository guidance

This lets developers keep personal defaults separate from project rules.

For example, repository rules should normally remain in the repository so they can be shared with the team.

A personal preference that should apply across your own Codex sessions may belong at the user level instead.

Again, this is Codex-specific behavior, not a requirement of the general AGENTS.md convention.

17. Design Scope Around Ownership

Another useful way to decide scope is to ask:

Who owns this rule?

For example:

"Use pnpm across the monorepo"
→ Repository

"Use Server Components in the storefront"
→ Web application

"Use repository classes for database access"
→ API application

"Reusable UI cannot import application code"
→ Shared UI package

Put the instruction at the highest level where it remains correct.

This is an important principle:

Place a rule at the broadest scope where it is universally true.

18. Don't Use Nesting to Hide Bad Organization

If your instruction hierarchy becomes:

Root says X
↓
App overrides X
↓
Feature overrides the override
↓
Subfeature adds another exception

the problem may not be missing AGENTS.md files.

The rules themselves may need simplification.

Nested instructions should make your repository easier to understand—not create another configuration system developers have to debug.

A Useful Pattern

For many monorepos, this is enough:

repository/
├── AGENTS.md
│
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   │
│   ├── api/
│   │   └── AGENTS.md
│   │
│   └── mobile/
│       └── AGENTS.md
│
└── packages/

Root:

Shared rules

Nested:

Only rules specific to that application

Simple.

Predictable.

Maintainable.

Mini Exercise

You have:

platform/
├── web/
├── api/
└── mobile/

All three use:

pnpm
TypeScript
ESLint

Only the API uses:

Zod
Vitest
Repository pattern

Where should the instructions go?

Root AGENTS.md

- Use `pnpm`.
- Use TypeScript.
- Run the repository lint command before completing application changes.

api/AGENTS.md

- Validate incoming API payloads using Zod.
- Use Vitest for service-layer unit tests.
- Access the database through repository classes.

Don't repeat the shared instructions inside the API file.

Scope Checklist

Before creating or modifying a nested file, ask:

• Does this instruction apply everywhere?
• What's the broadest scope where it's always correct?
• Does this area genuinely need different guidance?
• Am I duplicating a parent instruction?
• Am I introducing a conflict?
• Could this rule live at a simpler level?
• Will a developer understand where to update it six months from now?

Key Takeaway

Don't think:

"Where can I add another AGENTS.md?"

Think:

"What is the correct scope for this instruction?"

A useful hierarchy usually follows:

Shared repository rules
          ↓
Application-specific rules
          ↓
Specialized rules only when necessary

Keep shared guidance high.

Keep specialized guidance close to the code it affects.

Avoid duplication.

Avoid unnecessary depth.

And remember that the exact discovery and precedence rules depend on the coding agent you're using.

Up Next

Common Mistakes & Conflicting Instructions

Now that we can design an instruction hierarchy, we'll intentionally break one.

Next we'll examine duplicated rules, contradictions, stale instructions, vague guidance, excessive restrictions, scope mistakes, and conflicts between root and nested AGENTS.md files—and learn how to debug them.