Blueprints

Blueprints são artefatos de design visual e estrutural vinculados a especificações. Diagramas de arquitetura, máquinas de estado, diagramas de sequência, contratos de API, ADRs — qualquer coisa que ajude agentes a entender a intenção além do que descrições de tickets conseguem transmitir.

O Que É um Blueprint?

Um blueprint captura decisões de design que não cabem em descrições de tickets. Quando um ticket diz “Construir o endpoint de login,” ele diz ao agente o que construir. Um blueprint mostrando o fluxo de request de autenticação diz ao agente como as peças se conectam — onde o request entra, o que valida, onde tokens são gerados, como erros propagam.

Agentes leem blueprints durante a implementação. Um diagrama de sequência vinculado aos tickets que implementam uma interação dá a cada worker neles um modelo mental compartilhado do fluxo. Um ERD com cobertura de spec inteira garante que todo agente que cria uma migration ou query entenda os relacionamentos do schema.

Blueprints são opcionais. Uma spec pequena de 4 tickets não precisa de um. Uma spec de 50 tickets distribuídos em 8 épicos precisa de vários — a complexidade exige contexto visual compartilhado que texto sozinho não consegue fornecer.

Tipos de Blueprint

O SpecForge suporta 14 tipos de blueprint. Cada um serve a um propósito diferente e mapeia para um estágio diferente do pensamento de design.

Architecture

Formato: Diagrama Mermaid Quando usar: Quando a spec envolve múltiplos serviços, módulos ou camadas que interagem. O blueprint de arquitetura mostra fronteiras, o movimento dos dados entre os componentes, e onde cada parte do trabalho se encaixa no sistema.

Use quando o agente precisa saber onde seu código vive no cenário maior. Se sua spec toca tanto o API gateway quanto o serviço de auth, um diagrama de arquitetura previne o agente de construir a lógica de auth na camada errada.

Flowchart

Formato: Diagrama Mermaid Quando usar: Quando um processo tem ramificações, decisões e resultados. Fluxos de onboarding, pipelines de validação, caminhos de processamento de requests, árvores de decisão — qualquer coisa onde o caminho se bifurca com base em condições.

Use quando o agente precisa implementar lógica de ramificação corretamente. Um flowchart torna cada ponto de decisão e seus resultados explícitos, para que agentes não percam um caso de borda ou invertam uma condição.

State Machine

Formato: Diagrama Mermaid Quando usar: Quando uma entidade tem um ciclo de vida com estados e transições definidos. Contas de usuário (ativa, suspensa, deletada), pedidos (pendente, pago, enviado, entregue), especificações em si.

Use quando o agente precisa implementar lógica de transição. Um blueprint de state machine traduz diretamente para código — cada transição se torna um método, cada estado se torna uma verificação. Sem ele, agentes inventam sua própria lógica de estado, que raramente corresponde ao que você tinha em mente.

Sequence

Formato: Diagrama Mermaid Quando usar: Quando múltiplos atores interagem em uma ordem específica. Fluxos de chamada de API, handshakes de autenticação, processamento de webhooks, jornadas de usuário de múltiplos passos.

Use quando timing e ordem de interações importam. O diagrama de sequência mostra quem chama quem, em que ordem, e que respostas retornam. Isso é especialmente valioso para tickets que implementam lógica de middleware ou orquestração.

ERD (Diagrama de Entidade-Relacionamento)

Formato: Diagrama Mermaid Quando usar: Quando a spec envolve design de banco de dados. Tabelas, relacionamentos, cardinalidade, campos-chave. Qualquer spec que cria ou modifica modelos de dados se beneficia de um ERD.

Use quando múltiplos tickets criam ou modificam tabelas. Sem um ERD, o Agente A cria uma tabela users e o Agente B cria uma tabela sessions com uma suposição de foreign key ligeiramente diferente. O ERD é a única fonte de verdade para design de schema.

Mockup

Formato: Imagem ou descrição em texto Quando usar: Quando a spec tem componentes de UI. Wireframes, descrições de layout, hierarquias de componentes. Não precisa ser pixel-perfect — até uma descrição em texto como “header com logo à esquerda, nav à direita, seção hero abaixo” dá aos agentes a intenção de layout.

Use quando “construa um dashboard” não é específico o suficiente. Agentes interpretam descrições de UI com liberdade. Um mockup restringe a interpretação ao que você realmente quer.

ADR (Architecture Decision Record)

Formato: Markdown Quando usar: Quando uma decisão técnica não-óbvia foi tomada e agentes precisam entender por quê. “Escolhemos JWT ao invés de session cookies porque a API serve tanto clientes web quanto mobile.” “Usamos event sourcing para o sistema de pedidos porque precisamos de histórico completo de auditoria.”

Use quando a decisão pareceria errada sem contexto. Agentes otimizam para padrões comuns. Se sua spec deliberadamente desvia do padrão comum, um ADR previne o agente de “corrigir” sua decisão de volta ao padrão.

Component

Formato: Diagrama Mermaid Quando usar: Quando a spec envolve um sistema modular onde componentes têm interfaces claras. Arquiteturas de plugins, cadeias de middleware, registros de serviço.

Use quando agentes precisam entender o contrato de interface entre componentes. As entradas, saídas e responsabilidades de cada componente devem estar claras antes da implementação começar.

Deployment

Formato: Diagrama Mermaid Quando usar: Quando a spec inclui preocupações de infraestrutura ou deploy. Topologia de containers, layout de service mesh, estágios de pipeline CI/CD.

Use quando tickets envolvem infrastructure-as-code ou configuração de deploy. Sem ele, agentes fazem suposições sobre o ambiente de runtime que podem não corresponder ao seu setup real.

API Contract

Formato: Spec OpenAPI ou descrição em texto Quando usar: Quando a spec define APIs que outros sistemas (ou outros tickets) vão consumir. Formatos de request/response, formatos de erro, requisitos de autenticação, versionamento.

Use quando múltiplos tickets implementam lados diferentes da mesma API. O contrato garante que o ticket do endpoint e o ticket do cliente concordem na forma. Este é o tipo mais importante de blueprint para evitar bugs de integração.

Algorithm

Formato: Diagrama Mermaid ou pseudocódigo Quando usar: Quando um ticket implementa uma computação não-trivial — ranqueamento, agendamento, deduplicação, uma fórmula de scoring. O blueprint fixa os passos exatos, entradas e casos de borda.

Use quando a correção de uma computação importa mais que sua estrutura. Agentes deixados para inferir um algoritmo de uma descrição de uma linha frequentemente perdem um caso de borda ou reordenam passos de um jeito que muda o resultado.

Protocol

Formato: Diagrama Mermaid ou descrição em texto Quando usar: Quando componentes se comunicam por um protocolo definido — formatos de mensagem, handshakes, regras de retry e acknowledgement, garantias de ordenação. Comum para consumidores de fila, canais em tempo real e mensageria entre serviços.

Use quando o contrato de wire entre as partes precisa ser exato. Um blueprint de protocolo mantém o ticket produtor e o ticket consumidor concordando nos formatos de mensagem e no sequenciamento.

Glossary

Formato: Markdown Quando usar: Quando o domínio tem termos que agentes poderiam interpretar de forma inconsistente. Um glossário fixa o vocabulário — o que “account” versus “workspace” significa, o que é uma “session” — para que todo worker use os mesmos nomes.

Use quando a linguagem de domínio é ambígua e a consistência entre tickets importa. Sem ele, o Account de um agente é o Workspace de outro, e as junções de integração não se alinham.

Design System

Formato: Markdown ou imagem Quando usar: Quando o trabalho de UI precisa seguir tokens e componentes compartilhados — cores, espaçamento, tipografia, variantes de botão e formulário. O blueprint de design system mantém todo ticket de UI visualmente consistente.

Use quando múltiplos tickets constroem UI que precisa parecer um único produto. Ele dá a todo agente de UI os mesmos tokens para usar, ao invés de inventar um tom de azul ligeiramente diferente.

Como Blueprints Afetam a Implementação

Blueprints não são apenas documentação — são parte do contexto de implementação do agente.

Quando uma work session começa para um ticket, o agente recebe o contexto próprio do ticket (passos, critérios de aceite, expectativas de arquivo) mais quaisquer blueprints vinculados àquele ticket, mais os blueprints de spec inteira (coverageType: all). Isso significa:

• Um agente implementando uma migration de banco de dados vê o ERD
• Um agente construindo um endpoint vê o diagrama de sequência e o contrato de API
• Um agente escrevendo uma transição de estado vê a state machine

O agente usa estes como referência durante a implementação. Um diagrama de sequência não substitui passos do ticket — ele os complementa com o contexto visual que passos não conseguem transmitir.

💡 Dê a um blueprint cobertura de spec inteira (coverageType: all) quando todo ticket se beneficia — um diagrama de arquitetura ou ERD, por exemplo — ao invés de anexá-lo ticket por ticket. Quando um blueprint é relevante só para alguns poucos tickets, use link_blueprint_to_tickets para anexá-lo exatamente a esses. Blueprints pertencem à especificação; eles se anexam à spec inteira ou a tickets específicos — nada entre os dois.

Cobertura de Blueprint

O Planning Review opcionalmente verifica a cobertura de blueprints — uma proporção mínima de blueprints por número de épicos. O padrão é 1 blueprint a cada 2 épicos.

Por que isso existe? Porque a correlação entre presença de blueprints e qualidade de implementação é forte. Specs com blueprints produzem menos falhas de review, menos conflitos de dependência e menos casos onde agentes “interpretaram a intenção diferentemente.”

Cobertura não é sobre atingir um número. É sobre perguntar: “Cada épico tem contexto visual suficiente para agentes implementarem corretamente?” Épicos pequenos com 2-3 tickets diretos podem não precisar de um blueprint. Épicos grandes com preocupações transversais quase certamente precisam.

A cobertura de blueprint é uma verificação de cross-validation durante o planejamento, não uma chave do configure — você a ajusta na configuração de Padrões de Qualidade do seu projeto (painel).

Padrões Práticos

Comece com architecture + ERD. Esses dois cobrem a maior parte do terreno. Architecture mostra onde as coisas vivem. ERD mostra como os dados se parecem. Juntos, dão aos agentes 80% do contexto estrutural que precisam.

Adicione diagramas de sequência para épicos de integração. Qualquer épico onde múltiplos componentes interagem se beneficia de um diagrama de sequência. Fluxos de auth, processamento de pagamentos, handling de webhooks — são onde agentes mais frequentemente constroem peças que não se encaixam.

Use ADRs para decisões não-óbvias. Se você está escolhendo Drizzle ao invés de Prisma, ou event sourcing ao invés de CRUD, ou WebSockets ao invés de polling — escreva um ADR de um parágrafo. Agentes padronizam para a escolha popular. Se a sua é deliberadamente diferente, diga por quê.

Mockups para qualquer trabalho de UI. Mesmo os rascunhados. “Construa uma página de configurações” sem mockup produz resultados drasticamente diferentes entre agentes. “Construa uma página de configurações com navegação lateral, agrupada por categoria, switches toggle para opções booleanas” com um wireframe produz resultados consistentes.

Veja Também

• Especificações — O pai ao qual blueprints são vinculados
• Gates de Qualidade — Cobertura de blueprint como dimensão do planning review
• Épicos & Tickets — Tickets são a que um blueprint se anexa, diretamente ou por spec inteira