AGENTS.md vs CLAUDE.md vs Cursor rules

Cursor reads AGENTS.md at the repo root and extra rules under .cursor/rules. Claude Code reads CLAUDE.md. v0 and Lovable do not read those files; they want a prompt. HelpKoder exports the artifact that matches the agent you picked so you are not pasting a Cursor rule into Claude or a CLAUDE.md into a browser generator.

I learned this the expensive way. Early HelpKoder dumps were “context.md” for everyone. Cursor ignored half of it. Claude Code treated a Tailwind token table as optional flavor. The fix was not a longer prompt. The fix was the right filename.

What is AGENTS.md and who reads it?

AGENTS.md is a root-level brief for coding agents that follow the Agents.md convention. Cursor is the one I target first. The file should be short enough to stay in context: what the product is, the stack, the visual source of truth (the screenshot), token roles, and the build order.

It should not be a novel. It should not duplicate every component prop. If the spec is 1,500 lines, AGENTS.md is the spine. The rest lives in the studio document or in a rule file the agent can pull when it touches UI.

HelpKoder’s Cursor export is that spine plus a project rule that says: the screenshot is canonical for layout and color; do not substitute a default palette.

What is CLAUDE.md?

CLAUDE.md is Claude Code’s project memory. Same job as AGENTS.md, different reader. Claude Code looks for it in the working directory. The tone that works is imperative and local: “Use the App Router. Do not add a /pages directory. Copy hex from the token table. Ask if a state is missing.”

A CLAUDE.md that reads like a blog post gets skimmed. A CLAUDE.md that reads like a shop drawing gets followed. HelpKoder’s Claude export is closer to the shop drawing. The kickoff you paste in the terminal is even shorter, because Claude Code deep links and first messages have a tight budget. See copy a Claude Code kickoff.

What are Cursor rules for?

Cursor rules (.cursor/rules or the older .cursorrules) fire when you work in matching files. They are the wrong place for the whole product story. They are the right place for invariants: “UI color comes from CSS variables in globals.css.” “Do not introduce a second button component.” “Prisma stays the source of schema.”

I export one UI rule from HelpKoder and keep AGENTS.md as the overview. If you paste the entire spec into a rule, you pay the token cost on every chat. If you paste nothing, Cursor invents shadcn defaults that miss the mock.

Why not one file for every agent?

Because the tools do not share a reader. Claude Code will not crawl .cursor/rules unless you tell it to. Cursor will not prefer CLAUDE.md unless you also maintain AGENTS.md. v0 has no repo. A portable context.md is the fallback HelpKoder still offers when you pick a generic target.

The studio asks which agent you will paste into before the spec streams. That choice changes the export pack, the kickoff wording, and sometimes the stack defaults. Web plus Cursor leans Next.js App Router. Claude Code is the same stack unless you chat otherwise. v0 leans a single-file or small-tree React prompt.

How should I drop these files into a repo?

Create the repo (or an empty folder). Save AGENTS.md or CLAUDE.md at the root. Save the Cursor rule where Cursor looks. Put the screenshot in the project, or attach it on the first message. Paste the kickoff.

Do not start the agent, then add the files later. The first turn is when the model picks the tree. The Cursor walkthrough is the click path. The studio intro is why the spec exists at all.

What still belongs in the human spec?

Agent files are not the studio. The studio keeps the long inventory: screens, hidden states, component list, Prisma sketch, routes. You chat that document until it matches the frame. Then you export. If you only save AGENTS.md and throw away the spec, you will re-litigate empty states next week.

Use the agent file to start. Use the spec to settle arguments. Use the screenshot to judge the result.