How can we maintain one set of project instructions when developers use different AI coding tools?

TL;DR

When a team mixes Claude Code, Cursor, Codex and Copilot, conventions get copied into each tool's file until the copies disagree. Put the project's instructions in one AGENTS.md, which most current agents read directly and Claude Code can import. Keep each tool's own file to a few tool-specific lines, and record separately what each tool enforces, since hooks and permissions do not travel with the instructions. A convention change then means editing one reviewed file.

Agent rules have become team configuration

In July 2025 a developer asked on Hacker News how a team should collaborate on its AI agent tooling. Editors had always been personal choices, they pointed out, but agent rules are shared configuration: if one person uses Cursor and another Claude Code, which file holds the rules, and how does the team review a rule change that affects every task?

In March 2026 someone running Cursor beside VS Code with Copilot asked on the Cursor forum whether Cursor could read Copilot's instruction files, to avoid writing the rules twice. A Cursor staff reply said it could not, suggested AGENTS.md in the project root as a shared entry point, and warned that symlinks were currently unreliable for Cursor's rule discovery.

Separate what describes the project from what configures a tool

Most drift starts because two kinds of content share the same files. Some instructions describe the project and are true whatever tool reads them; others only make sense to one tool. Sorting them usually shrinks the tool-specific files to a few lines.

Content	Belongs in	Why
Build, test and lint commands	Shared instructions	Every agent needs the same commands
Architecture, module boundaries, naming, where files go	Shared instructions	Describes the codebase, not the tool
Things the agent must not do in this repository	Shared instructions, and a check where possible	The rule is shared; enforcement is per tool
Hooks, permission rules, sandbox settings	That tool's own config	Each tool has its own format and events
MCP servers and tool connections	That tool's own config	Formats differ; secrets must not live in instructions
Notes about one tool's modes or commands	That tool's file, kept short	Other tools cannot act on them

A useful test: if a line would still be correct after you switched tools, it belongs in the shared file.

Make AGENTS.md the shared file, and check how each tool reads it

AGENTS.md is plain Markdown with no required fields, and most current coding agents read it, though not in the same way. From each vendor's documentation as of 30 September 2026:

• Codex reads one AGENTS.md per directory from the project root down to where you started it, joined in that order, up to a combined 32 KiB by default (Codex AGENTS.md guide). It also honors AGENTS.override.md, which Claude Code's documentation says it does not read, so an override there quietly becomes a Codex-only rule.
• Claude Code reads AGENTS.md itself from version 2.1.277, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it (Claude Code memory documentation). If you keep a CLAUDE.md, the documented bridge is an @AGENTS.md line at its top. A developer who adds a CLAUDE.local.md for personal notes silently stops Claude Code reading AGENTS.md unless they change the Project instructions setting, which cannot be committed in project settings files.
• Cursor reads AGENTS.md in the project root and in subdirectories, combining nested files with their parents (Cursor rules documentation). It also reads CLAUDE.md and applies it to every conversation, so a Claude-only note there reaches Cursor's agent too.
• GitHub Copilot differs by feature (Copilot support matrix). Its cloud agent and CLI read AGENTS.md, CLAUDE.md or GEMINI.md alongside .github/copilot-instructions.md, with the nearest AGENTS.md taking precedence. Code review on GitHub.com reads AGENTS.md but not CLAUDE.md or GEMINI.md, and Copilot Chat on GitHub.com uses only .github/copilot-instructions.md.
• Gemini CLI looks for GEMINI.md unless you set context.fileName to include AGENTS.md (Gemini CLI context files). Since 18 June 2026, Gemini CLI no longer serves Google AI Pro, Ultra or free-tier users, who were moved to Antigravity CLI; enterprise, Google Cloud and paid API-key access continue, so check which your team runs.

Symlinking one file to another looks like the shortest route. Claude Code's documentation warns that a committed symlink becomes a one-line text file on a Windows clone without core.symlinks enabled, and Cursor's staff called symlinks unreliable for its rule discovery. An import line or a documented setting avoids both problems.

Keep the tool files thin, and review the shared file like code

With AGENTS.md carrying the project, each tool file should contain almost nothing:

@AGENTS.md

## Claude Code only

Use plan mode for changes under src/billing/.

That CLAUDE.md imports the shared file and adds one line. Cursor reads it too, so the "Claude Code only" heading labels the section for people without keeping other tools out. If a line would confuse another agent, move it into Claude Code's own settings or drop it.

Two habits stop the copies coming back. Treat a change to AGENTS.md as a code change: it goes through a pull request, someone who knows the affected area reviews it, and the description says what behavior the rule should change. Then add a small check that fails when a tool file starts restating shared rules, for example a CI step that allows CLAUDE.md to contain only the import line and a short tool section. That check is a suggestion to adapt, not a standard tool.

The same rule is not enforced the same way

A shared instruction file gives every agent the same text, not the same guardrails. Claude Code, Codex, Cursor, Copilot and Gemini CLI all document hooks that can deny an action, but each keeps that configuration in its own files with its own event names, and none reads it from AGENTS.md. There are two documented crossovers: Cursor can load Claude Code's hooks when its third-party setting is enabled, as it is by default, and Copilot CLI also reads hooks from a repository's .claude/settings.json. So in a repository configured for Claude Code, those tools may run the same hooks; test it rather than assume either way.

Paqad's source shows the difference concretely. In the published 1.93.0 code at commit 29548baf, one shared list of twelve hooks is rendered per host.

For your own team, keep a short table in the repository with one row per tool: which checks block an edit, which run when the agent finishes, which exist only in CI, and which tools have no local checks. Code that goes through your required CI and merge path meets the same checks whichever tool wrote it, so rules that must hold for everyone belong there. Paqad can generate those thin entry files for your repository, and its adapters overview shows which coverage tier each of your team's hosts would get.

Check each developer's setup before calling it consistent

Consistency is a property of each machine, not of the repository. Check these on at least one setup per tool:

When one developer's agent still breaks a shared rule, a diagnosis of why coding agents ignore project rules helps you tell a rule that never loaded from one that loaded and was ignored. To confirm loading before any edit happens, see how to check that an agent loaded the project instructions.

Frequently Asked Questions