AGENTS.md, CLAUDE.md and Cursor Rules: Keeping Instructions in Sync

Check discovery before copying instructions

Start by recording the client versions, launch directories and instruction settings your team actually uses. A developer opening the repository root and a CI job starting inside a service can receive different instruction sets. Treat those as separate cases in your migration checklist.

OpenAI's instruction guide says Codex builds its instruction chain at startup. Within each directory from the project root to the working directory, it selects at most one file: AGENTS.override.md, then AGENTS.md, then configured fallback names. Deeper instructions take precedence; the default combined limit is 32 KiB.

Anthropic documents direct AGENTS.md support from Claude Code v2.1.277. Its default selects Claude instruction files when one exists in the working directory or above it. Cursor documents root and nested AGENTS.md support alongside project rules.

My recommendation is to make the repository's shared contract independent of those selection mechanisms. Give every shared requirement one editable home, then document how each supported client receives it. Do not begin by making three manually maintained copies identical.

Write a small shared contract

Put requirements that apply to every coding client in the root AGENTS.md. Include the repository's actual commands, important editing boundaries and the checks expected before handing work back. For an example repository with lint and test scripts, the shared file could contain:

# Repository instructions

## Verification
- Run npm run lint after changing application code.
- Run npm test after changing behavior.
- Report checks that could not run and explain why.

## Editing boundaries
- Change source files rather than generated output under dist/.
- Reuse existing design tokens for component styling.
- Add a regression case when fixing an API behavior bug.

Replace those commands and directories with ones verified in your repository. An instruction to run a nonexistent script creates another correction that every client must learn separately. Avoid putting several alternative package managers in the same contract unless the repository actually supports them.

Keep detailed procedures outside the always-loaded core. A release runbook or component reference can have its own owner and review cycle. Use a shared skills repository for reusable procedures; keep this file focused on the expectations that remain true while any of those procedures runs.

Use an explicit Claude import where needed

Where a Claude adapter is needed, put this complete content in a root CLAUDE.md beside the shared file:

@AGENTS.md

Anthropic documents this as an expanded import. Relative paths resolve from the importing file. A sentence telling Claude to read another file leaves that read to the agent's discretion. Keep the import outside Markdown code spans and fenced blocks.

Append only Claude-specific guidance, if necessary. Move any new repository-wide requirement into the shared file during review. This keeps the adapter small enough that a reviewer can immediately spot an accidental second policy document.

For nested shared files, consider a neighboring wrapper with the same import, then verify its loading in your supported sessions. Check /context for loaded memory files. If your fleet uses direct native loading instead, document that choice and its settings. Avoid introducing both a wrapper and a hook that prints the same instructions.

Keep Cursor rules focused on activation

Use Cursor's native AGENTS.md support for the shared core. Reserve .cursor/rules/*.mdc for cases needing explicit activation metadata or focused reference material. Cursor's rules documentation defines description, globs and alwaysApply; a plain .md file in that directory is ignored.

For example, after creating a component reference document, a rule at .cursor/rules/component-references.mdc could contain:

---
description: Reference examples for component changes
globs: src/components/**/*.tsx
alwaysApply: false
---
For component changes, consult @docs/component-patterns.md
for worked examples.

With those fields, a matching file in context activates the rule. Cursor says a file mention directs a tool read when needed; it does not inline the referenced document. Keep requirements that must always be present in the shared core. Setting alwaysApply: true would ignore the glob restriction.

The design-token requirement in the example core therefore stays there. The component document supplies examples without becoming a second editable definition of that requirement. During migration, compare every existing Cursor rule against the shared contract and remove obsolete copies of common instructions.

Make drift visible in code review

Define the files people may edit before introducing automation. For this layout, reviewers should accept shared policy changes in AGENTS.md, Claude-specific additions in its wrapper, and Cursor activation changes in .mdc metadata. Give the shared file an accountable maintainer so conflicting edits have a clear resolution path.

A useful pull-request check verifies that the Claude wrapper still contains the expected import and that its target exists. It should also flag a newly added root instruction file for review. These checks catch broken wiring; they cannot establish that two differently worded requirements mean the same thing.

If you must distribute complete files to environments that cannot consume your chosen layout, use a deterministic renderer from the canonical text. Mark outputs as generated, compare regenerated bytes in CI, and reject manual edits. Keep selection metadata separate from the rendered policy body. Generate only the adapters that environment needs to avoid loading the same policy twice.

For example, changing the test command should require one policy edit. The review should show either unchanged import wrappers or mechanically updated generated bodies. A reviewer resolving three independently phrased test instructions is evidence that the synchronization design still depends on copy-paste.

Where SPYN3 fits

Keep repository instructions versioned with code. For procedures and notes shared beyond one checkout, SPYN3's opt-in Memory & skills setting exposes context through MCP, including spyn3://workspace/skills/<name>/SKILL.md and workspace notes. Any MCP client can use its context tools. Reading needs call:tools; writing needs write:memory. Enable it in workspace Settings when you want a shared location for that material. Plan the boundary using an agent-agnostic context layer, while retaining explicit instruction adapters for each client.

Test loading and behavior separately

Before retiring old instruction files, run a small acceptance exercise in fresh sessions. For Codex, OpenAI documents launching from a target subdirectory to check the active instruction sources. Repeat your checks at the repository root and in a service directory; do not assume an already-running session has rebuilt its startup chain.

1. Ask each client to identify the repository's verification command and instruction sources before editing anything.
2. Give each client the same small component change and check whether it reuses existing design tokens.
3. Open a matching component file in Cursor and inspect whether the reference rule activates; repeat with an unrelated backend file.
4. Repeat in the clean environment used by CI or a new teammate, without relying on your personal configuration.

Record client versions, working directory, expected files and observed behavior. When a result differs, first distinguish an instruction that never loaded from one the agent read but did not follow. Changing the wording cannot fix a missing import or the wrong launch directory.

Finish the migration by removing superseded copies and assigning future edits to the canonical file. Keep formatter, test and access controls enforced by their actual tools. Instruction synchronization gives agents a consistent contract; the acceptance exercise tells you whether your supported clients receive and use it.