Escrevendo um Blueprint

Um Blueprint é um arquivo markdown que define uma unidade por completo. Aqui está o processo inteiro, na ordem que de fato funciona.

1. Leia o Framework, não a sua memória

   Do _eidos/Framework.md, pegue três coisas: o Schema, a convenção de nomes e os flavors da coleção de destino.

   Isso importa mesmo que você tenha escrito o Framework, porque ele se desvia. Importa mais para um agente, que nunca deve presumir o nome de uma coleção ou seção: o padrão faz uma skill ler o Framework a partir da raiz, nunca de uma cópia própria.

2. Escolha um flavor

   O padrão da coleção, a menos que você tenha um motivo. Comece leve: micro na semente software, sketch em book, note em research.

   Depois leia o arquivo de shape daquele flavor para o corpo. Um Blueprint num flavor mais leve nunca é cobrado pelas seções que só um mais completo carrega. Mais →

3. Nomeie o arquivo

   Pelo título dele, na convenção do Framework: kebab-case a menos que o seu Framework diga outra coisa.

   Convenção	Um arquivo de Blueprint	Uma pasta de grupo	Para
   kebab-case (padrão)	resume-playback.md	playback/	legível em todo lugar: sem escapes, sem %20, e o nome do arquivo é o id
   TitleCase	ResumePlayback.md	Playback/	sem espaços, com maiúsculas
   Title Case	Resume Playback.md	Playback/	uma árvore que se lê como prosa, ao custo de %20 em cada link

   Uma chave naming ausente significa kebab-case.

   Seja qual for a que você escolheu: _eidos/ é sempre minúsculo, README.md mantém o nome que toda ferramenta já procura, o id é sempre kebab-case, o valor de uma propriedade de agrupamento coincide exatamente com a pasta dela, e campos feitos para ferramentas nunca são nomes na árvore.

4. Gere o frontmatter

   A partir das propriedades que se aplicam àquela coleção, não de todas as do Schema. Uma propriedade exclusiva de specs nunca aterrissa em um 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]
   ---

   Deixe em branco em vez de adivinhar

   Uma propriedade não preenchida é uma lacuna visível. Uma plausivelmente errada é uma mentira bem formatada. Este é o hábito mais importante quando um agente está ajudando: ele vai inferir um status com prazer se você deixar.

   Escreva summary como uma linha simples: o que este Blueprint é. É a fonte da listagem do index.md da coleção, tal e qual. Um Blueprint sem ela é sinalizado pelo índice, nunca inventado para você.

5. Escreva o corpo nesta ordem

   Não de cima para baixo. Nesta ordem:

   1. A seção de abertura: ## Intent na semente software. Por que isto existe, o problema, e quem o tem. Um ou dois parágrafos.
   2. A seção de não-objetivos: ## Out of Scope. Sim, em segundo. Por quê →
   3. Perguntas em aberto: o que você ainda não sabe. Escrevê-las cedo é quase todo o valor de escrever o Blueprint cedo.
   4. Todo o resto: comportamentos, dependências, testes, decisões.

   Mantenha a ordem e os nomes do shape no arquivo; esta é apenas a ordem em que pensar.

6. Siga a rotulagem do shape

   Onde um shape pedir rótulos, use-os. Na semente software, cada critério de aceitação é AC1:, AC2:: em negrito, e único dentro do 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.

   Mantenha cada um curto e verificável. Empurre o detalhe rico para uma tabela ou uma subseção para a qual o critério aponte. Um critério que você não consegue verificar não é um critério; é uma esperança.

   Dica

   Os rótulos são a alça de que todo o resto se segura. Uma revisão de código diz “o AC4 não foi atendido”, um teste nomeia o critério que cobre, uma pergunta num PR aponta para uma linha. É por isso que eles são únicos dentro do Blueprint.

7. Omita o que não se aplica

   Deixe uma seção de fora em vez de deixá-la vazia. Um título vazio afirma que você considerou algo e não achou nada a dizer; um ausente é honesto sobre o que você pulou.

Nomes

Uma única convenção rege a raiz inteira, e mudá-la depois significa renomear arquivos, então ela é decidida no início. Tudo o que uma pessoa lê na árvore a segue: documentos de nível superior, coleções e subpastas, arquivos de Blueprint.

Cinco coisas valem seja qual for a que você escolheu:

• _eidos/ é sempre minúsculo.
• README.md mantém o nome, seja qual for a convenção: toda ferramenta já o procura.
• O id é sempre kebab-case.
• O valor de uma propriedade de agrupamento coincide exatamente com a pasta dela.
• Campos feitos para ferramentas não são nomes na árvore.

Links

Referencie outros Blueprints com links, não com nomes soltos, tanto na prosa quanto nas propriedades.

O texto é o título humano; o caminho é o nome de arquivo do destino na convenção do Framework. Só uma raiz em Title Case carrega %20, que é boa parte do motivo de kebab-case ser o padrão. Acrescente uma âncora #heading para uma seção.

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

Em YAML, coloque-os entre aspas: caso contrário, um [ inicial começa uma lista:

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

Nunca fabrique um link

Se o destino ainda não tem Blueprint, nomeie-o com clareza na prosa. Um link para um arquivo que não existe é pior do que link nenhum: ele parece resolvido.

Escreva como uma pessoa leria

Esta é a convenção que separa um Blueprint que vale a pena manter de uma pasta de formulários:

As seções são um andaime para um Blueprint vivo, não um formulário em que despejar texto. Se um Blueprint se lê como um modelo preenchido, remodele-o até que se leia como algo que alguém escreveu.

Dentro e abaixo das seções do shape, use o que deixar o sentido mais claro: subtítulos, tabelas, listas, pequenos diagramas. O shape restringe o esqueleto, não a prosa.

Um exemplo desenvolvido

Do exemplo Blueprint distribuído, um subconjunto do 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.

Releia a linha de Assumptions. “If it isn’t, the whole playback approach changes.” Essa frase é o Blueprint se pagando: ela nomeia a coisa que invalidaria o resto, para que a próxima pessoa saiba o que conferir.

A seguir

• Delimitando escopo com não-objetivos
• Trabalhando com agentes