Los artefactos de esta fase

Cada fase de la metodología Problem-Driven AI produce artefactos específicos. No son opcionales. Son la evidencia de que el trabajo se hizo con rigor y el sistema operativo que impulsa todo lo que viene después. A diferencia de fases anteriores, en Context Phase los artefactos son producidos tanto por humanos como por Agentes de IA, y cada uno tiene productores y consumidores definidos dentro de la cadena.

Artefacto	Formato	Construye
project-context.md	Archivo Markdown, 2-5 páginas. Raíz del proyecto	Context Engineer (inicial), Architect Agent (actualizaciones)
Definiciones de Agentes	Un documento Markdown por Agente o único documento con secciones separadas	Context Engineer
PRD	Documento estructurado (Markdown, Google Docs)	PM Agent a partir del Solution Brief
Architecture Document	Documento con ADRs (Architecture Decision Records)	Architect Agent. Decisiones promovidas a project-context.md
Story Files (Skills)	Un archivo Markdown por Skill, cinco elementos obligatorios	SM Agent
Decision Log	Log cronológico (Markdown, hoja de cálculo)	Todos los participantes. Continuo desde el primer documento

Secuencia de creación

Los artefactos se crean en una secuencia estricta. Cada uno depende del anterior:

Solution Brief (de la Fase 2)
    │
    ▼
1. project-context.md ──────────────────────────┐
    │                                            │
    ▼                                            │
2. Definiciones de Agentes                       │
    │                                            │ (El Architect actualiza
    ▼                                            │  con nuevas Reglas)
3. PRD ──────────────────────────────────────────│
    │                                            │
    ▼                                            │
4. Architecture Document ───────────────────────-┘
    │
    ▼
5. Story Files (Skills)

6. Decision Log (continuo, desde el paso 1)

El project-context.md se crea primero y se actualiza conforme el Architect Agent toma decisiones técnicas. El Decision Log corre de forma continua, registrando cada cambio desde el momento en que se crea el primer artefacto.

1. project-context.md (Reglas)

La constitución del proyecto. Contiene todas las Reglas que aplican globalmente: stack tecnológico, convenciones de código, restricciones de seguridad, reglas de integración, límites de Agentes, protocolo ante gaps y decisiones globales justificadas.

• Formato: Documento Markdown con secciones claramente separadas y niveles de precisión explícitos para cada Regla.
• Construye: Context Engineer (versión inicial). Architect Agent (actualizaciones cuando las decisiones técnicas generan nuevas Reglas).
• Consume: Todos los Agentes, antes de cada Skill.
• Tamaño: Típicamente 2-5 páginas. Si supera 10 páginas, probablemente estás sobre-especificando (decisiones de Nivel 1-2 que deberían delegarse).
• Validación: La regla de las tres lecturas: un Agente que lea solo este documento puede responder: ¿Qué tecnologías uso? ¿Qué no puedo hacer? ¿Cuál es la convención para cualquier patrón recurrente?
• Ubicación: La raíz del proyecto, accesible para todos los Agentes.

Consulta la página de Anatomía para la estructura completa y la plantilla.

2. Definiciones de Agentes

Fichas de identidad para cada rol de IA en el proyecto. Cada definición incluye cinco elementos obligatorios: identidad, responsabilidades, límites, referencia a Reglas y protocolo ante gaps.

• Formato: Un documento por Agente, o un único documento con secciones claramente separadas por Agente.
• Construye: Context Engineer.
• Consume: Context Engineer (diseño), IA (ejecución).
• Cadena estándar: Analyst Agent, PM Agent, Architect Agent, SM Agent, QA Agent. Agentes adicionales según necesidad (Dev Agent, Design Agent, Data Agent).
• Validación: Cada Agente tiene límites explícitos. Si la sección "Límites" está vacía, la definición está incompleta.

3. PRD (Product Requirements Document)

Qué construir, para quién y con qué prioridad. Producido por el PM Agent a partir del Solution Brief.

• Formato: Documento estructurado con visión, casos de uso, criterios de éxito, restricciones, asunciones activas y prioridades.
• Construye: PM Agent a partir del Solution Brief.
• Consume: Architect Agent, SM Agent, QA Agent.
• Trazabilidad: Cada sección debe trazarse al Problem Statement o al Solution Brief. Si una sección no se puede trazar, es invención o un gap.

4. Architecture Document

Decisiones técnicas que traducen el PRD en guía de implementación. Producido por el Architect Agent.

• Formato: ADRs (Architecture Decision Records), modelo de datos, estrategia de IA, requisitos no funcionales.
• Construye: Architect Agent.
• Consume: SM Agent, Dev Agent, QA Agent.
• Función crítica: Las decisiones de arquitectura se convierten en nuevas Reglas. El Architect Agent es el único Agente que actualiza el project-context.md.
• Trazabilidad: Cada decisión técnica traza a un requisito del PRD. Cada promoción a Regla traza a un ADR.

5. Story Files (Skills)

Tareas autocontenidas que los Agentes de desarrollo ejecutan. Producidos por el SM Agent a partir del PRD y el Architecture Document.

• Formato: Un archivo por Skill con cinco elementos: objetivo, contexto específico, criterios de aceptación, dependencias y restricciones.
• Construye: SM Agent.
• Consume: Dev Agent. Un Skill por interacción.
• Test de autocontención: Un Agente que lea el Skill y el project-context.md puede completar la tarea sin preguntar nada.
• Tipos: Atómico (una tarea), Compuesto (sub-tareas coordinadas), De integración (conecta outputs de otros Skills).
• Cantidad: Depende de la complejidad del proyecto. Típicamente 10-20 para proyectos pequeños, 20-50 para medianos, 50+ para complejos.

6. Decision Log

Un registro continuo de cada cambio a Reglas, Agentes o Skills desde su creación.

• Formato: Log cronológico con fecha, qué cambió, por qué, quién lo autorizó y qué artefactos se vieron afectados.
• Construye: Todos los participantes. Continuo desde el primer documento.
• Consume: Context Engineer, QA Agent, todos.
• Propósito: Trazabilidad. Cuando surge una pregunta sobre "¿por qué existe esta Regla?" o "¿por qué se cambió este Skill?", la respuesta está en el log.
• Entradas clave: Adiciones de Reglas, modificaciones de Reglas, cambios en límites de Agentes, actualizaciones de contexto de Skills, resoluciones de gaps, cambios en restricciones.

La cadena de trazabilidad

La cadena de trazabilidad completa es: Problem Statement → Solution Brief → PRD → Reglas + Skills. Si un Skill no puede trazarse hasta el Problem Statement, es invención. Si una Regla no puede trazarse a una decisión de arquitectura, es una asunción. El Decision Log es el registro que hace verificable esta trazabilidad.

Qué viaja a la Fase 4

Cuando se pasa el Gate Review, los seis artefactos viajan juntos a la Fase 4 (AI Build Phase):

Qué viaja	Qué contiene	Cómo lo usa la Fase 4
project-context.md	Stack tecnológico, convenciones, restricciones, límites de Agentes, protocolo ante gaps, decisiones justificadas.	Cada Agente de desarrollo lo carga antes de ejecutar cualquier Skill. Es la restricción base.
Definiciones de Agentes	Identidad, responsabilidades, límites, Reglas, protocolo ante gaps para cada Agente.	Cada Agente sabe su rol, sus fronteras y qué hacer cuando la información es insuficiente.
PRD	Qué construir, para quién, casos de uso, prioridades, criterios de éxito.	Guía la secuencia y alcance de los Skills. El QA Agent usa los criterios de éxito para validación.
Architecture Document	Decisiones técnicas, ADRs, modelo de datos, estrategia de IA, requisitos no funcionales.	Los Agentes de desarrollo aplican las decisiones de arquitectura. Las decisiones del Architect Agent son Reglas.
Story Files (Skills)	Tareas autocontenidas con objetivo, contexto, criterios, dependencias, restricciones.	Cada Skill es una interacción. El Agente de desarrollo lo recibe, aplica Reglas, produce output.
Decision Log	Cada cambio a Reglas, Agentes o Skills desde su creación.	Trazabilidad. Si surge una pregunta sobre "¿por qué esta Regla?", la respuesta está en el log.