Writing a good card

A card with just a title is something an agent has to guess its way through. A few more minutes filling it in gives the agent, and the review after it, something to work from.

Title — what it is, in one line. The only required field.

Brief — what it is and anything the person building it would otherwise have to ask you. A sentence or two is usually enough.

Kind — code, design or research. Code is the default: an agent works your repository and delivers commits on a branch. Design means one mockup — a self-contained page, no repository files changed. Research means a read-only write-up. Pick design or research when you want to see an idea before anyone touches the codebase; leave it as code for anything that should ship as a change. The kind can only be changed before anyone has been handed the card.

Acceptance criteria — the specific, checkable things that make the card done. These matter more than they look: the review your Claude generates at the end is built from them, so a card with no criteria gets a thin review. Write one per line, as a fact someone can confirm — “An invited teammate can sign in,” not “invites work.”

Owns — the files or folders this card touches, comma separated. When you plan several cards together, this is what lets the split spot two cards about to collide in the same file.

Nothing here is required except the title, and a field you can’t answer yet is better left empty than guessed — an agent treats an empty field as “nobody said,” not as an answer.

See Write your first card for where these fields live, and Agents and branches for what happens once a card is handed to an agent.