Guías

Desarrollar una feature

Tienes una feature nueva por construir —una página, un módulo, un endpoint, un formulario— y quieres que el agente la implemente sin inventar requerimientos ni salirse del alcance. protocolo-features ordena el trabajo antes y durante el código; test-fix lo verifica al final.

Cuándo usarla

Feature nuevo: página, módulo, endpoint, formulario o flujo.
Cualquier implementación que agregue modelos, casos de uso o componentes nuevos.

No es para fixes de bugs, cambios cosméticos ni refactors sin comportamiento nuevo: eso es Cambiar algo que ya funciona. Si la implementación exige cambiar la arquitectura existente, tampoco: es un cambio, no una feature.

Antes de empezar

protocolo-features y test-fix vienen en la instalación por defecto. Si todavía no corriste init:

npx @falcux/ai-first@latest init

Necesitas además una spec implementable: qué hace la feature, criterios de aceptación verificables, qué incluye y qué no, y qué módulos usa y cuáles no debe tocar. Si el producto salió de Arrancar un producto, está en docs/specs/. Si no existe, la skill la genera y te pide validarla antes de implementar.

Paso a paso

Pide la pre-implementación, sin código. Son siete pasos obligatorios, y el último deja escrita la secuencia:

Usa protocolo-features para el módulo de reportes (docs/specs/reportes.md).
Haz sólo la pre-implementación: verifica la spec, arma la tabla de reuso,
revisa dependencias y deja escrita la secuencia. No escribas código todavía.

Revisa el plan. Lo que tiene que traer:
- La comprobación de Zonas Prohibidas: si la feature entra en una, se pide la aprobación o se replantea el enfoque antes de escribir código.
- La tabla de reuso, con una fila por pieza: reusa, extiende, nueva compartida o nueva local. Toda pieza «nueva local» justifica por qué no se pudo reusar. Sin esta tabla, el plan está incompleto.
- Las dependencias técnicas: migración, tipos compartidos, endpoints, claves de i18n.
- La secuencia: qué variante aplica —full-stack, solo-backend o solo-frontend—, qué pasos se omiten y qué comando verifica cada uno.
Si alguna fila de la tabla es difícil de revertir —un paquete compartido nuevo, un límite entre capas, una dependencia de producción—, va también como fila en docs/ADR.md.
Implementa por capas, de adentro hacia afuera. El orden por defecto va del schema al dominio, la aplicación, la infraestructura de backend, lo compartido y la interfaz, y después los tests. Si la entrevista de init fijó otra secuencia, está en la sección «Adaptación a tu proyecto» de la skill. La regla no cambia: no se avanza si el paso actual no compila o rompe tests.
```
Plan aprobado. Implementa el paso 2 de la secuencia, dominio, y nada más.
Cuando compile y los tests existentes pasen, muéstrame el diff y espera.
```
Todo texto visible nuevo pasa por ux-writer antes de escribirse.
Verifica con test-fix. Corre los tests del alcance que tocó la sesión, con la salida filtrada para que al contexto sólo lleguen las fallas:
```
Usa test-fix sobre lo que tocó esta sesión. Unitarios e integración;
E2E no por ahora.
```
Cada falla se clasifica. Las mecánicas —un mock viejo, un import movido, un campo renombrado— se corrigen sin preguntar. Las de negocio —el test espera A, el código da B y no está claro cuál es correcto— te las pregunta con opciones. Hay un máximo de dos rondas; si quedan fallas, reporta con diagnóstico y para. Con el alcance en verde, corre la suite completa, tipos y lint una sola vez.
Pasa los checklists. Técnico, de UX si hay interfaz, y de completitud. El que más se olvida: lo que estaba fuera de alcance no se implementó.
Cierra la sesión. Con protocolo-cierre, antes del commit. Ver Cerrar la sesión.

Los tests E2E se corren sólo si lo pides, nunca como consecuencia de la parte unitaria. Los tests que protegen una invariante de seguridad o de aislamiento no se ajustan: si fallan, es un incidente. Esos se listan en la adaptación de test-fix.

Qué queda escrito

El código y los tests de la feature, en el orden de la secuencia.
La spec, si no existía y hubo que generarla.
Una fila en docs/ADR.md por cada decisión difícil de revertir que salió del plan.
El inventario de componentes al día, en el mismo commit, si se tocó la librería de componentes.

protocolo-features no escribe el registro de sesión: eso lo hace protocolo-cierre.

Qué vigila el detector

Zona Prohibida tocada (P0). Si la feature tocó una zona declarada, el hook pre-push detiene el push. Por eso la skill la comprueba en el paso 1.
Decisión sin fila en ADR (P1). Un package.json que suma o quita una dependencia de producción, o un archivo de superficies_de_decision, sin una fila nueva en el ADR. Se evita escribiendo la fila; si no era decisión, con  en el cuerpo del commit.
Alcance excedido (P1). Por defecto alcance.spec apunta a docs/changes/pending/, y sin un cambio abierto el check se omite. Si apuntas alcance.spec a la spec del módulo, su sección «Archivos del módulo» define el alcance de la sesión.
Inventario de componentes (P2). Un componente nuevo en componentes_dir que el inventario no menciona, si AI-FIRST.md declara las dos claves.

El detalle está en Las cinco verificaciones.

Por qué funciona así

Sin spec, la AI inventa requerimientos; sin secuencia escrita, los pasos se saltan sobre la marcha. El inventario de reuso es el paso que más deuda evita y el que más se salta. El criterio completo está en el Protocolo de desarrollo de features.

Próximos pasos

Cerrar la sesiónEl registro de sesión, los docs y la versión, antes del commit.

Cambiar algo que ya funcionaCuando la feature toca lo que ya existe.

Las 11 skillsprotocolo-ux, ux-writer e i18n, que entran cuando hay interfaz.