design-doc

O que design-doc faz?

gemini-4-argon escreve e revisa toda a prosa, incluindo resumos, gêmeos simples, identificadores, notas de revisão e texto de publicação. A sessão fornece os fatos e as regras (o contrato de escrita, as regras antissujeira, os limites de tamanho) através de gemini -m gemini-4-argon --skip-trust -p, aplica a resposta literalmente, e coleta evidências e publica o resultado ela mesma. Os auxiliares de prosa chamam o mesmo modelo através de gemini --skip-trust -p, sem modelo de fallback.

Um design de arquitetura é uma pilha de decisões sobre uma pilha de suposições. Esta skill executa o design como uma conversa — o usuário decide tudo — e renderiza o resultado como um documento onde cada afirmação remonta a uma suposição, uma decisão e a rodada de perguntas que a produziu.

Um comando controla as partes mecânicas:

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <nome>   # cria um diretório ./<slug>/ novo para este documento de design
$TOOL scaffold --example        # ./tinyq/, um pequeno exemplo preenchido
$TOOL check <dir>               # verifica os registros, os gêmeos simples, o diagrama fonte e o deck de resumo; erros saem com código não-zero, --strict faz com que avisos que bloqueiam a publicação sejam erros também
$TOOL summary-text <dir>        # o deck como Markdown, uma seção ## por painel; a entrada para os portões
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # termos que a prosa usa e que faltam no glossário, como entradas candidatas
$TOOL build <dir>               # compila components/*.tsx em components.js; apenas para um documento com um diretório components/
$TOOL render-check <dir>        # renderiza cada bloco Mermaid no Chrome headless; falha em erro de análise ou exceção de página
$TOOL pdf <dir>                 # imprime o documento através da folha de estilo de impressão do template em <dir>/design-doc.pdf
$TOOL snapshot <dir> --note "…" --item "…" # carimba uma revisão contra a qual a visualização 'mudanças desde' é comparada; note é o título voltado ao leitor, cada --item é uma mudança
$TOOL links <dir> [--fetch] [--missing] # cada decisão e item em aberto com seus links de pull request e status; --fetch pergunta ao GitHub se cada link foi mesclado e relata divergências, --missing lista as entradas ainda sem link

Leia reference/method.md antes da Fase 1, reference/writing.md antes da Fase 5 e reference/publish.md antes da Fase 6 — o arquivo de método é o protocolo de rodada/registro, o arquivo de escrita é o contrato de voz, o arquivo de publicação é o fluxo de hospedagem. reference/schema.md é o contrato campo por campo para os arquivos JSON; use o exemplo tinyq quando quiser um registro preenchido junto com o esquema.

Terminologia

• Registro — uma lista estruturada em registers.json cujas entradas têm IDs estáveis: A# suposições, DQ# decisões, Q# perguntas em aberto, V# spikes, c-<slug> cartões de arquitetura.
• Rodada — um quadro apresentado ao usuário, registrado literalmente em qa-log.json. Uma rodada pergunta sobre todos os forks em aberto de uma vez, cada um como um bloco design-doc.fork, e não pergunta mais nada. Respostas que abrem novos forks iniciam a próxima rodada, novamente todos de uma vez; qa-log.json registra as rodadas em ordem, para que um quadro posterior possa depender de uma resposta anterior.
• Supersessão — uma decisão alterada ganha uma nova entrada e a antiga recebe s: "superseded" mais um ponteiro by, que o documento renderiza como "Substituído por" e o título do sucessor. O histórico permanece legível porque nada é editado no lugar.
• Estrela (★) — marca a suposição crítica, aquela cuja falha invalida o documento.
• Spike — um experimento nomeado e com prazo (V#) que transforma uma estimativa marcada como (E) em um número medido.
• Resumo executivo — summary.html, um fragmento HTML escrito à mão ao lado de registers.json, para o leitor que não lê mais nada: um deck de painéis em tela cheia por padrão, um pôster quando o design é uma ideia e uma figura. Nunca analisado como dados; check verifica sua forma, seus orçamentos de palavras e suas citações.
• Gêmeo simples — o campo p ao lado da redação precisa de uma entrada, uma ou duas frases curtas dizendo o que a entrada significa para alguém que não vai lê-la. O documento mostra os gêmeos por padrão e a redação exata a um clique de distância.
• Chave e tema — key: true marca as 3–8 decisões e suposições que o documento abre como cartões; theme arquiva cada entrada sob um dos 3–5 temas do design, nomeados na Fase 0 e definidos no mapa themes.
• Diagrama — a fonte Mermaid do diagrama do sistema, na chave de registro diagram; o documento o renderiza, o leitor pode navegar e passar o mouse, e os caminhos de requisição percorrem-no. diagram.overview é o subconjunto de dez nós que o cartão Visão Geral desenha, com o gráfico completo a um clique de distância. Um sysd.svg desenhado à mão permanece válido como diagram.kind: "svg".
• Identificador — o campo h em cada decisão, suposição, item em aberto, cartão de arquitetura e tabela de números: como um leitor o chamaria, de duas a cinco palavras. As citações e linhas de chips mostram o identificador; o ID vive no cartão de hover.
• Componente — uma figura interativa declarada no mapa components (dd.tabs, dd.before-after, dd.whatif, dd.steps, dd.timeline, dd.matrix, as duas figuras de painel de comparação dd.flow e dd.lanes, o mapa do sistema desenhado à mão dd.system, e dd.arch, que incorpora um documento de arquitetura publicado) e colocada por id no deck ou em uma entrada; um arquivo TSX em components/ é a porta de escape que build compila.
• Brief da figura e crítica — as duas seções do NOTES.md das quais o deck é extraído e contra as quais é lido. Um brief tem cinco linhas por figura, escrito antes de a figura ser desenhada: o ponto que ela faz, a decisão que ela serve por ID, a menor visão que faz o ponto, o que ela omite e os rótulos reais que usa. Suas duas primeiras linhas se tornam o <figcaption>. A crítica é uma linha por painel, figura, tabela e estatística, escrita antes dos portões: a decisão que serve, a afirmação que faz, a pergunta que um leitor fica e corrigido ou cortado. check avisa quando algum desses cabeçalhos está faltando.
• Link — uma entrada de links[] em uma decisão, um item em aberto ou uma linha de descoberta: o pull request, issue, commit ou documento que a concretiza. closes: true em um link de um item em aberto marca aquele que o encerra. O documento mostra cada link como um chip com seu estado no GitHub e encabeça cada grupo em aberto com quantos de seus itens estão fechados.
• Status: decisões são resolved | superseded | open, que o documento renderiza como Decidido, Substituído e Ainda em aberto; suposições são working | validate, renderizadas como Assumido e Precisa de confirmação (alguém de fora do documento tem que dizer sim). Itens em aberto são open | closed, renderizados Ainda em aberto e Fechado; um link closes mesclado fecha um item antes de s dizê-lo. A prosa usa as palavras renderizadas, o JSON os valores.

Escopo

Esta skill para no design. Suas saídas são um registro de decisões e um documento; o código de implementação é uma tarefa diferente que começa depois que a proposta sobrevive à revisão. Quatro portões mantêm o registro honesto:

• Os forks de design são do usuário para decidir. Cada fork passa por uma rodada, mesmo quando uma opção parece obviamente correta: o registro do porquê vale mais do que o diálogo economizado.
• qa-log.json é literal e somente anexação. Corrija a ortografia nas respostas, não mude nada substancial e pule trocas apenas explicativas; é um registro de decisões, não uma transcrição.
• O artefato da revisão adversarial fica fora do documento renderizado. Apenas as decisões que ela gerou são enviadas; uma seção de descobertas soa como autoparabéns e não diz nada ao leitor.
• O documento não carrega contagens de vaidade ("27 entradas", "9 spikes pendentes"). Os números aparecem quando descrevem o sistema, não o esforço.

Fase 0 — Scaffold e diagnóstico

Execute $TOOL scaffold --title <nome>. Cada documento de design vive em seu próprio diretório novo — scaffold cria ./<slug>/ (passe um caminho explícito como argumento posicional para colocá-lo em outro lugar) e recusa um alvo não vazio, para que um design nunca se misture com arquivos de outro ou de um projeto existente. Entreviste o usuário sobre o sistema atual antes de propor qualquer coisa: o que existe, o que dói e por quê. Escreva o diagnóstico no NOTES.md como causas raiz, não sintomas ("a latência de durabilidade é a latência do S3", não "as gravações são lentas"). O diagnóstico nunca vai para um quadro: escreva-o diretamente no NOTES.md, o usuário o revisa no documento renderizado, e cada correção que fizer é incorporada de volta com suas próprias palavras. Feche o diagnóstico com a única classificação da qual o resumo executivo depende: uma mudança em um sistema que existe hoje, ou novo , sem nada atrás além de requisitos. Nomeie os três a cinco temas do design na mesma frase ("armazenamento", "distribuição", "locação"): eles se tornam o mapa themes sob o qual as decisões e suposições são arquivadas, e um tema que o diagnóstico não consegue nomear é um tema que o design não tem. Projetar contra um diagnóstico errado desperdiça todas as fases posteriores.

Critérios de saída: o diretório do projeto existe; o usuário leu o diagnóstico no documento renderizado, mudança ou novo e os temas incluídos, e concorda com ele.

Fase 1 — Suposições

Antes da primeira rodada, verifique a lista de habilidades disponíveis para cc-present:present (a habilidade de quadro /cc-present) e a invoque com a ferramenta Skill quando listada; a entrevista é executada como um quadro ao vivo desde a primeira pergunta, com AskUserQuestion apenas como fallback sem cc-present. Este plugin envia seu próprio pacote de blocos — execute cc-present pack list e leia o fragmento de referência do design-doc; seu bloco design-doc.fork é a superfície da entrevista, e o único bloco que um quadro de entrevista carrega.

Escreva as suposições diretamente em registers.json; nenhum quadro as confirma ou desafia. Nunca coloque um bloco design-doc.claims, uma varredura de confirmar/desafiar ou um despejo de registro na frente do usuário: eles revisam as suposições no documento renderizado, e uma correção que fizerem é incorporada de volta com suas próprias palavras. Uma suposição que o design não pode prosseguir sem escolher entre é um fork e vai para o quadro da Fase 2 como um bloco design-doc.fork. Colete verdades fundamentais da entrevista de diagnóstico, do código e do que o usuário já disse: restrições que o design deve satisfazer, fatos sobre escala e carga de trabalho, coisas que o usuário acredita mas não verificou. Cada uma se torna uma entrada A# com status working ou validate; estrela a crítica, e registre quem precisa confirmar cada entrada validate como um item em aberto. Quando o usuário sinalizar uma suposição como instável, essa sinalização vai para a entrada; resolvê-la em nome do usuário derrotaria o objetivo do registro.

Critérios de saída: o usuário revisou as suposições no documento renderizado e elas cobrem o que o usuário sabe; $TOOL check está limpo.

Fase 2 — Rodadas de design

Projete por rodadas de perguntas. A entrevista é um quadro cc-present que pergunta sobre todos os forks em aberto de uma vez, cada um como um bloco design-doc.fork com opções ricas: uma consequência em cada opção, prós e contras, exatamente uma recomendada e a porta de escape da lista em aberto. O quadro carrega blocos de fork e nada mais. Qualquer coisa além dos forks é um defeito: um bloco design-doc.claims, uma varredura de confirmar/desafiar, um despejo design-doc.registers ou um bloco de contexto. A própria pergunta de um fork, consequências e prós e contras carregam o contexto de que precisam. Respostas que abrem novos forks vão para o próximo quadro, construído da mesma forma.

As rodadas são executadas em um quadro cc-present ao vivo: antes da primeira rodada (na Fase 1 e novamente aqui), verifique a lista de habilidades disponíveis para cc-present:present (a habilidade de quadro /cc-present) e a invoque com a ferramenta Skill — suas instruções governam a composição e o envio do quadro, e cada rodada a partir de então passa por um quadro. Um fork é um bloco design-doc.fork, cujas opções carregam sua consequência inline e cuja porta de escape retorna {defer: {title, why}}: o humano nomeia a pergunta em aberto, para que o Q# chegue sem gastar outra rodada perguntando como chamá-lo. Onde o pacote estiver faltando, um bloco choice simples carrega a mesma forma manualmente — descrições de consequência em cada opção, exatamente uma marcada como "(Recomendado)" e uma última opção "Adicionar à lista em aberto" que realmente enfileira um Q# — e AskUserQuestion é a superfície de último recurso, usada apenas quando cc-present:present está ausente da lista de habilidades. Enquanto a habilidade de quadro existir, os forks de design nunca passam por AskUserQuestion. Pergunte cada fork como uma pergunta simples que uma pessoa pode responder friamente ("Como os workers devem receber jobs?"). O ID do registro que ela resolve vai no campo decides do bloco, ou acompanha o header do AskUserQuestion, nunca no texto da pergunta; a consequência de uma opção diz o que acontece, não qual entrada ela substitui. As rodadas são uma entrevista, não uma pesquisa: aponte falhas no rascunho atual, sugira alternativas que o usuário não nomeou, pressione onde as evidências discordam e não decida nada você mesmo. Cada resposta se torna um DQ# com a resolução, as alternativas rejeitadas e o número da rodada. Quando uma rodada posterior altera uma decisão anterior, faça a supersessão: um novo DQ#, um ponteiro by no antigo.

Critérios de saída: nenhum fork indeciso permanece fora da lista em aberto; cada DQ# remonta a uma rodada em qa-log.json.

Fase 3 — Revisão adversarial

Ataque o rascunho intermediário, antes que o polimento torne as falhas mais difíceis de ver. Use a habilidade do plugin codex quando disponível; caso contrário, crie um subagente de contexto novo sem interesse no design e com a missão de atacá-lo como um engenheiro sênior cético: bugs de correção, modos de falha ausentes, números injustificados. Salve a saída literalmente como <revisor>-review-<data>.md, indexe cada descoberta no registro findings (dados apenas — nunca renderizados) e disponha de cada uma: uma nova decisão, um item em aberto ou uma rejeição registrada com um motivo. Uma descoberta corrigida por código carrega o pull request que a corrigiu como o quinto elemento da linha, na mesma forma de uma entrada links[]. Uma descoberta que precisa da decisão do usuário se torna uma rodada como qualquer outra, cuja pergunta diz o que o revisor encontrou, em palavras; o número da descoberta se torna o ID do fork no bloco design-doc.fork. A disposição final de cada descoberta vai na entrada, não no texto do quadro; o quadro pergunta ao usuário o que fazer, não o que a descoberta significa. Depois que as descobertas forem resolvidas, execute o bloco design-doc.adversarial uma vez: ele escreve a seção de descobertas, nomeia o revisor e confirma que ela nunca apareceu no documento. Marque a seção como leitura obrigatória para o portão de custos.

Critérios de saída: $TOOL check está limpo; findings está completo; a revisão adversarial está concluída.

Fase 4 — Spikes

Para cada entrada marcada com (E) em sua estimativa, inclua a justificativa para o 'E' no texto. Quando um (E) aparecer na saída, ele é o único item no registro, e nada mais acontece. Um (E) em uma estimativa inicia um Spike (V#): um experimento com prazo que entrega um número medido. O experimento deve ser pequeno o suficiente para caber em alguns dias e grande o suficiente para eliminar o 'E'. O resultado do spike substitui a estimativa (E) por uma real. Se o spike não eliminar o 'E', um novo spike começa. A lista de spikes é registrada em registers.json como entradas V#.

Critérios de saída: nenhuma entrada (E) permanece no design; cada uma foi substituída por um número medido de um V#.

Fase 5 — Prosa e publicação

Execute $TOOL build se houver um diretório components/. Execute $TOOL render-check para verificar os diagramas Mermaid. Escreva o summary.html a partir dos briefs das figuras e do diagnóstico, uma seção ## por painel. Execute $TOOL summary-text para obter o deck como Markdown. Passe o texto do resumo pelos portões: verifique se cada afirmação remonta a uma suposição ou decisão, se cada figura tem um brief e uma crítica, e se o vocabulário está no glossário. Use os auxiliares de escrita do contrato de voz. Quando estiver satisfeito, execute $TOOL pdf para gerar o PDF. Publique o documento em um local acordado com o usuário.

Critérios de saída: o documento HTML e o PDF existem; o usuário aprovou o resumo executivo e o documento completo.

Fase 6 — Revisão e feedback

O documento é uma proposta humilde que explica e pede feedback. O usuário ou o público-alvo revisa o documento. As perguntas e o feedback são registrados como novas rodadas ou itens em aberto. Mudanças são feitas através do ciclo de supersessão ou novas entradas. O documento é atualizado e republicado conforme necessário.

Critérios de saída: o feedback foi coletado e as alterações foram tratadas.