Escribir un Blueprint

Un Blueprint es un archivo markdown que define una unidad por completo. Aquí está el proceso entero, en el orden que de verdad funciona.

1. Lee el Framework, no tu memoria

   De _eidos/Framework.md, toma tres cosas: el Schema, la convención de nombres y los flavors de la colección destino.

   Esto importa aunque hayas escrito tú el Framework, porque se desvía. Importa más para un agente, que nunca debe dar por supuesto el nombre de una colección o una sección: el estándar hace que una skill lea el Framework desde la raíz, nunca desde una copia propia.

2. Elige un flavor

   El por defecto de la colección, salvo que tengas un motivo. Empieza ligero: micro en la semilla software, sketch en book, note en research.

   Luego lee el archivo de shape de ese flavor para el cuerpo. A un Blueprint en un flavor más ligero nunca se le reprochan las secciones que solo lleva uno más completo. Más →

3. Nombra el archivo

   Por su título, en la convención del Framework: kebab-case salvo que tu Framework diga otra cosa.

   Convención	Un archivo de Blueprint	Una carpeta de grupo	Para
   kebab-case (por defecto)	resume-playback.md	playback/	legible en todas partes: sin escapes, sin %20, y el nombre del archivo es el id
   TitleCase	ResumePlayback.md	Playback/	sin espacios, con mayúsculas
   Title Case	Resume Playback.md	Playback/	un árbol que se lee como prosa, a costa de %20 en cada enlace

   Una clave naming ausente significa kebab-case.

   Sea cual sea la que elegiste: _eidos/ siempre va en minúscula, README.md conserva el nombre que toda herramienta ya busca, el id siempre va en kebab-case, el valor de una propiedad de agrupación coincide exactamente con su carpeta, y los campos pensados para herramientas nunca son nombres en el árbol.

4. Genera el frontmatter

   A partir de las propiedades que aplican a esa colección, no de todas las del Schema. Una propiedad exclusiva de specs nunca aterriza en un frame.

   ---
   id: resume-playback          # kebab-case, permanent, never renamed
   title: Resume Playback
   summary: Returns a viewer to the exact second they stopped.
   type: feature
   domain: playback             # matches the sub-folder exactly
   status: Intake
   date_created: 2026-06-20
   date_modified: 2026-06-23
   depends_on:
     - "[Watch a Video](../playback/watch-a-video.md)"
   tags: [playback]
   ---

   Déjala en blanco antes que adivinar

   Una propiedad sin rellenar es un hueco visible. Una plausiblemente equivocada es una mentira bien formateada. Este es el hábito más importante cuando ayuda un agente: inferirá un status encantado si se lo permites.

   Escribe summary como una línea llana: qué es este Blueprint. Es la fuente del listado del index.md de la colección, tal cual. Un Blueprint sin ella lo señala el índice, nunca se inventa por ti.

5. Escribe el cuerpo en este orden

   No de arriba abajo. En este orden:

   1. La sección de apertura: ## Intent en la semilla software. Por qué existe esto, el problema, y quién lo tiene. Uno o dos párrafos.
   2. La sección de no-objetivos: ## Out of Scope. Sí, la segunda. Por qué →
   3. Preguntas abiertas: lo que aún no sabes. Escribirlas pronto es casi todo el valor de escribir el Blueprint pronto.
   4. Todo lo demás: comportamientos, dependencias, pruebas, decisiones.

   Mantén el orden y los nombres del shape en el archivo; esto es solo el orden en el que pensar.

6. Sigue el etiquetado del shape

   Donde un shape pida etiquetas, úsalas. En la semilla software, cada criterio de aceptación es AC1:, AC2:: en negrita, y único dentro del Blueprint.

   ## Behaviors & Acceptance Criteria
   
   ### Functional
   
   - **AC1:** A viewer opens a video and the player loads with its title,
     channel, and controls.
   - **AC2:** The viewer can play, pause, and seek anywhere within the video.
   
   ### Performance
   
   - **AC5:** Playback starts within a couple of seconds on a normal connection.

   Mantén cada uno corto y comprobable. Empuja el detalle rico a una tabla o una subsección a la que apunte el criterio. Un criterio que no puedes verificar no es un criterio; es una esperanza.

   Consejo

   Las etiquetas son el asa de la que agarra todo lo demás. Una revisión de código dice «AC4 no se cumple», una prueba nombra el criterio que cubre, una pregunta en un PR apunta a una línea. Por eso son únicas dentro del Blueprint.

7. Omite lo que no aplica

   Deja una sección fuera antes que dejarla vacía. Un encabezado vacío afirma que consideraste algo y no encontraste nada que decir; uno ausente es honesto sobre lo que te saltaste.

Nombres

Una sola convención gobierna toda la raíz, y cambiarla después significa renombrar archivos, así que se zanja al empezar. Todo lo que una persona lee en el árbol la sigue: documentos de nivel superior, colecciones y subcarpetas, archivos de Blueprint.

Cinco cosas se mantienen sea cual sea la que elegiste:

• _eidos/ va siempre en minúscula.
• README.md conserva su nombre, sea cual sea la convención: toda herramienta ya lo busca.
• El id va siempre en kebab-case.
• El valor de una propiedad de agrupación coincide exactamente con su carpeta.
• Los campos pensados para herramientas no son nombres en el árbol.

Enlaces

Referencia otros Blueprints con enlaces, no con nombres sueltos, tanto en la prosa como en las propiedades.

El texto es el título humano; la ruta es el nombre de archivo del destino en la convención del Framework. Solo una raíz en Title Case lleva %20, que es buena parte de por qué kebab-case es el valor por defecto. Añade un ancla #heading para una sección.

See [Resume Playback](resume-playback.md#intent) for the saved-position rules.

En YAML, entrecomíllalos: si no, un [ inicial empieza una lista:

depends_on:
  - "[Watch a Video](../playback/watch-a-video.md)"

Nunca fabriques un enlace

Si el destino todavía no tiene Blueprint, nómbralo llanamente en la prosa. Un enlace a un archivo que no existe es peor que ningún enlace: parece resuelto.

Escríbelo como lo leería una persona

Esta es la convención que separa un Blueprint que vale la pena conservar de una carpeta de formularios:

Las secciones son un andamio para un Blueprint vivo, no un formulario en el que verter texto. Si un Blueprint se lee como una plantilla rellenada, remodélalo hasta que se lea como algo que escribió alguien.

Dentro y debajo de las secciones del shape, usa lo que aclare el sentido: subencabezados, tablas, listas, diagramas pequeños. El shape restringe el esqueleto, no la prosa.

Un ejemplo desarrollado

Del ejemplo Blueprint distribuido, un subconjunto de YouTube:

Blueprints/specs/playback/watch-a-video.md

---
id: watch-a-video
title: Watch a Video
summary: play a video reliably, signed in or not, adapting to the connection.
type: feature
domain: playback
status: Intake
depends_on: [video-catalog, cdn-delivery]
---

# Watch a Video

## Intent

A view is the core action of the whole product. If a video is slow to start
or stalls, the viewer leaves — so what "playing a video" means, and what a
viewer can count on, is the first thing to pin down.

### Assumptions

Assuming adaptive-bitrate delivery over the CDN is available and affordable
at launch scale — if it isn't, the whole playback approach changes.

## Open Questions

- How long should a signed playback URL stay valid before it has to refresh?
- Does a view count on play start, or only after a watch-time threshold?

## Behaviors & Acceptance Criteria

### Functional

- **AC1:** A viewer opens a video and the player loads with its title,
  channel, and controls.
- **AC3:** A signed-out viewer who opens a shared link can still watch.

### Quality attributes

- **AC7:** A stalled segment recovers by dropping quality rather than
  stopping playback.

## Out of Scope

- No comments, ratings, or next-up recommendations on the watch page.

Vuelve a leer la línea de Assumptions. «If it isn’t, the whole playback approach changes.» Esa frase es el Blueprint ganándose su sitio: nombra la cosa que invalidaría el resto, para que la siguiente persona sepa qué comprobar.

Siguiente

• Acotar con no-objetivos
• Trabajar con agentes