How to Share AGENTS.md Instructions Across Copilot, Codex, and Claude Code¶

For / Key Points

For: Teams using GitHub Copilot, Codex, and Claude Code in one repository that want to reduce duplicated build, test, and coding instructions

Key Points:

Codex and several Copilot surfaces read AGENTS.md, but support differs by product surface
Claude Code does not read AGENTS.md directly; import it from CLAUDE.md with @AGENTS.md
Keep shared instructions as a short map and enforce mandatory checks through CI or hooks

AGENTS.md is a Markdown file that tells an agent how a repository is organized, which commands to run, and how to validate changes. Codex reads AGENTS.md across the repository hierarchy, while GitHub Copilot supports it in selected IDE, CLI, cloud-agent, and code-review surfaces.¹²

That does not mean every coding tool automatically behaves the same way. Claude Code's native file is CLAUDE.md, and Copilot supports different instruction types in different surfaces. A durable layout uses AGENTS.md as the common core with small product-specific entry points:

AGENTS.md                         # Shared build, test, and repository guidance
CLAUDE.md                         # @AGENTS.md plus Claude-specific guidance
.github/copilot-instructions.md   # Copilot-only guidance, when needed
.github/instructions/             # Copilot path-specific guidance, when needed

Current support matrix¶

GitHub's official matrix documents differences even within Copilot.²

Surface	`AGENTS.md`	Notes
Codex CLI / IDE / cloud	Supported	Collects instructions from the root toward the working directory, with more specific guidance later
Copilot Chat in VS Code	Supported	Treated as agent instructions in the workspace
Copilot CLI	Supported	Supports `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`
Copilot cloud agent	Supported	Can combine repository-wide, path-specific, and agent instructions
Copilot code review	Supported	Root support became generally available in June 2026; more instruction files are now supported
Copilot Chat in Visual Studio / JetBrains	Varies	Check the matrix for the exact IDE and feature
Claude Code	Not directly	Import from `CLAUDE.md` or use a symlink

As of July 2026, Copilot code review can read instructions and Skills from the feature branch being reviewed. It also supports REVIEW.md, GEMINI.md, and CLAUDE.md in addition to AGENTS.md.³ Do not freeze your design around the older assumption that only a root AGENTS.md is available.

Write a minimal AGENTS.md¶

Use it for commands and pointers, not as a copy of every design document.

# Repository Guide

## Scope
- Web application code lives in `src/`.
- Architecture decisions live in `docs/architecture/`.

## Setup
- Install dependencies with `pnpm install --frozen-lockfile`.
- Copy `.env.example` to `.env`; never commit credentials.

## Checks
- Run `pnpm lint` after source changes.
- Run `pnpm test` before proposing a pull request.
- Run `pnpm test:e2e` when routes or authentication change.

## Conventions
- Use TypeScript strict mode.
- Keep API handlers in `src/api/handlers/`.
- Do not edit generated files under `src/generated/`.

## Pull requests
- Explain the user-visible change and tests run.
- Call out migrations, security boundaries, and rollback steps.

Good instructions are verifiable. Replace “test appropriately” with a command and trigger. Replace “follow existing conventions” with the location of those conventions.

OpenAI has also described why a giant AGENTS.md becomes counterproductive. Its agent-first repository uses a short file, roughly 100 lines, as a table of contents that points to deeper documentation.⁴

Import the shared file into Claude Code¶

Claude Code reads CLAUDE.md, not AGENTS.md. Anthropic documents the following import pattern:⁵

@AGENTS.md

## Claude Code
- Use plan mode before changing `src/billing/`.
- Ask before running production migrations.

If the content should be exactly identical, a symlink also works on macOS and Linux:

ln -s AGENTS.md CLAUDE.md

The import is more portable on Windows, where symlinks can require Administrator privileges or Developer Mode. It also leaves room for Claude-specific guidance.

Add only Copilot-specific instructions¶

Use .github/copilot-instructions.md only when Copilot needs additional repository-wide guidance:

# Copilot-specific instructions

- Link the originating issue in the pull request body.
- Do not change files under `infra/prod/` unless the task names them.

Put path-specific rules in .github/instructions/*.instructions.md. Copilot can combine repository-wide and path-specific instructions.⁶

Do not copy the same rule into both files. Drift creates contradictory prompts. Keep common guidance in AGENTS.md and only product-specific deltas in product-specific files.

Scope a monorepo by ownership boundary¶

Put global rules at the root and package-only commands near the package:

AGENTS.md
packages/
├── web/
│   └── AGENTS.md
└── api/
    └── AGENTS.md

Codex and supported Copilot surfaces use instructions close to the work, but their exact discovery and precedence rules are not identical. Avoid deliberate conflicts. Let the root define shared policy and nested files add local commands.

Verify every surface you actually use¶

A committed file is not proof that each product loaded it.

Ask, “List the checks required after changing this repository.”
Compare the response in each surface your team uses: Codex, Copilot Chat, cloud agent, or code review
In Claude Code, open /memory and confirm that CLAUDE.md and its import were loaded
Tighten unclear rules and remove duplication or contradictions

AGENTS.md is model context, not an enforcement boundary. Secrets checks, mandatory tests, approvals, and protected-branch requirements belong in CI, hooks, and rulesets.

Summary¶

Use AGENTS.md as a shared core for Codex and supported Copilot surfaces
Import it into Claude Code from CLAUDE.md
Verify support by surface, not by product name alone
Keep the file short and enforce non-negotiable requirements mechanically

This preserves one source of shared guidance without hiding real product differences.