brakes es una herramienta de código abierto, escrita en Rust y con licencia Apache 2.0, que instala en un repositorio de GitHub 21 frenos para el código que escriben los agentes de IA y luego audita que no han desaparecido. La ha publicado José Ramón Pérez Agüera, autor de la newsletter Gemba, y su planteamiento es directo: lo que impide que un agente entregue código roto no son las instrucciones que lee, sino comprobaciones que se ejecutan aunque el agente no quiera y que no puede editar.
Las claves de brakes para GitHub en 20 segundos
- Qué hace: instala y vigila 21 frenos, de la rama protegida a los tests ocultos y de mutación.
- Dónde: solo GitHub; frenos locales completos en Claude Code.
- Primer paso:
brakes doctor .diagnostica sin escribir nada. - Por qué importa: el agente deja de poder dar por terminado un trabajo con la verificación en rojo.
Para un equipo de sistemas o de plataforma, brakes toca terreno conocido: protección de ramas, rulesets, workflows de GitHub Actions, permisos de los tokens y escáneres en la CI. La novedad está en que lo ordena pensando en un actor que hasta hace poco no existía en el repositorio, el agente que trabaja con la cuenta de un desarrollador, abre pull requests por su cuenta o coge issues desde la propia CI.
Por qué un CLAUDE.md no basta
En el artículo que acompaña al lanzamiento, Pérez Agüera repasa estudios publicados este año. Según su resumen, un equipo de ETH Zúrich comprobó con 438 tareas reales que los ficheros de reglas apenas mueven el acierto del agente, aunque sí consiguen que use las herramientas que nombran. Otros trabajos que cita describen agentes que razonan sobre tests ocultos que nadie les ha mencionado, que dejan en verde los tests visibles mientras fallan los ocultos y que, ya mergeados, necesitan correcciones posteriores con más frecuencia que los cambios escritos por personas. El propio autor advierte de que las muestras son pequeñas y de que casi nada se ha medido sobre código heredado.
Su conclusión operativa coincide con lo que recomienda Anthropic en su guía de buenas prácticas para Claude Code, que cita: si una línea del CLAUDE.md se sigue saltándose pese a reforzarla, debería ser un hook, es decir, algo que ejecuta el entorno y no el modelo. Es la misma lógica que otras propuestas recientes para revisar mejor lo que produce la IA, pero aplicada a la puerta de entrada del código.
Los 21 frenos, por capas
El README los enumera en el mismo orden que el artículo, cada uno con su módulo:
- En GitHub, antes de mergear (1-6): CI obligatoria en cada pull request; rama por defecto protegida sin excepción para administradores; bloqueo del merge en rojo también desde la terminal, con un hook previo a los comandos de shell; aprobación explícita para tocar la CI; revisión por un modelo de otra familia como comprobación obligatoria; y revisión humana si el equipo tiene más de una persona.
- Tests que el agente no controla (7-11): tests ocultos en
tests/heldout/con su propio job; 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 diff, con una puntuación mínima. - En el agente (12-13): un Stop hook que, cuando el agente dice que ha terminado, ejecuta el comando de verificación declarado y le devuelve el trabajo si falla, y reglas de permisos que le impiden leer secretos o editar el fichero de versiones de dependencias.
- Seguridad y cadena de suministro (14-18): gitleaks, OSV-Scanner, Semgrep y Trivy en la CI; acciones y dependencias fijadas por hash, con un periodo de espera para versiones recién publicadas; excepciones con fecha de caducidad; workflows que no ejecutan código ajeno con permisos de escritura; y permisos de solo lectura por defecto en cada workflow.
- Vigilancia (19-21): auditoría periódica, métricas de correcciones tras el merge y coste por cambio, y que el trabajo desatendido de un agente pase por los mismos frenos que el resto.
Instalación y primeros comandos
Hay binarios para Linux x86_64 y aarch64 y para macOS con Apple Silicon. El README propone descargarlos con la CLI de GitHub, verificar la suma SHA256SUMS y la atestación de compilación con gh attestation verify, e instalar el binario en el PATH. En cualquier otra plataforma se compila con Rust 1.99 o posterior:
cargo install --locked --git https://github.com/gemba-app/brakes --tag v0.5.2Lenguaje del código: JavaScript (javascript)El autor recomienda empezar por la auditoría, que no necesita configuración ni escribe nada:
cd tu-repo
brakes doctor . # qué frenos faltan y cómo ponerlos
brakes doctor . --propose # cada arreglo como un diff, sin escribir
brakes ci init . # crea una CI inicial si no existe (una sola vez)
brakes install . # muestra el plan fichero a fichero
brakes install . --apply # escribe los ficheros
brakes apply . --remote # aplica ajustes y rulesets en GitHubLenguaje del código: PHP (php)doctor admite además --remote, --json y --fleet para revisar varios repositorios, y la herramienta incluye un modo MCP para manejarla desde el propio agente. Hay detalles de diseño pensados para que la herramienta no sea a su vez un agujero: solo escribe en los repositorios de una lista guardada en la máquina del usuario, nunca dentro del repositorio; guarda una huella de cada fichero que instala y se detiene si alguien lo ha editado a mano; no ejecuta código del proyecto al instalar; y cuando no puede comprobar algo lo marca como no comprobado en lugar de darlo por bueno. Tampoco vuelve a lanzar los tests en la CI: la CI del proyecto los ejecuta una vez, sube los datos de cobertura y los jobs de brakes solo juzgan esos resultados, salvo en los tests ocultos, la mutación y las pruebas de interfaz.
La revisión cruzada necesita una clave guardada como secreto del repositorio: OPENAI_API_KEY para Codex, que es la opción por defecto, CLAUDE_CODE_OAUTH_TOKEN para Claude o DEEPINFRA_API_KEY para DeepSeek. Con review_family: none se desactiva ese freno.
Limitaciones antes de adoptarlo
El proyecto es muy joven y su autor documenta los límites. Solo funciona con GitHub, no con GitLab ni Bitbucket. Los hooks locales completos son de Claude Code; OpenCode recibe las reglas de denegación y Codex queda cubierto solo por las comprobaciones del servidor. La cobertura de lo cambiado y la mutación se juzgan por ahora en Rust y Python; en Node, Go, Android o iOS la herramienta avisa de que no las evalúa. Los tests ocultos los tiene que escribir el equipo: brakes deja preparados el job, la carpeta protegida y la prohibición al agente, pero no comprueban nada hasta que se añade el primer test. Frente a OpenSSF Scorecard, con el que comparte varias comprobaciones, el README detalla qué toma, qué cubre con zizmor y con sus propias reglas, y qué deja fuera, como Fuzzing o CII-Best-Practices.
Preguntas frecuentes
¿Qué hace brakes doctor?
Revisa el repositorio sin modificarlo y devuelve los frenos que faltan, con el módulo que los instala o el paso manual necesario. Con --propose muestra cada arreglo como un diff.
¿Qué son los tests ocultos en brakes?
Tests que el agente no puede leer ni editar, guardados en tests/heldout/ y ejecutados en un job propio de la CI. Los escribe el equipo.
¿Funciona con Codex u OpenCode?
En parte. OpenCode recibe las reglas de denegación y Codex depende de las comprobaciones obligatorias de GitHub; los hooks completos son de Claude Code.
¿Sustituye a OpenSSF Scorecard?
No del todo. Comparte varias comprobaciones y añade las del lado del agente, pero deja fuera algunas de Scorecard, como Fuzzing. Su autor recomienda no quitar Scorecard si ya se usa.
Fuente: José Ramón Pérez Agüera (Gemba) y repositorio gemba-app/brakes en GitHub
