← Volver al listado de tecnologías ← Índice de Impeccable

El contexto de diseño: init, PRODUCT.md y DESIGN.md

Por: Artiko
impeccableinitproduct-mddesign-mdcontexto

El contexto de diseño: init, PRODUCT.md y DESIGN.md

En el capítulo anterior dejamos Impeccable instalado y disponible como skill dentro del agente de coding. Tenemos los comandos /impeccable a mano, pero todavía les falta algo fundamental: saber qué estamos construyendo y para quién. Un agente que no conoce tu audiencia, tu voz de marca ni tu sistema visual solo puede producir diseño genérico, ese “AI slop” que Impeccable existe precisamente para evitar.

Aquí es donde entra /impeccable init. Es el comando que arranca el proyecto generando la documentación estratégica y visual que todos los demás comandos van a leer antes de actuar. Sin este contexto, comandos como polish, audit o craft trabajan a ciegas; con él, cada decisión de diseño queda anclada a una intención compartida. En este capítulo desmenuzamos el flujo de init, los dos archivos que produce (PRODUCT.md y DESIGN.md), la entrevista que conduce para construirlos y las buenas prácticas para mantenerlos vivos en el tiempo.

Por qué el contexto importa

La idea central de Impeccable es que el diseño de calidad no nace de instrucciones sueltas en cada prompt, sino de un contexto persistente que viaja con el proyecto. Si cada vez que pides “mejora este componente” tuvieras que reexplicar a quién sirve el producto, qué tono usa la marca y qué paleta emplea, dos cosas malas ocurrirían: gastarías tokens repitiéndote y, peor aún, el agente improvisaría decisiones distintas cada vez. El resultado sería un producto incoherente.

init resuelve esto materializando ese contexto en archivos versionables dentro del repositorio. A partir de ese momento, cualquier comando posterior carga PRODUCT.md y DESIGN.md como primer paso, igual que un diseñador humano consultaría el manual de marca antes de tocar un pixel.

flowchart LR
    Init["/impeccable init"] --> P["PRODUCT.md<br/>(qué/quién/por qué)"]
    Init --> D["DESIGN.md<br/>(cómo se ve)"]
    P --> Ctx[(Contexto<br/>persistente)]
    D --> Ctx
    Ctx --> Craft["/impeccable craft"]
    Ctx --> Audit["/impeccable audit"]
    Ctx --> Polish["/impeccable polish"]
    Ctx --> Critique["/impeccable critique"]

La clave del diagrama: el contexto se genera una vez y se consume muchas. Por eso vale la pena invertir tiempo en una buena sesión de init.

Los dos archivos que genera init

init produce dos documentos con responsabilidades bien separadas, más un archivo de configuración de runtime para el modo live.

PRODUCT.md: la capa estratégica

PRODUCT.md responde a las preguntas quién / qué / por qué. Se ubica en la raíz del proyecto, en .agents/context/ o en docs/, según la convención que prefieras. Su contenido cubre:

DESIGN.md: la capa visual

DESIGN.md responde a cómo se ve. Vive en la raíz del proyecto y sigue la especificación oficial de design.md (el formato abierto publicado por Google Labs Code). Documenta el sistema visual concreto:

La separación es deliberada: PRODUCT.md casi nunca cambia (es la estrategia), mientras DESIGN.md puede evolucionar conforme madura el sistema visual. Mantenerlos en archivos distintos evita que un ajuste de paleta toque accidentalmente la definición de audiencia.

.impeccable/live/config.json: configuración de runtime

Cuando el proyecto ya tiene código con entradas HTML y un servidor de desarrollo, init también escribe .impeccable/live/config.json. Este archivo deja preconfigurado el modo variant para que /impeccable live arranque sin pasar por una configuración de primera vez. Volveremos sobre live en su capítulo dedicado.

El flujo de la entrevista

init no te bombardea con un formulario gigante. Conduce una entrevista estructurada por pasos, descubriendo por sí mismo todo lo que pueda inferir del código antes de preguntarte. Este es el flujo completo.

sequenceDiagram
    participant U as Tú
    participant I as /impeccable init
    participant FS as Repositorio

    I->>FS: Step 1 - Cargar estado actual
    Note over I,FS: ¿Existen ya PRODUCT.md / DESIGN.md?<br/>No sobrescribe en silencio
    I->>FS: Step 2 - Explorar el código
    Note over I,FS: README, package.json, componentes,<br/>tokens CSS, assets de marca
    I-->>U: Step 3 - Preguntas estratégicas (2-3 por ronda)
    U-->>I: Respuestas
    I-->>U: Propone PRODUCT.md
    U-->>I: Confirma
    I->>FS: Step 4 - Escribe PRODUCT.md
    I-->>U: Step 5 - ¿Generamos DESIGN.md?
    U-->>I: Sí
    I->>FS: Delega en /impeccable document
    I->>FS: Step 6 - Configura .impeccable/live (si aplica)

Step 1: cargar el estado actual

Antes que nada, init revisa qué existe ya en el proyecto y decide si conviene un init completo o saltarse pasos. Un detalle importante de seguridad: no sobrescribe archivos existentes en silencio. Si ya tienes un PRODUCT.md, te lo dirá en lugar de pisarlo.

Step 2: explorar el código

init escanea README, package.json, componentes, assets de marca, tokens CSS y guías de estilo. Con esa evidencia forma una “register hypothesis”: deduce si está ante una marca o un producto, basándose en patrones como landing pages, dashboards o flujos de autenticación. Cuantas más pistas encuentre, menos preguntas tendrá que hacerte.

Step 3: las preguntas estratégicas

Aquí ocurre la entrevista. init cubre, en rondas de 2 a 3 preguntas cada una, esperando tus respuestas antes de seguir:

La regla del flujo es clara: hacer al menos una ronda completa antes de proponer PRODUCT.md, y saltarse las preguntas cuya respuesta sea descubrible desde el código. Esto evita que te pregunte cosas que ya están en tu package.json.

Step 4: escribir PRODUCT.md

Solo después de tu confirmación, init escribe el archivo con la estructura que vimos arriba. Nunca lo persiste sin tu visto bueno.

Step 5: la decisión de DESIGN.md

Si ya hay código, init ofrece:

“I can generate a DESIGN.md that captures your visual system (colors, typography, components) so variants stay on-brand. Want to do that now?”

Si el proyecto está en fase pre-implementación (sin código visual aún), propone un DESIGN.md inicial sembrado a partir de cinco preguntas rápidas sobre color, tipografía, movimiento y referencias. En cualquiera de los dos casos, si aceptas, delega la generación en /impeccable document, el comando especializado en documentar el sistema visual existente.

Step 6: configuración de live mode

Cuando existe código con entradas HTML y servidor de desarrollo, init escribe .impeccable/live/config.json con ajustes específicos del framework (qué archivos tocar, insertBefore, commentSyntax). Además ejecuta una detección de CSP:

node .claude/skills/impeccable/scripts/detect-csp.mjs

Solo pide tu consentimiento para parches en archivos fuente y marca cspChecked: true una vez resuelto. En proyectos vacíos, este paso se omite por completo.

Reanudación de tareas

Un detalle útil: si init se disparó como prerrequisito de otro comando (por ejemplo, ejecutaste /impeccable polish sin tener PRODUCT.md), al terminar el init retoma automáticamente la tarea original. No tienes que volver a lanzar el comando que querías originalmente.

Cómo invocar init

El comando es directo. Dentro del agente, escribes:

/impeccable init

No requiere argumentos: él mismo explora y pregunta. A partir de su finalización, los siguientes pasos recomendados dependen de tu register y de lo que encontró al explorar:

# Trabajo nuevo
/impeccable craft <feature>
/impeccable shape <feature>

# Mejorar lo existente
/impeccable critique <page>
/impeccable audit <area>
/impeccable polish <component>

# Iteración visual en vivo
/impeccable live

Ejemplo realista de PRODUCT.md

Supongamos un SaaS de facturación para freelancers. Tras la entrevista, un PRODUCT.md podría quedar así:

# PRODUCT.md

Register: product

## Users
Freelancers y pequeños estudios (1-5 personas) que facturan a
clientes recurrentes. Su job-to-be-done: emitir y cobrar facturas
sin perder tiempo en administración ni en aprender software contable.

## Product Purpose
Reducir el tiempo entre "trabajo entregado" y "dinero cobrado".
Cada pantalla debe acercar al usuario a enviar la siguiente factura.

## Brand Personality
Tres palabras: preciso, sereno, profesional.
Referencias: Stripe Dashboard (claridad de datos densos),
Linear (jerarquía visual y velocidad percibida).

## Anti-references
- NO parecer software contable de los 2000 (tablas grises, menús
  anidados infinitos).
- NO el tono lúdico/startup con ilustraciones de personajes y
  confeti en cada acción.
- NO la estética "plantilla genérica de admin" (Bootstrap default).

## Design Principles
1. Los datos primero: números legibles, alineación a la derecha.
2. Acción primaria siempre visible y única por pantalla.
3. Estados de carga y vacío diseñados, nunca improvisados.

## Accessibility & Inclusion
- Objetivo WCAG 2.2 AA.
- Paleta verificada contra deuteranopía y protanopía.
- Respetar prefers-reduced-motion en todas las transiciones.

Fíjate cómo las anti-referencias hacen tanto trabajo como las referencias: le dicen al agente qué territorios evitar, lo que reduce drásticamente el riesgo de diseño genérico.

Ejemplo realista de DESIGN.md

Para ese mismo producto, un DESIGN.md (siguiendo la spec de design.md) podría verse así:

# DESIGN.md

## Visual Theme
Interfaz densa en datos, fondo claro por defecto con modo oscuro
real (no invertido). Sensación de instrumento de precisión.

## Color Palette
- Background:  #FBFBFA
- Surface:     #FFFFFF
- Ink:         #1A1D21
- Muted:       #6B7280
- Brand:       #1F6F54   (verde "cobrado", único acento)
- Positive:    #1F6F54
- Negative:    #B42318
- Border:      #E7E5E4

## Typography
- Family: "Geist" para UI y headings (una sola familia).
- Escala modular ratio 1.25: 12 / 14 / 16 / 20 / 25 / 31 px.
- Tabular numbers activados en montos y tablas.
- Line-height body: 1.5; headings: 1.2.

## Components
- Button: una variante primaria sólida, una secundaria outline.
  Radio 6px, altura 36px, focus-ring visible de 2px.
- Card: borde 1px + sombra mínima, padding 24px.
- Table: filas de 44px, hover de fila, columnas de monto a la derecha.
- Loading: skeleton, nunca spinner centrado.
- Empty state: ilustración mínima + acción primaria.

## Layout
- Grid de 12 columnas, gutter 24px, max-width 1200px.
- Espaciado fluido con clamp() entre secciones.
- Transiciones 150-250 ms.

Este archivo le da al agente todo lo que necesita para que cualquier componente nuevo nazca alineado con el sistema, en vez de inventarse colores y tamaños sobre la marcha.

Editar y versionar el contexto

Ambos archivos son Markdown plano y viven en el repositorio, así que se versionan como cualquier otro código. Algunas buenas prácticas:

Definir un buen “lane” y buenas anti-referencias

El lane (el carril de marca/producto) es la franja en la que tu diseño debe moverse. Definirlo bien es lo que separa un contexto útil de uno decorativo:

Resumen

/impeccable init es el comando fundacional: con una sola entrevista genera el contexto de diseño persistente que todos los demás comandos consultan antes de actuar. Produce PRODUCT.md (la capa estratégica: register, users, propósito, personalidad de marca, anti-referencias, principios y accesibilidad) y DESIGN.md (la capa visual: tema, paleta, tipografía, componentes y layout), además de configurar el modo live cuando hay código. El flujo es disciplinado: carga el estado actual sin sobrescribir, explora el código para inferir lo descubrible, entrevista en rondas de 2-3 preguntas y solo escribe tras tu confirmación. Mantener estos archivos editados, versionados y con un lane bien definido —apoyado en referencias y anti-referencias concretas— es la inversión que vuelve consistente todo el trabajo posterior.

Con el contexto en su sitio, el siguiente paso es entender la pieza determinista que no depende del agente: el detector de reglas.

Siguiente: El detector: 44 reglas deterministas

← Volver al listado de tecnologías ← Índice de Impeccable