Claude Code, Codex and Cursor load project instructions differently. Moving the same Markdown into a shared folder can simplify maintenance, but linking that folder everywhere is not enough to preserve the original behavior. A frontend rule that once loaded only for component files can become permanent context, or disappear from an agent’s instruction chain entirely.
The useful idea behind a one-folder setup is to separate the instructions you maintain from the files each agent knows how to load. A canonical .agents/rules/ directory holds reusable rule text, while .agents/skills/ holds reusable skills. Agent-specific entry points then import, link to or receive generated copies of that material.
Published guidance from Wingo UI on instruction-file compatibility and the agent-sync documentation supports that architecture, with important limits. The migration checklist below treats shared storage, instruction loading and rule activation as separate problems. That distinction is what keeps deduplication from quietly changing an agent’s behavior.
The Compatibility Matrix Needs Two Questions
“Can this agent read the file?” is only the first question. The second is “Under what conditions will it read the file?”
An unconditional project instruction, a path-scoped rule and a task-selected rule can contain identical Markdown while behaving very differently.
Wingo UI’s guide, which says its documentation checks were made on October 9, 2026, describes these loading differences:
| Agent | Documented instruction entry points | Import or link detail | Migration consequence |
|---|---|---|---|
| Claude Code | CLAUDE.md, related memory files and .claude/rules/ | Supports @path imports, reported up to four levels deep. Agent-sync also documents instruction imports or symlinks. | Import shared baseline text explicitly. Preserve path conditions in native rules. |
| Codex | AGENTS.md, with AGENTS.override.md taking precedence in the same directory | Wingo UI reports no documented import syntax. Agent-sync supports symlinking its instruction file. | Put actual instruction content in a discoverable file, or link that file to compatible canonical content. |
| Cursor | AGENTS.md and .cursor/rules/*.mdc, alongside user and team rules | Wingo UI describes @file references as on-demand reads, not inlined imports. | Keep conditional rules in native .mdc files. Do not assume a reference preloads the target. |
| Kiro | Not established by the two cited references | Neither reference verifies Kiro’s import or symlink behavior. | Keep existing, known-working native rules as copies until compatibility is checked. |
This is a bounded comparison, not a certification of every current release. In particular, the cited material does not establish that all four agents will traverse a symlinked rules directory.
For Kiro, keeping copies is a conservative migration policy, not a claim that every version rejects symlinks. Agent-sync’s published coverage lists twelve agents, but Kiro is absent. That is enough reason to leave Kiro outside an automated fan-out until its behavior is verified.
My view is that a generated copy is a better adapter than an elegant link whose loading behavior is uncertain. The maintenance goal is one authoritative source, not necessarily one physical file.
Separate Shared Text From Activation Metadata
A rule file usually contains two things:
- The instruction body: what the agent should do.
- The activation condition: when that instruction should enter the agent’s context.
The body is often portable. The activation condition frequently is not.
For example, “Use the project’s design tokens for component spacing” could be shared text. Applying it only to files under a frontend directory requires an agent-specific loading mechanism.
Wingo UI describes Claude Code rules with a paths list and Cursor .mdc rules with glob or description-based activation. Codex uses instruction files arranged along its directory-based loading chain. Those are different mechanisms, even when the underlying instruction is the same.
A useful first pass is to classify every existing rule:
| Rule category | Example purpose | Migration treatment |
|---|---|---|
| Repository-wide | Build commands, formatting policy, repository conventions | Include in the shared baseline loaded for every relevant session. |
| Path-scoped | Frontend conventions, database migration requirements | Share the text, but retain native path or directory scoping. |
| Task-selected | Release preparation, security review, a specialist workflow | Keep a deliberate selection mechanism. Do not automatically move it into baseline context. |
| Agent-specific | Tool permissions or behavior unique to one product | Leave it in that agent’s configuration. |
The task-selected category is easy to mishandle. Importing a description-selected Cursor rule into an unconditional Claude instruction file changes its behavior: the imported text becomes part of the baseline instructions. Keeping the description as prose does not recreate Cursor’s selection mechanism.
That is an inference from the documented loaders, not a measured performance result. Its practical consequence is straightforward: copying the words preserves content; preserving the trigger preserves behavior.
A Practical Layout for the Shared Library
A project-level arrangement can keep reusable source text separate from generated or native adapters:
project/
├── .agents/
│ ├── rules/
│ │ ├── shared.md
│ │ └── frontend.md
│ └── skills/
├── AGENTS.md
├── CLAUDE.md
├── .claude/
│ └── rules/
│ └── frontend.md
└── .cursor/
└── rules/
└── frontend.mdc
This is a proposed layout, not a claim that every agent automatically discovers .agents/. In this arrangement:
.agents/rules/shared.mdis the maintained source for universal project instructions.AGENTS.mdcontains the rendered baseline text for agents that read it.CLAUDE.mdexplicitly imports that baseline.- The Claude and Cursor frontend files retain their respective activation metadata.
- Existing Kiro rules remain in their working native location, with their text synchronized from the canonical source where appropriate.
A build or synchronization step could generate the adapters. No particular generation command is established by the cited sources, so this layout does not depend on an invented utility.
The small Claude adapter has a documented form:
@AGENTS.md
Placed in CLAUDE.md, that line imports the project’s AGENTS.md content. It is an instruction-file example, not a command that has been executed.
A symlink can also work where the destination accepts exactly the same bytes. But if one agent needs extra metadata or different activation rules, a rendered file is the more suitable adapter.
Claude Code: Make the Shared Baseline Explicit
Wingo UI reports that Claude Code added conditional native AGENTS.md reading in version 2.1.277. Its guide says this fallback applies when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it.
That creates a migration trap. A developer can add a local Claude instruction file and change whether the shared AGENTS.md is loaded.
The guide recommends a CLAUDE.md containing @AGENTS.md to make the relationship explicit. That is the approach I would choose for a mixed-agent repository: it records the dependency in version control and makes it easier to review than relying on fallback discovery.
Keep path-scoped instructions out of that unconditional baseline. Claude’s native .claude/rules/ mechanism can retain a paths list for the relevant rule, while the instruction body comes from the shared library.
Wingo UI also recommends Claude Code’s /memory command to inspect loaded files. Use that inspection during migration; the presence of an import in the repository is not, by itself, proof that a particular session loaded it.
Codex: Supply Content, Not a Markdown Pointer
Wingo UI reports that Codex documents no import syntax for AGENTS.md. It also says Codex builds its instruction chain at startup, using files from the Git root down to the launch directory.
A root AGENTS.md that merely tells Codex to “see .agents/rules/shared.md” is therefore a weaker configuration than an actual instruction file. It may ask the agent to read another file, but it is not a documented loader-level import.
Two practical options follow:
- Generate
AGENTS.mdfrom the shared baseline. The loader receives the actual instruction text. - Symlink
AGENTS.mdto a compatible canonical file. Agent-sync documents symlink-based instruction handling for Codex.
Neither option reproduces Claude or Cursor path conditions automatically. Directory-specific Codex instructions still need to fit Codex’s own discovery chain.
Wingo UI reports a 32 KiB combined instruction limit, equivalent to 32,768 bytes. Treat that as a loading budget to check when consolidating files. Combining every specialist rule into a single baseline can consume the budget while adding instructions irrelevant to most tasks.
Frequently Asked Questions
3 questions
1Can all four agents use one symlinked rules folder?
The cited sources do not establish that. They document specific import, symlink and native-discovery mechanisms, but do not verify Kiro compatibility or universal traversal of a shared rules directory.
