Sessão de Design

O que Sessão de Design faz?

Pense em um design junto com o proprietário antes que qualquer coisa seja registrada. O proprietário lidera; o agente amplia as opções, mostra o que cada uma implica e mantém a conversa honesta. Nada entra no design do sistema até a etapa de promoção no final, onde o proprietário escolhe o que entra.

Use a qualquer momento: antes de existir um design do sistema, durante o planejamento de marcos, ou no meio de um marco. Termos (design do sistema, verificação aditiva, superfícies revisáveis, settled/working, owner/proposed, marco, spike, código provisório, preferência do proprietário, regra de duas sobreposições) são definidos no terms.md da skill system-design; use-os conforme definidos lá.

Arquivos

<DocDir>/SystemDesign/
  Overview.md                       o design do sistema (system-design); alterado apenas pela etapa de promoção
  Sessions/<data>-<Topico_Curto>.md  notas de rascunho desta skill, deletadas após a etapa de promoção

<data> é YYYY-MM-DD; Topico_Curto são 2–3 palavras em Snake_Case, ex. 2026-11-01-Revisar_Import.md. As notas são de forma livre: sem IDs, sem status, sem marcas de concordância e sem limite de perguntas. Elas contêm o esboço do proprietário, as formas consideradas com seus diagramas, consequências traçadas, contradições encontradas e como foram resolvidas, resultados de spikes, e para onde o proprietário está inclinado. Atualize-as sempre que a conversa avançar, para que uma sessão que pare cedo possa retomar do arquivo.

Fluxo de Trabalho

1. Leia, depois deixe o proprietário liderar

Leia o design do sistema e qualquer documento de subsistema que o tópico toque, o marco atual do roteiro, <DocDir>/Taxonomy.md, o arquivo de regras do projeto (CLAUDE.md ou equivalente) e o arquivo de preferências do proprietário ${DANNY_SKILLS_STATE_DIR:-$HOME/.local/state/danny-agent-skills}/owner-preferences.md se existir. Se um arquivo de notas para este tópico existir em Sessions/, continue a partir dele. Caso contrário, crie-o e informe o caminho.

Pergunte ao proprietário o que ele está imaginando, e reflita seu esboço de volta em algumas linhas e, quando tiver duas ou mais partes, um diagrama. Pergunte apenas o que mudaria a forma; nunca pergunte o que você poderia declarar como padrão.

2. Ofereça formas alternativas

Ofereça 2–3 formas, contando o próprio esboço do proprietário como uma. Para cada: um diagrama Mermaid seguindo o diagrams.md da skill plan-milestone (rótulos dos nós são exatamente os nomes dos componentes do design do sistema, novas peças sketched, o que a forma altera marcado touched), um exemplo simples de como ela se comporta em um caso do projeto, e um pró e contra em uma linha. Em seguida, recomende uma, ou diga "nenhuma recomendação" e o porquê. Nomeie coisas novas pelo que elas fazem (terms.md, "Nomes e rótulos"). Verifique a renderização de cada diagrama conforme diagrams.md.

3. Trace consequências

Para a forma para a qual o proprietário está inclinado, diga o que ela altera: subsistemas, interfaces, o modelo de dados, superfícies revisáveis (campo por campo apenas lá), nomes e a seção de ameaça e privacidade. Execute a verificação aditiva contra a linha de cada marco posterior: se um marco posterior não puder ser adicionado sem reestruturação, diga qual interface teria que ser decidida agora. Sem design do sistema ou sem linhas de marcos posteriores ainda, pule a verificação aditiva até que marcos existam; nunca invente marcos para verificar. Nomeie cada item settled que a forma alteraria; alterar um é um gatilho de replanejamento. Deixe os internos dentro das interfaces indecisos; minúcias vão para a lista "decidir depois de executar".

4. Capture contradições

Diga claramente quando algo que o proprietário diz entra em conflito com uma declaração anterior nesta sessão, um item settled, uma preferência do proprietário, as regras do projeto ou um nome em Taxonomy.md. Cite ambos os lados e pergunte qual prevalece. Registre a resposta nas notas.

5. Ofereça um spike descartável

Quando apenas executar algo resolverá uma questão (é rápido o suficiente, a API retorna isso, a plataforma pode fazer aquilo), ofereça a menor execução que a responda: o que faz, qual resultado aponta para qual direção, e aproximadamente quanto tempo leva. Construa-o apenas se o proprietário aceitar, fora do código do produto (um diretório de rascunho ou um branch descartável), execute-o e registre o resultado nas notas. O código é descartado; se o proprietário quiser mantê-lo, ele é promovido como código provisório na etapa 6.

6. Promova

Quando o proprietário disser que terminou, ou a conversa convergiu, liste cada item nas notas que poderia entrar no design do sistema, na forma em presenting-for-review.md, cada um com um resultado recomendado:

• Promover como settled ou promover como working com sua nota de revisão ("revisitar se …").
• Arquivar para um marco posterior, nomeando o marco.
• Descartar.

Na mesma mensagem, proponha linhas de preferência do proprietário de acordo com a regra de duas sobreposições: apenas onde o proprietário sobrepôs o mesmo tipo de forma que você ofereceu duas vezes nesta sessão, ou declarou um gosto explicitamente. Uma linha cada (a preferência, um exemplo, a data), dizendo se vai para o arquivo de preferências do proprietário entre projetos ou para o arquivo de regras do projeto. Uma única decisão é uma decisão, não uma preferência; feedback sobre como esta skill se comporta vai para a retrospectiva, não aqui. Para cada item na redação do proprietário (um nome, texto de resultado, uma interface), faça a oferta de aperfeiçoamento da etapa 4 da skill system-design uma vez na mesma mensagem: liste cada ambiguidade e mostre uma versão ajustada ao lado da original; o proprietário aceita, edita ou mantém. Termine com uma pergunta.

Aplique as decisões do proprietário ao design do sistema (overview-template.md) como uma edição normal:

Item promovido	Onde vai
Um componente	uma linha de Componentes (sketched, Alvo de construção, Acordo) e um nó de diagrama com sua classe de profundidade apenas, nunca touched
Uma interface	uma linha de Interfaces e interfaces com seu Acordo
Uma tabela, API ou símbolo público	Superfícies revisáveis, campo por campo, com sua marca
Uma entidade ou relacionamento	Modelo de dados
Um nome	Nomes, depois <DocDir>/Taxonomy.md, revisado com o restante como um conjunto
Uma escolha entre formas	uma linha de Decisões: próximo ID D livre, Tipo choice, Acordo settled ou working (revisit if …), Por que nomeando a forma rejeitada
Uma desconhecida que a sessão encontrou	uma linha de Riscos com seu experimento mais barato
Uma alteração em um marco posterior	sua linha de Escopo e marcos e célula de Verificação aditiva
Código de spike que o proprietário mantém	uma linha de Código provisório, e o marcador PROVISIONAL no código
Um item estrutural arquivado	uma linha de Perguntas em aberto nomeando o marco pelo qual espera, ex. "Q4 (arquivado até M3, registrar alterações): …"
Uma minúcia arquivada	a lista "decidir depois de executar", sob o marco que a resolverá

As marcas de acordo seguem o modelo: um item que o proprietário escreveu ou editou lê owner (ex. settled · owner); um item que o proprietário aceitou inalterado não carrega marca proposed. Novos IDs continuam a sequência do documento e nunca são reutilizados. Uma alteração em um item acordado passa pelo registro de decisões, não por uma edição silenciosa. Quando um item promovido altera um item settled (uma interface, por exemplo) ou uma solicitação do proprietário adiciona estrutura ao marco atual, diga claramente que um replanejamento é devido, e após os commits abaixo escreva uma nota de passagem para que /rung roteie o replanejamento em qualquer sessão posterior: <DocDir>/Handoff/replan-<data>.md com Route: replan, Model: opus, Waiting on: re-plan after the design session on <topico>, Date:, e um corpo nomeando os itens alterados e o commit (handoff.md). Itens descartados não são registrados; o arquivo de notas no histórico do git os mantém. Escreva as linhas de preferência aceitas no arquivo que o proprietário escolheu.

Se ainda não existir um design do sistema, escreva os itens promovidos em um novo Overview.md com o cabeçalho do modelo (Status: draft) e apenas as seções que eles preenchem; system-design continua a partir dele.

Faça commit, estagiando por caminho explícito, do design do sistema, Taxonomy.md, do arquivo de regras do projeto se alterado, e do arquivo de notas, como Design session: <topico>, para que o histórico mantenha as notas. Em seguida, git rm o arquivo de notas e faça commit disso como Remove design session notes: <topico>. Registre um evento step com skill design-session 1.0.1 e kind design-session (outros campos no log de métricas de tasklist-run), além das contagens dos itens que você propôs para promoção: proposed, accepted (inalterados), edited e rejected.

Termine com uma frase simples dizendo o que mudou e qual é o próximo passo, depois Next: /rung, adicionando (Opus: /model opus) quando esse passo precisar de Opus: um design do sistema ainda a ser acordado, planejamento de marco, ou um replanejamento que a etapa 6 disse ser devido.

Se o proprietário parar antes de promover, deixe o arquivo de notas no lugar, sem commit, e informe seu caminho; a próxima sessão de design sobre o tópico continua a partir dele.

Se um arquivo ou skill vinculado estiver faltando

Quando um arquivo vinculado estiver ausente, não pare: use o mínimo aqui, e diga uma vez, em uma ou duas linhas, o que está faltando e como instalá-lo (claude plugin install project-planning@danny-sung-agent-skills, ou npx skills add dannys42/agent-skills --skill <nome-da-skill> no mesmo diretório de skills para que links relativos funcionem).

• Sem terms.md: espera-se que settled se mantenha; working é bom o suficiente para começar e nomeia o que nos faria revisitar; itens owner são as palavras do proprietário, proposed as do agente. A verificação aditiva pergunta se cada marco posterior pode ser adicionado sem reestruturação.
• Sem diagrams.md: Mermaid flowchart, cite cada rótulo, rótulos são os nomes dos componentes, uma classe por profundidade (sketched tracejado, designed fino, built negrito).
• Sem presenting-for-review.md: itens importantes primeiro (no máximo 5, difíceis de reverter ou de amplo alcance), cada um com opções, um exemplo simples, um pró e contra e uma recomendação; termine com uma pergunta.
• Sem overview-template.md: promova para as seções existentes do design do sistema, combinando suas tabelas e marcas.

Decisões de julgamento

• O proprietário lidera. Ofereça formas e consequências; não interrogue ou direcione para sua favorita. Uma pergunta que não mudaria a forma não vale a pena ser feita.
• Explore livremente, promova com moderação. Qualquer coisa pode ser discutida na sessão, mas apenas a estrutura entra no design do sistema: subsistemas, interfaces, modelo de dados, superfícies revisáveis, nomes, decisões e riscos. Internos ficam de fora.
• Um spike vence uma discussão. Quando o proprietário e o agente discordam sobre um fato que uma execução curta resolveria, ofereça a execução em vez de debater.