Shapes e flavors

Um shape é um modelo de corpo

Um shape (o modelo do corpo) são as seções que um Blueprint carrega: em ordem, sob nomes fixos, cada uma com a sua orientação. Ele nunca descreve o frontmatter: isso é gerado a partir do Schema.

Um arquivo por shape, em _eidos/shapes/, com o nome <kind>.<flavor>.md, em minúsculas e com pontos.

• Directory_eidos/shapes/

  • spec.full.md a coleção specs, flavor full
  • spec.micro.md a coleção specs, flavor micro
  • frame.architecture.md a coleção de enquadramento, um arquivo por tipo de frame
  • frame.audience.md

Flavors

Os shapes de uma coleção são variantes de uma mesma família, e cada variante é um flavor (a variante). Uma coleção declara um ou mais e marca um como padrão.

O que flexiona é quais seções aparecem e qual flavor um Blueprint usa, nunca a ordem ou os nomes delas dentro de um flavor.

Aqui está a mesma coleção em dois flavors, da semente software:

spec.micro	spec.full
## Intent	## Intent
### Assumptions	### Assumptions
—	### Implementation Notes
## Open Questions	## Open Questions
## Behaviors & Acceptance Criteria	## Behaviors & Acceptance Criteria
—	### Functional · ### Performance · ### Design · ### External interface · ### Quality attributes
## Out of Scope	## Out of Scope
—	## Dependencies
—	## Testing
—	## Constraints & Decisions

micro é a menor spec que vale a pena escrever: por que ela existe, o que você está ganhando e o que ela não vai fazer. É um ponto de partida que cresce até full conforme a unidade se firma.

Repare no que micro mantém mesmo no seu tamanho mínimo: Intent, Open Questions, Acceptance Criteria e Out of Scope. Essas quatro são o que uma spec é. Testing e Dependencies podem esperar; escopo não.

Declarar qual flavor um Blueprint usa

Um Blueprint que não está no flavor padrão registra isso no frontmatter:

flavor: micro

Ausente significa o flavor padrão da coleção. O padrão também é o que é gerado ao criar o arquivo.

Um flavor mais leve não é um Blueprint pior

Um Blueprint num flavor mais leve nunca é cobrado pelas seções que só um mais completo carrega. A validação confere um Blueprint contra o flavor que ele nomeia, não contra o mais completo disponível.

Fazer um Blueprint crescer

O caminho pretendido, e a razão de os flavors existirem:

1. Escreva-o como micro cedo, quando há mais pergunta do que resposta.
2. Acrescente as seções do flavor mais completo conforme elas ganham o seu lugar: dependências reais, uma história real de testes, uma decisão de fato tomada.
3. Defina flavor: full (ou remova a propriedade) assim que ele tiver crescido até lá.

Não gere o shape completo e o deixe vazio

Uma spec full com cinco títulos vazios é pior do que uma spec micro completa, porque dá a entender que você considerou coisas que não considerou. Ela deve se ler como algo que alguém escreveu.

Duas convenções que sustentam os shapes

Uma família de shapes por coleção

O shape nunca é bifurcado por categoria. Se metade das suas specs precisa de seções diferentes, isso ou é um flavor ou é outra coleção, não um segundo shape contrabandeado para dentro da mesma. É isso que mantém uma coleção legível como conjunto.

Um shape documenta as suas próprias convenções

Os nomes das seções, a ordem e o significado delas, e qualquer rotulagem que o shape peça vivem no arquivo do shape. O padrão rege coleções, shapes, flavors e propriedades; ele nunca rege uma seção.

Essa segunda regra é a razão de você não encontrar ## Intent nem ## Out of Scope em lugar nenhum do EIDOS.md. Essas são palavras da semente software. book abre um capítulo de outro jeito; research abre uma investigação de outro jeito ainda. A máquina é idêntica.

Com o que se parece um arquivo de shape

_eidos/shapes/spec.micro.md

<!--
The Spec shape — micro flavor. The smallest spec worth writing: why it exists,
what you're getting, and what it will not do. Grows into spec.full.md.
Keep the order and headings; the italic prompts are guidance — delete them
as you fill each section in.
-->

# {{title}}

## Intent

_Why this exists — the problem and who has it. This is the stable part: if
Intent changes substantially, you probably have a different spec._

### Assumptions

_What you're taking as given, not yet confirmed._

## Open Questions

_What you don't yet know and still need answered. Kept high, right after
Intent, so uncertainty is seen rather than buried._

## Behaviors & Acceptance Criteria

_What it does, as observable outcomes. If a behavior isn't listed here, it
isn't promised. Label each **AC1:**, **AC2:**, … Keep each short and checkable._

- **AC1:** <!-- the first observable outcome -->

## Out of Scope

_Explicit non-goals — the section the standard leans on hardest. It's the
first thing to write, not the last._

Três coisas para reparar, porque são convenções que vale a pena copiar para os seus próprios shapes:

• O comentário HTML no topo diz para que serve o flavor e no que ele cresce. É orientação para quem abrir o arquivo em seguida.
• {{title}} é o único marcador; todo o resto é estrutura real.
• Os avisos em itálico são instruções para apagar conforme você preenche cada seção. Eles não são conteúdo.

Escrever dentro de um shape

Mantenha a ordem e os nomes do shape. Além disso, escreva como uma pessoa leria: subtítulos, tabelas, listas e pequenos diagramas onde deixarem o sentido mais claro.

Onde um shape pedir rotulagem (AC1:, AC2: …), siga: mantenha cada afirmação verificável curta e observável, e empurre o detalhe de apoio para uma tabela ou subseção para a qual ela aponte.

Deixe de fora, não deixe vazio

Omita uma seção que genuinamente não se aplica. Um título vazio afirma que você pensou sobre algo e não achou nada; um ausente é honesto.

Documentos de nível superior não têm shape

Um documento de nível superior (um Roadmap, uma Visão, o canvas gerado) é único: preenchido uma vez e editado no lugar. Ele não recebe shape, nem flavors, nem validação.

Um shape se paga sendo estampado de novo. Um documento escrito uma única vez não precisa de fôrma.

Essa é também a única diferença entre um frame e um documento de nível superior. Os dois são prosa solta, revisada no lugar. Mas um frame é um Blueprint de coleção: ele segue um shape, carrega o contrato de frontmatter e é validado. Mais sobre os frames →

A seguir

• Schema
• Dando forma ao seu Framework: acrescentar um flavor.