Lee .codex/docs/codex-runtime.md antes de usar este flujo de trabajo. Sigue la autorización del usuario actual y los permisos del host.
Argumentos: [ruta-al-doc-diseño] [--revisión completa|ágil|solo]
Antes de continuar, ejecuta este comando de configuración desde la raíz del proyecto:
bash ".codex/hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides
Resuelve usando el comando anterior — úsalo tal cual; --revisión anula review_mode. --profundidad es el nombre anterior a la v1.1 para el mismo indicador: trata --profundidad <modo> exactamente como --revisión <modo>, y di una vez que fue renombrado. Si se dan ambos, --revisión gana y --profundidad se ignora — dilo. Sin bloque → valores predeterminados en .codex/docs/config-resolution.md.
Revisión de Diseño
Fase 0: Analizar Argumentos
Consulta .codex/docs/director-gates.md para el patrón de verificación completo. Las definiciones de puertas individuales están en .codex/docs/director-gates/[gate-id].md — el agente generado lee su propio archivo de puerta; no lo leas en la sesión principal.
Cada llamada a request_user_input sigue .codex/docs/automation-modes.md
(colaborativo siempre pregunta · guiado solo-mayor · autónomo registra y procede;
las categorías automation_always_ask siempre preguntan).
workflow para el GDD bajo revisión — usa la fila system_overrides para <sistema> si el bloque enumera una, de lo contrario el valor del proyecto. El alcance de la validación sigue el nivel:
completa— las 8 secciones validadas; cualquier sección faltante bloquea la aprobación.estándar— las 5 secciones requeridas (Resumen, Reglas Detalladas, Casos Límite, Dependencias, Criterios de Aceptación) bloquean si faltan; Fórmulas bloquea solo cuando el sistema define reglas numéricas (tasas, curvas, umbrales, costos — la categoría es una pista, no la prueba); Fantasía del Jugador y Perillas de Ajuste son de asesoramiento (advierte, nunca bloquea) a menos queworkflow_overrideslo requieran.mínima— no se espera un GDD; si existe uno, valida las 5 secciones estándar de forma asesora.
El modo resuelto controla qué tan exhaustiva es esta revisión:
completa: Revisión completa — todas las fases + delegación de agente especialista (Fase 3b)ágil: Todas las fases, sin agentes especialistas — análisis más rápido en una sola sesiónsolo: Fases 1-4 solamente, sin delegación, sin aviso de siguiente paso en la Fase 5 — úsalo cuando se llame desde otra habilidad
Fase 1: Cargar Documentos
Primero verifica la frescura — una re-revisión de un documento sin cambios cuesta el precio completo y reproduce el mismo veredicto. Ejecuta:
Bash: bash .codex/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".agents/skills/design-review/SKILL.md"
El registro está en la verificación porque esta revisión lo consulta para
hechos entre documentos — un GDD sin cambios revisado contra un registro cambiado
puede llegar a conclusiones diferentes, por lo que la omisión solo es segura cuando
cada línea dice SIN CAMBIOS (un registro que nunca existió no aparece
en la salida y no bloquea la omisión). El archivo de esta habilidad está incluido
porque una habilidad cambiada revisa de manera diferente. La verificación también compara cada
archivo adicional que el registro marca — los GDD relacionados, el concepto o resumen y archivos narrativos
que las revisiones anteriores leyeron — e imprime DESAPARECIDO: para uno que ya no existe.
Luego lee la línea Modo de revisión: de la entrada más reciente. Esa revisión cubre esta
solo cuando su modo es igual o más profundo que el modo resuelto ahora
(completa > ágil > solo) y su flujo de trabajo es igual o más profundo (completa >
estándar > mínima). Una entrada sin la línea fue escrita antes de que existiera
y no cubre nada.
- Todo
SIN CAMBIOSy la entrada más reciente del registro tiene un veredicto — preséntalo: "Este documento es idéntico byte por byte a su última revisión del [fecha] ([modo] revisión, veredicto: [veredicto])." Si ese veredicto fue APROBADO y esa revisión cubre esta ejecución, ofrece medianterequest_user_input:[A] Usar el veredicto anterior (Recomendado)/[B] Re-revisar de todos modos—guiadoprocede con [A] y lo anota;autónomoregistra mediantelog_decisiony usa el veredicto anterior. Si fue APROBADO pero la revisión solicitada ahora es más profunda que la registrada, dilo — "Esa fue una revisión [modo] en el flujo de trabajo [nivel]; esta ejecución solicita [modo] en [nivel]." — y ofrece[A] Re-revisar en [modo] (Recomendado)/[B] Usar el veredicto [modo] anterior;guiadoyautónomore-revisan (autónomolo registra mediantelog_decision). Si fue NECESITA REVISIÓN o NECESITA REVISIÓN MAYOR, dilo claramente: el documento no ha cambiado desde que falló la revisión — los hallazgos anteriores se mantienen; revisar el documento es el siguiente paso, no re-revisarlo. Ofrece mostrar los hallazgos anteriores del registro. - El documento objetivo y el archivo de esta habilidad
SIN CAMBIOS, y solo el registro u otro archivo de hechos entre documentos estáCAMBIADO,NUEVOoDESAPARECIDO— el veredicto anterior se mantiene excepto por los hechos entre documentos: vuelve a verificar los valores del documento contra los archivos cambiados y vuelve a emitir el veredicto; escala a una re-revisión completa si aparece un conflicto o esa revisión no cubre esta ejecución. - Documento objetivo o archivo de esta habilidad
CAMBIADOoNUEVO, oRECIBO: NINGUNO— procede con la revisión completa a continuación. No ofrezcas una re-revisión parcial/delta que omita leer o reanalizar secciones sin cambios. Una re-revisión por secciones omite defectos que una revisión completa encuentra, y ahorra poco o nada. "Sin cambios desde la última revisión" solo significa idéntico byte por byte a lo que se revisó entonces — no dice nada sobre si esa revisión anterior fue en sí misma completa, y la atención se reduce al cambio marcado incluso bajo una instrucción de escanear todo de todos modos.
Lee el documento de diseño objetivo en su totalidad. Este paso necesita el GDD completo: léelo en rangos por sus encabezados (encontrados con la herramienta Grep: patrón ^#, modo contenido), ya que una lectura de archivo completo de más de 40 KB es rechazada. Lee AGENTS.md para entender el contexto y los estándares del proyecto.
Para hechos entre documentos, prefiere el registro sobre los GDD hermanos. Si
design/registry/entities.yaml existe y lista entradas para este sistema,
usa grep — estos son los hechos establecidos que este GDD no debe contradecir, y reemplazan
la lectura de GDD hermanos para redescubrirlos:
Grep pattern="source: design/gdd/[sistema].md" path="design/registry/entities.yaml" output_mode="content" -A 6
Grep pattern="design/gdd/[sistema].md" path="design/registry/entities.yaml" output_mode="content" -B 8
El primero encuentra entradas que este sistema posee — el contexto -A 6 incluye su
bloque referenced_by:. El segundo encuentra entradas que referencian este sistema —
referenced_by: es una secuencia de bloque (la clave y sus rutas están en líneas
separadas), así que coincide la ruta con el contexto -B 8 para ver la entrada propietaria, no un
referenced_by.*name de una línea (que nunca coincide con la forma de bloque).
Si design/registry/entities.yaml no existe, o no lista entrada para este sistema —
el archivo se entrega como un stub vacío, así que este es el valor predeterminado hasta
que $design-system lo haya poblado — recurre a leer los GDD relacionados que el documento
objetivo nombra en su sección de Dependencias. Limita la lectura a esos, no a todo lo "implicado".
No leas con glob todo design/gdd/.
Validación del gráfico de dependencias: Para cada sistema listado en la sección de Dependencias, usa Globo para verificar si su archivo GDD existe en design/gdd/. Marca aquellos que aún no existan — estas son referencias rotas que los autores posteriores encontrarán.
Alineación de lore/narrativa: Si design/gdd/game-concept.md (o, en rigor: mínimo, el resumen de una página design/game-brief.md) o cualquier archivo en design/narrative/ existe, léelo. Nota cualquier elección mecánica en este GDD que contradiga las reglas del mundo, el tono o los pilares de diseño establecidos. Pasa este contexto a game-designer en la Fase 3b.
Verificación de revisión anterior: Verifica si design/gdd/reviews/[doc-name]-review-log.md existe. Si existe, lee la entrada más reciente — nota qué veredicto se dio y qué elementos bloqueantes se enumeraron. Esta sesión es una re-revisión; rastrea si los elementos anteriores fueron abordados.
Fase 2: Verificación de Completitud
Paso 2a — recopilar presencia de secciones de manera determinista (sin lectura del documento):
Bash: bash .codex/scripts/gdd-structure-check.sh [target-doc-path]
Imprime una lista PRESENTE: y, cuando corresponda, una lista AUSENTE: y una lista
MARCA POSICIÓN: (secciones presentes que contienen solo [Por diseñar]: aún no escritas, así que
trátalas como faltantes para la lista de verificación). Reporta solo presencia
y no hace juicios de REQUERIDO/ASESORAMIENTO — ese es el trabajo del Paso 2b.
Ya acepta ## Diseño Detallado como satisfaciendo el requisito de Reglas Detalladas,
así que no lo marques como faltante.
Paso 2b — aplicar el nivel. Usando las listas del Paso 2a, evalúa contra la lista de verificación del Estándar de Documento de Diseño a continuación. Marca cada sección como REQUERIDA o ASESORAMIENTO según el nivel de flujo de trabajo resuelto (Fase 0). Una sección REQUERIDA faltante bloquea la aprobación; una sección ASESORAMIENTO faltante se presenta como una recomendación pero no bloquea.
Una sección reportada como PRESENTE aún puede fallar la revisión si es un encabezado vacío — lee al azar cualquier sección de la que dependa el veredicto.
- Tiene sección de Resumen (resumen de un párrafo) — REQUERIDA en todos los niveles
- Tiene sección de Fantasía del Jugador (sensación prevista) — REQUERIDA en
completa; ASESORAMIENTO enestándar - Tiene sección de Reglas Detalladas (mecánicas inequívocas) — REQUERIDA en
completa/estándar. La plantilla del GDD titula esta sección## Diseño Detallado(contiene subencabezados de Reglas Centrales / Estados / Interacciones); acepta cualquier encabezado como satisfaciendo este requisito — no marques "Reglas Detalladas" como faltante cuando una sección## Diseño Detalladoestá presente. - Tiene sección de Fórmulas (todas las matemáticas definidas con variables) — REQUERIDA en
completa; enestándarREQUERIDA siempre que el sistema defina reglas numéricas (tasas, curvas, umbrales, costos, daño, pesos de botín), de lo contrario ASESORAMIENTO. LaCategoríadel sistema es una pista, no la prueba — no despejes esto solo con un token de categoría - Tiene sección de Casos Límite (situaciones inusuales manejadas) — REQUERIDA en
completa/estándar - Tiene sección de Dependencias (otros sistemas listados) — REQUERIDA en
completa/estándar - Tiene sección de Perillas de Ajuste (valores configurables identificados) — REQUERIDA en
completa; ASESORAMIENTO enestándara menos queworkflow_overrides.tuning_knobs - Tiene sección de Criterios de Aceptación (condiciones de éxito comprobables) — REQUERIDA en
completa/estándar
Fase 3: Coherencia e Implementabilidad
Coherencia interna:
- ¿Las fórmulas producen valores que coinciden con el comportamiento descrito?
- ¿Los casos límite contradicen las reglas principales?
- ¿Las dependencias son bidireccionales (el otro sistema sabe de este)?
Implementabilidad:
- ¿Son las reglas lo suficientemente precisas para que un programador las implemente sin adivinar?
- ¿Hay secciones "ambiguas" donde faltan detalles?
- ¿Se consideran las implicaciones de rendimiento?
- ¿Es cada criterio de aceptación comprobable de forma independiente? Marca cada uno que no
lo sea, citándolo — "se siente equilibrado", "funciona correctamente", "funciona bien" no son
criterios — con una reescritura medible. En modo
completaqa-leadtambién los verifica (Fase 3b); enágilysolono se ejecutan especialistas, así que esta verificación de la revisión principal es la única.
Coherencia entre sistemas:
- ¿Esto entra en conflicto con alguna mecánica existente?
- ¿Esto crea interacciones no previstas con otros sistemas?
- ¿Es esto coherente con el tono y los pilares establecidos del juego?
Valores del registro, dondequiera que el GDD los indique. Un valor reformulado en una tabla,
una entrada de catálogo o una nota de variante contradice el registro tan seguramente como uno en
Reglas Detalladas, y leer por secciones hace que esos cuerpos sean fáciles de ojear. Enumera los nombres
de entrada del registro (grep -E '^ - name:' design/registry/entities.yaml),
luego busca en todo el documento objetivo una vez por todos ellos más las claves numéricas
que llevan, sin distinción entre mayúsculas y minúsculas, escribiendo cada _ como [_ ] para que goblin_scout
también coincida con "Goblin scouts":
grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]
Verifica cada línea que imprime contra el registro, sin importar en qué sección se encuentre. Una línea que da a una entrada un valor diferente, incluso para una sala, variante, nivel o excepción, contradice el GDD propietario: enumérala bajo Requerido Antes de la Implementación con su número de línea, el valor de este documento y el del registro. Sin entradas de registro, ejecuta la misma búsqueda para las entidades y valores que los GDD relacionados definen.
Fase 3b: Revisión Especialista Adversaria (solo modo completo)
Omite esta fase en modo ágil o solo.
Esta fase es OBLIGATORIA en modo completo. No la omitas.
Antes de generar cualquier agente, imprime este aviso:
"Revisión completa: generando agentes especialistas en paralelo. Esto suele tomar de 8 a 15 minutos. Usa
--revisión ágilpara un análisis más rápido en una sola sesión."
Paso 1 — Identificar todos los dominios que toca el GDD
Usando el GDD ya cargado en la Fase 1 — no lo vuelvas a leer — identifica cada dominio presente. Un GDD puede tocar múltiples dominios simultáneamente — sé exhaustivo. Señales comunes:
| Si el GDD contiene... | Genera estos agentes |
|---|---|
| Costos, precios, botines, recompensas, economía | economy-designer |
| Estadísticas de combate, daño, salud, DPS | game-designer, systems-designer |
| Comportamiento de IA, pathfinding, targeting | ai-programmer |
| Diseño de niveles, generación, estructura de oleadas | level-designer |
| Progresión del jugador, XP, desbloqueos | economy-designer, game-designer |
| UI, HUD, menús, pantallas para el jugador | ux-designer, ui-programmer |
| Diálogos, misiones, historia, lore | narrative-director |
| Animación, sensación, sincronización, dinamismo | gameplay-programmer |
| Multijugador, sincronización, replicación | network-programmer |
| Señales de audio, disparadores musicales | audio-director |
| Rendimiento, llamadas de dibujo, memoria | performance-analyst |
| Patrones o APIs específicos del motor | Especialista del motor principal (<engine>-specialist de engine.name — Godot→godot-specialist, Unity→unity-specialist, Unreal→unreal-specialist; recurre a la línea Primaria de ## Especialistas del Motor en |
...
[truncado para la traducción]