Protocolo de desarrollo de features

Nota

Este protocolo también existe como skill ejecutable. El capítulo explica el criterio detrás de cada regla; el skill es el procedimiento que la AI carga y ejecuta sola cuando detecta la tarea.

Ya la tienes si corriste npx @falcux/ai-first@latest init: la instala por defecto en .agents/skills/. Cómo se usa en una sesión: Desarrollar una feature.

Ver protocolo-features/SKILL.md

Este documento define el proceso para implementar features nuevos con AI coding agents. No reemplaza la creatividad ni la velocidad — la estructura existe para que la AI produzca mejor resultado desde el primer intento.

Principio fundamental

La AI implementa mejor cuando sabe QUÉ construir, CÓMO debe verse, y QUÉ NO hacer. Invertir 15 minutos en contexto ahorra 2 horas de correcciones. La documentación previa no es overhead — es el prompt más importante que vas a escribir.

---

1. Entradas: cómo llega un feature

Un feature puede llegar de múltiples fuentes. El protocolo funciona con todas.

Fuente	Ejemplo	Qué hacer primero
Documento de requerimientos	Archivo .docx/.xlsx del cliente	Convertir a spec implementable (paso 2)
PRD existente	docs/PRD.md con el feature descrito	Verificar que la spec es suficiente (paso 2)
Definición del PO	Google Doc, ticket, conversación	Documentar como spec mínima (paso 2)
Idea propia / mejora	“Esto debería funcionar diferente”	Documentar como spec mínima (paso 2)
Feature generado por AI	PRD generado por LLM desde requerimientos	Validar con humano antes de implementar (paso 2)

Regla: Sin importar de dónde venga, todo feature pasa por el mismo protocolo antes de llegar a código. La fuente varía; el proceso no.

---

2. Pre-implementación: los 7 pasos antes de código

Paso 1 — Asegurar que existe una spec implementable

Verificar que tienes documentación suficiente para que la AI entienda qué construir.

Spec mínima viable (lo que necesitas como mínimo):

## Feature: [Nombre]

### Qué hace
[1-3 párrafos describiendo el comportamiento desde la perspectiva del usuario]

### Criterios de aceptación
- [ ] [El usuario puede hacer X]
- [ ] [El sistema responde con Y]
- [ ] [En caso de error, ocurre Z]

### Alcance
- Incluye: [qué sí]
- NO incluye: [qué no — esto es crítico para la AI]

### Dependencias
- [Módulos, endpoints, o componentes que ya existen y que este feature usa]
- [Módulos que este feature NO debe modificar]

Si la spec no existe: Usar la AI para generarla a partir de la fuente original (requerimiento del cliente, PRD, etc.), pero SIEMPRE validar con el PO o decisor antes de implementar. La AI es buena generando specs, pero puede inventar requerimientos que nadie pidió.

Si la spec fue generada por AI: Leerla completa. Verificar que no agregó features que no se pidieron. Confirmar con el PO si hay dudas.

Paso 2 — Inventario de reuso y lógica compartida

Es el paso que más deuda evita y el que más se salta. Se responde en las dos direcciones:

a) ¿Qué existe que se pueda reusar? Buscar por concepto de dominio —notificación, validación, scoring, exportación—, no por nombre de módulo. Un agente que busca «módulo de facturación» no encuentra la lógica de cálculo que vive en «pedidos».

b) ¿Lo que se va a construir le sirve a otro módulo? Si la lógica nueva tiene relación con otro módulo, actual o del backlog, se diseña compartida desde el inicio: servicio de dominio reutilizable, puerto común o paquete compartido. No enterrada dentro del módulo que la estrena.

Salida obligatoria del paso. Una tabla que va en el plan y se puede auditar:

Pieza	Decisión	Justificación
[lógica / componente]	Reusa X / Extiende X / Nueva compartida / Nueva local	[por qué]

Toda pieza marcada «Nueva local» justifica por qué no se pudo reusar ni conviene compartir. Sin esta tabla, el plan está incompleto.

Unificar después siempre cuesta más que diseñar compartido al inicio. La duplicación no duele el día que se escribe: duele el día que las dos copias divergen.

Si alguna fila de esa tabla es una decisión difícil de revertir —un paquete compartido nuevo, un límite entre capas, una dependencia de producción que entra—, no basta con justificarla en el plan, que se archiva. Va como fila en el docs/ADR.md, con lo que se descartó. Ver Gobierno del contexto.

Paso 3 — Leer la documentación de diseño

Antes de que la AI escriba una línea de código:

• Leer docs/GUIA_DISENO.md — tokens, componentes, patrones de layout, dark mode
• Consultar la skill protocolo-ux — navegación por capas, interacciones estándar

Preguntas clave de diseño:

• ¿En qué capa de navegación vive este feature? (Browse, Create, Detail)
• ¿Usa componentes existentes o necesita nuevos?
• ¿Cómo se ve el estado vacío, loading, error?
• ¿Tiene vista mobile?

Si las respuestas no están claras, definirlas ANTES de implementar.

Paso 4 — Validar enfoque UX (recomendado)

Antes de construir, validar que el enfoque de UX es correcto. Dos opciones:

Opción A — Agente especializado (si la herramienta lo soporta): Lanzar un agente ux-ui-critic o equivalente con el prompt:

Revisa la spec del feature [nombre] y la guía de diseño del proyecto.
Evalúa:
1. ¿El flujo de usuario es coherente con los patrones de navegación existentes?
2. ¿Los componentes propuestos son consistentes con lo que ya existe?
3. ¿Hay edge cases de UX no contemplados? (empty state, error, mobile)
4. ¿La interacción propuesta sigue el protocolo UX del proyecto?

NO implementes nada. Solo dame tu evaluación y recomendaciones.

Opción B — Revisión mental (siempre disponible): Revisar la spec contra el checklist de verificación del protocolo UX. Si algún punto no se cumple, ajustar la spec antes de implementar.

Cuándo es obligatorio vs. recomendado:

• Feature con UI nueva (página, modal, formulario) → obligatorio
• Feature solo backend (endpoint, use case, migración) → omitir
• Fix de UI existente → obligatorio si cambia interacción, omitir si es cosmético

Paso 5 — Verificar dependencias técnicas

Antes de implementar, confirmar:

• ¿Se requiere migración de BD? → planificarla primero
• ¿Se necesitan schemas de validación nuevos? → crearlos en packages/shared
• ¿Hay endpoints que este feature necesita y no existen? → implementar backend primero
• ¿Hay claves de i18n que crear? → prepararlas en archivos de mensajes
• ¿Este feature afecta features existentes? → si sí, usar protocolo de cambios

Paso 6 — Preparar el contexto para la AI

Construir el prompt de implementación con contexto completo:

FEATURE: [Nombre del feature]

SPEC: [Referencia a la spec o resumen breve]

DOCUMENTACIÓN A CONSULTAR:
- docs/GUIA_DISENO.md — para tokens, componentes, patrones visuales
- skill protocolo-ux — para interacciones y navegación
- [Otros docs relevantes]

ARQUITECTURA:
- [Dónde vive este feature en la estructura del proyecto]
- [Qué módulos/componentes existentes debe usar]
- [Patrón de arquitectura a seguir — ej: Clean Architecture 3 capas]

RESTRICCIONES:
- NO modificar [archivos/módulos que no deben cambiar]
- NO implementar [funcionalidad fuera de alcance]
- Seguir los patrones de [navegación/interacción/diseño] existentes

IMPLEMENTA paso a paso. Después de cada paso, muéstrame qué hiciste
para que yo valide antes de continuar.

Paso 7 — Definir la secuencia de implementación

El orden importa. Implementar en esta secuencia:

1. Schema/Migración BD (si aplica)
    ↓
2. Domain (entities, ports, value objects)
    ↓
3. Application (use cases, DTOs)
    ↓
4. Infrastructure — Backend (repositories, controllers, servicios externos)
    ↓
5. Shared (schemas Zod, tipos, constantes)
    ↓
6. Infrastructure — Frontend (páginas, componentes, formularios)
    ↓
7. Tests (unit + E2E backend, componentes frontend)
    ↓
8. Verificación final (typecheck, lint, tests completos)

No todos los features necesitan todos los pasos. Un feature solo-frontend empieza en el paso 6. Un feature solo-backend termina en el paso 4. Pero el ORDEN dentro de los pasos aplicables es estricto.

---

3. Implementación: durante la sesión

3.1 Una sesión = un feature

Cada feature se implementa en una sesión limpia dedicada. Esto significa:

• Contexto fresco (no arrastrar contexto de otro feature)
• La spec del feature es el primer input
• El SESSION_LOG.md de la sesión anterior se leyó para tener contexto

3.2 Con equipos de agentes (si la herramienta lo soporta)

Para features que tocan backend + frontend + tests, los agentes especializados paralelizar el trabajo:

Agente	Scope	Pasos que ejecuta
Backend Agent	apps/api/ + packages/prisma + packages/shared	1-5
Frontend Agent	apps/web/ + packages/ui	6
Test Agent	apps/api/test/ + apps/web/**/.test.	7

Reglas de coordinación:

• Backend Agent completa primero (crea endpoints que Frontend consume)
• Frontend Agent trabaja después (usa los endpoints y schemas compartidos)
• Test Agent valida al final (verifica que todo funciona junto)
• Schemas compartidos (packages/shared) los crea Backend Agent
• Si hay conflicto en un archivo, el agente owner del scope tiene prioridad

Configuración (Claude Code):

# En .claude/settings.json o por sesión
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Sin equipos de agentes: Seguir la secuencia del paso 7 manualmente, validando después de cada paso antes de continuar.

3.3 Validación incremental

Después de CADA paso de la secuencia:

Implementar paso N
    ↓
¿Compila? (typecheck)
    ↓
¿Los tests existentes siguen pasando?
    ↓
¿El comportamiento es el esperado? (prueba manual rápida)
    ↓
Confirmar → siguiente paso

Si algo falla: Corregir ANTES de avanzar. No acumular errores.

3.4 Señales de que algo va mal

Detener la implementación y reevaluar si:

• La AI modifica archivos que no están en el scope del feature
• La implementación requiere cambiar la arquitectura existente (→ es un cambio, no un feature)
• Aparecen más de 3 archivos que no estaban en la spec
• Los tests existentes empiezan a fallar sin razón aparente

---

4. Post-implementación: verificación

4.1 Checklist técnico

# Ejecutar en orden
pnpm typecheck              # 0 errores de tipos
pnpm lint                   # 0 warnings/errores
pnpm test                   # todos los tests pasan (incluyendo los nuevos)

4.2 Checklist de UX (para features con interfaz)

Referencia: el checklist del protocolo UX, que la skill protocolo-ux ejecuta.

• ¿La navegación respeta las capas (Browse → Create → Detail)?
• ¿Las interacciones son consistentes con componentes existentes?
• ¿Los 4 estados están cubiertos? (loading, empty, error, success)
• ¿Funciona en mobile?
• ¿Dark mode funciona correctamente?
• ¿Los textos están en archivos de i18n, no hardcodeados?

4.3 Checklist de completitud

• ¿Todos los criterios de aceptación de la spec se cumplen?
• ¿Se crearon tests para el feature nuevo?
• ¿El feature NO rompe features existentes?
• ¿Lo que está fuera de alcance NO se implementó?

4.4 Cierre

Seguir el Protocolo de cierre de sesión, que ejecuta la skill protocolo-cierre:

• AI documenta en SESSION_LOG.md
• Humano verifica
• Commit de código + docs juntos

---

5. Casos especiales

Feature que resulta ser más grande de lo esperado

Si durante la implementación descubres que el feature requiere más de una sesión:

1. Parar la implementación en un punto estable (que lo hecho funcione por sí solo)
2. Hacer cierre de sesión con lo completado
3. Documentar en SESSION_LOG.md qué falta exactamente
4. La siguiente sesión retoma desde los pendientes

Regla: Nunca dejar código a medio implementar sin cierre. Si hay que dividir, cada parte debe ser funcional por separado.

Feature que requiere cambios en features existentes

Si el feature nuevo necesita modificar algo que ya funciona:

1. Separar: implementar la parte nueva primero (sin tocar lo existente)
2. Después: usar el Protocolo de gestión de cambios para las modificaciones
3. Nunca mezclar feature nuevo + cambios en existente en el mismo paso

Feature solo-backend (sin UI)

Simplificar: omitir pasos 2, 3 de pre-implementación y checklist de UX en post-implementación. El resto del protocolo aplica igual.

Feature solo-frontend (sin backend nuevo)

Simplificar: la secuencia de implementación empieza en el paso 6. Los pasos de pre-implementación aplican completos (especialmente diseño y UX).

---

6. Spec mínima viable — template

Para features que llegan sin documentación formal. Llenar este template ANTES de pedirle a la AI que implemente:

# Feature: [Nombre]

## Contexto
[¿Por qué se necesita este feature? ¿Qué problema resuelve?]

## Comportamiento esperado
[Describir desde la perspectiva del usuario — qué hace, qué ve, qué resultado obtiene]

## Criterios de aceptación
- [ ] [Criterio 1]
- [ ] [Criterio 2]
- [ ] [Criterio 3]

## Alcance
**Incluye:**
- [Lo que sí se implementa]

**NO incluye:**
- [Lo que queda fuera — ser explícito]

## Diseño
**Capa de navegación:** [Browse / Create / Detail]
**Componentes:** [Existentes que reutiliza / Nuevos que necesita]
**Estados:** [Loading / Empty / Error / Success — cómo se ve cada uno]

## Dependencias técnicas
- [ ] Migración de BD: [Sí/No — detalle]
- [ ] Endpoints necesarios: [Existentes / Nuevos]
- [ ] Schemas Zod: [Existentes / Nuevos]
- [ ] Claves i18n: [Nuevas que crear]

## Archivos que NO deben modificarse
- [Lista explícita de archivos/módulos fuera de scope]

---

7. Conexión con otros protocolos

                    ┌────────────────────────────────┐
                    │  ESTE PROTOCOLO                │
                    │  (Feature Development)         │
                    └──────┬──────────────┬──────────┘
                           │              │
              ┌────────────▼──┐    ┌──────▼──────────────┐
              │ UX Protocol   │    │ Change Management   │
              │ (Consistencia │    │ (Si el feature      │
              │  visual)      │    │  modifica algo      │
              │ Pre-impl: ✓   │    │  existente)         │
              └───────────────┘    └─────────────────────┘
                                          │
                              ┌───────────▼────────────┐
                              │ Session Closure        │
                              │ (Al terminar la sesión │
                              │  de implementación)    │
                              └────────────────────────┘

• UX Protocol se consulta en el paso 3 y 4 de pre-implementación
• Change Management se activa si el feature nuevo requiere modificar algo existente
• Session Closure se ejecuta al terminar la sesión de implementación

---

8. Cómo usar este protocolo

Como skill

Copiar la skill protocolo-features a .agents/skills/protocolo-features/. La AI la carga sola al detectar que se va a implementar un feature nuevo.

Como referencia en AGENTS.md

## Protocolo de Desarrollo de Features (OBLIGATORIO)
Antes de implementar cualquier feature nuevo, se activa la skill protocolo-features.
Incluye: spec → reuso → diseño → UX → implementar → verificar.

Para herramientas agnósticas

Los principios (documentar antes de codear, validar UX, implementar en secuencia, verificar post-implementación) aplican sin importar la herramienta.