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, 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 bridge

```md
# Repository instructions

Treat the root AGENTS.md as the canonical repository instructions. Read and follow it before making changes.
```

Keep this bridge because AGENTS.md support differs between Copilot surfaces. Put Copilot-only instructions here; do not duplicate the shared body.

## 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 can follow directory scope. Use .cursor/rules/*.mdc only when a rule needs globs or another activation mode.
- Windsurf: AGENTS.md works directly. Use .windsurf/rules/*.md only for cross-cutting rules that need explicit activation behavior.
- Claude Code: verify the import with /memory after adding CLAUDE.md.
- GitHub Copilot: verify active instructions in the specific IDE, CLI, review, or cloud-agent surface your team uses.
- 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.