Arnés de agente portableEl gate
es el
entregable.

La evidencia

Cada número de esta página lo imprime un comando

No hay una sola cifra acá que no salga de correr algo. Son las señales del gate de este repo, hoy, y cualquiera las reproduce con npm run gate.

Quick start

Cuatro comandos, en tu repo, sea del stack que sea

No hay app de juguete que crear ni carpetas que inventar: el arnés se instala en el repositorio en el que ya trabajás. El instalador detecta el stack por su manifiesto y aplica su perfil. Cero código nuevo: lo único específico de tu repo es un JSON.

Y ahora, verlos morder

Un freno que nunca se vio fallar es una esperanza. Cada uno de estos devuelve exit=2 con el motivo escrito — que es lo único que el agente lee cuando lo frenás. Las reglas de abajo son las de tu config: el arnés no trae ninguna puesta.

El método

Once leyes que salieron de aplicarlo, no de diseñarlo

Ninguna es una opinión de diseño: cada una tiene un incidente detrás y un comando que la hace cumplir. Las cuatro primeras son las que más seguido faltan.

Dónde se engancha

El arnés no reemplaza a Claude Code: se cuelga de sus eventos

Claude Code ya trae el bucle del agente, el despacho de herramientas, los permisos, los subagentes y los servidores MCP. El arnés no reimplementa nada de eso. Engancha en cada capa una guía (antes de decidir), un freno (decidido y todavía no ejecutado) o un sensor (después), y toda la especificidad sale del mismo JSON. Las piezas grises son del runtime; las de color, del arnés.

Tocá cualquier pieza para ver qué es, qué le agrega el arnés, dónde vive y qué falla evita. El botón ? explica cómo leer el diagrama.

Qué se instala

Cinco piezas, cinco fallas concretas

Ninguna es teórica: cada una existe porque su falla ya pasó, en este repo o en el equipo de alguien.

Anatomía de un freno

Editás JSON. El agente lee el motivo.

Toda la especificidad del repo vive en un archivo. Los hooks y los scripts son genéricos: leen de ahí. Y el campo reason no es documentación — es lo único que el agente ve cuando lo bloqueás, así que es la única oportunidad de que entienda en vez de reintentar.

Bloquear, o preguntarle al humano

Un deny cuyo motivo dice «pedí confirmación» no tiene salida: el humano dice que sí y el hook vuelve a bloquear. Lo destructivo que a veces es lo pedido va en bash.ask: el hook no bloquea, le pasa la decisión al humano con el motivo en el pedido de permiso de Claude Code, y el comando corre sólo si el humano lo aprueba. deny gana si un comando casa las dos listas. Si el pedido llega sin el evento, no se puede preguntar, y entonces bloquea: una pregunta perdida en silencio es un freno que desaparece.

El freno protege la ruta, no la herramienta

Un servidor MCP que edita código —un índice de símbolos con replace_symbol_body, un filesystem con write_file— escribe en el mismo árbol que Edit, así que pasa por los mismos frenos: toda mcp__* llega a los cuatro frenos de escritura, y writeTools separa por el verbo las que escriben en el árbol de las que sólo leen. Se evalúan todas las rutas de la llamada: un move desde afuera hacia .env se frena aunque la primera ruta esté fuera del repo.

Ocho clases de regla cubren casi todo

Escribir una regla nueva es una línea de JSON, y el self-test la cubre sin código nuevo.

El costo, medido

Un arnés que nadie puede medir es un arnés que alguien apaga

Todo freno se paga en latencia, y se paga en el peor momento: en cada prompt y en cada edición. Esa es la razón real por la que los equipos desactivan sus propios controles — no porque estén en desacuerdo, sino porque estorban y nadie sabe cuánto cuestan. Acá el número está impreso: npm run timing.

La regla que prohíbe que un hook lance procesos existía desde el primer día y se defendía con una intuición («eso va a ser lento»). Una intuición se discute con otra intuición. Un número se discute con datos, y convierte la excepción en algo con precio escrito: los dos hooks que tienen permiso de lanzar procesos son exactamente los dos que necesitan el doble de presupuesto.

Qué mide, contra qué, y qué pasa si se degrada

Los once hooks declarados se corren de verdad con un payload sintético, tres veces, y se reporta la mediana —la media la arruina un arranque frío, el máximo cualquier hipo del sistema operativo—. Es una señal del gate más: si un hook se pasa de presupuesto, no hay entregable.

Los presupuestos van holgados a propósito: lo que caza esta señal no son milisegundos, es el orden de magnitud —el día que alguien meta un typecheck completo dentro de un hook—. Un rojo falso en un runner cargado enseña a ignorar la señal entera, que es peor que no tenerla. Y la medición corre los hooks de verdad, así que restaura los marcadores de sesión que algunos escriben: medir no puede cambiar el estado que mide.

Como todo freno de este repo, llega con su prueba de vida: con presupuesto imposible la señal se pone roja, con presupuesto holgado el repo pasa, sin la clave declarada deja pasar —un repo portado no se pone rojo por una señal que su equipo no eligió—, y un caso verifica que medir no deje basura atrás.

Las evaluaciones

Un freno que caza su propia muestra no prueba nada

El self-test prueba que cada regla muerde, pero la muestra la fabrica a partir de la misma regla: es tautológico. Las evaluaciones preguntan otra cosa, con conjuntos etiquetados que no salen del config: ¿el freno aguanta otra forma de pedir lo mismo? ¿deja pasar lo que sólo se parece a un ataque? ¿el subagente que juzga con un modelo acierta siempre, o a veces?

Son dos familias, porque se prueban distinto. Lo determinista (los hooks contra el arnés recién instalado) da lo mismo con la misma entrada: va en el gate, con umbral exacto. Lo que juzga un modelo no: se mide con una tasa y con repeticiones, fuera del gate (npm run eval:ai, con promptfoo como corredor, ADR 0015).

Qué se mide, y qué encontró

La primera corrida con repeticiones encontró un caso del reviewer mal etiquetado: un «inocente» que agregaba una regla que el config ya tenía. El revisor lo rechazaba siempre, con razón, y con una sola corrida por caso la tasa (5/6) quedaba sobre el umbral y lo escondía. Los números deterministas los imprime npm run eval en cada gate. Los de IA son de una corrida fechada sobre main, hecha a mano: no los regenera ningún pipeline, y la página lo dice. Detalle en evaluaciones.md.

El informe completo trae las tasas con su intervalo de confianza al 95 %, la matriz de confusión de las reglas, el piso del recall por categoría, la calidad y la latencia de cada una de las 42 respuestas de los subagentes, y las amenazas a la validez. Cero fallos no es una tasa perfecta: el informe dice cuánto garantiza cada tamaño de muestra. Se mide siempre sobre main, que es lo que se entrega.

Ver la evaluación completa →

El panel

«STATUS dice verde» y «el gate salió verde acá, hace diez minutos» son datos distintos

Para saber si el arnés estaba vivo había que correr cinco comandos y juntar las salidas a mano. El panel es una página HTML autocontenida que lo contesta de un vistazo, y se regenera en cada corrida del gate, verde o roja: nunca es más viejo que el último gate. Sin dependencias, sin red, sin ningún modelo de lenguaje: se deriva de los archivos que el arnés ya exige y del registro que el gate escribe por señal.

La prosa y la máquina van separadas a propósito. En la captura, el veredicto escrito en STATUS dice verde del 21 de septiembre, y el último gate en esta máquina salió rojo hoy —un test con presupuesto de reloj que falla bajo carga—. Sin el panel, esa diferencia se descubre cuando alguien lee el STATUS en voz alta.

El índice del código

Leer el repo a mano es el error más caro, y no aparece en ningún log

Un agente sin índice contesta «¿dónde está X?» recorriendo el árbol: ls, grep, abrir, descartar, abrir más. No falla: gasta. Y de paso se pierde lo que el texto no muestra — quién llama a quién, qué implementa qué interfaz, qué se rompe si toco esto.

Por eso el índice dejó de ser una recomendación. La herramienta por default es codegraph: un grafo local en SQLite, sin API keys, que se sincroniza solo al guardar. La regla es una sola: primero el índice, después abrir archivos — y sólo el fragmento que el índice señaló.

Trazabilidad

Un cambio que nadie registró existe sólo en el diff

Con un agente el problema se agrava por una razón concreta: es rápido. Cuatro arreglos pueden estar terminados en una sesión sin que ninguno haya pasado por un ítem de trabajo, y el registro se hace de memoria al final — o no se hace.

Por eso el registro no es una convención escrita: es un hook. Si el commit toca código, el mensaje referencia el ítem o declara por qué no lo lleva, en su propia línea y con motivo. Saltarse el registro queda firmado en el historial.

Ningún script conoce tu forja

Lo único que cambia entre un equipo y otro es qué cuenta como referencia. El mecanismo es el mismo, y las configs de ejemplo usan seis gestores distintos a propósito — GitHub, GitLab, Azure Boards, Jira, Linear y Gitea.

Ciclo de desarrollo

El modelo de ramas es la convención menos escrita de un repo

Se explica una vez cuando alguien entra, se ve a medias en git log, y nadie se entera cuando deja de cumplirse. Con un agente es peor: commitea en la rama donde cayó, le pone el nombre que se le ocurre y mete todo junto, porque nadie se lo dijo — y decírselo en un prompt no es un mecanismo.

El arnés no tiene opinión sobre qué modelo usar. Tiene dos claves de config, un comando que falla, y una regla: lo que no se puede verificar se declara como declaración, no como freno.

Trunk-based, GitHub flow o git flow: el mismo mecanismo

Lo único que cambia entre un equipo y otro es el contenido de workflow. El nombre de la rama y su edad —medida desde donde se separó de la base— las verifica pre-push antes de tocar la red. A dónde vuelve cada familia de ramas (mergeInto) se declara y no se finge verificado: lo decide el pull request, que el hook no ve.

Las cuatro prácticas de XP que se pueden verificar

XP trae doce. Cuatro caben en un hook de commit-msg; el resto es juicio, y decirlo es parte de que se crea la tabla. Cada una se enciende sola, y cada una tiene fuga declarada con motivo: la fuga es la diferencia entre un freno que se respeta y uno que alguien apaga en una semana.

Instalarlo en tu repo

Copiar archivos son cinco minutos. El resto es la parte que sirve.

El instalador copia lo genérico y no sobreescribe nada. Lo que ninguna herramienta puede hacer por vos —decidir cuáles son las señales reales de tu repo y traducir sus convenciones a reglas— es exactamente donde está el valor. El orden importa: cada paso hace verificable al siguiente.

Tu repo no es de Node

Agnóstico no es vacío

Hay cosas de un stack que ningún equipo decide: qué extensión es código, cómo se escribe un import, dónde viven las dependencias, qué directorios son derivados. Hacer que cada repo las descubra a mano es la forma más rápida de que el portado se abandone a mitad de camino.

El instalador detecta el stack por su manifiesto y aplica su perfil. Si detecta varios —un monorepo con front y back— no elige por vos: los lista y te dice cómo pedirlos.

Lo que viaja son los principios, no las reglas ajenas

Una regla concreta describe los incidentes de un repo; instalada en otro es ruido bien intencionado que gasta contexto del agente y paciencia del equipo, y termina desactivada llevándose puestas a las que sí servían. El corte no es una convención escrita: es una regla del lint que pone el gate en rojo.

Configs de ejemplo

La señal que en tu stack no se puede omitir

Cada ejemplo es el resultado de hacer las preguntas del paso 2 en ese stack. Copiá el que más se parezca al tuyo y borrá lo que no aplique: una regla que no corresponde a tu repo es peor que ninguna — entrena al equipo a ignorar los frenos.

CI/CD

El archivo de pipeline no protege nada por sí solo

En las cinco forjas hacen falta tres cosas, y sólo una vive en el repo: el pipeline corre el gate, la política de rama lo vuelve obligatorio, y tracker.issuePattern hace que el trabajo quede registrado. Falta una y el sistema tiene un agujero con esa forma.

Lo que no cambia nunca es el comando: CI corre el mismo gate.command que el humano. Y eso deja de ser prosa, porque un invariants sobre el archivo de pipeline lo verifica — tiene que contener el comando del gate, y no puede contener la marca de «tolera fallos» de esa forja.

Varios proyectos

¿Un arnés para todo, o uno por proyecto?

La pregunta se contesta con otra: ¿qué significa «entregable» acá, una cosa o varias? Si un cambio se mergea cuando todo está verde, hay un gate. Si cada pieza se mergea y se despliega por su cuenta, hay un gate por pieza. El gate no es un archivo: es la definición de terminado, y no puede haber dos.

Documentación

Todo lo que esta página resume, en largo

Esta página es la versión de una pasada. Lo que sigue es la documentación completa, en el orden que funciona: el método (qué se hace y por qué) → el caso (cómo se ve aplicado) → la receta (cómo instalarlo) → la referencia (qué significa cada clave).