Buyer guide · agentic harnesses
AGENTS.md, CLAUDE.md, and Cursor rules as project memory
Agent harnesses read different instruction files by convention. Without one portable source of truth, switching tools or running two agents scatters conflicting teaching across the repository.
Who this is for: Teams running multiple agent harnesses (Cursor, Claude Code, Aider, OpenCode) who need one portable instruction file instead of scattered .cursor/rules, CLAUDE.md, and extension-specific configs.
What actually matters
- Each harness reads different files by convention — AGENTS.md, CLAUDE.md, .cursor/rules, extension configs — without coordination they diverge.
- Conflicting instructions (test command, style, forbidden paths) produce confident wrong patches when two agents run on one repo.
- Project memory should be reviewed like code when the stack or policies change.
- Init commands (/init, muse init) can overwrite local guidance — always read the diff before committing.
- New hires should find test commands, branch policy, and secret rules in one canonical file.
- Portable AGENTS.md survives tool switches; vendor-specific-only configs do not.
ACE recommendation
Publish one AGENTS.md (or equivalent) in the repo root, link or copy into each harness’s native format, and treat instruction drift as a bug — not an inevitable side effect of multi-tool teams.
Set up the shortlist
Useful comparisons
How to run this decision
- 01Audit existing instruction files (.cursor/rules, CLAUDE.md, .aider.conf, extension JSON) and list conflicts.
- 02Write AGENTS.md at the repo root: test command, lint/format, branch policy, forbidden paths, secret handling, review expectations.
- 03Link or symlink into each harness’s native format (CLAUDE.md excerpt, .cursor/rules reference) without duplicating conflicting text.
- 04Add AGENTS.md updates to the PR checklist when tooling or CI changes.
- 05Block auto-init overwrites without human review — treat instruction drift as a bug.
- 06Onboard one new developer using only AGENTS.md and note what was missing.
Common pitfalls
- Maintaining three separate instruction files that contradict each other on test commands or style.
- Letting /init replace a carefully tuned CLAUDE.md without reading the diff.
- Putting secrets or internal URLs in project memory files that sync to vendor indexes.
- Assuming developers will discover .cursor/rules buried three directories deep.
- Never updating instructions after switching from npm test to pnpm test — agents keep running the old command.
Ask before you buy
- Which file is canonical today — AGENTS.md, CLAUDE.md, .cursor/rules, or extension-specific configs?
- Do instructions conflict (style, test commands, forbidden paths) when Cursor and a terminal agent run on the same repo?
- Who updates project memory when the stack changes — and is that update reviewed like code?
- Does /init or muse init overwrite local guidance without a human read?
- Can a new hire find the test command, branch policy, and secret-handling rules in one place?
More buyer guides
Related decisions
Other harness buyer guides that answer the next question after this one.
Buyer guide
Editor vs terminal: which coding assistant workflow fits?
Choose the surface your team will actually use before comparing model quality.
Buyer guide
How to roll out an agentic harness without losing review discipline
A staged rollout pattern for teams that want speed without turning generated patches into unowned production risk.
Buyer guide
Agentic harness pricing: seats, tokens, and overage
Compare subscriptions and usage-based plans by the work they enable, not the number printed on the landing page.
Buyer guide
Coding-assistant myths in 2026: what the product pages blur
A myth-versus-reality check for coding assistants whose pricing, editor surfaces, privacy paths, and autonomy are easy to collapse into one misleading label.
Buyer guide
Enterprise AI coding assistant procurement checklist
A compact procurement block for security, legal, IT, and finance teams evaluating coding assistants beyond the demo and the seat price.
Buyer guide
Local LLM coding setup: Ollama, LM Studio, llama.cpp, and MLX
Pick a local inference stack and wire it to an agent harness without the usual traps — wrong ports, tiny default context, bad quants, and mismatched API prefixes that make agents look broken when the model is fine.