Agentes de IA

becwright está pensado para que un agente de IA lo configure y lo corra por ti. CLAUDE.md y .cursorrules le piden al agente que se porte bien; becwright es la red determinista que verifica el resultado en cada commit. Hay dos formas de conectarlo a un agente — un plugin dedicado de Claude Code y un camino genérico que sirve para cualquier agente que hable MCP o que pueda correr un comando.

¿Qué agentes funcionan con becwright?

Todos — ese es el objetivo del diseño. La imposición vive en un hook pre-commit nativo de git, así que la garantía nunca depende de qué agente (o humano) esté tecleando. Lo que cambia según el agente es qué tan cómodo resulta manejar becwright:

Agente	Camino recomendado	Qué obtiene
Claude Code	plugin dedicado	el skill becwright + el comando /becwright (init · check · add · status)
Cursor	servidor MCP	herramientas estructuradas: check, list_rules, list_checks, preview_rule, add_rule
Windsurf, opencode, otros clientes MCP	servidor MCP	las mismas herramientas MCP estructuradas
Cualquier cosa con shell	CLI a secas	becwright check --json y el resto de los comandos

Si tu agente no está en la tabla, empieza por la última fila: becwright es una CLI común, así que cualquier agente que pueda correr un comando de shell puede manejarlo. Las secciones de abajo recorren cada camino.

Claude Code (plugin)

Claude Code tiene un plugin de primera clase. Instálalo desde el marketplace de becwright:

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

El primer comando registra el repo como marketplace de plugins; el segundo instala el plugin desde ahí. No empaqueta becwright — instala el paquete publicado becwright (npm / PyPI) en tu proyecto.

Lo que obtienes:

• 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. El agente lo invoca solo cuando pides una barrera, un chequeo pre-commit o una regla que “no se pueda ignorar”.
• Comando /becwright — un punto de entrada directo:

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

La guía de integración de Claude Code recorre la configuración paso a paso.

Cualquier agente compatible con MCP

Cursor, Windsurf, opencode y cualquier otro cliente MCP pueden usar becwright a través de su servidor MCP — sin plugin dedicado. Apunta la configuración MCP del agente al comando:

{
  "mcpServers": {
    "becwright": {
      "command": "becwright",
      "args": ["mcp"]
    }
  }
}

Esto expone las herramientas estructuradas de becwright:

• check — corre las reglas y devuelve un flag blocked más una lista por regla de {id, severity, passed, intent, why_it_matters, output}.
• list_rules — las reglas del repo como registros de decisión, pensadas para leerse antes de escribir código y así esquivar un commit bloqueado.
• list_checks — los checks integrados a partir de los cuales un agente arma reglas.
• propose_rules_from_claude_md / preview_rule / add_rule — derivan reglas del CLAUDE.md del repo, prueban en seco una candidata y la agregan (add_rule solo hace una vista previa salvo que se llame con confirm=true).

El servidor MCP viene con el paquete de Python (pipx install "becwright[mcp]"). Mira MCP y salida JSON para los esquemas de las herramientas y el formato JSON, y la guía de integración de Cursor para una configuración concreta.

Cualquier agente con shell

No necesitas ninguna integración. becwright es una CLI común, así que cualquier agente que pueda correr comandos — incluido opencode — lo maneja directo:

npm install --save-dev becwright   # sin Python
npx becwright init                 # genera reglas + hook pre-commit
npx becwright check --all          # corre todas las reglas sobre el repo
npx becwright check --json         # resultados legibles por máquina para parsear

Más allá de check, la misma CLI le da al agente becwright why (leer el intent de las reglas antes de programar), becwright doctor (diagnosticar una instalación rota), becwright validate (lintear .bec/rules.yaml sin correr un check), becwright search / becwright add (instalar una BEC del catálogo integrado) y becwright run <check> (invocar un solo check integrado).

Como el hook pre-commit es nativo, los checks corren en cada commit sin importar qué agente hizo el cambio — ese es el punto: la garantía no depende de que el agente coopere.

¿Cómo reacciona un agente ante un commit bloqueado?

Este ciclo es lo que vuelve útil la integración en la práctica. Supón que el agente escribe código, lo pasa a staging y hace commit:

1. El hook pre-commit corre becwright check sobre los archivos en staging. Una regla blocking falla, el commit se rechaza y el comando sale con código 1.
2. El agente ve el fallo y corre becwright check --json (o llama a la herramienta MCP check, que devuelve el mismo resumen) para obtener una foto legible por máquina en vez de texto coloreado de terminal.
3. Cada entrada fallida lleva el id de la regla, su intent (qué exige la regla), su why_it_matters (el razonamiento detrás) y un campo output que apunta al archivo y la línea del problema.
4. El agente lee intent y why_it_matters, arregla el código — no la regla — y pasa el arreglo a staging.
5. Reintenta el commit. Cuando todas las reglas blocking pasan, becwright check sale con 0 y el commit aterriza.

Los dos campos de prosa existen justo para el paso 4. intent le dice al agente a qué estado debe llegar el código; why_it_matters explica lo que está en juego, lo que empuja al agente hacia un arreglo real en vez de un parche cosmético — quitar el token filtrado, digamos, en lugar de renombrar la variable que disparó el check. Mira MCP y salida JSON para el formato JSON completo.

Y cuando el agente no encuentra un arreglo, la salida del fallo sigue siendo un artefacto útil para pasarle a un humano: nombra la regla, la razón y las líneas exactas.

¿Por qué importa la salida determinista para los agentes?

Pregúntale a un agente si siguió todas tus reglas y casi siempre dirá que sí — pero eso es un auto-reporte, y los auto-reportes de un modelo probabilístico son exactamente aquello de lo que ya dependen CLAUDE.md y .cursorrules. Los modelos derivan, pierden contexto a mitad de sesión y a veces declaran éxito sobre trabajo que nunca hicieron. Ninguna cantidad extra de prosa en un archivo de instrucciones arregla eso.

becwright esquiva el problema al no preguntar nunca. El check corre sobre los archivos en staging y devuelve un código de salida: 0 significa que el código cumple las reglas, 1 significa que falló una regla blocking. Mismo código de entrada, mismo veredicto de salida, sin importar qué modelo produjo el cambio ni cómo fue prompteado. El código de salida — no el resumen del agente — es la verdad de base.

Ese determinismo rinde de tres maneras:

• Ningún prompt puede saltárselo. El hook es git nativo; corre aunque el agente nunca haya leído un solo archivo de instrucciones.
• Los reintentos convergen. Como el veredicto de una regla nunca tambalea, un agente que itera “arreglar → re-chequear” persigue un objetivo fijo, no uno móvil.
• La automatización puede ramificar sobre él. Un script o un job de CI puede condicionar sobre el código de salida sin parsear prosa — la misma propiedad sobre la que se apoyan el servidor MCP y check --json.

Si becwright todavía no está configurado en tu repo, el Quickstart lo deja protegido en tres comandos — y el agente puede correr esos comandos por sí mismo.