Desarrollo Basado en Intenciones
Producir criterios de aceptación útiles sin convertir la especificación en un mero trámite. Inspeccionar primero el contexto disponible, exponer la ambigüedad genuina y elegir métodos de verificación que se ajusten al trabajo y su riesgo.
Cuándo activarlo
- El usuario pide aclarar una funcionalidad, definir criterios de aceptación o reducir el riesgo de un cambio antes de implementarlo.
- La solicitud afecta a seguridad, autenticación, datos persistentes, migraciones, APIs externas o cumplimiento normativo.
- El usuario quiere preparar un artefacto para transferir a otro agente o equipo.
- La solicitud es lo suficientemente ambigua como para que el resultado esperado no sea aún observable o comprobable.
- El usuario invoca explícitamente esta habilidad con
/desarrollo-basado-en-intenciones.
No activar para ediciones triviales, correcciones directas de una línea, sesiones de depuración activa, solicitudes de revisión de código o peticiones de implementación cuyas condiciones de aceptación ya están claras.
Cómo funciona
- Inspeccionar contexto primero: lee el repositorio, la documentación, los esquemas y la infraestructura de pruebas en busca de hechos técnicos antes de hacer cualquier pregunta, tratando las restricciones de producto o negocio como algo que solo el usuario o un artefacto de producto puede proporcionar.
- Elegir profundidad: selecciona Captura Rápida (3-7 criterios, riesgo bajo/moderado) o Informe de Aceptación Completo (seguridad, datos, migraciones, cambios entre sistemas) según el perfil de riesgo.
- Preguntar mínimamente: solo formula preguntas cuyas respuestas no se puedan inferir y que cambien materialmente el alcance o el comportamiento.
- Escribir criterios observables: cada AC-NNN describe una condición inicial, un desencadenante, un resultado esperado, un efecto secundario prohibido, un método de verificación y una prioridad; sin palabras vagas como "correctamente" o "de forma segura" sin evidencia.
- Proceder o transferir: para solicitudes claras sin riesgos bloqueantes, registra criterios y continúa; para cambios arriesgados, presenta bloqueadores y espera confirmación.
- Manejar revisiones: si un AC falla durante la implementación debido a restricciones arquitectónicas, lo marca como
[revisado], actualiza el alcance o método de verificación, incrementa el número de revisión y vuelve a presentar solo los criterios modificados.
Ejemplos
Captura Rápida — "Añadir exportación CSV al panel de control"
Objetivo: Los usuarios autenticados pueden descargar los datos del panel de control como un archivo CSV.
Dentro del alcance: Exportación de las filas actualmente filtradas; el nombre del archivo incluye la fecha.
Fuera del alcance: Exportaciones programadas, entrega por correo electrónico, formato Excel.
Suposiciones: El número máximo de filas es inferior a 10k; no hay PII en los campos exportados.
AC-001: La exportación genera un archivo con los encabezados correctos
- Escenario: usuario autenticado, al menos una fila de datos visible
- Acción: hacer clic en "Exportar CSV"
- Esperado: el navegador descarga un archivo con las columnas [id, nombre, fecha_creación]
- No debe: exponer campos internos ni filas pertenecientes a otros usuarios
- Verificación: prueba de integración automatizada + comprobación manual del esquema
- Prioridad: Obligatorio
Disparador de Informe Completo — "Migrar autenticación de usuarios a OAuth"
Cambio de autenticación + dependencia externa + datos de sesión existentes → Informe Completo con tabla de Revisión de Riesgos, decisiones bloqueantes sobre la estrategia de invalidación de sesión y AC explícito de reversión.
Revisión de especificación existente — el usuario pega un PRD
La habilidad lo revisa en busca de límites de alcance faltantes, requisitos no verificables ("el sistema será rápido") y suposiciones silenciosas, luego devuelve criterios corregidos o complementarios sin reiniciar el descubrimiento.
Reglas operativas
- Inspeccionar el repositorio, la documentación, el issue, el diseño y el contexto de pruebas disponibles antes de pedir datos técnicos que puedan descubrirse localmente.
- No inferir restricciones de producto o negocio a partir del código. Las reglas de negocio, las obligaciones de cumplimiento y regulatorias, los SLA contractuales, los precios, la política de retención de datos, la priorización y los usuarios objetivo no pueden leerse de un repositorio. Tratarlos como desconocidos hasta que el usuario los proporcione o un artefacto de producto autorizado (PRD, contrato, documento de políticas) los establezca. Registrarlos como suposiciones marcadas para confirmación, nunca como hechos descubiertos. El repositorio indica cómo se comporta el sistema hoy, no lo que el negocio requiere que haga.
- Hacer solo preguntas cuyas respuestas sean necesarias y no puedan inferirse de forma segura. Agrupar preguntas cortas y relacionadas cuando ello ahorre turnos innecesarios.
- No bloquear la implementación por defecto. Cuando el usuario haya pedido implementar un cambio suficientemente claro, registrar brevemente las suposiciones clave y los criterios de aceptación, luego proceder o transferirlos al flujo de trabajo de implementación.
- Requerir confirmación explícita del usuario antes de proceder solo cuando una decisión no resuelta pueda crear una exposición de seguridad material, pérdida de datos, migración irreversible, ruptura contractual/de API, coste significativo o acción externa destructiva.
- No escribir un documento de aceptación en un repositorio, alterar archivos del proyecto, crear una rama, hacer commit o invocar otra habilidad a menos que el usuario lo solicite o el flujo de trabajo del repositorio activo lo exija explícitamente.
- Tratar las pruebas automatizadas como evidencia, no como verdad. Preferir la automatización cuando sea fiable y proporcionada; permitir verificación manual de UX, accesibilidad, seguridad, legal u operativa cuando la automatización no pueda establecer el resultado.
- No incluir nunca secretos reales, credenciales, tokens, claves privadas, datos personales o cargas de producción sensibles en los criterios de aceptación, fixtures, ejemplos o artefactos guardados. Usar valores redactados o sintéticos.
- No ejecutar pruebas destructivas, migraciones, sondas de seguridad, pruebas de carga, llamadas externas de pago u operaciones contra datos de producción/vivos sin autorización explícita y un entorno seguro identificado.
- Cuando un criterio de aceptación no pueda satisfacerse debido a una restricción arquitectónica, de plataforma o externa descubierta durante la implementación, no omitirlo silenciosamente ni sortearlo. Actualizar el criterio afectado (marcarlo como
[revisado], indicar la restricción y ajustar el alcance o el método de verificación), incrementar el número de revisión y volver a presentar solo los criterios modificados al usuario antes de continuar. Requerir confirmación explícita solo si la revisión cambia una decisión bloqueante o reduce materialmente las garantías de seguridad o corrección.
Elegir la profundidad
Usar la salida más pequeña y útil.
Captura Rápida
Usar para un cambio claro pero no trivial con riesgo bajo o moderado. Producir:
- Objetivo
- Dentro del alcance / Fuera del alcance
- Suposiciones
- 3-7 criterios de aceptación con métodos de verificación
- Preguntas bloqueantes, si las hay
No retrasar la implementación para aprobación a menos que exista un riesgo bloqueante de las reglas operativas o el usuario haya solicitado específicamente una especificación primero.
Informe de Aceptación Completo
Usar para cambios ambiguos, entre sistemas, sensibles a la seguridad, que modifican datos, de migración, cumplimiento normativo o de alto coste, o cuando el usuario solicite un artefacto de transferencia. Producir la plantilla completa a continuación y solicitar confirmación para decisiones bloqueantes no resueltas antes de la implementación arriesgada.
Revisión de Especificación Existente
Cuando el usuario ya haya proporcionado un PRD, issue, plan o criterios de aceptación:
- Revisarlo en lugar de reiniciar el descubrimiento.
- Identificar límites de alcance faltantes, suposiciones inseguras, contradicciones y requisitos no verificables.
- Devolver criterios corregidos o complementarios.
Flujo de trabajo
1. Establecer objetivo y riesgo
Extraer o preguntar:
- El resultado observable para el usuario o el sistema.
- Los actores afectados.
- La principal consecuencia de fallo.
- Las dimensiones de riesgo que realmente aplican: seguridad/privacidad, datos persistentes, compatibilidad/API, migración, dependencias externas, coste, concurrencia, rendimiento, usabilidad/accesibilidad.
Evitar hacer preguntas genéricas sobre riesgos irrelevantes.
2. Descubrir contexto
Cuando haya artefactos locales o conectados disponibles, inspeccionar solo lo necesario:
- Comportamiento existente y archivos o interfaces directamente relacionados.
- Convenciones del repositorio, documentación del producto, contratos de API, esquemas de datos o historial de migraciones.
- Infraestructura de verificación existente y comandos realistas.
- Dependencias externas y si se pueden probar de forma aislada.
Registrar los hechos descubiertos por separado de las suposiciones proporcionadas por el usuario. Si no se puede inspeccionar el contexto, indicar qué se desconoce y hacer preguntas enfocadas.
El repositorio revela hechos técnicos: cómo se comporta el sistema hoy, sus convenciones y sus contratos. No revela restricciones de producto o negocio: reglas de negocio, obligaciones de cumplimiento y regulatorias, SLA contractuales, precios, política de retención de datos, priorización y usuarios objetivo. Nunca reconstruirlas a partir del código o los nombres. Capturarlas solo del usuario o de un artefacto de producto autorizado, y enumerarlas como suposiciones a confirmar hasta entonces.
3. Definir alcance
Indicar:
- Objetivo: una frase que describa el resultado previsto.
- Dentro del alcance: comportamiento que este cambio debe entregar.
- Fuera del alcance: trabajo adyacente tentador explícitamente excluido.
- Suposiciones: afirmaciones aún no probadas.
- Decisiones bloqueantes: elecciones no resueltas que afectan materialmente a la seguridad o el comportamiento.
4. Escribir criterios de aceptación
Usar AC-001, AC-002, etc. Cada criterio debe describir un comportamiento observable y un método de verificación apropiado; no es necesario que los criterios y las pruebas se correspondan uno a uno.
Para cada criterio aplicable incluir:
- Escenario o condición inicial.
- Acción o desencadenante.
- Comportamiento observable esperado.
- Efecto secundario prohibido cuando sea significativo.
- Método de verificación: prueba automatizada, comprobación de integración, revisión manual de UX, comprobación de accesibilidad, revisión de seguridad, comprobación operativa o aceptación de las partes interesadas.
- Restricción de entorno/seguridad cuando la verificación pueda afectar a datos, servicios, coste o secretos.
- Prioridad: obligatorio, importante u opcional.
No usar palabras como "correctamente", "de forma segura", "rápido", "intuitivo" o "robusto" sin definir evidencia observable o registrarlas como un juicio de revisión humana.
5. Cubrir solo los límites relevantes
Considerar estas categorías, pero incluir solo las que apliquen:
| Categoría | Incluir cuando | Evidencia típica |
|---|---|---|
| Camino feliz | Comportamiento visible para el usuario nuevo o modificado | Flujo de trabajo exitoso o transición de estado |
| Validación | El cambio acepta entrada | Entrada malformada o de valor límite rechazada sin mutación |
| Autorización/privacidad | Datos o acciones tienen límites de acceso | Acceso denegado y sin divulgación sensible |
| Persistencia/migración | Datos almacenados o esquemas cambian | Lectura hacia atrás, migración, reversión o comportamiento de copia de seguridad |
| Compatibilidad | APIs públicas, archivos, eventos o clientes pueden romperse | Contrato existente o fixture sigue siendo válido |
| Recuperación de fallos | Existe red, servicio o fallo asíncrono | Sin estado parcial o comportamiento claro de reintento/degradación |
| Idempotencia/concurrencia | Se pueden producir repeticiones o escrituras simultáneas | Sin efecto secundario duplicado ni estado final inválido |
| Rendimiento | Importa un umbral de usuario o servicio | Condiciones de medición y umbral definidos |
| UX/accesibilidad | Una persona interactúa con el resultado | Teclado, retroalimentación, recuperación de errores, revisión visual/manual |
6. Presentar y continuar
- Para una solicitud de aclaración/especificación, presentar el informe y pedir decisiones solo sobre los bloqueadores enumerados.
- Para una solicitud de implementación sin bloqueador, presentar un resumen compacto de criterios como parte del trabajo y continuar con la implementación.
- Para la transferencia a otro agente o equipo, incluir suficiente contexto y detalle de verificación para que puedan actuar sin inventar requisitos.
- Guardar el informe en un archivo solo cuando se solicite. Usar una ruta aprobada por el repositorio cuando exista; de lo contrario, preguntar o indicar el destino elegido antes de escribir.
Plantilla de salida
Usar esta plantilla para un Informe de Aceptación Completo. Omitir secciones irrelevantes para Captura Rápida.
# Informe de Aceptación: <Nombre del Cambio>
**Estado:** Borrador | Aprobado | Implementado | Verificado
**Revisión:** <número>
**Preparado para:** <usuario/equipo/agente, cuando se conozca>
**Aprobación requerida antes del trabajo arriesgado:** Sí | No - <motivo>
## Registro de Revisiones
| Rev | Fecha | Criterios cambiados | Motivo |
| --- | --- | --- | --- |
| 1 | <fecha> | — | Borrador inicial |
## Objetivo
<Una frase con el resultado observable.>
## Alcance
**Dentro del alcance**
- <comportamiento incluido>
**Fuera del alcance**
- <trabajo adyacente excluido>
## Contexto
**Hechos descubiertos** (técnicos, verificados del repositorio o artefacto)
- <cómo se comporta el sistema hoy, convenciones, contratos>
**Restricciones de producto/negocio** (proporcionadas por el usuario o artefacto de producto, nunca inferidas del código)
- <regla de negocio, obligación de cumplimiento/SLA, política de retención, prioridad, usuario objetivo — o "ninguna proporcionada aún">
**Suposiciones**
- <afirmación no verificada a confirmar o validar>
**Dependencias y restricciones**
- <servicio externo, convención local, obligación de compatibilidad, límite de entorno>
## Revisión de Riesgos
| Área de riesgo | ¿Aplica? | Manejo requerido |
| --- | --- | --- |
| Seguridad/privacidad | Sí/No | <redacción, autorización, revisión, etc.> |
| Datos persistentes/migración | Sí/No | <compatibilidad, copia de seguridad, reversión, etc.> |
| Efectos externos/coste | Sí/No | <entorno sandbox/pruebas/autorización> |
| Compatibilidad/API | Sí/No | <contrato a conservar o versionar> |
| UX/accesibilidad | Sí/No | <evidencia manual o automatizada> |
## Criterios de Aceptación
### AC-001: <comportamiento observable>
- **Escenario:** <condición inicial>
- **Acción:** <desencadenante único>
- **Esperado:** <resultado observable>
- **No debe:** <efecto secundario prohibido, si aplica>
- **Verificación:** <método y evidencia prevista>
- **Entorno/seguridad:** <restricciones, si aplica>
- **Prioridad:** Obligatorio | Importante | Opcional
## Decisiones Bloqueantes
- [ ] <solo decisiones que impidan un progreso seguro o correcto>
## Plan de Verificación
| Criterio | Evidencia de verificación | Estado |
| --- | --- | --- |
| AC-001 | <comando de prueba/comprobación/revisión o tipo de evidencia> | Pendiente |
Ejemplos de aprobado/suspenso
Usar estos para juzgar si la habilidad produjo realmente un informe verificable, no prosa de planificación.
Un criterio de aceptación suspenso
AC-001: La exportación funciona correctamente y es segura.
Suspenso — "funciona correctamente" y "segura" no son observables, no hay escenario, desencadenante, esperado...