Desarrollo Guiado por Restricciones

¿Qué hace Desarrollo Guiado por Restricciones?

Descripción general

Otras habilidades en este paquete describen cómo se ve lo "bueno". code-review-and-quality te da cinco ejes. test-driven-development te da un ciclo. security-and-hardening te da una lista de amenazas. Todo eso vive en prosa que el agente lee y puede o no seguir, y nada de eso sobrevive al final de la sesión.

Esta habilidad produce algo diferente: un registro escrito del estándar de este proyecto, con números, que sobrevive a la conversación y se puede verificar mecánicamente.

La razón es importante. Cuando escribías el código, leerlo te decía si era bueno. Un agente escribe más en una tarde de lo que leerás esa semana, por lo que el juicio sale de tu cabeza y entra en comprobaciones que se ejecutan en el bucle. Esas comprobaciones deben existir, necesitan números que realmente elegiste y deben activarse lo suficientemente cerca del trabajo para que el agente corrija su propia salida.

El desarrollo guiado por especificaciones dice qué construir. El desarrollo guiado por pruebas demuestra que funciona. El desarrollo guiado por restricciones define lo que significa "suficientemente bueno para enviar", antes de que alguien discuta sobre ello en una solicitud de extracción.

Cuándo usar

Aplica esta habilidad cuando:

• Estás iniciando un proyecto o una característica importante y no hay un estándar de calidad escrito
• El usuario pide "configurar restricciones", "agregar barreras de calidad", "definir nuestros estándares" o "evitar que el agente envíe basura"
• Un agente está produciendo volumen que nadie está leyendo línea por línea
• CI tiene comprobaciones pero nadie puede decir cuáles bloquean una fusión y cuáles son decorativas
• Los números de cobertura, rendimiento o accesibilidad se discuten por solicitud de extracción en lugar de decidirse una vez
• Estás a punto de ejecutar /build auto o cualquier bucle autónomo, y lo único que se interpone entre eso y la rama principal es un conjunto de pruebas que el agente también escribió

Cuándo NO usar:

• El proyecto ya tiene un CONSTRAINTS.md y el usuario no lo está cambiando — léelo y síguelo en su lugar
• Scripts únicos, prototipos desechables
• El usuario quiere una revisión de código ahora mismo (code-review-and-quality) o una canalización de CI construida (ci-cd-and-automation)
• Código anterior a la adecuación producto-mercado con una vida útil esperada de dos semanas — el piso de abajo sigue valiendo la pena, el resto no

Carga de restricciones

La entrevista necesita un usuario activo. No la ejecutes en contextos no interactivos (CI, /loop, ejecuciones autónomas). Si faltan restricciones y estás en uno de esos, aplica el Piso a continuación, anota que lo hiciste y marca el resto para un humano.

El Proceso

Paso 1: Detectar antes de preguntar

Nunca preguntes lo que puedes leer. Antes de la primera pregunta, recopila:

Qué	Dónde buscar
Lenguaje y pila	package.json, pyproject.toml, go.mod, Cargo.toml
Ejecutor de pruebas	dependencias de desarrollo, script test, archivos de prueba existentes
Linters existentes	eslint.config.*, biome.json, .ruff.toml
Cobertura hoy	salida de coverage/, o ejecuta la suite una vez
CI	.github/workflows/, .gitlab-ci.yml
Arnés de agente	.claude/, .codex/, AGENTS.md

Informa lo que encontraste en dos líneas, luego pregunta solo lo que queda.

Paso 2: Cuatro preguntas, cada una con un valor predeterminado

Sigue la disciplina de una pregunta a la vez de interview-me, con un cambio: cada pregunta aquí tiene un valor predeterminado, por lo que "no sé" es una respuesta completa que aún produce una configuración funcional.

P1: Además del piso, ¿cuál de estos quieres que se aplique?
    (a) Cobertura de pruebas en código nuevo
    (b) Escaneo de seguridad
    (c) Presupuestos de rendimiento
    (d) Accesibilidad
    (e) Límites de arquitectura
SUPOSICIÓN: (a) y (b) — ya tienes un ejecutor de pruebas y estás manejando entrada del usuario.
VALOR PREDETERMINADO si no estás seguro: (a) y (b).
Di lo que cuesta cada opción: (c) y (d) necesitan una URL en ejecución, (e) necesita un archivo de reglas escrito.

P2: Cuando una comprobación falla mientras el agente está en medio de una tarea, ¿debe bloquear o advertir?
SUPOSICIÓN: Bloquear. Estás ejecutando agentes sin supervisión y una advertencia que nadie lee es una advertencia.
VALOR PREDETERMINADO si no estás seguro: Bloquear en el piso, advertir en todo lo demás durante las primeras dos semanas.

P3: ¿Tienes números objetivo en mente, o debería medir dónde estás hoy y mantener esa línea?
SUPOSICIÓN: Medir. La mayoría de los equipos no tienen un número, y uno inventado se ignora.
VALOR PREDETERMINADO si no estás seguro: Medir y mantener. Consulta "Trinquete" a continuación.

P4: ¿Cuál es la comprobación más lenta que tolerarás antes de que el agente devuelva el trabajo?
SUPOSICIÓN: Alrededor de 90 segundos. Más tiempo y dejarás de ejecutarla.
VALOR PREDETERMINADO si no estás seguro: 90 segundos al final de la tarea, ilimitado en CI.

Detente en cuatro. Una admisión de doce preguntas produce una configuración que nadie entiende y un usuario que se arrepiente de haber comenzado.

Paso 3: Escribir CONSTRAINTS.md

Un archivo en la raíz del repositorio. Cualquier agente en cualquier arnés puede leerlo, y un cambio en él aparece en la revisión donde corresponde.

# Restricciones

Última revisión: 2026-08-08 por @addy

## Piso (siempre aplicado, no requiere configuración)

- Sin nuevos comentarios de supresión: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
- Sin código auxiliar no implementado: `throw new Error("Not implemented")`, `catch {}` vacío
- Sin pruebas omitidas o eliminadas sin una razón en el mensaje de confirmación
- Sin secretos en el código fuente
- Este archivo no se debilita para que un cambio pase

## Aplicado con números

| Dimensión | Regla | Verificado por | Se ejecuta en |
|-----------|------|-----------|---------|
| Tipos | Cero errores de tipo | `tsc --noEmit` | cada edición |
| Lint | Cero errores de nuestra configuración | `biome check` | cada edición |
| Secretos | Sin secretos en el código fuente | `gitleaks detect --redact` | cada edición |
| Cobertura | Líneas cambiadas ≥ 80% cubiertas | `vitest run --coverage` + git diff | final de tarea, CI |
| Seguridad: código | Sin hallazgos de alto nivel | `semgrep scan --config p/default` | CI |
| Seguridad: dependencias | Nada de alto o superior | `osv-scanner scan source -r .` | CI |
| Accesibilidad | Cero críticos o graves | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | despliegue de vista previa |
| Rendimiento | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | despliegue de vista previa |

Cada fila nombra el comando que produce el veredicto. Una dimensión con un número y sin comando en esta columna es una aspiración, no una restricción.

## Medido, aún no aplicado

| Métrica | Hoy | Dirección |
|--------|-------|-----------|
| Cobertura del proyecto | 62.4% | no debe caer |
| Tamaño del paquete (principal) | 184 kB | no debe crecer |

## Excepciones

| ID | Regla | Ruta | Razón | Propietario | Vence |
|----|------|------|--------|-------|---------|
| W1 | `no-explicit-any` | `src/legacy/**` | Reescritura rastreada en ENG-441 | @addy | 2026-11-01 |

Luego agrega una línea a AGENTS.md y CLAUDE.md: Lee CONSTRAINTS.md antes de escribir código. No lo debilites para que un cambio pase.

Paso 4: Instalar lo que necesita cada dimensión

Elegir una dimensión significa instalar algo. No dejes al usuario con un número y sin mecanismo, y no inventes tu propio verificador cuando exista uno de facto — estas herramientas se enumeran porque sus formatos de reglas y umbrales son a lo que apunta todo lo demás en el ecosistema, por lo que la configuración existente del equipo sigue funcionando.

Dimensión	Herramienta	Instalar	Ejecutar	Barrera
Tipos (TS)	tsc	ya está allí	tsc --noEmit	cualquier error
Tipos (Python)	mypy	pip install mypy	mypy .	cualquier error
Lint	tu configuración existente	ya está allí	eslint . / biome check / ruff check	cualquier error
Cobertura (JS)	tu ejecutor de pruebas	ya está allí	vitest run --coverage (o jest --coverage)	cobertura de líneas cambiadas
Cobertura (Python)	pytest-cov	pip install pytest-cov	pytest --cov --cov-report=lcov	lo mismo
Seguridad: código	Semgrep	pipx install semgrep	semgrep scan --config p/default --config p/owasp-top-ten	cualquier hallazgo de alto nivel
Seguridad: secretos	gitleaks	brew install gitleaks	gitleaks detect --redact --no-banner	cualquier hallazgo
Seguridad: dependencias	osv-scanner	brew install osv-scanner	osv-scanner scan source -r .	alto o superior
Rendimiento: página	Lighthouse	npm i -D lighthouse	lighthouse $URL --output=json --quiet	LCP, CLS, puntuación de rendimiento
Rendimiento: paquete	size-limit	npm i -D size-limit	size-limit --json	presupuesto de bytes por entrada
Accesibilidad	axe-core	npm i -D @axe-core/cli	axe $URL --tags wcag2a,wcag2aa,wcag21aa	cero críticos o graves
Arquitectura	dependency-cruiser	npm i -D dependency-cruiser	depcruise --validate src	cualquier violación
Calidad de aserciones	Stryker	npm i -D @stryker-mutator/core	stryker run --mutate <archivos cambiados>	puntuación de mutación

Cinco cosas que te morderán si las omites:

1. --redact en gitleaks no es opcional. Sin él, el secreto coincidente termina en la transcripción del agente, que es cómo una clave filtrada termina en un registro, un resumen o un mensaje de confirmación. Informa la regla y la ubicación, nunca el valor.
2. Lighthouse y axe necesitan una URL. Solo funcionan contra una aplicación en ejecución, por lo que pertenecen a la etapa de tiempo de ejecución contra un despliegue de vista previa o un servidor local que inicies primero. Si el proyecto no tiene una URL a la que acceder — una CLI, una biblioteca, una aplicación de escritorio — dilo y elimina la dimensión en lugar de inventar una comprobación que no se puede ejecutar.
3. Limita las costosas al diff. stryker run --mutate en todo el repositorio lleva horas y se desactiva; en los archivos que tocó un cambio lleva menos de un minuto. Lo mismo para Semgrep, que toma una lista de rutas.
4. La cobertura no necesita una segunda ejecución de prueba. Lee el lcov que tu suite ya escribe e interprétalo con git diff. Ejecutar la suite dos veces para obtener un número es la forma más rápida de hacer que la gente odie esto.
5. Las reglas del registro de Semgrep son gratuitas de ejecutar; verifica la licencia antes de redistribuirlas. opengrep es un fork de reemplazo directo con el mismo formato de reglas y salida JSON si eso es importante para tu equipo legal.

Agrega cada una al script del proyecto para que sea reproducible sin un agente:

{
  "scripts": {
    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
    "check:task": "npm run check:fast && vitest run --coverage",
    "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
  }
}

Esa asignación importa más que las herramientas. check:fast es lo que se ejecuta después de una edición, check:task cuando el agente cree que ha terminado, check:full en CI.

Los comandos ahora viven en dos lugares: la columna Verificado por en CONSTRAINTS.md y estos scripts. CONSTRAINTS.md es la fuente canónica: lleva la razón junto a cada comando y aparece en la revisión. Los scripts son envoltorios convenientes que deben reflejarlo, no una segunda fuente de verdad; si se desvían, el archivo gana.

Paso 5: Conectarlo al ciclo de vida

El error más grande es ejecutar todo en todas partes. Una comprobación que detiene al agente se desactiva, y una barrera que la gente desactivó es peor que ninguna barrera, porque el estándar aún parece que existe.

Fase	Comando	Qué se ejecuta	Presupuesto
CONSTRUIR	/build	Tipos, lint, secretos, el piso	menos de 5s, solo archivo cambiado
VERIFICAR	/test	Pruebas relacionadas, cobertura en líneas cambiadas	menos de 90s
REVISAR	/review	Todo, más las salvaguardas a continuación	minutos
ENVIAR	/ship	Comprobaciones de dirección, sin regresiones	CI

Dos reglas que mantienen esto tolerable:

1. Limita al diff. Verifica las líneas que tocó este cambio, no todo el repositorio. La cobertura de las líneas cambiadas es un número que el agente puede mover; la cobertura del proyecto es una que heredó.
2. El costo decide la ubicación. Cualquier cosa que dure más de unos segundos sale del bucle de edición. Las pruebas de mutación en todo el repositorio llevan horas; en los archivos que tocó un cambio llevan menos de un minuto, que es la diferencia entre una comprobación que la gente ejecuta y una que no.

Paso 6: Proteger el estándar mismo

Alguien señalará que si el agente escribe el código y las comprobaciones, las comprobaciones no prueban nada. Medio cierto, y vale la pena diseñar alrededor de eso.

Los agentes no crean lagunas inteligentes. Se topan con una verificación roja y toman el camino más barato hacia el verde. Vigila estos cinco movimientos en el diff, en el momento de la revisión:

1. El umbral se movió. Un presupuesto bajó, una gravedad disminuyó, una comprobación se eliminó de la etapa rápida. Compara CONSTRAINTS.md con su estado en el punto de ramificación.
2. Una prueba se volvió más fácil. Se agregó .skip, se eliminó un archivo de prueba, se eliminaron aserciones de pruebas que se quedaron.
3. Un verificador fue silenciado. Nuevo @ts-ignore o eslint-disable. Cuatro supresiones merecen atención especial porque desactivan una comprobación en la que estás confiando: istanbul ignore elimina el código de la cobertura en lugar de probarlo, Stryker disable oculta un mutante superviviente, nosemgrep y gitleaks:allow lo hacen para hallazgos de seguridad.
4. El trabajo está sin terminar. Un stub que lanza, un catch vacío que convierte una falla en silencio, un TODO donde debería estar la implementación.
5. Apareció una excepción. Una nueva fila en la tabla de Excepciones que nadie discutió.

Nada de esto necesita herramientas más allá de git diff. Ajustar el estándar debe ser silencioso; aflojarlo debe ser ruidoso.

A diferencia de las dimensiones numeradas, el piso no tiene una herramienta de facto propia, por lo que un agente al que se le pide que lo aplique tiende a escribir un verificador desde cero, y dos agentes escriben dos diferentes. Una implementación de referencia de estas cinco comprobaciones se incluye con esta habilidad en references/floor-guard.md (limitada al diff, salida 0/1/2, patrones adaptables por ecosistema). Adáptala en lugar de reinventarla, por la misma razón por la que cada dimensión nombra una herramienta de facto: para que el mecanismo sea el mismo en todas las ejecuciones y pilas.

No todas las comprobaciones son igualmente circulares. Clasifícalas por una pregunta: ¿puede el agente hacer que esto pase escribiendo código que no funciona?

• Externa — axe-core codifica WCAG, osv-scanner lee una base de datos de vulnerabilidades, Lighthouse mide un navegador real. El agente no puede discutir con estas.
• Proyecto — tus reglas de lint, tus límites de capa. Un humano es dueño del archivo.
• Suite — tus propias pruebas. Lo más útil, y la única genuinamente circular.

Un estándar apuntalado por una combinación de estos tres tipos importa más que uno donde todo es circular, y esa es la diferencia entre una barrera y una formalidad.

Trinquete

Trinquete significa medir el punto de partida real, no elegir un objetivo soñado, y luego solo permitir que la línea se mueva hacia arriba. El mecanismo de este estándar ya está en CONSTRAINTS.md bajo "Medido, aún no aplicado": ejecuta tus comprobaciones, anota los números de hoy, y haz que el agente los mantenga. Si la cobertura del proyecto es del 62.4%, el trinquete es "no puede caer más abajo". Si el tamaño del paquete es de 184 kB, el trinquete es "no puede crecer".

Dos razones por las que el trinquete funciona cuando un objetivo soñado fracasa:

1. Es real. No puedes debatir el 62.4%. Puedes debatir el 80%.
2. El agente no puede inventarlo. Un objetivo soñado es un piso de vidrio que el agente rompe y promete que no volverá a pasar. Una medición real como el trinquete es un piso de hormigón: la herramienta lo comprueba, el agente lo lee directamente.

Actualizar: Después de cada fusión, vuelve a medir el número de trinquete y escribe el nuevo mínimo. Si la cobertura del proyecto alcanza el 67.1%, el trinquete se convierte en "nunca por debajo del 67.1%". El trinquete se mueve en una dirección.

Inverso: Si una dimensión se considera ahora urgente y la medición de hoy es demasiado baja, no muevas el trinquete hacia abajo. Mueve la dimensión a la tabla de