becwright + Claude Code: guardrails deterministas

Claude Code produce código rápido, y todo equipo que lo usa acaba viendo el mismo patrón de fallo: el agente commitea un debugger suelto, un volcado de console.log o una API key hardcodeada — aunque CLAUDE.md diga, con todas las letras, que no lo haga. No es un bug de Claude; es la naturaleza de las instrucciones. becwright es un motor determinista de guardrails pre-commit: en vez de pedirle al agente que se porte bien, verifica el código real en el momento del commit y lo frena (código de salida 1) cuando una regla blocking falla. Mantén CLAUDE.md como el lugar donde describes cómo quieres el código; becwright es la capa de enforcement que vuelve innegociable lo innegociable.

¿Por qué CLAUDE.md solo no puede imponer reglas?

CLAUDE.md es contexto, no un contrato. El agente lo lee al inicio de la sesión y normalmente lo sigue — pero ese “normalmente” carga con mucho peso:

• Las reglas compiten por atención. Tu línea de “nunca commitees secretos” comparte la ventana de contexto con la tarea, el código y toda la conversación. En una sesión larga, sobre todo tras una compactación de contexto, puede sencillamente perder.
• El cumplimiento es probabilístico. La misma instrucción que ayer se respetó hoy puede saltarse, porque los modelos de lenguaje no ejecutan reglas — las ponderan contra todo lo demás en contexto.
• Los hooks de Claude Code protegen una sesión. El sistema de hooks propio de Claude Code puede ejecutar comandos alrededor del uso de herramientas, y es útil de verdad — pero restringe a ese agente, en esa sesión. No hace nada frente a un segundo agente, el editor de un compañero, o tú a la 1 a.m.

becwright toma el enfoque opuesto: un hook de git pre-commit nativo corre tus reglas sobre los archivos staged en cada commit, lo haga quien — o lo que — lo haga. La regla pasa o no pasa, sin importar qué modelo produjo el cambio. Si quieres impedir que Claude Code commitee secretos, este es el mecanismo que realmente lo impide en lugar de solicitarlo. Cómo se relaciona esto con el framework clásico del espacio está en becwright vs pre-commit.

Instalación

Los paquetes de npm traen un binario autónomo, así que no necesitas Python:

npm install --save-dev becwright   # o: pnpm add -D becwright
pipx install becwright             # alternativa para plataformas fuera de los binarios npm

Después genera las reglas y el hook con un solo comando:

becwright init

init detecta si el repo tiene archivos Python o JS/TS, escribe un .bec/rules.yaml inicial con reglas acordes e instala el hook de git. El recorrido completo de tres minutos está en el quickstart.

El plugin de Claude Code

No hace falta salir del chat para nada de lo anterior. becwright tiene un plugin de primera clase para Claude Code, instalable desde su marketplace:

/plugin marketplace add DataDave-Dev/becwright
/plugin install becwright@becwright

El plugin no incluye becwright dentro — instala el paquete publicado (npm/PyPI) en tu proyecto. Lo que agrega:

• Una skill becwright. Le enseña al agente qué es becwright, cómo instalarlo (npm/pnpm sin Python, o pipx), cómo generar reglas y cómo leer y arreglar la salida de check. Claude la invoca automáticamente cuando pides “un guardrail”, “un check pre-commit” o “una regla que no se pueda ignorar”.
• Un comando /becwright — un punto de entrada directo con cuatro subcomandos:

Comando	Qué hace
/becwright init	Instala becwright y genera .bec/rules.yaml + hook
/becwright check	Corre las reglas y resume PASS / WARN / BLOCK
/becwright add <regex-o-url>	Agrega una regla forbid o importa un BEC
/becwright status	Reporta instalación + hook + número de reglas

¿Cómo reacciona el agente a un commit frenado?

Aquí es donde el diseño rinde. Cuando Claude Code ejecuta git commit y una regla blocking falla, el hook sale con 1 y git rechaza el commit. El agente entonces corre becwright check --json y recibe resultados estructurados:

{
  "blocked": true,
  "results": [
    {
      "id": "no-ai-debug-leftovers",
      "severity": "blocking",
      "passed": false,
      "intent": "Ninguna sentencia debugger ni llamada a console.log puede llegar a un commit.",
      "why_it_matters": "Un 'debugger' olvidado detiene la ejecución en producción.",
      "output": "src/api/client.ts:42\n      > debugger;"
    }
  ]
}

Cada regla que falla lleva su intent (qué exige la regla) y su why_it_matters (por qué existe). El agente no solo sabe que fue frenado — lee por qué, arregla el código para satisfacer la intención y vuelve a commitear. El ciclo se cierra sin un humano dentro, y sin que un debugger llegue jamás al historial. check --json no necesita dependencias extra y funciona desde el binario autónomo; el esquema está documentado en MCP y salida JSON.

Ejemplo: frenar restos de debug de la IA

El código generado por IA tiene un fallo de firma: andamiaje de debug que el agente usó mientras iteraba y luego olvidó. Un BEC en .bec/rules.yaml lo cierra:

rules:
  - id: no-ai-debug-leftovers
    intent: >
      Ninguna sentencia debugger ni llamada a console.log puede llegar a un
      commit.
    why_it_matters: >
      Los agentes agregan salida de debug mientras iteran y suelen olvidar
      quitarla; un 'debugger' olvidado detiene la ejecución en producción.
    paths:
      - "src/**/*.js"
      - "src/**/*.ts"
    check: "becwright run forbid --pattern '\\bdebugger\\b|console\\.log\\('"
    severity: blocking

El check integrado forbid acepta cualquier regex (más --ignore-case y --message), así que la mayoría de los guardrails no requieren código propio. Para credenciales existe el check integrado hardcoded_secrets, que detecta claves de AWS, claves privadas y asignaciones password = "..." — y reglas listas para usar que importas con becwright import <url> desde el catálogo, sin escribir nada. Si un patrón aparece de forma legítima, un comentario becwright: ignore en esa línea lo exime.

Próximos pasos

• Consigue un repo protegido en unos tres minutos con el quickstart.
• Mira las otras vías de integración — servidor MCP y CLI directa — en Agentes de IA.
• ¿Ya usas pre-commit? Se complementan — el detalle está en becwright vs pre-commit.