Agent Instruction Files

# Agent Instruction Files

Checked: 2026-06-05

## Design Rule

Use one shared root instruction file when possible, then thin tool-specific adapters. Avoid duplicating long rules across many files. Prefer `AGENTS.md` for shared project rules, and create tool-specific files when the user uses that tool or asks for broad agent compatibility.

## Supported Files And Current Notes

| Tool | File(s) | Notes |
| --- | --- | --- |
| Codex | `AGENTS.md`; repo skills in `.agents/skills/<name>/SKILL.md` | Codex discovers `AGENTS.md` in global and project scopes and uses skill `description` for implicit invocation. |
| Claude Code | `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; import `@AGENTS.md` to avoid duplication. Keep each CLAUDE.md concise, preferably under 200 lines. |
| Cursor | `.cursor/rules/*.mdc`, `AGENTS.md`, `.cursorrules` legacy | Project Rules are preferred; `.cursorrules` is supported but legacy/deprecated. |
| Windsurf / Devin Desktop Cascade | `.devin/rules/*.md`, `.windsurf/rules/*.md`, `AGENTS.md`, `.windsurfrules` legacy | Prefer `.devin/rules`; legacy Windsurf paths can be included for compatibility. |
| Continue | `.continue/rules/*` or `.continue/rules.md` | Local rules are version-controlled and best for project-specific conventions. |
| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `AGENTS.md` | Repo-wide file gives guidance for build/test/validation; path-specific instructions use frontmatter. |
| Aider | `AGENTS.md` via `.aider.conf.yml` or `--read`; `CONVENTIONS.md` via `/read` or `--read` | Aider can read convention files as read-only context and cache them when prompt caching is enabled. |

## Agent File Contents

Every agent instruction file should include:

- project mission in 2-4 lines
- source-of-truth order
- setup/build/test/lint/run commands if known
- architecture and directory map if known
- scope and non-goals
- safety and secret handling
- quality gates
- approval-required actions
- final report expectations

They should not rely on instruction text as a hard security control. For hard enforcement, pair instructions with hooks, CI, sandboxing, permissions, tests, or policy.

## Adapter Patterns

`CLAUDE.md`: