Nesting and path-scoped rules

By agent-playbook · 0 stars

### Nested files per tool

| Tool | Behaviour |
|---|---|
| Codex | Root to cwd, one file per directory, until 32 KiB; `AGENTS.override.md` replaces `AGENTS.md` in its directory |
| Claude Code | Ancestors load at launch; a subdirectory `CLAUDE.md` (or `AGENTS.md` if that directory has no `CLAUDE.md`) loads when Claude reads a file there |
| Cursor | Subdirectory `AGENTS.md` supported |
| Copilot cloud agent | Multiple `AGENTS.md` allowed; nearest wins |
| Copilot in VS Code | Nested only with `chat.useNestedAgentsMdFiles` (off by default) |
| Gemini CLI | Scans for `GEMINI.md` when a tool touches a directory |
| Zed | Root only, first matching filename |

Launch directory, ancestor-walking tools:

| Start in | Edit in | Loads |
|---|---|---|
| Repo root | `packages/api` | Root file; `packages/api/AGENTS.md` only once a file there is opened |
| `packages/api` | `packages/api` | Root and package files at launch |

### Layout

~~~text
repo/
  AGENTS.md                 # shared: package manager, workspace commands, git rules, boundaries
  packages/
    api/AGENTS.md           # api only: run/test commands, DB rules
    web/AGENTS.md           # web only: component conventions, e2e tests
    shared/AGENTS.md        # "public API; changes need a changeset"
~~~

Package files: differences from root only, overrides stated ("Unlike the root, this package uses npm, not pnpm."), typically 20 to 60 lines.

### Scoped rule formats

Claude Code, `.claude/rules/testing.md`:

~~~markdown
---
paths:
  - "**/*.test.ts"
  - "tests/**"
---
Use the factories in `tests/factories`; never hit the network in unit tests.
~~~

| Tool | File | Scoping |
|---|---|---|
| Claude Code | `.claude/rules/*.md` | `paths` list |
| Cursor | `.cursor/rules/*.mdc` | `globs`, `alwaysApply: false` |
| Copilot | `.github/instructions/*.instructions.md` | `applyTo: "**/*.test.ts"` |
| Cline | `.clinerules/*.md` | `paths` list |
| Windsurf | `.devin/rules/*.md` or `.windsurf/rules/*.md` | `glob` activation mode |

### Excluding inherited files

- Claude Code `claudeMdExcludes`: Globs on absolute paths; set at user, project, local or managed level.
- Codex `AGENTS.override.md`: Replaces inherited instructions for its directory instead of adding to them.

### Sources

- https://learn.chatgpt.com/docs/agent-configuration/agents-md
- https://code.claude.com/docs/en/memory
- https://code.visualstudio.com/docs/copilot/customization/custom-instructions
- https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
- https://geminicli.com/docs/cli/gemini-md/
- https://docs.cline.bot/features/cline-rules