Forum threads keep offering the same fix: ln -s AGENTS.md CLAUDE.md so Claude Code and the shared contract stay the same. That works on a solo machine when every tool resolves the link—and it fails quietly on teams, CI, and mixed OS checkouts. Prefer a thin CLAUDE.md that imports @AGENTS.md (or the import your Claude Code version documents) so one source of truth stays visible and portable. Soft path: start at /free. Harness templates that assume the bridge: the Agent Starter Kit ($47). This post owns the symlink versus import bridge those companion posts assume. Cheat Sheet is the skim checklist mindset only.
Who this is for
You’re past “what goes where” and stuck on the symlink shortcut—or you already have two fat files drifting. Day-one multi-harness layout: One AGENTS.md for Cursor, Claude Code, and Codex. File map (AGENTS vs CLAUDE vs Cursor rules): AGENTS.md vs CLAUDE.md vs `.cursor/rules`. Human vs agent boundary: What belongs in AGENTS.md vs README. Monorepo depth (optional): Nested AGENTS.md monorepo playbook. This post owns the symlink vs import bridge decision those posts assume.
When symlink is OK vs not
| Situation | Symlink? | Prefer instead |
|---|---|---|
| Solo laptop; every tool resolves the link; you accept breakage risk | OK, still optional | Thin `CLAUDE.md` → `@AGENTS.md` (clearer in git) |
| Team repo, CI, mixed macOS / Linux / Windows checkouts | No | Explicit import bridge |
| Link breaks silently; Claude grows a second encyclopedia | No | One SoT in `AGENTS.md`; thin Claude bridge |
| You want the relationship visible in PRs and diffs | Prefer not | Import line reviewers can see |
Preferred pattern: keep root `AGENTS.md` as the portable contract. Make `CLAUDE.md` a short bridge that imports `@AGENTS.md` (or the documented import form). Don’t fork a second novel. Don’t hide the relationship behind a symlink that some clones never follow.
Do / Don’t
Do
- Put shared commands, verify, and guardrails in root `AGENTS.md` only.
- Keep `CLAUDE.md` thin—import the contract; don’t restate it.
- Document the bridge in the kit README so teammates don’t invent a second SoT.
- Use Cursor `.cursor/rules` for globs / alwaysApply only—not a paste of `AGENTS.md`.
Don’t
- Symlink across CI / mixed OS without proving every checkout resolves the link.
- Maintain fat `CLAUDE.md` + fat `AGENTS.md` (fastest drift).
- Treat a broken link as “Claude has no contract”—it will invent one.
- Put secrets in either file (env / secret stores only).
Harness drift
Two full files drift fastest: someone edits verify in `AGENTS.md`, Claude keeps the old path from a fat `CLAUDE.md`, and you debug “which contract did it read?” Symlinks hide the relationship in git and break silently when a checkout doesn’t follow links. Imports make the single SoT obvious in every PR. Debug order when harnesses disagree: open root `AGENTS.md` → confirm `CLAUDE.md` is a thin `@AGENTS.md` bridge (not a fork) → confirm Cursor rules aren’t a third encyclopedia → confirm nested overrides stay local (nested playbook).
What the Agent Starter Kit is for
The Agent Starter Kit ($47) is aimed at production harness templates under the instruction layer—`AGENTS.md` plus thin adapters—not another symlink tutorial. Use it when you want a kit-backed file map that already assumes the import bridge. Soft path: /free for the starter desk; Cheat Sheet when you want the skim checklist mindset; kit when you’re standardizing Cursor + Claude Code + Codex on one contract.
Companion layout: One AGENTS.md for Cursor, Claude Code, and Codex. Decision tree: AGENTS.md vs CLAUDE.md vs `.cursor/rules`.
Soft next step
Replace dual encyclopedias with one visible bridge: root `AGENTS.md` as SoT, thin `CLAUDE.md` → `@AGENTS.md`, no silent symlink dependency. Soft ladder: /free for the starter desk, then the Agent Starter Kit ($47) for harness templates under that bridge. Multi-harness layout: agents-md-cursor-claude-codex; file map: agents-md-vs-claude-md-vs-cursor-rules; human vs agent: agents-md-vs-readme.