AGENTS.md is the agent operating contract—commands, verify steps, guardrails, handoff expectations—short enough to stay true. README.md is for humans: product story, install overview, screenshots, and links. Don’t make agents hunt verify commands in marketing prose, and don’t bury the human story inside always-on agent context. Secrets belong in neither file: env / secret stores only (document env names in README if needed, never values). Split one drifted pair today; keep one source of agent truth. Soft path: start at /free. Harness templates under that split: the Agent Starter Kit ($47).
The split you’ll actually need
Teams that run Cursor, Claude Code, and Codex often grow one fat file that tries to be both a product README and an agent runbook. Humans skim past verify steps. Agents burn tokens on screenshots and “why we built this.” Then someone edits only one copy and the other drifts.
Day-one multi-harness layout (Claude `@AGENTS.md` bridge, Cursor adapters): One AGENTS.md for Cursor, Claude Code, and Codex. Monorepo depth (root vs nested overrides): Nested AGENTS.md monorepo playbook. This post owns the human vs agent boundary those posts assume.
Do / Don’t
| Put in `AGENTS.md` | Put in `README.md` | Put nowhere in either |
|---|---|---|
| Install / run / verify commands agents must use | Product story, audience, screenshots | Secrets, tokens, API keys |
| Guardrails and stop-before-send/publish/pay | Install overview for humans | Long tutorials that belong in docs/skills |
| Handoff expectations between roles | Links to docs, kits, changelogs | Duplicate novels that will drift |
| Pointers to nested package overrides | Required env *names* (not values) | Cursor-only style guides (→ `.cursor/rules`) |
| “Stop and ask” language for irreversible actions | Contributing / support for people | Marketing CTAs as always-on agent context |
Short beats clever. If a section needs a novel, link out from `AGENTS.md`—don’t paste the whole guide into always-on context.
Common handoff mistakes
- Same long guide in both files until they disagree about verify or approval stops.
- Verify only in README so agents invent commands or skip checks.
- Secrets “documented” as values in either file (or in chat).
- Fat `CLAUDE.md` / always-on Cursor rules that restate the README novel instead of bridging root `AGENTS.md`.
Debug order when harnesses and humans disagree: open root `AGENTS.md` → confirm README doesn’t own the only verify path → confirm Claude bridge imports `@AGENTS.md` → confirm nested overrides stay local (nested playbook).
Split checklist
- [ ] Root `AGENTS.md` has commands, verify, guardrails, and handoff expectations.
- [ ] `README.md` holds product story and human install overview—not the only verify source.
- [ ] No secrets in either file; README may list env *names* only.
- [ ] No duplicate encyclopedia across README + AGENTS.md + `CLAUDE.md` + always-on Cursor rules.
- [ ] Nested `AGENTS.md` (if any) stays short and local—not a rewrite of root or README.
- [ ] Thin Claude bridge → `@AGENTS.md`; Cursor `.cursor/rules` for globs only.
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 adapters—not another “what is a README” gloss. Use it when you want a kit-backed file map that already assumes the human vs agent split. 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 for the multi-harness day-one layout: One AGENTS.md for Cursor, Claude Code, and Codex. Monorepo inheritance: Nested AGENTS.md monorepo playbook. If remote MCP Connect is the other half of the desk, pair with the MCP Starter Kit—different job, same agent-ops shelf.
Soft next step
Split one drifted README / `AGENTS.md` pair into human story vs agent contract, keep secrets out of both, and bridge Claude with `@AGENTS.md`. Soft ladder: /free for the starter desk, then the Agent Starter Kit ($47) for harness templates under that split. No rush—write the boundary into your own runbook either way. Multi-harness layout: agents-md-cursor-claude-codex; monorepo depth: nested-agents-md-monorepo.