📘 Entiende qué es un playbook
Un playbook es un procedimiento reutilizable para una tarea recurrente. No es un principio ("prueba bien"), es una secuencia de pasos con orden, entradas, salidas y criterio de finalización.
Cómo leer: los cuatro playbooks tratan situaciones diferentes, pero convergen en el mismo formato. Si aprendes este esqueleto, escribes cualquier playbook nuevo en quince minutos y todos son consumibles por el mismo agente.
🆕 ¿Nuevo por aquí?
Playbook es el procedimiento escrito para personas y agentes. Skill (módulo 5.2) es ese mismo procedimiento empaquetado para que el agente lo ejecute directamente. Rule es un límite que se aplica en todas las tareas, independientemente del playbook. Uno describe el camino, el otro lo acorta y el tercero cerca la ruta.
Secuencia
No es consejo
Recurrente
Tarea que se repite
Repetible
Entre personas y agentes
Esqueleto
Igual para todos
✨ Playbook de nueva funcionalidad
El camino estándar para el trabajo nuevo. Dejarlo por escrito elimina la diferencia de calidad entre la tarea hecha el lunes por la mañana y la hecha el viernes a las 18h.
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
✓ Dónde el playbook ayuda
- ✓"Confirmar el alcance" detecta el malentendido antes de que exista el código
- ✓"Mapear el impacto" revela al consumidor que estaba por fallar
- ✓"Planificar antes de implementar" permite corregir el rumbo a bajo costo
✗ Atajos que salen caros
- ✗Saltarse el plan "porque es rápido"
- ✗Dejar la documentación para después (nunca llega)
- ✗Escribir las pruebas solo cuando todo esté listo
Confirmar
Antes de programar
Impacto
¿Quién rompe?
Mínima
El cambio correcto
Documentar
Es parte de lo que significa estar listo
🐞 Playbook de corrección de bugs
Aquí el orden lo es todo. Sin reproducción, corriges lo que imaginas; sin una prueba que falle antes, no hay evidencia de que el bug haya desaparecido.
Reproduzir o erro → registrar evidência → identificar causa → criar teste que falha → implementar correção → executar regressão → revisar impacto → documentar
💡 Consejo práctico
Si el error no se reproduce, cambia el procedimiento: la tarea pasa a ser «lograr reproducirlo», con más registros, más datos y un entorno más parecido. Corregir sin reproducir es adivinar con apariencia de trabajo.
Reproducir
Primer paso, siempre
Prueba que falla
Es la prueba
Regresión
Cierra el ciclo
¿No reproduce?
Esta se convierte en la tarea
🏚️ Playbook de modernización
Es la ruta 4 condensada en un procedimiento: el formato en que realmente se usa.
Mapear dependências → criar testes de caracterização → definir fronteira → criar adaptador → migrar pequeno módulo → executar em paralelo → comparar resultados → liberar gradualmente
🧪 Ejercicio copiable — generar tus playbooks a partir de lo que ya hace el equipo
Objetivo: escribir el primer playbook de tu repositorio sin partir de cero, usando el historial real.
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.
Cómo verificar: usa el playbook en la próxima tarea de este tipo y anota dónde se trabó o quedó poco claro. La segunda versión —escrita después del primer uso real— es la que cuenta.
Del historial
No es de la imaginación
Qué faltó
Se convierte en un paso explícito
Evidencia
Parte del playbook
Automatizable
Márcalo desde ahora
🚨 Playbook de incidentes
Bajo presión nadie improvisa bien. Este playbook existe principalmente para impedir que la primera reacción borre la evidencia de lo ocurrido.
Coletar logs → classificar gravidade → preservar evidências → identificar causa provável → criar mitigação → validar → aplicar correção → registrar aprendizado
⚠️ Atención
Reiniciar el servicio suele resolver el síntoma y destruir la evidencia. Si necesitas reiniciarlo para restablecer el servicio, captura antes los logs, el estado, las métricas y el volcado. Sin eso, el mismo incidente vuelve y empiezas desde cero.
🔁 El paso más olvidado: registrar lo aprendido
Todo incidente resuelto debe terminar con una decisión: esto se convierte en prueba, se convierte en rule, se convierte en gate o se convierte en alerta? Un incidente que termina solo cuando el servicio vuelve a estar en línea se repite.
Conservar
Antes de actuar
Mitigar
No es corregir
Gravedad
Define la respuesta
Aprendizaje
Se convierte en prueba o gate
♻️ Mantén los playbooks actualizados
Un playbook desactualizado es peor que no tener uno: el agente sigue un procedimiento que ya no describe el sistema, con toda la confianza del mundo.
¿Falló en la práctica? Actualízalo de inmediato
El mejor momento para corregir un playbook es justo después de que haya fallado, mientras recuerdas exactamente dónde se atascó.
Con control de versiones en el repositorio
En /docs/playbooks/, revisado como código. Cambiar el playbook es cambiar el proceso y merece una revisión.
Pocos y buenos
Cinco playbooks en uso valen más que treinta archivados. Si no consultaste uno de ellos en seis meses, elimínalo o fusiónalo con otro.
Verificación rápida: ¿cuál es el mejor punto de partida para escribir el primer playbook del equipo?
Actualiza
Cuando falle
Con control de versiones
Revisado como código
Pocos
Y realmente usados
Muerto
Borra sin piedad
📌 Resumen del módulo
Próximo módulo:
5.3 - Gobernanza y niveles de autonomía: quién es el agente y hasta dónde llega.