Multi-Tool Path
Who it's for
Individuals or teams running more than one coding agent/tool and tired of divergent instructions, duplicated CLAUDE.md vs AGENTS.md drift, and "works in Cursor, fails in Claude Code."
Prerequisites
- At least two tools in active use on the same repo
- Permission to standardize on AGENTS.md (or equivalent) as source of truth
- Willingness to delete tool-specific folklore that isn't load-bearing
Ordered modules
- CLAUDE.md & AGENTS.md — one content contract, multiple readers
- Context and Instruction Hierarchy — how layers compose and conflict
- Repository Structure — layout that every tool can navigate
- Docs as Agent Memory — put truth in files, not chat profiles
- Control Techniques — portable controls vs tool-only tricks
- Prompt Anatomy — structure that transfers
- AGENTS.md template — standardize the file
- Agent Handoff note — switch tools mid-task without amnesia
- Stuck Loops and Thrash — thrash looks different per tool; reset is the same
- Maintenance Prompts — keep docs true across tools
Exercises
- Diff CLAUDE.md vs AGENTS.md vs Cursor rules; merge into one AGENTS.md; make CLAUDE.md a pointer/symlink.
- Run the same feature spec through two tools; compare drive-bys and checklist failures; update standing orders to prevent the shared failure.
- Document which workflows are tool-specific (e.g. Claude Code plan mode, Cursor Composer) vs portable in a one-pager linked from README.
- Add a CI check or script that fails if CLAUDE.md and AGENTS.md diverge beyond an allowed pointer pattern.
Capstone
Deliver a multi-tool standard for one repo: single instruction source, shared templates, handoff note convention, and a short evaluation showing equivalent outcomes on a real task in two tools.
Expected outcome
Engineers can switch tools without rewriting the project's brain; instruction drift becomes a detectable defect, not a culture.