Production Best Practices for AI Coding Specifications
How to write agent instructions that survive real repos, with Refract's AGENTS.md layout as the worked example and an honest read next to MakerKit and Supastarter.
FAQ
- Is AGENTS.md only for Claude Code?
No. Refract treats AGENTS.md as the cross-agent index. Claude Code gets a thin CLAUDE.md that imports it. Cursor loads glob-scoped .cursor/rules/*.mdc files. The goal is one canonical text per rule, not one vendor format.
- Why not put everything in one always-on Cursor rule?
Because Cursor can double-load it against root AGENTS.md, and you will fix the copy that was not in context. Refract explicitly forbids duplicating universal bodies in an alwaysApply .mdc.
- What goes in root AGENTS.md versus apps/backend/AGENTS.md?
Universal invariants, Makefile-only commands, precedence, read-before-edit, and the spec contract live at the root. Package guides answer where to put a change and point at nested guides for billing or payment processor ownership.
- How is this different from Supastarter's Prompting the AI doc?
That page is about in-app LLM prompts in packages/ai, not repository governance for coding agents. Confusing the two is how you end up tuning product copy while the agent still runs pnpm on the host.
- Does MakerKit ship agent guidance?
Yes. Their installation docs cover AGENTS.md, package-level files, CLAUDE.md, skills, and MCP. The shopping question is whether they document drift prevention the same way: precedence tables, mirror contracts, read-before-edit, staged test edits.
- How do you stop an agent from rewriting legacy tests on autopilot?
Root AGENTS.md documents a staged spec contract: production code first, manual verification in prose, new contract tests in isolation with make markers, then batched human confirmation before legacy assertions move.
- Isn't this overkill for a solo dev?
Probably, if you are one person on one app and you never touch billing webhooks in the same week as a cross-package refactor. The payoff shows up when agents do exactly that and your CI stays green for the wrong reasons.
