📘 Understand what a playbook is
A playbook is a reusable procedure for a recurring task. It’s not a principle ("test thoroughly"), it’s a sequence of steps with sequence, inputs, outputs, and a completion criterion.
How to read: the four playbooks cover different situations, but converge on the same format. If you learn this skeleton, you can write any new playbook in fifteen minutes — and they’ll all be usable by the same agent.
🆕 New here?
Playbook is the procedure written for humans and agents. Skill (module 5.2) is that same procedure packaged for the agent to run directly. Rule is a limit that applies in all the tasks, regardless of playbook. One describes the path, the other shortens it, and the third fences off the road.
Sequence
Not advice
Recurring
Recurring task
Repeatable
Between people and agents
Skeleton
The same for everyone
✨ New feature playbook
The default path for new work. Having this written down eliminates the difference in quality between a task done on Monday morning and one done at 6 p.m. on Friday.
Ler a especificação → confirmar escopo → mapear impacto → criar plano → implementar mudança mínima → criar testes → executar quality gates → revisar → documentar → preparar pull request
✓ Where the playbook helps
- ✓"Confirm scope" catches the misunderstanding before any code exists
- ✓"Map the impact" reveals the consumer that was about to break
- ✓"Plan before implementing" makes it cheap to change course
✗ Shortcuts that cost you dearly
- ✗Skip the plan “because it’s quick”
- ✗Leave documentation for later (it never happens)
- ✗Write the tests only after everything is ready
Confirm
Before coding
Impact
Who breaks it?
Minimal
The right change
Document
Part of done
🐞 Bug fix playbook
Here, the order is everything. Without reproduction, you fix what you imagine; without a test that fails first, there’s no proof that the bug is gone.
Reproduzir o erro → registrar evidência → identificar causa → criar teste que falha → implementar correção → executar regressão → revisar impacto → documentar
💡 Practical tip
If the bug can’t be reproduced, the playbook changes: the task becomes “reproduce it”—with more logs, more data, and a more similar environment. Fixing it without reproducing it is guesswork disguised as work.
Reproduce
First step, always
Failing test
This is the proof
Regression
Close the cycle
Can’t reproduce?
This becomes the task
🏚️ Modernization playbook
This is Track 4 condensed into a procedure—the format in which it’s actually used.
Mapear dependências → criar testes de caracterização → definir fronteira → criar adaptador → migrar pequeno módulo → executar em paralelo → comparar resultados → liberar gradualmente
🧪 Copyable exercise — generate your playbooks from what the team already does
Objective: write your repository’s first playbook without starting from scratch, using the real history.
Analise os últimos 30 pull requests deste repositório (use git log e os arquivos alterados). Não altere nada. 1. agrupe os PRs por TIPO de tarefa (feature, bug, dependência, refatoração, infra, outros) e diga quantos caíram em cada grupo; 2. para o grupo mais frequente, descreva os passos que as pessoas de fato seguiram — inclusive os passos que ficaram FALTANDO em alguns PRs (ex.: sem teste, sem documentação, escopo estourado); 3. escreva um PLAYBOOK desse tipo de tarefa, no formato: quando usar · entradas · passos numerados · critério de pronto · ações proibidas · o que anexar como evidência; 4. aponte quais passos poderiam virar verificação automática. Salve a proposta em docs/playbooks/<nome>.md e me mostre o conteúdo.
How to verify: use the playbook on your next task of this type and note where it got stuck or was vague. The second version—written after the first real use—is the one that counts.
From history
Not from imagination
What was missing
Becomes an explicit step
Evidence
Part of the playbook
Automatable
Mark it now
🚨 Incident Playbook
Under pressure, no one improvises well. This playbook exists mainly to keep the first reaction from erasing the evidence of what happened.
Coletar logs → classificar gravidade → preservar evidências → identificar causa provável → criar mitigação → validar → aplicar correção → registrar aprendizado
⚠️ Attention
Restarting the service often resolves the symptom and destroys the evidence. If you need to restart to restore the service, capture logs, state, metrics, and a dump first. Without that, the same incident will return and you’ll start over.
🔁 The most overlooked step: recording what you learned
Every resolved incident should end with a decision: does this become test, becomes rule, becomes gate or becomes alert? An incident that ends with only the service back online will happen again.
Preserve
Before acting
Mitigate
Isn’t about fixing
Severity
Defines the response
Learning
Becomes a test or gate
♻️ Keep the playbooks up to date
An outdated playbook is worse than no playbook: the agent follows a procedure that no longer describes the system—with complete confidence.
Did it fail in practice? Update it right away
The best time to fix a playbook is right after it has failed—while you remember exactly where it got stuck.
Versioned in the repository
In /docs/playbooks/, reviewed as code. A playbook change is a process change and deserves review.
Few and good
Five playbooks you use are worth more than thirty archived ones. If you haven’t consulted one in six months, delete it or merge it with another.
Quick check: what’s the best starting point for writing the team’s first playbook?
Update
When it fails
Versioned
Reviewed as code
Few
And actually used
Dead
Delete without mercy
📌 Module Summary
Next Module:
5.2 - Skills and Rules: package capabilities and set permanent limits.