Introducción

becwright es un motor de guardrails determinista para repositorios git. Cada vez que haces commit, ejecuta los checks que declaraste sobre el código real en staging — los archivos exactos que están por entrar a la historia — y cada regla devuelve un veredicto duro: pasa o falla. Cuando falla una regla blocking, el commit se detiene antes de aterrizar. Los archivos de consejo como CLAUDE.md o .cursorrules solo le piden a un agente de IA que siga una regla, y el agente puede leerlos, malinterpretarlos o saltárselos; becwright no le pide a nadie que se porte bien — inspecciona el resultado.

Una nota de consejo solo funciona cuando el agente la lee, la entiende y la sigue. Un check de becwright no depende de nada de eso: se ejecuta sobre el código mismo y devuelve el mismo veredicto siempre, sin importar qué agente, modelo o humano hizo el cambio.

En corto: instala becwright una vez, corre becwright init dentro de tu proyecto, y a partir de ahí cada vez que guardas tu trabajo (un commit) revisa tu código contra tus reglas y frena el commit si se rompe una regla blocking. Ese es todo el ciclo — el resto de esta página es el detalle.

Instalación

Elige tu ecosistema. Los paquetes de npm traen un binario autocontenido, así que no se necesita Python:

npm install --save-dev becwright    # o global: npm install -g becwright
pnpm add -D becwright
pipx install becwright              # o: pip install becwright

Los paquetes de npm traen un binario autocontenido para linux-x64, linux-arm64, darwin-x64, darwin-arm64 y win32-x64. En cualquier otra plataforma usa pipx install becwright (Python 3.10 o más nuevo).

Windows es best-effort por ahora: la CLI y el hook corren bajo Git Bash (incluido con Git para Windows), pero Windows todavía no se ejercita en CI — el soporte de primera clase está planeado.

Configurar un repo

cd tu-repo
becwright init      # genera .bec/rules.yaml (según el lenguaje) e instala el hook

init detecta si el repo tiene archivos Python o JS/TS y escribe un .bec/rules.yaml de arranque con reglas acordes, y luego instala el hook pre-commit. Revisa las reglas generadas y corre becwright check --all para ver el estado actual.

A partir de ahí, cada git commit corre los checks. También puedes configurarlo a mano: becwright install más un .bec/rules.yaml que escribas tú.

Comandos

Comando	Descripción
becwright demo	Muestra a becwright frenando un commit malo de ejemplo (sin configurar nada, sin git)
becwright init	Genera un .bec/rules.yaml de arranque e instala el hook
becwright list	Lista los checks incluidos
becwright check	Corre las reglas sobre los archivos en staging
becwright check --all	Corre las reglas sobre todo el repo (git ls-files)
becwright check --diff <base>	Corre las reglas solo sobre los archivos cambiados vs <base> (para CI/PR)
becwright why [id]	Muestra el intent + porqué detrás de las reglas — la memoria de decisiones del repo (--json para agentes)
becwright validate	Valida .bec/rules.yaml sin correr ningún check (para editores/CI)
becwright doctor	Diagnostica la configuración: archivo de reglas, checks, hooks y gestores de hooks
becwright search [query]	Lista las BECs listas del catálogo offline incluido
becwright add <nombre>	Instala una BEC del catálogo en .bec/rules.yaml (offline)
becwright install	Instala el hook pre-commit
becwright uninstall	Quita el hook
becwright export <id> [-o archivo]	Exporta una regla a un bundle .bec.yaml
becwright import <fuente> [--yes]	Importa una BEC de un archivo o URL http(s)

¿“Archivos en staging”? Cuando corres git add, los archivos que elegiste quedan en staging — en la fila para el próximo commit. becwright check mira solo esos por defecto (justo lo que el commit va a crear), por eso es rápido. Usa --all para escanear todo el proyecto.

Códigos de salida (el número que devuelve un comando al terminar; 0 significa éxito): 0 pasa · 1 falló una regla blocking · 2 no es un repo git / error de uso.

¿Qué va en .bec/rules.yaml?

rules:
  - id: no-token-in-logs        # identificador único
    intent: >                   # qué pide la regla (la parte "bound")
      Los tokens de sesión nunca deben llegar a ningún log.
    why_it_matters: >           # por qué existe (se muestra cuando la regla falla)
      Un token en los logs deja que cualquiera robe una sesión.
    rejected_alternatives:      # opcional: enfoques considerados y descartados
      - "Redactar al loguear -> demasiado fácil de saltarse"
    paths:                      # globs de los archivos a los que aplica la regla
      - "src/**/*.py"
    check: "becwright run no_token_in_logs"
    severity: blocking          # blocking (frena el commit) | warning (solo avisa)

Campos

Campo	Requerido	Significado
id	sí	Id único de la regla
paths	sí	Globs (ver abajo)
check	sí	Comando de shell a correr (el check ejecutable)
intent	no	Qué hace cumplir la regla
why_it_matters	no	Por qué importa; se imprime cuando la regla falla
rejected_alternatives	no	Contexto: enfoques descartados
severity	no	blocking (por defecto) o warning

Globs

• * matchea cualquier cosa menos /.
• ** matchea a través de directorios.
• p.ej. src/**/*.py matchea src/a.py y src/x/y/z.py; src/*.py matchea solo el nivel superior.

¿De dónde puedes sacar reglas listas para usar?

¿No quieres escribir reglas tú mismo? El catálogo viene dentro de becwright — sin URL, funciona offline. search lista lo que hay y add instala una, mostrándote la regla antes de meterla en tu .bec/rules.yaml:

becwright search                 # lista cada BEC del catálogo offline
becwright add no-token-in-logs   # instala una; becwright te la muestra primero

La lista completa (Python, JS/TS, Go, Rust — más lenguajes en camino) está en el catálogo becs/. Para traer una regla de otro repo o de una URL, usa becwright import — ver Portabilidad.

Próximos pasos

• Configura un repo protegido de punta a punta en el Quickstart.
• Cómo decide pasa/no-pasa el motor en Arquitectura.
• Escribe tus propias reglas en Escribir checks.
• Comparte reglas entre repos con Portabilidad.
• Conecta becwright a un agente de IA con Agentes de IA y MCP y salida JSON.