Which AI agent instruction files does your repo actually need?

# AI coding agent instruction file plan

Selected tools: OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Devin Desktop (formerly Windsurf)

## 1. AGENTS.md — canonical shared instructions

Keep repository-wide commands, architecture boundaries, safety rules, and the definition of done here. Treat this file as the source of truth.

## 2. CLAUDE.md — Claude Code bridge

```md
@AGENTS.md
```

Add Claude-only guidance below the import only when it genuinely differs from the shared rules.

## 3. .github/copilot-instructions.md — Copilot surface bridge

```md
# Copilot compatibility

Follow the repository-wide rules in the root AGENTS.md.
```

Keep this bridge only for Copilot surfaces that do not load AGENTS.md. Copilot CLI can replace the pointer above with a real relative include:

```md
@../AGENTS.md
```

Do not assume that @ file references expand outside Copilot CLI. If a surface neither loads AGENTS.md nor expands the reference, keep the minimum essential repository rules self-contained here and verify the active instructions in that surface.

## 4. GEMINI.md — Gemini CLI bridge

```md
@./AGENTS.md
```

Add Gemini-only context below the import only when needed.

## Tool-specific notes

- Codex: AGENTS.md is the repository instruction file; no bridge is needed.
- Cursor: AGENTS.md currently applies at the project root. Use .cursor/rules/*.mdc when a rule needs directory or file-pattern scope, globs, or another activation mode.
- Devin Desktop (formerly Windsurf): AGENTS.md works directly. Use .devin/rules/*.md for cross-cutting rules that need explicit activation behavior; .windsurf/rules/*.md remains a legacy path.
- Claude Code: verify the import with /memory after adding CLAUDE.md.
- GitHub Copilot: cloud agent, code review, VS Code, and CLI can load AGENTS.md. Keep the .github bridge for surfaces that require repository-wide custom instructions; @ file references are explicitly documented for Copilot CLI only.
- Gemini CLI: verify loaded context with /memory show.

## Drift-prevention checklist

- Edit shared rules in AGENTS.md first.
- Keep bridge files short and tool-specific.
- Use scoped native rules only when the scope cannot be expressed by file location.
- Re-check loaded instructions after changing filenames, imports, or repository layout.

---

Rebuild this 6-tool plan: [Repo Agent Kit](https://repoagentkit.com/ai-agent-instruction-files?tools=codex%2Cclaude%2Ccursor%2Ccopilot%2Cgemini%2Cwindsurf&utm_source=plan-artifact&utm_medium=markdown&utm_campaign=compatibility-plan)