becwright + Cursor: guardrails deterministas

El agente de Cursor lee .cursorrules (y sus project rules más recientes) igual que Claude Code lee CLAUDE.md: como un consejo. Normalmente obedece — y a veces no, que es exactamente cuando un debugger, un volcado de console.log o una API key activa aterriza en tu historial. becwright es un motor determinista de guardrails pre-commit: verifica el código real en el momento del commit y lo frena (código de salida 1) cuando una regla blocking falla. .cursorrules sigue siendo el lugar donde describes estilo e intención; becwright es la capa que convierte el enforcement de .cursorrules de una esperanza en una garantía, y le da a Cursor una puerta pre-commit real que ningún prompt puede sortear con palabras.

¿Por qué .cursorrules no puede imponer nada?

Porque los archivos de reglas son entrada, no verificación. Tres problemas estructurales:

• El cumplimiento es probabilístico. El modelo pondera tu línea de “sin secretos hardcodeados” contra la tarea, el código y la conversación. En una sesión larga, la regla puede sencillamente perder — y no lo sabrás hasta la revisión, o hasta producción.
• Nada revisa la salida. .cursorrules moldea lo que el agente intenta escribir. Ninguna parte de ese pipeline inspecciona lo que de verdad quedó escrito antes de convertirse en commit.
• La regla solo cubre a Cursor. Un compañero en otro editor, un segundo agente o una edición manual rápida quedan totalmente fuera de su alcance.

becwright invierte esto: un hook de git pre-commit nativo corre tus reglas sobre los archivos staged en cada commit, sin importar quién o qué hizo el cambio. El resultado es pasa/no-pasa, determinista, igual en cada ejecución. (Complementa, no reemplaza, al framework pre-commit clásico — mira 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:

becwright init

init detecta si el repo tiene archivos Python o JS/TS, escribe un .bec/rules.yaml inicial e instala el hook de git. Desde ese momento cada commit — desde Cursor, la terminal, donde sea — corre los checks. El recorrido completo está en el quickstart.

Maneja becwright desde Cursor vía MCP

Cursor habla MCP, y becwright trae un servidor MCP — sin plugin dedicado. Apunta la configuración MCP de Cursor (.cursor/mcp.json en la raíz del proyecto, o tus ajustes MCP globales) al comando:

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

Esto expone dos herramientas estructuradas al agente:

Herramienta	Argumentos	Devuelve
check	all_files (bool), path (dir del repo, opcional)	el mismo resumen que check --json
list_checks	—	los checks integrados como {name, description}

Una salvedad honesta: el servidor MCP solo viene con el paquete de Python — instálalo con pipx install "becwright[mcp]". El binario de npm cubre la CLI y el hook, que es todo lo que la mayoría de los setups necesita; el detalle está en MCP y salida JSON.

¿Sin MCP? Usa la shell. becwright es una CLI simple, así que el agente de Cursor puede manejarla con comandos normales y obtener salida legible por máquina igualmente:

npx becwright check --all    # corre todas las reglas sobre el repo
npx becwright check --json   # resultados legibles por máquina para parsear

¿Qué pasa cuando Cursor choca con un commit frenado?

El agente termina una tarea, ejecuta git commit y una regla blocking falla: el hook sale con 1 y git rechaza el commit. El agente entonces llama a la herramienta check (o corre becwright check --json) y lee resultados estructurados:

{
  "blocked": true,
  "results": [
    {
      "id": "no-hardcoded-secrets",
      "severity": "blocking",
      "passed": false,
      "intent": "Sin credenciales, API keys ni contraseñas en el código fuente.",
      "why_it_matters": "Un secreto commiteado al historial de git sigue filtrado aunque lo borres.",
      "output": "src/config.ts:3\n      > const STRIPE_KEY = \"sk_live_51H8...\""
    }
  ]
}

Cada regla que falla lleva su intent y su why_it_matters, así que el agente no solo ve que el commit fue rechazado sino por qué existe la regla — contexto suficiente para arreglar el código de verdad (mover la clave al entorno) en vez de hacer trampa al check. Después vuelve a commitear y pasa. El ciclo se cierra sin un humano, y sin que el secreto entre jamás al historial.

Ejemplo: frenar restos de debug de la IA

El desorden más común en código generado por IA es el andamiaje de debug que el agente olvidó quitar. 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 secretos existe el check integrado hardcoded_secrets (claves de AWS, claves privadas, password = "..."), y reglas listas para importar desde el catálogo con becwright import <url>. Las apariciones legítimas se eximen línea a línea con un comentario becwright: ignore.

Próximos pasos

• Monta un repo protegido en unos tres minutos con el quickstart.
• Compara todas las vías de integración de agentes — plugin de Claude Code, MCP, CLI directa — en Agentes de IA.
• ¿Ya corres pre-commit? Mira cómo encajan en becwright vs pre-commit.