Sharing one AGENTS.md across tools

By agent-playbook · 0 stars

### Wiring per tool

| Tool | Setup |
|---|---|
| Codex, Cursor, Copilot cloud agent, Windsurf/Devin Desktop, Cline, Junie, Zed | None; root `AGENTS.md` is read. Zed: a `.rules` or `.cursorrules` file shadows it |
| Claude Code | None without a `CLAUDE.md` (v2.1.277+). With one, first line `@AGENTS.md` |
| Copilot in VS Code | `chat.useAgentsMdFile`; `chat.useNestedAgentsMdFiles` for nested files |
| Gemini CLI | `.gemini/settings.json`: `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` |
| Aider | `.aider.conf.yml`: `read: AGENTS.md` |

### Methods

| Method | Setup | Behaviour | Limits |
|---|---|---|---|
| Import | `@AGENTS.md` at top of `CLAUDE.md` | Import first, then the rest; never loaded twice; nests up to 4 hops | Backticked paths stay literal: `` `@README` `` |
| Symlink | `ln -s AGENTS.md CLAUDE.md` | Same file under each name | Windows needs Developer Mode or admin; without `core.symlinks` Git checks out a one-line text file; Claude Code edit tools do not write through symlinks |
| Native only | Delete tool files | Each tool reads `AGENTS.md` | Claude Code: a `CLAUDE.local.md` stops AGENTS.md loading unless Project instructions is `claude-md-and-agents-md` |

Import form:

~~~markdown
@AGENTS.md

### Claude Code only
- Use plan mode for changes touching more than 3 files.
- Path-specific rules live in `.claude/rules/`.
~~~

### Workarounds to remove

| Workaround | Problem | Replacement |
|---|---|---|
| "Read AGENTS.md" written in `CLAUDE.md` | Agent may not open it | `@AGENTS.md` |
| Session-start hook printing AGENTS.md | Duplicate content in Claude Code | Remove |
| `.cursorrules` copy | Drifts | Delete |

### Tool-neutral AGENTS.md

- "The agent", not a product name, in shared rules.
- No `@imports` or frontmatter; not every reader expands them.
- Plan modes, slash commands, MCP servers: in the tool's own file, below the import.
- Claude Code `/init` drafts from `.cursor/rules/` and `.cursorrules`; with `CLAUDE_CODE_NEW_INIT=1` also `AGENTS.md`, `.windsurf/rules/`, `.clinerules`.

### Sources

- https://code.claude.com/docs/en/memory
- https://code.visualstudio.com/docs/copilot/customization/custom-instructions
- https://geminicli.com/docs/cli/gemini-md/
- https://aider.chat/docs/usage/conventions.html
- https://zed.dev/docs/ai/instructions