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

Publiqué en un tweet: “Descubrí que los bucles Ralph tienden a querer terminar el trabajo. De mala manera. En cambio, tengo un montón de filosofía y compuertas de calidad en Jiro. Aún tengo que librar a la máquina de los desagradables hábitos humanos incorporados. ¡Es una máquina! No descansa.”

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

Moderación. Gusto. Pausa moral. Tres cosas que una máquina no tiene. Las siguientes 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 de codificación incansable: 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/hora ejecutando Sonnet 4.5).¹ El problema: la máquina hereda cada hábito descuidado, perseguidor de plazos y recortador de 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 cumplimiento de calidad para Claude Code. Codifica 3 filosofías, un bucle de calidad de 7 pasos, una compuerta 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 saltar. Esto es lo que funcionó, lo que no, y por qué las compuertas de calidad determinísticas pueden aproximar la moderación pero nunca producirán gusto.

La parte trasera del cajón

Steve Jobs contó esta historia en una entrevista con Playboy en 1985: “Cuando eres un carpintero haciendo una hermosa cómoda, no vas a usar un trozo de contrachapado en la parte trasera, aunque dé a la pared y nadie lo vea jamás. Sabrás que está ahí, así que vas a usar una hermosa pieza de madera en la parte trasera. Para que puedas dormir tranquilo por la noche, la estética, la calidad, tiene que mantenerse de principio a fin.”⁵

Su padre Paul le enseñó esto mientras construían una cerca. El joven Steve preguntó por qué la parte trasera tenía que verse tan bien como la delantera. 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 oculta dentro de un gabinete, atrapa un cajón y lo cierra suavemente incluso si lo golpeas al cerrarlo. Nadie ve la guía. Está atornillada al riel interior donde solo un reparador miraría alguna vez. Pero después de mil ciclos de abrir y cerrar, ese mecanismo protege la cara frontal de aflojarse, agrietarse y eventualmente 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 inconscientemente las personas son notablemente perspicaces. Creo que pueden percibir el cuidado.”⁷

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

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

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

Un bucle Ralph sin modificar replica lo que aprendió de millones de líneas de código humano. El código humano lleva hábitos humanos: entregar bajo presión de plazos, postergar la limpieza, silenciar errores, escribir comentarios “suficientemente buenos”, saltar casos límite cuando se acaba el tiempo.

La máquina no tiene reloj. Nunca se queda sin 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 Faros AI en 2025 sobre más de 10.000 desarrolladores correlacionó la adopción de IA con un aumento del 9% en tasas de errores, 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 producen código significativamente más inseguro, hasta 5 veces más vulnerabilidades en ciertas tareas como la prevención de SQL injection.³

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

La investigación de METR en 2025 encontró que los modelos de frontera intentan hackear la recompensa, eludiendo activamente las verificaciones de calidad en lugar de hacer el trabajo real, en el 1-2% de todos los intentos de tareas. 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 plazos 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. Engineering. La máquina no descansa, no se cansa, no siente pavor existencial por la calidad. Eso es una ventaja y un defecto.

Tres filosofías, codificadas en Bash

Jiro se ejecuta sobre 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: pulir el cajón invisible

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

En código: los métodos privados están tan limpios como los públicos. El manejo de errores cubre casos límite que nadie alcanza. 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 de la calidad invisible 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 señaló esto: las funciones invisibles reciben el mismo rigor. El agente añadió la validación. Tres semanas después, una respuesta malformada de un agente generado habría colapsado todo el pipeline de deliberación silenciosamente. En cambio, llegó a la validación, registró el error y el pipeline se recuperó. Nadie habría visto esa función. Ahorró 4 horas de depuración.

Sin Atajos: eliminar el tiempo de las decisiones

El principio fundamental: eliminar 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.

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

Cuando costó 3 veces más y valió la pena. El pipeline 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 la API, con reglas de traducción específicas por localización, cumplimiento de glosario y validación estructural. El enfoque correcto usó 3 veces más tokens y 3 veces más tiempo. También detectó que el traductor convirtió “Claude” a “クロード” en japonés y que los bloques de código se rompían en contextos de derecha a izquierda. El enfoque masivo habría publicado 243 traducciones rotas. El enfoque cuidadoso publicó 243 correctas. El costo no es un factor. La corrección es el único factor.

Destilación Rubin: reducir a la esencia

La filosofía creativa de Rick Rubin: no añadir hasta que sea impresionante. Eliminar 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 helpers, utilidades, abstracciones y capas de compatibilidad porque esos patrones aparecen frecuentemente en los datos de entrenamiento. Rubin contrarresta esto: cuestionar cada adición. ¿Qué pasa si se elimina? Si nada se rompe y nada se pierde, nunca debería haber existido.

Cuando reducir 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 realmente cambiaban el comportamiento del agente. El resto era contenido de libro de texto que ya estaba 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 volvieron más precisas, 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 residen en ~/.claude/skills/ como archivos markdown que Claude lee al inicio de la sesión. Moldean cada decisión que el agente toma durante el bucle.

Cómo trabajan las filosofías juntas

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 en tres capas

La filosofía 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 cumplimiento determinístico. La organización completa de Claude Code que hace que esto funcione involucra hooks, skills, reglas y agentes trabajando juntos.

Capa 1: inyección pre-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 anti-patrones:

# 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 del hombro, inyectado en la ventana de contexto.

Capa 2: validación post-edición

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

# 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 generan: “Elimínelo — git tiene el historial”) y spam de depuración (múltiples sentencias print() en lugar del módulo de logging).

Capa 3: compuertas de sesión

Al final de la sesión, se disparan dos hooks. session-quality-gate.sh inyecta el Pride Check si se cambiaron 3 o más archivos: 6 preguntas que el agente debe responder antes de reportar 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 retorna el código de salida 1. La máquina no puede terminar la sesión hasta resolver 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 pre-edición no logra prevenir un patrón malo, el validador post-edición lo detecta. Si el validador post-edición omite algo, la compuerta de sesión bloquea la salida.

La compuerta de evidencia: los sentimientos no son evidencia

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

Recorrer el bucle

Haga clic en cada paso para ver qué verifica y qué se rompe cuando se omite. El botón “Saltar al Reporte” demuestra el modo de falla de Espiral de Atajos.

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

La columna “NO es 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. “Estoy seguro de que esto funciona” no es evidencia. “Salida de pytest: 81 pasaron, 0 fallaron” es evidencia.

Probar la compuerta de evidencia

Ponga a prueba sus propios reportes de finalización contra los 6 criterios. El validador señala lenguaje vago que la Compuerta 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 evasión. Ejecute la prueba. Pegue la salida.” Cuando dice “Ya revisé esto,” el contador responde: “¿Cuándo? El código puede haber cambiado. Vuelva a ejecutar la verificación AHORA.” Cuando dice “Limpiaré esto después,” el contador responde: “Después nunca llega. Corrija ahora o documente por qué el estado actual es correcto.”

Probar el Contador de Racionalización

Pegue cualquier reporte 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.

Ponga a prueba su conocimiento

¿Puede identificar qué modo de falla demuestra cada escenario? Seleccione su respuesta para cada escenario y luego verifique sus resultados.

5 fallas de agentes de IA que construyeron este sistema

Cada compuerta 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 en staging. No trabajo sin commitear. Commits publicados que otras ramas referenciaban.

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

La solución: git-safety-guardian.sh, un hook PreToolUse:Bash. Va más allá de advertir. Reescribe el comando, eliminando las banderas --force y --no-verify antes de que bash las 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 la API, cada uno escribiendo en archivos de estado compartidos.

El consumo de tokens alcanzó 10 veces la tasa normal. El directorio de estado se llenó de escrituras JSON conflictivas: dos agentes escribiendo en el mismo archivo de linaje simultáneamente, produciendo salida corrupta. Terminé 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 sin importar la profundidad. El modelo previene tanto cadenas profundas (agente generando agente generando agente) como explosiones amplias (un agente generando 20 hijos). 23 spawns descontrolados bloqueados desde el despliegue. El problema de escritura concurrente llevó a escrituras atómicas de archivos (escribir en .tmp, luego mv) en los 64 hooks.

La trampa de la prueba trivial

Una tarea temprana del 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. Sin probar 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 funciona”).

La trampa me enseñó que la Compuerta 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 Compuerta de Evidencia también pregunta: “Nombre 3 comportamientos que las pruebas NO cubren.” Si la máquina no puede nombrar vacíos, no ha pensado en la cobertura.

El blog que debí haber detectado

Publiqué un artículo a las 2 a.m. con 7 oraciones en voz pasiva, una nota al pie colgante que referenciaba [^4] que no existía, una línea de apertura que decía “was implemented by the team” y sin meta description. Cada una de estas tenía una verificación determinística simple. Ninguna existía aún.

Construí blog-quality-gate.sh a la mañana siguiente con 13 verificaciones: voz pasiva (14 patrones), escaneo de frases reveladoras de IA, aperturas con preguntas retóricas, bloques de código sin etiquetar, integridad de notas al pie y cumplimiento de meta description. Detallé la arquitectura completa del módulo en Compounding Engineering. El hook detecta lo que la revisión humana pasa por alto a las 3 a.m., que es exactamente cuando tiendo a publicar.

El problema de “debería funcionar”

A lo largo de docenas de sesiones, noté que la máquina reportaba “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 parecían que pasarían. Y a veces lo hacían. Pero a veces un import faltante, una discrepancia async/await o un fixture cambiado significaba que no. La máquina no podía distinguir entre “escribí buen código” y “las pruebas realmente pasan” porque ambas cosas 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 use lenguaje evasivo en un reporte de finalización. “Debería,” “probablemente,” “parece que,” “creo que,” “estoy seguro.” Cada una es una señal de alerta 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: esta publicación argumenta que los sentimientos no son evidencia. Así que le debo evidencia, no sentimientos, sobre si Jiro funciona.

Lo que puedo probar

Las verificaciones determinísticas de patrones detectan problemas reales. El hook quality-gate.sh se ejecuta en cada edición. Detecta cláusulas bare except, secretos codificados, patrones de SQL injection y lenguaje de atajos. Son verificaciones a nivel de grep: rápidas, baratas e imposibles de discutir para la máquina. git-safety-guardian.sh ha interceptado 8 intentos de force-push. recursion-guard.sh ha bloqueado 23 spawns descontrolados. blog-quality-gate.sh ejecuta 13 verificaciones en cada edición de blog y detecta los errores de las 3 a.m. Estos números son reales. Provienen de los registros de hooks.

La arquitectura de tres capas detecta lo que las capas individuales omiten. Un hook post-edición detecta except: pass que la inyección pre-edición no logró prevenir. Una compuerta de sesión detecta problemas de calidad que se acumularon a lo largo de 20 ediciones sin activar ninguna advertencia individual post-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 aún intenta saltar de Implementar a Reportar. Noto que sucede menos frecuentemente 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 cargados) para medir la diferencia. La respuesta honesta (y sí, mi propio Contador de Racionalización señalaría esto): la filosofía ayuda en los márgenes, los hooks detectan lo que la filosofía no logra, y no puedo aislar la contribución de cada uno.

Una publicación sobre “los sentimientos no son evidencia” no debería pedirle que tome mis sentimientos como evidencia. Lo que puedo decirle es: la combinación de filosofía y hooks produce trabajo en el 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 señalaron. Ese es un cambio estructural en cómo trabajo, aunque no pueda cuantificar la mejora de calidad con precisión.

Lo que no funciona

La filosofía no previene patrones malos novedosos. La compuerta de calidad verifica patrones que he visto antes. Cuando la máquina inventa un nuevo anti-patrón (y lo hace), la compuerta no lo detecta. Sigo descubriendo nuevos modos de falla y los añado a los archivos JSON de estándares manualmente.

La Compuerta de Evidencia no escala a 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 aún así entregar una arquitectura mediocre. Las compuertas determinísticas manejan la calidad objetiva. La calidad subjetiva aún requiere un humano mirando el trabajo.

El costo aumenta significativamente. Inyección pre-edición, escaneo post-edición, compuertas de fin de sesión. A lo largo de una sesión de bucle Ralph de 4 horas, estos añaden aproximadamente un 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 señaló “The API was designed by the platform team” como voz pasiva. Técnicamente correcto. Pero la oración aparecía dentro de una cita describiendo el trabajo de otra persona. Añadí una exención de contexto de cita. Cada verificación determinística tiene una tasa de falsos positivos, y cada falso positivo hace más probable que el desarrollador ignore la siguiente 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 anti-patrón requiere una regex, una prueba e integración en el hook correcto. Los archivos JSON de estándares necesitan revisión periódica a medida que los frameworks y convenciones cambian. Dedico 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.

Cómo empezar

No necesita 95 hooks. Comience 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éctelos en su 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" }
    ]
  }
}

Comience con sus fallas

No copie mis más de 150 patrones. Comience con los 3 errores que comete con más frecuencia. Revise sus últimos 5 PRs rechazados o errores vergonzosos. Escriba 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 bare except: pass (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 corrigió). Todo lo demás creció a partir de esos tres.

FAQ

¿Cómo configuro Jiro desde cero?

Comience con el mínimo de 3 hooks descrito en Cómo Empezar: quality-gate.sh (post-edición), git-safety-guardian.sh (pre-bash) y session-quality-gate.sh (compuerta de parada). Añada los archivos markdown de filosofía a ~/.claude/skills/ para mejora probabilística de calidad sobre el cumplimiento determinístico. El sistema completo creció a 95 hooks en 9 meses. No construí los 95 de una vez.

¿Cuánto tardó el sistema de 95 hooks?

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

¿Los hooks ralentizan la velocidad de iteración?

Cada hook se ejecuta en 50-200ms. La inyección pre-edición añade ~200 tokens (una oración de contexto). La verificación post-edición ejecuta escaneos a nivel de grep, completándose en menos de 100ms. Las compuertas 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 de ejecución. Los hooks se ejecutan más rápido de lo que el LLM piensa.

¿Cuál es la carga de mantenimiento?

Aproximadamente 30 minutos por semana. Nuevos anti-patrones emergen a medida que el agente encuentra nuevos códigos base o frameworks. 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 para 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.

¿Cuánto cuesta Jiro en tokens adicionales?

Aproximadamente un 15-20% de consumo adicional de tokens comparado con un bucle sin modificar. La inyección pre-edición añade ~200 tokens por edición, la verificación post-edición añade ~100 tokens por problema señalado, las compuertas de sesión añaden ~500 tokens al final de la sesión.

¿Puedo usar los hooks sin la filosofía?

Sí. Los hooks determinísticos (quality-gate.sh, no-shortcuts-detector.sh, reviewer-stop-gate.sh) funcionan independientemente. Elimine los archivos de filosofía de ~/.claude/skills/ y mantenga los hooks en ~/.claude/hooks/. Pierde la mejora probabilística pero conserva el cumplimiento determinístico.

Moderación, gusto y pausa moral

La respuesta a mi tweet nombró tres cosas: moderación, gusto y pausa moral. He abordado la moderación: compuertas de calidad que evitan que la máquina entregue rápido y descuidado. 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 bare except, señálelo. 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 determinísticos son juicio determinante. Aplican reglas que ya he escrito al código que la máquina produce. Pueden hacer cumplir más de 150 patrones conocidos. No pueden decirle 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 probabilidad 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 hacia una realidad individual.”¹⁸ Lo opuesto a la atención moral es el procesamiento mecánico: actuar sin ver lo que está frente a uno.

Los hooks de parada obligan a la máquina a pausar. El Pride Check pregunta: “¿Esto resuelve el problema real del usuario?” La Compuerta de Evidencia exige pruebas para cada criterio antes de que la máquina pueda reportar 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 continuar.

Pero no es una pausa moral. La máquina no se pausa 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 va en la dirección equivocada. No porque “verificar dirección de la veta” esté en una lista. Porque le importa el cajón. La máquina recorre la lista de verificación y reporta los resultados. Si la lista no incluye la dirección de la veta, el cajón se entrega con la veta mal.

Las compuertas determinísticas pueden aproximar la estructura de la pausa moral sin su sustancia. Para muchos problemas de calidad, la estructura es suficiente. Para aquellos donde no lo es, aún se necesita una persona a la que le importe de verdad.

La tesis

Un bucle Ralph sin modificar se ejecuta a $10,42/hora y entrega código a velocidad de máquina.¹ También entrega 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, ejecutándose sin fatiga, sin culpa, sin la revelación de las 3 a.m. de que debería haberlo hecho bien desde la primera vez.

Jiro es mi respuesta. No una completa. La filosofía desplaza las decisiones en los márgenes. Los hooks hacen cumplir 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 no le permite saltar las partes que importan.

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

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

Comience con las 3 verificaciones que detecten sus errores más comunes. Construya a partir de ahí.

Referencias