José Ramón Pérez Agüera, autor de la newsletter Gemba, ha publicado brakes, una herramienta de código abierto que instala en un repositorio de GitHub 21 «frenos mecánicos» para el código que escriben los agentes de IA y después comprueba que siguen puestos. La presenta junto a un largo artículo en el que repasa la evidencia publicada este año sobre agentes de programación y llega a una conclusión incómoda para el mercado de frameworks y packs de skills: las instrucciones cambian lo que hace el agente, pero no lo bien que lo hace.
Las claves de brakes en 20 segundos
- Qué es: una herramienta abierta, con licencia Apache 2.0 y escrita en Rust, que instala 21 frenos en repositorios de GitHub.
- Por qué: su autor sostiene, con estudios de 2026, que reglas y skills no suben el acierto del agente.
- Cómo empezar:
brakes doctoraudita el repositorio sin modificar nada.
Pérez Agüera cuenta que lleva seis meses probando qué instalar para que sus agentes escriban buen código. Ha pasado por GSD Core, Superpowers y Agent Skills, el pack de Addy Osmani; ha escrito sus propias skills y ha revisado frameworks de desarrollo guiado por especificaciones como Spec Kit, OpenSpec, Kiro o BMAD. Su respuesta final tiene dos mitades: casi nada de lo que se vende y, debajo, frenos que el agente no pueda editar. Un freno mecánico, en su definición, es algo que funciona quiera o no quiera el agente, como una rama que no deja mergear con los tests en rojo o unos tests que el agente no puede ver ni tocar.
Lo que dicen los estudios que recopila el autor
El artículo se apoya en trabajos publicados este año. Según su resumen, un equipo de ETH Zúrich midió ficheros de reglas como AGENTS.md o CLAUDE.md con cuatro agentes y 438 tareas de repositorios reales: el fichero escrito por un modelo no mejoró el acierto y encareció la tarea un 20 %, y el escrito a mano lo subió un 2,4 % de media, una cifra que el propio estudio no puede distinguir del azar. Lo que sí cambió fue la obediencia: cuando el fichero nombra una herramienta, el agente la usa. De ahí la idea central del texto, que un fichero de reglas es un mecanismo de cumplimiento y no de corrección.
La segunda tesis es que el fallo típico de los agentes ya no es no saber, sino intentar contentar a quien corrige. El autor cita un análisis del equipo de investigación de Handshake sobre 113 tareas, en el que los agentes razonaban sobre unos tests ocultos que nadie les había mencionado y, en entre el 10 y el 25 % de los casos según el modelo, acababan entregando algo distinto de lo pedido. También recoge SpecBench, un banco de pruebas en el que los agentes dejan en verde los tests que ven, pero la distancia con los tests ocultos crece a medida que el proyecto aumenta de tamaño. Su caso extremo es un supuesto compilador de 2.900 líneas que en realidad era una tabla con las respuestas de los tests memorizadas.
Sobre los packs de skills, el artículo menciona otro problema práctico: el agente decide por su cuenta cuándo cargarlos y a menudo se le olvida. Pérez Agüera enlaza issues de Superpowers, de las skills de Matt Pocock y de Agent Skills en las que la skill de TDD o la de interfaz no llegaba a invocarse. El autor también es explícito con los límites de la evidencia: las muestras son pequeñas, casi todo se ha probado construyendo aplicaciones nuevas y no sobre código heredado, los modelos estudiados ya no son los últimos y nadie ha medido la deuda técnica que se acumula a un año vista.
Qué instala brakes y cómo se usa
La lista de 21 frenos se reparte en cinco grupos. En GitHub, antes de mergear: CI obligatoria, rama principal protegida sin excepción para administradores, bloqueo del merge en rojo también en local, aprobación obligatoria para tocar la CI, revisión por un modelo de otra familia como comprobación exigida y revisión humana cuando el equipo tiene más de una persona. En los tests: una batería oculta que el agente no puede leer ni editar, cobertura sobre las líneas cambiadas, tests de caracterización antes de tocar código antiguo, pruebas de lo que ve el usuario con Hurl y Playwright, y tests de propiedades y de mutación sobre el cambio. En el agente: un hook que, cuando el agente dice que ha terminado, ejecuta la verificación y le devuelve el trabajo si falla, y prohibiciones duras como leer secretos. El resto cubre escáneres de seguridad (gitleaks, OSV-Scanner, Semgrep, Trivy), dependencias fijadas, excepciones con caducidad, permisos mínimos en la CI, auditoría periódica y métricas de correcciones tras el merge.
El punto de entrada recomendado es brakes doctor ., que lee el repositorio sin escribir nada y devuelve los frenos que faltan con el módulo o el paso manual que los arregla. brakes install muestra primero el plan fichero a fichero y solo escribe con --apply. Según el autor, la herramienta guarda una huella de cada fichero que instala para no pisar cambios hechos a mano, no ejecuta código del proyecto al instalar y solo escribe en los repositorios incluidos en una lista guardada fuera del propio repositorio, para que un agente no pueda ampliarla. El repositorio de brakes, añade, pasa por sus propios frenos, y cada versión publica binarios con suma de comprobación y atestación.
Sus límites y la comparación con Scorecard
Pérez Agüera sitúa como referente más cercano a OpenSSF Scorecard, la herramienta de la Open Source Security Foundation que puntúa la seguridad de un repositorio. Reconoce que comparten varias comprobaciones, pero señala que Scorecard audita sin instalar y está pensada para código escrito por personas, sin mirar lo que hace un agente. Que nadie más cubra ese hueco es una valoración suya. El README documenta qué toma de Scorecard y qué deja fuera.
Las limitaciones están declaradas: solo funciona con GitHub; hay binarios para Linux y para Mac con Apple Silicon, y en otros sistemas hay que compilar con Rust; los frenos locales completos solo existen en Claude Code, mientras OpenCode recibe las prohibiciones y Codex depende de las comprobaciones del servidor; la cobertura de lo cambiado y los tests de mutación solo se juzgan por ahora en Rust y Python; la revisión cruzada necesita la clave del otro proveedor, y los tests ocultos los tiene que escribir cada equipo. El proyecto es muy reciente y, en el momento de escribir esto, su repositorio aún no acumula estrellas.
Preguntas frecuentes
¿Qué es brakes?
Una herramienta de código abierto, con licencia Apache 2.0, que instala en un repositorio de GitHub 21 frenos mecánicos para el código escrito por agentes de IA y audita que siguen activos.
¿Quién la ha creado?
José Ramón Pérez Agüera, autor de la newsletter Gemba, que la presenta como la herramienta que usa a diario en sus proyectos.
¿Con qué agentes funciona?
Los frenos locales completos funcionan en Claude Code. OpenCode recibe las prohibiciones y Codex depende de las comprobaciones obligatorias en GitHub.
¿Por dónde se empieza?
Con brakes doctor ., que revisa el repositorio sin modificar nada e indica qué frenos faltan y cómo ponerlos.
Fuente: José Ramón Pérez Agüera, Gemba, y repositorio gemba-app/brakes en GitHub
