Writing a good playbook

A playbook is the way-of-working instruction attached to a flow (the part that tells the model how your company wants a task done, not just what the task is). Get this part vague, and the flow runs, but it doesn't actually help. Get it specific, and it's the closest thing to cloning your best person's judgment.

Start from a real example, not a description

The weakest playbooks describe a role in the abstract: "act as a helpful reviewer." The strongest ones come from watching how your actual best person handles the task and writing down what they do differently. Our "Reviewer" playbook isn't "review the code." It's "review for correctness, tests, and risk; leave specific, actionable comments; do not approve or merge; report judgment calls." Every clause in there came from a real PR someone pointed at and said "this is what good looks like."

Say what not to do

The most useful line in most of our playbooks is a boundary, not an instruction. "Never promise refunds or timelines." "Do not modify files." "Do not approve or merge." A capable model will happily do more than you asked if you don't tell it where to stop, and "more than you asked" is usually where the risk lives.

Keep it short enough that it actually gets followed

A playbook that reads like a policy manual gets followed like a policy manual: loosely, and worse under pressure. Our "Summarizer" playbook is four lines: what happened, what was tried, what's needed, under 200 words. That's not a limitation, it's the whole point. Specific and short beats thorough and long.

• Write from a real example your best person produced, not a generic description of the role.
• Include at least one explicit boundary: what the task should never do on its own.
• Match the tone to how the output should read, not how a policy document reads.
• Keep it to a few sentences. If it needs headings, it's trying to be two playbooks.

Test it on an edge case before you ship it

Run the flow on the hardest version of the task before you turn it on for everyone: the ticket your newest hire would get stuck on, the PR with the subtle bug. If the playbook holds up there, it'll hold up on the easy 90% without you having to check.