Root vs Nested Overrides
Shows how nested instructions refine inherited rules while resolving direct conflicts explicitly.
Scenario
You maintain a repository where most code follows modern TypeScript conventions.
One subdirectory contains an older application that requires different commands and coding constraints.
The root instructions establish repository defaults.
The nested instructions provide more specific guidance for the legacy area.
This example demonstrates an important principle:
Put defaults at a broad scope and exceptions at the narrow scope where they apply.
Repository Structure
company-platform/
├── AGENTS.md
├── apps/
│ ├── modern-web/
│ │ └── src/
│ └── admin-legacy/
│ ├── AGENTS.md
│ ├── src/
│ └── package.json
├── packages/
└── package.json
AGENTS.md
Root AGENTS.md:
# Repository Instructions
## Development
- Use `pnpm`.
- Prefer TypeScript for new repository code.
- Follow existing workspace boundaries.
## Code
- Follow the architecture of the application or package being modified.
- Do not introduce new cross-workspace dependencies without checking existing public interfaces.
## Validation
- Run lint, typecheck, and relevant tests for affected modern workspaces.
The legacy application has more specific requirements.
apps/admin-legacy/AGENTS.md:
# Legacy Admin Instructions
## Runtime
- This application still contains JavaScript modules.
- Do not convert existing JavaScript files to TypeScript as part of unrelated work.
- New files should follow the local module style unless modernization is explicitly part of the task.
## Package Commands
- Use the scripts defined in this application's `package.json`.
- Run its tests with `pnpm --dir apps/admin-legacy test`.
- This application does not currently have a standalone typecheck step.
## Changes
- Preserve existing behavior outside the requested change.
- Avoid broad modernization while making targeted fixes.
- Follow existing local patterns when they differ from newer applications.
## Validation
Before completing changes here, run:
- `pnpm --dir apps/admin-legacy lint`
- `pnpm --dir apps/admin-legacy test`
What This Does
The root establishes the normal repository expectations:
pnpm
TypeScript
modern workspace validation
The nested file tells the agent that one area differs.
For example, the root says:
- Prefer TypeScript for new repository code.
But the legacy application says:
- New files should follow the local module style unless modernization is explicitly part of the task.
The narrower instruction provides the context needed for that specific area.
What This Does NOT Do
Nested instructions should not casually contradict root instructions.
If two files disagree without a clear reason, agents and humans may struggle to determine the intended behavior.
Differences should represent genuine scope-specific requirements.
For example:
Root:
Use pnpm.
Nested:
Use Yarn because I prefer it.
would be suspicious if the nested project has no Yarn setup.
By contrast:
Root:
Run typecheck for modern workspaces.
Nested:
This legacy application has no standalone typecheck step.
documents a real technical difference.
Why These Instructions Matter
Repository-wide defaults are useful, but exceptions are common.
Without scoped guidance, root instructions tend to accumulate caveats:
- Use TypeScript, except in admin.
- Run typecheck, except in admin.
- Follow modern module conventions, except in admin.
- Refactor old patterns, except in admin.
As exceptions grow, the root file becomes harder to understand.
Moving specialized guidance closer to the affected code produces a cleaner model:
Root
→ normal repository behavior
Nested
→ local specialization
Key Decisions
Broad instructions should represent defaults
The root file should describe what is normally true.
Exceptions belong near the exception
Do not make every agent learn legacy constraints when only one directory requires them.
More specific guidance should be intentional
A scoped instruction should exist because the local environment genuinely differs.
Avoid hidden contradictions
If a nested instruction changes a broader expectation, make the reason clear enough that the difference appears intentional.
Remember agent-specific discovery behavior
Hierarchical instruction discovery and precedence can vary between coding agents.
For Codex, repository instructions can be discovered hierarchically, with more specific applicable guidance taking precedence over broader guidance.
When portability across tools matters, keep scope relationships clear and avoid relying on subtle conflicts.
When to Use This Pattern
Use this pattern when:
- most of a repository follows one workflow;
- a specific directory has legitimate exceptions;
- legacy or specialized applications need different commands;
- putting every exception in the root would create noise.
Scoped specialization is useful.
Unnecessary contradiction is not.