Blueprints

Blueprints são artefatos de design visual e estrutural vinculados a especificações. Diagramas de arquitetura, máquinas de estado, fluxos de dados, 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 a um épico dá a cada worker naquele épico um modelo mental compartilhado do fluxo de interação. Um ERD vinculado ao épico de banco de dados garante que todo agente que cria uma migration ou query entenda os relacionamentos do schema.

Blueprints são opcionais. Uma spec pequena com 4 tickets não precisa de um. Uma spec com 50 tickets 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 10 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, fluxo de dados entre componentes, e onde o trabalho de cada épico 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.

Data Flow

Formato: Diagrama Mermaid Quando usar: Quando dados se transformam conforme se movem pelo sistema. Pipelines de processamento de requests, fluxos ETL, cadeias de propagação de eventos. Mostra o que entra, o que transforma, o que sai.

Use quando o caminho importa mais que a estrutura. Architecture mostra componentes. Data flow mostra o que acontece entre eles.

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.

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 ao épico pai do ticket. 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.

💡 Vincule blueprints a épicos, não a tickets individuais. Todo ticket no épico herda o contexto do blueprint. Isso é mais eficiente que vincular o mesmo diagrama a 5 tickets separadamente, e garante que todos os workers no mesmo épico compartilhem o mesmo contexto visual.

Cobertura de Blueprint

O Planning Review opcionalmente verifica a cobertura de blueprints — uma proporção mínima de blueprints para épicos. O padrão é 1:2 (um blueprint para cada dois é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.

Você pode desabilitar a verificação de cobertura de blueprint na configuração de Padrões de Qualidade do seu projeto:

specforge configure planningConfig.requireBlueprintCoverage false

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 — As unidades que herdam contexto de blueprint