⚡ Ryukami Labs

🧭 Opus 5.5 Dev — Definir «Terminado», TASKS.md y un Informe Fijo

Se lee en 11 min

🧭 Opus 5.5 Dev — Definir «Terminado», TASKS.md y un Informe Fijo

El playbook para que una tarea larga no se desinfle

ToroFelipe/opus-5-5-dev es una skill de Claude Code que impone hábitos de trabajo en tareas de varios pasos: features, refactors, migraciones, auditorías, revisiones y UI.

  • Las tres reglas que la definen: fijar qué significa «terminado» antes de tocar código, mantener un TASKS.md para sobrevivir a la compactación de contexto, y cerrar con un informe de cuatro bloques.
  • La cuarta, la que más cambia el día a día: no preguntar «¿continúo?». Sigue salvo que necesite información tuya o vaya a hacer algo destructivo.
  • Base: Getting the most out of Opus 5.5 in Claude and Claude Code, de Addy Osmani (claude.dev, sep-2026).
  • Licencia: MIT. Proyecto comunitario, no oficial de Anthropic.

Repo de 4 estrellas, un solo commit y cero mantenimiento

4 ⭐, 0 forks, 0 issues, 10 KB y 8 archivos. Se creó el 23-sep-2026 a las 04:59:13 y el último push es de las 04:59:18 — cinco segundos después.

Traducción: un commit inicial y nunca más se tocó. No lo juzgues por popularidad ni por actividad. Júzgalo por el contenido, que es denso y está bien pensado, y cópialo a tu proyecto en vez de esperar actualizaciones.

🧭 Qué es y qué no es

EsNo es
Una skill con hábitos de trabajoUn agente autónomo nuevo
Una capa de disciplina sobre Opus 5.5Un modelo o un plugin de terceros
Un CLAUDE.md listo para pegarConfiguración oficial de Anthropic
Una guía de prompting para humanosDocumentación de la API
MIT y 10 KB de textoUn framework con dependencias

No ejecuta nada: no hay scripts, ni hooks, ni instalador. Es texto que Claude lee para cambiar cómo trabaja. Toda su fuerza está en las reglas, no en el código.

flowchart TD
    A["🎯 Definir «terminado»<br/>+ cuándo parar"] --> B["📋 Crear TASKS.md"]
    B --> C["⚙️ Trabajar y marcar pasos"]
    C --> D{"¿Bloqueo real o<br/>acción destructiva?"}
    D -- "Sí" --> E["🛑 Parar y preguntar"]
    D -- "No" --> C
    C --> F["🧪 Tests + revisar el diff"]
    F --> G["📄 Informe: Blocked / Changed /<br/>Found / Not verified"]

🎯 Regla 1: «terminado» es una comprobación, no una sensación

Antes de tocar código, la skill exige dos frases explícitas:

  • «Done means…» — una línea de meta verificable: «pasa la suite», «todos los endpoints usan el cliente nuevo y el viejo está borrado», «cada servicio tiene un veredicto sí/no con evidencia».
  • «Stop and ask when…» — las condiciones en las que devuelve el control.

Si no se las das, las infiere y las declara en una línea al empezar, y sigue. Solo pregunta antes si el objetivo es ambiguo de verdad y una suposición equivocada tiraría a la basura una tirada larga.

Migra los endpoints de pago al cliente nuevo.
Terminado = todos usan el cliente nuevo, el viejo está borrado y pasan los tests.
Párate y pregúntame solo si falla un test por una razón que no puedas explicar.

Por qué esto importa más de lo que parece

Sin línea de meta, una tarea larga tiene dos finales posibles y los dos son malos: parar antes («ya está» cuando no lo está) o seguir de más (refactorizar lo que nadie pidió). La frase «Done = X» es lo que hace que el agente sepa cuándo soltar.

📋 Regla 2: TASKS.md sobrevive a la compactación

Para cualquier cosa más allá de un puñado de pasos, crea TASKS.md en la raíz y mantenlo vivo:

# Task: <una línea>
Done means: <línea de meta>
Stop and ask if: <condiciones>
 
- [x] Paso ya terminado
- [ ] Paso en curso — nota de lo que queda
- [ ] Hallazgo nuevo (encontrado mientras hacía X)
 
## Decisions made
- Elegí A sobre B porque … (reversible: sí/no)
Por qué funcionaDetalle
Sobrevive al contextoLas tiradas largas llenan la ventana y los turnos viejos se resumen; el archivo queda.
Se relee tras compactarEs la primera cosa que debe mirar al retomar.
Tú ves el progreso de un vistazoSin hacer scroll por el historial.
Registra decisionesLas no bloqueantes se anotan y se siguen, en vez de preguntarte.
No se borra soloAl acabar queda, salvo que pidas eliminarlo.

El bloque «Decisions made» es el que casi nadie copia

Y es el que evita la pregunta más cara: «¿por qué hiciste esto así?». Anotar la decisión y si es reversible convierte una discusión en una línea.

📄 Regla 3: el informe fijo de cuatro bloques

Toda tirada sustancial termina así, en este orden, porque lo primero que necesitas saber es qué te está esperando:

## Blocked on you
- Decisiones abiertas, aprobaciones, credenciales. «Nada» si no hay.
 
## Changed
- Qué se hizo, por áreas, en lenguaje llano. Archivos clave enlazados.
 
## Found
- Bugs, riesgos, sorpresas y seguimientos descubiertos por el camino.
 
## Not verified
- Qué no se pudo confirmar y dónde se buscó. «Todo verificado» si aplica.
BloqueLa pregunta que responde
Blocked on you¿Qué me toca hacer a mí?
Changed¿Qué cambió?
Found¿Qué descubriste que yo no sabía?
Not verified¿Qué me estás vendiendo como cierto sin serlo?

En inglés por defecto

Los encabezados del snippet están en inglés. Si los quieres en español, cámbialos en el CLAUDE.md: la skill dice explícitamente que el formato del usuario gana sobre el suyo.

⚙️ Las otras cuatro reglas

ReglaQué haceQué evita
Seguir sin preguntarSi el siguiente paso no te necesita, lo da. Notas de estado en el mismo mensaje que la acción.El «¿quieres que continúe?» y los menús de opciones que no bloquean nada
Parar solo por bloqueo o peligroBorrar datos, force-push, reescribir historia, desplegar, enviar algo externo, tocar fuera del repoQue la autonomía se coma tu red de seguridad
Repartir en subagentes y verificarUna unidad (servicio, paquete, endpoint) por subagente; cada uno devuelve evidencia, no veredictoAceptar «está afectado» sin abrir la línea citada
Revisar el diff antes de decir «hecho»Corre tests, build, linter y type-checker; lista solo lo que bloquearía un merge, con archivo:línea y cómo fallaEl «listo» sin pruebas y el auto-review complaciente

Sobre subagentes, la frase clave: «las afirmaciones de un subagente son pistas, no hechos». Se abre la línea citada y se repite el comando si es barato. Al final, una tabla consolidada:

UnidadResultadoEvidencia
services/billingafectadoretry.go:88 reintenta un POST no idempotente

🎨 El anexo de UI: 9 defaults a evitar

Sin dirección de diseño, Opus 5.5 cae en los mismos tics. Nombrarlos funciona; «hazlo menos genérico» no.

#DefaultPor qué se nota
1Fondos crema, beige o blanco rotoEl «look IA» de 2025-2026
2Palabras en cursiva o serif dentro de titulares sansAdorno sin función
3Etiquetas numeradas 01 / 02 / 03Relleno de sección
4Eyebrows en mono o versalitas sobre el titularDecoración repetida
5Botones píldora en todas partesForma por defecto, no decisión
6Degradado violeta→azul o pastel como acentoEl acento más previsible
7Tres tarjetas idénticas con icono, título y fraseEstructura sin contenido
8Emojis como iconosRompe la jerarquía visual
9Hero gigante centrado con dos botones como única ideaUna landing sin argumento

Cuidado con aplicar la lista donde no toca

Es una lista para UI de producto, no para documentación. Tu bóveda usa emojis como marcadores de navegación y tiene su propio sistema visual (Scorch); ahí la regla 8 no aplica. La propia skill lo dice: si hay una dirección de diseño —tu marca, un design system— esa gana y la lista se ignora donde choque.

El resto del anexo: si no hay dirección, elige una que encaje con el producto, evita esos patrones y di en una línea qué dirección tomaste. Si no te gusta, di qué exactamente: eso se convierte en un ítem de tu lista, no en un «prueba otra vez».

🚀 Instalación

git clone https://github.com/ToroFelipe/opus-5-5-dev.git
cp -r opus-5-5-dev/opus-5-5-dev ~/.claude/skills/
AlcanceDestino
Todos tus proyectos~/.claude/skills/
Un solo proyecto.claude/skills/ dentro del repo

En Windows (PowerShell):

Copy-Item -Recurse opus-5-5-dev\opus-5-5-dev $HOME\.claude\skills\

El paso que de verdad importa: el CLAUDE.md

Una skill solo se carga cuando se activa. Las reglas de cuándo parar y el formato del informe las quieres siempre, así que pega el snippet en tu CLAUDE.md (raíz del proyecto o ~/.claude/CLAUDE.md):

## Working style
- When a step doesn't need my input, keep going. Put status notes in the same
  message as your next action. Don't end a turn with "want me to continue?".
- Stop and ask only when you can't continue without me, or before anything
  destructive: deleting data, force-pushing, rewriting history, deploying,
  or changing anything outside this repository.
- For long tasks, keep a checklist in TASKS.md. Tick items when done and add
  anything new you find.
- Before saying you're done, run the tests and review your own diff.
- End every run with these headings: Blocked on me, Changed, Found, Not verified.

Hay un modo «pair programming»

El repo trae una alternativa para cuando no quieres autonomía: plan de una línea antes de empezar y esperar tu OK, recaps de dos líneas por paso. Útil en código delicado o cuando estás aprendiendo el flujo.

Menos paradas significa que los permisos son tu red

Si el agente deja de preguntar «¿continúo?», lo único que queda entre él y un desastre son las condiciones de parada y los prompts de permiso. La skill lo dice sin rodeos: no las sortees ni las desactives «para ir más rápido».

🗣️ La guía de prompting (para ti, no para Claude)

HábitoQué hacer
PedirEntrega la tarea completa en un mensaje, con línea de meta y condiciones de parada
Quitar«Think carefully» y «step by step»: el modelo ya piensa y decide cuánto; quitarlo hace que empiece antes
AñadirEscribe el seguimiento mientras trabaja y pulsa Enter; no reinicies
DiseñoDi qué patrones no quieres, no «hazlo bonito»
DatosAdjunta el gráfico o la captura en vez de reescribir números
RevisarLee primero Blocked on you; luego pide un pase de revisión con criterio de merge
Velocidad/fast en Claude Code: mismo modelo, salida más rápida, más caro por token

Lo del «razonamiento interno»

Pedirle que reproduzca su razonamiento paso a paso en la respuesta puede ser rechazado. Pide una explicación corta de la decisión, que es lo que realmente necesitas.

⚖️ Lectura crítica

Lo bueno:

  • Ataca el problema correcto: las tareas largas no fallan por falta de inteligencia, fallan por falta de línea de meta y de memoria.
  • Reglas cortas, comprobables y en imperativo. Se pueden pegar y funcionar el mismo día.
  • El informe de cuatro bloques es la mejor pieza: obliga a separar «hecho», «encontrado» y «no verificado». Ese último bloque es donde suele estar la verdad.
  • Bilingüe en el README (español primero), aunque la skill esté en inglés.
  • Anexo de UI muy concreto: nombra los patrones en vez de decir «sé original».
  • Reconoce la autoridad del usuario: tu CLAUDE.md gana sobre la skill.
  • Cita la fuente (Addy Osmani) en vez de venderlo como propio.

Lo que hay que tener en cuenta:

  • 4 estrellas, 0 forks y un solo commit de hace un mes. Cero señal de uso real y cero mantenimiento.
  • Un push de 5 segundos tras crear el repo: es un volcado inicial, no un proyecto en desarrollo.
  • No tiene tests ni validación de que las reglas funcionen; es texto opinado.
  • Reglas en inglés y formato de informe en inglés: si trabajas en español, hay que adaptarlo.
  • Sesgo hacia la autonomía. El modo por defecto empuja a no preguntar; en código delicado eso se paga. El modo pair-programming existe, pero es la alternativa, no el default.
  • No está empaquetado para marketplaces ni tiene versión; se instala copiando carpetas.
  • Depende de que tú leas el informe. Si no abres «Not verified», el bloque se vuelve decorativo.
  • La fuente es un artículo de blog, no documentación oficial de Anthropic. Las recomendaciones son de una persona, por buenas que sean.
  • TASKS.md puede ensuciar el repo si no lo añades a .gitignore o lo borras al cerrar.

La lectura de fondo

No es una skill para que Claude escriba mejor código: es una skill para que termine lo que empieza y te lo cuente sin adornos. Su valor está en tres frases que puedes copiar sin instalar nada — «Done = X», «me paro solo si Y» y «Blocked / Changed / Found / Not verified» — y en la disciplina de no confundir «hecho» con «creo que está hecho». Lo demás es un anexo de UI que está bien tener a mano. Con 4 estrellas y un commit, esto es un buen documento, no un proyecto con comunidad: úsalo como checklist y verifica tú mismo que las reglas se cumplen.

🔗 Enlaces

🔗 Notas relacionadas

Vista Gráfica

Retroenlaces