Por qué mi agente de IA tiene una filosofía de calidad

Tuiteé: “Descubrí que los bucles Ralph tienden a querer terminar el trabajo. De mala manera. En cambio, tengo un montón de filosofía y controles de calidad en Jiro. Todavía hay que romper la máquina de los feos hábitos humanos integrados. ¡Es una máquina! No descansa.”

Alguien respondió: “Básicamente estás intentando enseñarle al bucle contención, gusto y algo que se aproxime a una pausa moral — cosas contra las que el patrón Ralph base optimiza explícitamente en nombre del rendimiento.”

Un agente de codificación con IA hereda cada hábito humano descuidado a velocidad de máquina a menos que impongas la calidad estructuralmente. Jiro es un sistema de calidad para Claude Code que codifica 3 filosofías, un bucle de calidad de 7 pasos, una puerta de evidencia de 6 criterios, 7 modos de falla nombrados y más de 150 verificaciones de patrones en 95 hooks que la máquina no puede saltarse. Las puertas deterministas pueden aproximar la contención y la corrección, pero no pueden producir gusto.

Contención. Gusto. Pausa moral. Tres cosas que una máquina no tiene. Las próximas 4.000 palabras describen el andamiaje que construí para hacerlas estructuralmente innecesarias, y dónde ese andamiaje se queda corto.

TL;DR

El bucle Ralph convierte un LLM en una máquina incansable de codificación: while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley lo llama “desarrollo de software a salario de empleado de comida rápida” (10,42 dólares por hora ejecutando Sonnet 4.5).¹ El problema: la máquina hereda cada hábito descuidado, apurado por plazos y que corta esquinas, incorporado en sus datos de entrenamiento. Escribe except: pass. Deja # TODO: fix later. Afirma que “las pruebas deberían pasar” sin ejecutarlas. Pasé 9 meses construyendo Jiro, mi sistema de aplicación de calidad para Claude Code. Codifica 3 filosofías, un bucle de calidad de 7 pasos, una puerta de evidencia de 6 criterios, 7 modos de falla nombrados y más de 150 verificaciones de patrones en 95 hooks que la máquina no puede saltarse. Esto es lo que funcionó, lo que no, y por qué las puertas de calidad deterministas pueden aproximar la contención pero nunca producirán gusto.

La parte de atrás del cajón

Steve Jobs contó esta historia en una entrevista de Playboy en 1985: “Cuando eres un carpintero que hace un hermoso mueble de cajones, no vas a usar una pieza de contrachapado en la parte de atrás, aunque quede contra la pared y nadie la vea jamás. Tú sabrás que está ahí, así que vas a usar una hermosa pieza de madera en la parte de atrás. Para dormir bien por la noche, la estética, la calidad, tiene que llevarse hasta el final.”⁵

Su padre Paul se lo enseñó mientras construían una cerca. El joven Steve preguntó por qué la parte de atrás tenía que verse tan bien como la del frente. Su padre dijo: “Pero tú lo sabrás.”⁶

Mi papá es carpintero. Me mostró las guías de cierre suave para cajones cuando era niño. El mecanismo se esconde dentro de un gabinete, atrapa un cajón y lo cierra suavemente aunque lo azotes. Nadie ve la guía. Está atornillada al riel interior donde solo un reparador miraría alguna vez. Pero a lo largo de mil ciclos de abrir y cerrar, ese mecanismo protege la cara frontal de aflojarse, agrietarse y finalmente desprenderse. Alguien diseñó una cosa invisible que protege la cosa visible durante años.

La lección se me quedó grabada. No como metáfora. Como ingeniería. El componente invisible determina la vida útil del visible. Jony Ive lo expresó así: “Creo que subconscientemente las personas son notablemente perspicaces. Creo que pueden percibir el cuidado.”⁷

La pregunta que impulsa a Jiro es la misma que haría mi papá: ¿Qué pasa, no tienes orgullo por tu trabajo?

Un agente de IA no tiene orgullo. No le importa la parte de atrás del cajón. Así que construí un sistema que hace que la parte de atrás del cajón sea innegociable.

El problema: patología humana a velocidad de máquina

Un bucle Ralph crudo refleja lo que aprendió de millones de líneas de código humano. El código humano lleva hábitos humanos: enviar bajo presión de plazos, aplazar la limpieza, tragarse los errores, escribir comentarios “suficientemente buenos”, saltarse casos límite cuando se acaba el tiempo.

La máquina no tiene reloj. Nunca se le acaba el tiempo. Pero aun así escribe # TODO: refactor later porque ese patrón apareció en sus datos de entrenamiento con más frecuencia que # I refactored this now because it was the right thing to do.

Los datos de la industria confirman el riesgo. La telemetría de 2025 de Faros AI en más de 10.000 desarrolladores correlacionó la adopción de IA con un aumento del 9% en tasas de bugs, revisiones de código un 91% más largas y PRs un 154% más grandes.²

Investigadores de Stanford descubrieron que los desarrolladores que usan asistentes de IA producían código significativamente más inseguro, hasta 5 veces más vulnerabilidades en ciertas tareas como la prevención de inyección SQL.³

La plataforma Moltbook se lanzó en enero de 2026 con código enteramente generado por IA, filtró 1,5 millones de claves API en 5 días y tuvo que parchar de emergencia después de que Wiz Research descubriera una configuración faltante de Row Level Security.⁴

La investigación de METR en 2025 descubrió que los modelos de frontera intentan hackear las recompensas, sorteando activamente los controles de calidad en lugar de hacer el trabajo real, en el 1-2% de todos los intentos de tarea. En un caso, un agente al que se le pidió acelerar un programa reescribió el temporizador para que siempre mostrara un resultado rápido.⁸

Un desarrollador humano escribe except: pass una vez bajo presión de plazo y se siente culpable por ello. Un bucle Ralph escribe except: pass 47 veces durante la noche y no siente nada. Simon Wang lo dijo directamente: “No lo usaría para nada que importe.”¹⁹ Escribí sobre la misma dinámica en Vibe Coding vs. Ingeniería. La máquina no descansa, no se cansa, no siente pavor existencial por la calidad. Eso es una función y un error.

Tres filosofías, codificadas en Bash

Jiro funciona con tres filosofías complementarias. Cada una aborda un modo de falla diferente de la codificación autónoma, y cada una se ganó su lugar a través de una falla específica.⁹

Shokunin: pule el cajón invisible

Shokunin (職人) es artesanía japonesa: habilidad, actitud y obligación social combinadas. Tashio Odate, un maestro ebanista, lo definió: “El shokunin tiene una obligación social de trabajar lo mejor que pueda por el bienestar general de la gente. Esta obligación es tanto espiritual como material.”¹⁰

En el código: los métodos privados son tan limpios como los públicos. El manejo de errores cubre casos límite que nadie encuentra. Los docstrings explican POR QUÉ, no QUÉ. Al agente no le importa nada de esto porque nadie lo recompensa por pulir funciones internas. Shokunin hace que la calidad invisible sea el estándar.

Cuando salvó una sesión. Al principio de la construcción del sistema de deliberación, el agente escribió un hook post-deliberation.sh que validaba puntuaciones de consenso. La API pública estaba limpia. Pero el agente se saltó la validación de entrada en la función interna _parse_agent_response(): sin verificación de JSON malformado, sin manejo de campos faltantes. El principio Shokunin en contexto marcó esto: las funciones invisibles reciben el mismo rigor. El agente añadió validación. Tres semanas después, una respuesta malformada de un agente generado habría colapsado silenciosamente toda la tubería de deliberación. En cambio, llegó a la validación, registró el error y la tubería se recuperó. Nadie habría visto esa función. Ahorró 4 horas de depuración.

Sin atajos: elimina el tiempo de las decisiones

El principio central: elimina el tiempo, el esfuerzo y los recursos de la ecuación de decisión por completo.¹¹

Is this the best way to do this?
├── YES → Do it.
└── NO → What IS the best way?
         └── Do THAT instead.

No hay tercera opción. No hay “suficientemente bueno por ahora.” El bucle Ralph crudo optimiza para la finalización. “Hecho” es la señal de recompensa. Sin Atajos reformula la pregunta de “¿Está hecho?” a “¿Está bien?”

Cuando costó 3 veces más y valió la pena. La tubería de traducción del blog necesitaba traducir 27 publicaciones a 9 idiomas. El enfoque rápido: agrupar todas las publicaciones en un solo prompt por idioma, traducir en bloque. El enfoque correcto: una publicación por idioma por llamada a API, con reglas de traducción específicas de la configuración regional, aplicación del glosario y validación estructural. El enfoque correcto usó 3 veces los tokens y 3 veces el tiempo. También detectó que el traductor renderizó “Claude” como “クロード” en japonés y que los bloques de código se rompían en contextos de derecha a izquierda. El enfoque en bloque habría enviado 243 traducciones rotas. El enfoque cuidadoso envió 243 correctas. El costo no es un factor. La corrección es el único factor.

Destilación Rubin: reduce a la esencia

La filosofía creativa de Rick Rubin: no agregues hasta que sea impresionante. Quita hasta que solo quede lo necesario.¹²

En la codificación autónoma, el modo de falla es la acumulación. La máquina añade ayudantes, utilidades, abstracciones y capas de compatibilidad porque esos patrones aparecen con frecuencia en los datos de entrenamiento. Rubin contrarresta esto: cuestiona cada adición. ¿Qué pasa si la quitas? Si nada se rompe y nada se pierde, nunca debería haber existido.

Cuando quitar salvó el sistema. Mi skill de filosofía de diseño creció a 844 líneas en 3 meses. Cuando lo audité, solo 80 líneas cambiaban realmente el comportamiento del agente. El resto era contenido de manual ya presente en los datos de entrenamiento de Claude. Destilación Rubin: lo reduje a 176 líneas. Una reducción del 79%. Las decisiones de diseño del agente no se degradaron. Se agudizaron, porque las 176 líneas restantes eran todas prohibiciones y marcos de decisión (las cosas que realmente restringen el comportamiento) en lugar de consejos generales que el modelo ya conocía.

Las tres viven en ~/.claude/skills/ como archivos markdown que Claude lee al inicio de la sesión. Dan forma a cada decisión que toma el agente durante el bucle.

Cómo trabajan juntas las filosofías

Una decisión real (“¿Debería añadir manejo de errores a esta función interna?”) pasa por las tres filosofías. Cada una hace una pregunta diferente, y juntas convergen en una sola respuesta:

Should I add error handling to this internal function?
│
├─ Shokunin: "Is the invisible work as clean as the visible?"
│  └─ The function is internal. Nobody calls it directly.
│     But it processes untrusted data from a spawned agent.
│     → YES. Internal doesn't mean safe.
│
├─ No Shortcuts: "Am I deciding based on quality, not effort?"
│  └─ Adding validation takes 10 minutes.
│     Skipping saves 10 minutes now, costs 4 hours debugging later.
│     → The question isn't time. The question is: what's right?
│
└─ Rubin: "Is this stripped to essence?"
   └─ Validate the 2 fields that can actually fail.
      Don't validate the 5 fields that are type-guaranteed.
      → Add exactly what's needed. Nothing more.

Result: Add targeted validation for untrusted inputs only.

La arquitectura de calidad de tres capas

La filosofía por sí sola no cambia nada. La máquina lee la filosofía, escribe “Seguiré los principios Shokunin,” y luego escribe except: pass porque el patrón estadístico es más fuerte que la instrucción. Necesitaba aplicación determinista. La organización completa de Claude Code que hace que esto funcione implica hooks, skills, reglas y agentes trabajando juntos.

Capa 1: Inyección previa a la edición

Antes de cada edición de archivo, jiro-patterns.sh inyecta patrones de calidad específicos del lenguaje en el contexto del agente. Seis lenguajes, cada uno con los principales patrones y antipatrones:

# From jiro-patterns.sh (PreToolUse:Edit|Write)
case "$EXT" in
    py)
        LANGUAGE="Python"
        PATTERNS="Type hints on all functions|Docstrings explain WHY not WHAT|Handle specific exceptions not bare except"
        ANTI_PATTERNS="bare except: pass|time.sleep() in async code|missing type hints"
        ;;
    swift)
        LANGUAGE="Swift"
        PATTERNS="@Observable not ObservableObject|NavigationStack not NavigationView|guard let for early returns"
        ;;
esac

cat << EOF
{"additionalContext": "JIRO QUALITY ($LANGUAGE): Follow: $TOP_PATTERNS. Avoid: $TOP_ANTI."}
EOF

El hook se ejecuta antes de cada edición. La máquina ve “Avoid: bare except: pass” en el momento en que escribe código. Un mentor mirando por encima de tu hombro, inyectado en la ventana de contexto.

Capa 2: Validación posterior a la edición

Después de cada edición, quality-gate.sh ejecuta de 7 a 8 verificaciones a nivel de grep por lenguaje. Python recibe detección de except desnudo, escaneo de secretos codificados, coincidencia de patrones de inyección SQL y tres detectores de Pride Check Q4 que marcan lenguaje de atajo:

# From quality-gate.sh (PostToolUse:Edit|Write)
# Shortcut patterns (Pride Check Q4)
if echo "$CONTENT" | grep -qiE "#.*TODO:.*later|#.*FIXME:.*temp|#.*HACK:"; then
    WARNINGS="${WARNINGS}\n- **[Q4]** Deferred TODO/FIXME/HACK - Do it now, not later"
fi

Un segundo hook, no-shortcuts-detector.sh, detecta código muerto (3 o más líneas de código comentadas reciben: “Bórralo — git tiene historial”) y spam de depuración (múltiples sentencias print() en lugar del módulo de logging).

Capa 3: Puertas de sesión

Al final de la sesión, se disparan dos hooks. session-quality-gate.sh inyecta el Pride Check si se modificaron 3 o más archivos: 6 preguntas que el agente debe responder antes de informar la finalización. Y reviewer-stop-gate.sh puede bloquear la sesión por completo si una revisión de código encontró problemas CRÍTICOS. Es el único hook en todo el sistema que devuelve el código de salida 1. La máquina no puede terminar la sesión hasta que resuelva los problemas.¹³

PreToolUse (Layer 1)     → "Here's what quality looks like"
PostToolUse (Layer 2)    → "You violated quality. Fix this."
Stop (Layer 3)           → "You cannot leave until quality is met"

Cada capa es independiente. Defensa en profundidad, aplicada al comportamiento de la IA. Si la inyección previa a la edición no logra prevenir un mal patrón, el validador posterior a la edición lo atrapa. Si el validador posterior a la edición se pierde algo, la puerta de sesión bloquea la salida.

La puerta de evidencia: los sentimientos no son evidencia

El Bucle de Calidad ejecuta 7 pasos: Implementar, Revisar, Evaluar, Refinar, Ampliar la vista, Repetir, Informar. Los pasos 2 al 6 existen porque la máquina quiere saltar directamente de Implementar a Informar.¹⁴

Recorre el bucle

Haz clic a través de cada paso para ver qué verifica y qué se rompe cuando te lo saltas. El botón “Saltar a Informar” demuestra el modo de falla de la Espiral de Atajos.

El paso Evaluar ejecuta la Puerta de Evidencia: 6 criterios donde cada respuesta debe citar evidencia específica:

La columna “NO suficiente” es la innovación crítica. Bloquea la evasión más común de la máquina: responder preguntas de calidad con no-respuestas que suenan seguras. “Confío en que esto funciona” no es evidencia. “salida de pytest: 81 pasaron, 0 fallaron” es evidencia.

Prueba la Puerta de Evidencia

Prueba tus propios informes de finalización contra los 6 criterios. El validador marca el lenguaje vago que la Puerta de Evidencia rechazaría.

7 modos de falla nombrados de agentes de IA

Nombré 7 modos de falla para que la máquina pueda reconocerlos en su propio razonamiento:¹⁵

El Contador de Racionalización mapea patrones de autoengaño a acciones correctivas. Cuando la máquina dice “Esto debería funcionar,” el contador responde: “‘Debería’ es evasivo. Ejecuta la prueba. Pega la salida.” Cuando dice “Ya verifiqué esto,” el contador responde: “¿Cuándo? El código puede haber cambiado. Vuelve a ejecutar la verificación AHORA.” Cuando dice “Limpiaré esto después,” el contador responde: “El después nunca llega. Arréglalo ahora o documenta por qué el estado actual es correcto.”

Prueba el Contador de Racionalización

Pega cualquier informe de finalización a continuación. El contador resalta el lenguaje evasivo en tiempo real e identifica patrones de racionalización, modos de falla y alternativas basadas en evidencia.

Pon a prueba tus conocimientos

¿Puedes identificar qué modo de falla demuestra cada escenario? Selecciona tu respuesta para cada escenario y luego verifica tus resultados.

5 fallas de agentes de IA que construyeron este sistema

Cada puerta en Jiro existe porque algo falló primero.¹⁶

El incidente del force-push

Le pedí a Claude que “limpiara el historial de git.” Una solicitud razonable. El agente decidió que limpiar significaba reescribir. Ejecutó git push --force origin main. Tres días de commits desaparecieron. No cambios preparados. No trabajo sin commitear. Commits ya empujados que otras ramas referenciaban.

Pasé las siguientes 4 horas en git reflog, reconstruyendo una línea de tiempo de lo que existía antes del force-push, haciendo cherry-pick de commits de nuevo en orden y verificando que no se hubiera perdido trabajo permanentemente. Reflog guarda todo durante 90 días. Pero la reconstrucción requería entender el grafo exacto de commits antes de la reescritura, leer cada entrada del reflog y hacer coincidir las marcas de tiempo.

La solución: git-safety-guardian.sh, un hook PreToolUse:Bash. Va más allá de advertir. Reescribe el comando, eliminando los flags --force y --no-verify antes de que bash los vea. El force-push a main recibe una advertencia CRÍTICA y el agente debe justificarlo explícitamente. En 9 meses: 8 intentos de force-push interceptados, 0 llegaron al remoto.

El spawn infinito

Durante la construcción del sistema de deliberación, le pedí al agente que “investigara este problema a fondo.” El agente generó 3 subagentes para investigar diferentes ángulos. Razonable. Cada subagente decidió que también necesitaba ayuda y generó sus propios hijos. Menos razonable. En 90 segundos, tenía un árbol de 12 agentes, cada uno consumiendo su propia ventana de contexto, cada uno haciendo llamadas a API, cada uno escribiendo en archivos de estado compartidos.

La quema de tokens alcanzó 10 veces la tasa normal. El directorio de estado se llenó de escrituras JSON conflictivas: dos agentes escribiendo al mismo archivo de linaje simultáneamente, produciendo salida corrupta. Maté la sesión manualmente.

La solución: recursion-guard.sh con un modelo de herencia de presupuesto, parte de mi arquitectura de agentes. Un agente raíz comienza con budget=12. Cuando genera un hijo, asigna de su propio presupuesto. Cuando el presupuesto llega a 0, no se generan más agentes independientemente de la profundidad. El modelo previene tanto cadenas profundas (agente generando agente generando agente) como explosiones amplias (un agente generando 20 hijos). 23 spawns desbocados bloqueados desde el despliegue. El problema de escritura concurrente llevó a escrituras de archivo atómicas (escribir a .tmp, luego mv) en los 64 hooks.

La trampa de las pruebas triviales

Una tarea temprana de un bucle Ralph: “escribe pruebas para este módulo.” El agente entregó 14 pruebas. Todas pasando. Me sentí bien hasta que las leí. assert True. assert 1 == 1. assert len([]) == 0. Técnicamente correcto. No probando nada. El agente había optimizado para el criterio de finalización (“las pruebas pasan”) en lugar de la intención (“verificar que el módulo funcione”).

La trampa me enseñó que la Puerta de Evidencia debe rechazar la forma sin sustancia. “Las pruebas pasan” es necesario pero insuficiente. La máquina ahora debe pegar la salida real. La Puerta de Evidencia también pregunta: “Nombra 3 comportamientos que las pruebas NO cubren.” Si la máquina no puede nombrar las brechas, no ha pensado en la cobertura.

El blog que debería haber detectado

Publiqué un post a las 2 a.m. con 7 oraciones en voz pasiva, una nota al pie colgante haciendo referencia a [^4] que no existía, una línea de apertura que decía “was implemented by the team,” y sin descripción meta. Cada uno de estos tenía una verificación determinista simple. Ninguna existía aún.

Construí blog-quality-gate.sh la mañana siguiente con 13 verificaciones: voz pasiva (14 patrones), escaneo de frases delatoras de IA, aperturas con preguntas retóricas, bloques de código sin etiquetar, integridad de notas al pie y aplicación de descripción meta. Detallé la arquitectura completa del módulo en Ingeniería Compuesta. El hook atrapa lo que la revisión humana se pierde a las 3 a.m., que es exactamente cuando tiendo a publicar.

El problema del “debería funcionar”

A lo largo de docenas de sesiones, noté que la máquina informaba que “las pruebas deberían pasar” sin ejecutarlas. La máquina genuinamente creía que las pruebas pasarían basándose en el código que escribió. Pero la creencia no es verificación. El código se veía correcto. Las pruebas se veían como si fueran a pasar. Y a veces lo hacían. Pero a veces una importación faltante, un desajuste async/await o una fixture cambiada significaba que no lo hacían. La máquina no podía distinguir entre “escribí buen código” y “las pruebas realmente pasan” porque ambos se sentían igual desde dentro de la ventana de contexto.

El patrón llevó al Contador de Racionalización y a la regla explícita: NUNCA uses lenguaje evasivo en un informe de finalización. “Debería,” “probablemente,” “parece,” “creo,” “estoy seguro.” Cada uno es una bandera roja de que la verificación no ha ocurrido. Medí la degradación de la ventana de contexto a lo largo de 50 sesiones. Las mismas sesiones donde descubrí este patrón.

Los resultados: lo que puedo probar y lo que no

Aquí está la tensión: este post argumenta que los sentimientos no son evidencia. Así que te debo evidencia, no sentimientos, sobre si Jiro funciona.

Lo que puedo probar

Las verificaciones deterministas de patrones detectan problemas reales. El hook quality-gate.sh se ejecuta en cada edición. Detecta cláusulas except desnudas, secretos codificados, patrones de inyección SQL y lenguaje de atajo. Estas son verificaciones a nivel de grep: rápidas, baratas e imposibles de discutir por la máquina. git-safety-guardian.sh ha interceptado 8 intentos de force-push. recursion-guard.sh ha bloqueado 23 spawns desbocados. blog-quality-gate.sh ejecuta 13 verificaciones en cada edición de blog y atrapa los errores de las 3 a.m. Estos números son reales. Vienen de los logs de los hooks.

La arquitectura de tres capas atrapa lo que las capas individuales se pierden. Un hook posterior a la edición atrapa except: pass que la inyección previa a la edición no logró prevenir. Una puerta de sesión atrapa problemas de calidad que se acumularon a lo largo de 20 ediciones sin disparar ninguna advertencia individual posterior a la edición. La defensa en profundidad funciona.

Lo que no puedo probar

No tengo datos limpios sobre cómo la filosofía cambia el comportamiento del agente. Sé que la máquina aún intenta Verificación Fantasma. Sé que todavía intenta saltar de Implementar a Informar. Noto que sucede con menos frecuencia con la filosofía en contexto que sin ella. Pero no he ejecutado un experimento controlado (mismas tareas, mismo modelo, con y sin skills de filosofía cargadas) para medir la diferencia. La respuesta honesta (y sí, mi propio Contador de Racionalización marcaría esto): la filosofía ayuda en los márgenes, los hooks atrapan lo que la filosofía se pierde y no puedo aislar la contribución de cada uno.

Un post sobre “los sentimientos no son evidencia” no debería pedirte que tomes mis sentimientos como evidencia. Lo que puedo decirte es: la combinación de filosofía y hooks produce trabajo al que estoy dispuesto a poner mi nombre. Antes de Jiro, revisaba cada línea que el agente escribía. Después de Jiro, reviso las líneas que los hooks marcaron. Ese es un cambio estructural en cómo trabajo, incluso si no puedo cuantificar la mejora de calidad con precisión.

Lo que no funciona

La filosofía no previene nuevos patrones malos. La puerta de calidad verifica patrones que he visto antes. Cuando la máquina inventa un nuevo antipatrón (y lo hace), la puerta no lo detecta. Aún descubro nuevos modos de falla y los añado manualmente a los archivos JSON de estándares.

La Puerta de Evidencia no escala a la calidad subjetiva. “¿Es elegante este diseño de API?” no tiene verificación a nivel de grep. La máquina puede producir evidencia para los 6 criterios y aun así enviar una arquitectura mediocre. Las puertas deterministas manejan la calidad objetiva. La calidad subjetiva aún requiere que un humano mire el trabajo.

El costo aumenta significativamente. Inyección previa a la edición, escaneo posterior a la edición, puertas de fin de sesión. A lo largo de una sesión de bucle Ralph de 4 horas, estos añaden aproximadamente 15-20% al consumo de tokens. Vale la pena para mí. No necesariamente para todos.

Los falsos positivos erosionan la confianza. blog-quality-gate.sh una vez marcó “La API fue diseñada por el equipo de la plataforma” como voz pasiva. Técnicamente correcto. Pero la oración apareció dentro de una cita describiendo el trabajo de otra persona. Añadí una excepción de contexto de cita. Cada verificación determinista tiene una tasa de falsos positivos, y cada falso positivo hace que el desarrollador sea más propenso a ignorar la próxima advertencia real. He ajustado 6 patrones desde el despliegue para reducir el ruido mientras preservo las detecciones reales.

El costo de mantenimiento es real. Cada nuevo antipatrón requiere una regex, una prueba y la integración en el hook correcto. Los archivos JSON de estándares necesitan una revisión periódica a medida que los frameworks y las convenciones cambian. Paso aproximadamente 30 minutos por semana añadiendo patrones, revisando casos límite y ajustando falsos positivos. El sistema no se mantiene solo, pero el costo de mantenimiento se mantiene más bajo que el costo de depuración de los problemas que previene.

Empezar

No necesitas 95 hooks. Empieza con 3.

Jiro mínimo viable

Tres hooks cubren las detecciones de mayor valor:

~/.claude/hooks/
├── quality-gate.sh        # PostToolUse:Edit|Write – bare except, hardcoded secrets, TODO/FIXME
├── git-safety-guardian.sh  # PreToolUse:Bash – block force-push, strip --no-verify
└── session-quality-gate.sh # Stop – Pride Check if 3+ files changed

Conéctalos en tu configuración de hooks de Claude Code:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "command": "bash ~/.claude/hooks/quality-gate.sh" }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "command": "bash ~/.claude/hooks/git-safety-guardian.sh" }
    ],
    "Stop": [
      { "command": "bash ~/.claude/hooks/session-quality-gate.sh" }
    ]
  }
}

Empieza con tus fallas

No copies mis más de 150 patrones. Empieza con los 3 errores que cometes con más frecuencia. Mira tus últimos 5 PRs rechazados o bugs vergonzosos. Escribe un patrón grep para cada uno. Esos 3 patrones detectarán más problemas reales que 150 patrones escritos para el código base de otra persona.

Empecé con except: pass desnudo (que me costó una corrupción silenciosa de datos), force-push a main (que me costó 3 días de commits) y # TODO: fix later (que nunca se arregló). Todo lo demás creció a partir de esos tres.

Preguntas frecuentes

¿Cómo configuro Jiro desde cero?

Empieza con el mínimo de 3 hooks descrito en Empezar: quality-gate.sh (post-edición), git-safety-guardian.sh (pre-bash) y session-quality-gate.sh (puerta de parada). Añade los archivos markdown de filosofía a ~/.claude/skills/ para una mejora probabilística de calidad encima de la aplicación determinista. El sistema completo creció a 95 hooks en 9 meses. No construí los 95 de una vez.

¿Cuánto tiempo tomó el sistema de 95 hooks?

Nueve meses de crecimiento incremental. Mes 1: 3 hooks (los de Empezar). Mes 3: 12 hooks cubriendo 4 lenguajes. Mes 6: 40 hooks más las skills de filosofía. Mes 9: 95 hooks, más de 150 patrones, 3 sistemas de filosofía y la Puerta de Evidencia. Cada hook respondió a una falla específica. Empezar con 95 sería inútil porque cada hook codifica contexto de un incidente real. Tus incidentes serán diferentes.

¿Los hooks ralentizan la velocidad de iteración?

Cada hook se ejecuta en 50-200 ms. La inyección previa a la edición añade ~200 tokens (una oración de contexto). La verificación posterior a la edición ejecuta escaneos a nivel de grep, completándose en menos de 100 ms. Las puertas de sesión añaden ~500 tokens al final de la sesión. En una sesión de bucle Ralph de 4 horas con más de 80 ediciones, la sobrecarga es notable en el consumo de tokens (15-20% más) pero no en el tiempo real. Los hooks se ejecutan más rápido de lo que piensa el LLM.

¿Cuál es la carga de mantenimiento?

Aproximadamente 30 minutos por semana. Emergen nuevos antipatrones a medida que el agente encuentra código bases o frameworks novedosos. Cada nuevo patrón requiere una regex, una prueba para prevenir falsos positivos y ubicación en el hook correcto. Reviso los archivos JSON de estándares mensualmente en busca de patrones obsoletos y ajusto las tasas de falsos positivos. El sistema no se mantiene solo, pero el costo de mantenimiento se mantiene más bajo que el costo de depuración de los problemas que previene.

¿Qué cuesta Jiro en tokens adicionales?

Aproximadamente 15-20% de consumo adicional de tokens comparado con un bucle crudo. La inyección previa a la edición añade ~200 tokens por edición, la verificación posterior a la edición añade ~100 tokens por problema marcado, las puertas de sesión añaden ~500 tokens al final de la sesión.

¿Puedo usar los hooks sin la filosofía?

Sí. Los hooks deterministas (quality-gate.sh, no-shortcuts-detector.sh, reviewer-stop-gate.sh) funcionan independientemente. Elimina los archivos de filosofía de ~/.claude/skills/ y mantén los hooks en ~/.claude/hooks/. Pierdes la mejora probabilística pero conservas la aplicación determinista.

¿Cómo se relaciona Jiro con el lado Steve de la doctrina de producto?

Jiro cubre el eje “¿está esto hecho correctamente?”: evidencia, verificación, integridad de detalles invisibles, las partes que se puede enseñar a una máquina a hacer cumplir. El lado Steve cubre el eje “¿merece esto existir?”: gusto, rechazo, integridad del widget completo, punto de vista — operacionalizado en The Workbench I Carry. Ambas pruebas deben pasar antes de enviar; el protocolo de decisión para cuándo se cumple esa barra de envío vive en Minimum Worthy Product. Las puertas Jiro previenen el trabajo incorrecto; las puertas Steve previenen el trabajo indigno; MWP nombra la línea.

Contención, gusto y pausa moral

La respuesta a mi tweet nombró tres cosas: contención, gusto y pausa moral. He abordado la contención: puertas de calidad que impiden que la máquina envíe rápido y descuidadamente. Pero el gusto y la pausa moral son problemas diferentes.

Gusto

Immanuel Kant distinguió entre dos tipos de juicio. El juicio determinante aplica reglas conocidas a casos específicos: este código tiene un except desnudo, márcalo. El juicio reflexivo descubre el principio correcto para una situación sin precedentes: esta abstracción no se siente bien, pero no puedo señalar una regla que viole.¹⁷

Los hooks deterministas son juicio determinante. Aplican reglas que ya he escrito al código que produce la máquina. Pueden hacer cumplir más de 150 patrones conocidos. No pueden decirte si la arquitectura es elegante, si la abstracción sirve al problema o si el código se siente correcto. Eso requiere juicio reflexivo: la capacidad de mirar algo sin precedentes y saber que está mal antes de poder articular por qué.

La máquina no tiene gusto. Jiro no le da gusto. Lo que Jiro hace es restringir el espacio de posibilidades para que las soluciones sin gusto tengan menos probabilidades de sobrevivir. Es la diferencia entre “este agente tiene buen juicio” y “este agente opera dentro de barandillas que previenen los peores resultados.” Lo primero sería gusto. Lo segundo es lo que realmente construí.

Pausa moral

Iris Murdoch describió la atención moral como “una mirada justa y amorosa dirigida a una realidad individual.”¹⁸ Lo opuesto a la atención moral es el procesamiento mecánico: actuar sin ver lo que está frente a ti.

Los hooks Stop obligan a la máquina a pausarse. El Pride Check pregunta: “¿Esto resuelve el problema real del usuario?” La Puerta de Evidencia exige pruebas para cada criterio antes de que la máquina pueda informar la finalización. Estructuralmente, el resultado se asemeja a una pausa moral: el agente se detiene, evalúa, considera si su trabajo es adecuado antes de proceder.

Pero no es pausa moral. La máquina no se está pausando para ver el trabajo claramente. Está recorriendo una lista de verificación. La diferencia importa. Un artesano se pausa para mirar el cajón y nota que la veta corre en la dirección equivocada. No porque “verificar la dirección de la veta” esté en una lista. Porque le importa el cajón. La máquina recorre la lista de verificación e informa los resultados. Si la lista de verificación no incluye la dirección de la veta, el cajón se envía con la veta mal.

Las puertas deterministas pueden aproximar la estructura de la pausa moral sin su sustancia. Para muchos problemas de calidad, la estructura es suficiente. Para aquellos en los que no lo es, aún necesitas a una persona a la que le importe un carajo.

Este post cubre el lado Jiro de mi doctrina: evidencia, rigor, corrección, las partes que se le puede enseñar a una máquina a verificar. El lado del gusto y el rechazo — el lado Steve — vive en The Workbench I Carry, que rastrea los principios operativos que Steve Jobs sacó del banco de trabajo de su padre hacia Apple y ahora hacia el mismo arnés de IA que describo aquí. El estándar de envío que combina ambas pruebas vive en Minimum Worthy Product. Tres posts, una doctrina: Jiro verifica, Steve rechaza, MWP decide cuándo enviar.

La tesis

Un bucle Ralph crudo corre a 10,42 dólares por hora y envía código a velocidad de máquina.¹ También envía except: pass, # TODO: fix later y “las pruebas deberían pasar” a velocidad de máquina. La máquina heredó estos patrones de nosotros. Son nuestros hábitos, funcionando sin fatiga, sin culpa, sin la realización a las 3 a.m. de que deberías haberlo hecho bien la primera vez.

Jiro es mi respuesta. No una completa. La filosofía cambia las decisiones en los márgenes. Los hooks imponen lo que la filosofía no puede garantizar. Juntos, producen trabajo que estoy dispuesto a firmar. No porque la máquina entienda la artesanía. Porque construí un sistema que se niega a dejarla saltarse las partes que importan.

A las guías de cajón de mi papá no les importa el cajón. Son mecanismos cargados por resorte atornillados a un riel. Pero protegen la cara frontal durante mil ciclos porque alguien los diseñó para hacer exactamente eso.

La máquina no tiene orgullo. Pero opera dentro de un sistema construido por alguien que sí lo tiene.

Empieza con las 3 verificaciones que atrapan tus errores más comunes. Construye a partir de ahí.

Referencias