Skip to main content
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. 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 6 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):
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 — 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
  • Leer docs/UX_PATTERNS_PROTOCOL.md — 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 3 — 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:
Opción B — Revisión mental (siempre disponible): Revisar la spec contra el checklist del UX_PATTERNS_PROTOCOL.md (sección 5). 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 4 — 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 5 — Preparar el contexto para la AI

Construir el prompt de implementación con contexto completo:

Paso 6 — Definir la secuencia de implementación

El orden importa. Implementar en esta secuencia:
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: 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):
Sin equipos de agentes: Seguir la secuencia del paso 6 manualmente, validando después de cada paso antes de continuar.

3.3 Validación incremental

Después de CADA paso de la secuencia:
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

4.2 Checklist de UX (para features con interfaz)

Referencia: UX_PATTERNS_PROTOCOL.md, sección 5.
  • ¿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 (SESSION_CLOSURE_PROTOCOL.md):
  • 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:

7. Conexión con otros protocolos

  • UX Protocol se consulta en el paso 2 y 3 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 de Claude Code

Copiar a .claude/skills/feature-development/SKILL.md. Claude lo cargará al detectar que se va a implementar un feature nuevo.

Como referencia en AGENTS.md

Para herramientas agnósticas

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