Los principios de ODD

Objetivos

• Reconocer las ideas de fondo que se repiten en todas las reglas.
• Predecir cómo actuaría ODD ante una situación no descrita explícitamente.
• Distinguir un límite aconsejado de un límite obligatorio.

El repositorio no publica una lista oficial de principios. Esta síntesis es del curso y se obtuvo al leer las reglas juntas. Cada principio indica de qué texto proviene.

---

1. Lo pequeño sigue pequeño

Es el titular del README: Keep small work small. Una tarea comprendida, con riesgo contenido y reanudable desde el diff corre inline, sin subagentes ni documento.

La consecuencia práctica es que ningún contador convierte una tarea en grande. El texto canónico lo repite: el número de archivos, comandos, pruebas, correcciones o una lista de tareas pedida nunca decide el tamaño.

2. El tamaño se mide por comprensión, no por volumen

La medida del trabajo es si otra persona podría terminarlo a partir del pedido y de git diff. Un cambio de veinte archivos que se entiende puede ser pequeño. Una tarea de veinte líneas que espera a un tercero durante una semana es grande.

3. Delegar tiene un costo y necesita un motivo

El README lo dice sin rodeos: un subagente cuesta una sesión nueva, lecturas sin caché y un traspaso. Por eso el orquestador delega solo cuando puede nombrar el motivo.

flowchart LR
    A["¿Hay un motivo con nombre?"] -->|No| B["El parent trabaja inline"]
    A -->|Sí| C["Delegar es obligatorio"]
    C --> D["Volver a evaluar al terminar"]
    D --> A

Este principio tiene dos caras que suelen confundirse:

• Sin motivo, no se delega. Ante la duda, se trabaja inline.
• Con el motivo presente, se delega. Seguir de largo un disparador activado es un “defecto de enrutamiento”, aunque el trabajo salga bien.

4. Referenciar en lugar de parafrasear

El traspaso a un worker apunta al documento, a la tarea y a sus especificaciones. Nunca resume lo que pediste. Las frases exactas, los mensajes de error y los ejemplos se citan textualmente y en tu idioma.

El motivo proviene de una medición del proyecto: una especificación de 73 líneas con 26 comprobaciones ocultas seguía en 23 de 26 tras dos rondas con traspasos parafraseados. Las paráfrasis perdían requisitos y la solución fue pasar la especificación por referencia.

5. Solo cuenta lo observado

Esta idea aparece en casi todos los contratos:

• Un elemento se marca hecho solo después de observar su resultado y sus comprobaciones.
• No se inventa una ejecución RED, una ejecución GREEN ni un ejecutor de pruebas.
• Un worker nunca afirma que un comando corrió sin haber visto su salida.
• Lo que informa un worker es un autoinforme, y el parent comprueba al menos un comando.
• Si no hay verificador disponible, se informa como no disponible, sin simular que pasó.

El informe de cierre incluye todas las comprobaciones fallidas, omitidas o pendientes.

6. La proporción sustituye a la ceremonia

Los mecanismos existen, pero cada uno se enciende solo por su propio disparador. Una comprobación rápida corre una vez. Un trabajo largo recibe una estimación de costo antes de lanzarse. Hay límites explícitos para evitar bucles:

Situación	Límite
Correcciones tras un verificador	Un lote que arregle todos los bloqueos y una recomprobación limitada a ellos
Segunda corrección	Solo si la recomprobación muestra el mismo bloqueo fallando
Desafío de supuestos	Como máximo uno
Pregunta al usuario	Una, enfocada, y luego se espera
Pasadas para dividir un PR	Una pasada honesta

La fuente lo resume en una frase: no hay un comportamiento de repetir hasta que quede limpio.

7. Los límites numéricos son heurísticas, salvo que se diga lo contrario

Las 400 líneas por tarea son el ejemplo principal. El texto canónico enumera lo que no son: un criterio de aceptación, un tope, un disparador, una parada automática ni una división forzada.

También prohíbe explícitamente hacer trampa con ellas: borrar espacios, líneas en blanco o comentarios para ahorrar líneas, omitir pruebas, minificar o dividir de forma artificial.

Otros números, como el presupuesto de contexto de 150k tokens, se declaran como orientación que nadie observa mecánicamente. El agente no debe afirmar lo contrario.

8. El control humano no se delega

Los permisos están separados de forma deliberada:

flowchart TD
    A["Pedido autorizado"] --> B["Implementar, documentar y verificar<br/>sin pedir permiso en cada transición"]
    A -.->|no autoriza| C["Push, PR y merge"]
    A -.->|no autoriza| D["Acciones destructivas o publicación"]
    A -.->|no autoriza| E["Consentimiento de revisión nativa"]
    F["Hallazgos de revisión o verificación"] -.->|no autorizan| G["Ampliar el alcance"]

Los commits por unidad de trabajo en la rama de la feature forman parte de una implementación grande autorizada. El push, la creación de un PR y el merge siguen siendo decisiones del usuario. Las frases “las decisiones del usuario le ganan al impulso del agente” y “los hallazgos por sí solos nunca autorizan ampliar el alcance” sintetizan este criterio.

9. No inferir requisitos

Las especificaciones citan lo que dijiste y prohíben agregar requisitos no pedidos. Los supuestos se marcan como tales. Si un worker encuentra una decisión de producto abierta, se la devuelve al parent y no elige por ti.

Este principio tiene raíz en la anécdota del capítulo anterior: un agente que deduce necesidades de un documento que trataba de otra cosa.

10. Un mensaje solo puede nombrar un comando que funcione

Esta regla nace del trabajo en RDD y se aplica a todo el proyecto. El mantenedor descubrió que un mensaje indicaba ejecutar un comando, con pruebas en verde que confirmaban el texto, y que nadie había ejecutado ese comando. No funcionaba.

Un mensaje puede nombrar un comando solo si ejecutarlo resuelve el bloqueo.

docs/architecture/the-organic-rdd-story.md (traducción propia)

Y su generalización para cualquier prueba: verificar que algo se emitió no verifica que se pueda usar.

---

Cómo se aplican los principios a un caso nuevo

Supón que tu agente detecta durante una tarea pequeña que el módulo vecino tiene un error sin relación. ¿Qué haría ODD?

• El principio 8 indica que el hallazgo no autoriza ampliar el alcance.
• El principio 9 impide asumir que quieres el arreglo.
• El principio 5 pide que quede registrado lo observado.

El comportamiento esperado es informar el hallazgo al cerrar y seguir con lo pedido. Si tu instrucción incluyera ese arreglo, quedaría cubierto por el alcance.

---

Actividad

Elige una regla de tu propio CLAUDE.md, AGENTS.md o equivalente. Escribe a qué principio de esta lista corresponde y qué pasaría si un modelo la tomara como sugerencia. Si no corresponde a ninguno, anota qué problema resuelve.

---

Autoevaluación

1. Un agente activó un disparador de delegación, siguió inline y el trabajo salió correcto. ¿Cómo lo clasifica la fuente?

   • A. Como una optimización válida
   • B. Como un caso que requiere repetir el trabajo
   • C. Como una decisión del usuario
   • D. Como un defecto de enrutamiento

2. ¿Qué afirma la guía sobre las 400 líneas por tarea?

   • A. Son una heurística de planificación, no un límite
   • B. Son un tope que detiene el trabajo
   • C. Activan siempre una revisión RDD
   • D. Obligan a dividir la tarea

3. Una verificación encuentra un problema fuera del alcance pedido. ¿Qué autoriza ese hallazgo por sí solo?

   • A. Corregirlo si es pequeño
   • B. Abrir un PR separado de forma automática
   • C. Nada: los hallazgos no autorizan ampliar el alcance
   • D. Reabrir todas las tareas de la feature

4. ¿Cuál es el motivo declarado para limitar la delegación?

   • A. Los subagentes no pueden ejecutar pruebas
   • B. Un subagente cuesta una sesión nueva, lecturas sin caché y un traspaso
   • C. Los subagentes no tienen acceso al repositorio
   • D. La licencia del proyecto lo exige

Respuestas

1. D. El texto canónico dice que ejecutar más allá de un disparador activado es un defecto aunque el trabajo tenga éxito.
2. A. Se enumera expresamente que no es tope, criterio de aceptación ni disparador.
3. C. “Findings alone never authorize scope expansion.”
4. B. Es la frase con la que el README abre la sección de delegación.

Lista de control

• Puedo enunciar los diez principios con mis palabras.
• Distingo “sin motivo no se delega” de “con motivo es obligatorio”.
• Sé qué comportamientos de ahorro de líneas prohíbe la fuente.
• Puedo deducir la conducta esperada ante un hallazgo fuera de alcance.

Fuentes

README.md, internal/components/agentguidance/routing.go, internal/assets/skills/_shared/odd-orchestrator-sections.md, internal/assets/skills/chained-pr/SKILL.md, docs/architecture/the-organic-rdd-story.md.