XeroBis/website

Planejar e Documentar

Porquê

Solicitações como "portar cards" ou "adicionar tags ao portfólio" parecem decisões finais, mas geralmente escondem escolhas não resolvidas: quanto construir agora, o que descartar ou alterar do repositório antigo, qual esquema é dono dos dados, o que vai em @shared. Construir imediatamente arrisca fazer a coisa errada, refazê-la ou desviar de uma escolha já registrada em documentation/decisions.md. Perguntar primeiro mantém os documentos — e depois o código — como um registro preciso do que o usuário realmente quer.

Quando isso se aplica

Qualquer solicitação que alteraria algo que documentation/ rastreia: uma funcionalidade ou comportamento voltado ao usuário, um esquema/tabela/coluna/regra de negócio, uma escolha técnica ou de biblioteca, a estrutura de pastas/arquitetura, ou um passo de migration-plan.md. Edições pequenas e totalmente especificadas (corrigir este erro de digitação, renomear este rótulo para exatamente X) não precisam da entrevista — use o julgamento sobre o quanto realmente é ambíguo.

Passos

1. Ler antes de perguntar. Folheie as seções de documentation/*.md que se relacionam com a solicitação (e o código relevante). Ao portar, leia também os documentos do repositório antigo (../<repo>/documentation/, ../<repo>/CLAUDE.md) e o código sendo portado. Não pergunte algo que já está respondido. Use-os como base para suas perguntas.

2. Faça perguntas esclarecedoras com AskUserQuestion. Prefira várias perguntas pequenas e concretas a uma única ampla. Bons alvos para este repositório:

   • quanto construir agora vs. depois;
   • ao portar: o que manter como está, alterar ou descartar do aplicativo antigo (comportamento antigo não é automaticamente desejado);
   • qual esquema é dono das novas tabelas (o próprio aplicativo, ou core se todos os apps precisarem);
   • se uma parte pertence a um aplicativo ou a @shared / um módulo compartilhado do backend;
   • detalhes de UX que features.md precisaria registrar, e a forma dos novos dados.

   Dê a cada pergunta um padrão recomendado para que o usuário possa avançar rapidamente.

3. Respeite exatamente o escopo que o usuário devolver. Se ele restringir a "apenas documentação" ou "só X, não Y", não faça silenciosamente mais — confirme novamente antes de expandir o escopo mais tarde.

4. Atualize os documentos no mesmo passo da decisão, roteados conforme a tabela do CLAUDE.md:

   • Estrutura de pastas, ambientes, portas, fluxo de requisição → architecture.md
   • Esquemas, tabelas, colunas, relacionamentos, regras de negócio → data-model.md, sob a seção daquele esquema
   • Escolha técnica/biblioteca/arquitetura → decisions.md: uma entrada datada informando o que foi escolhido, sobre o que, e por quê, no estilo do arquivo
   • Comportamento voltado ao usuário, regras de validação → features.md, sob a seção daquele aplicativo
   • Qualquer coisa adiada, descartada ou ainda apenas uma possibilidade → ideas.md
   • Progresso da portabilidade → coluna de status de migration-plan.md
   • Alterações no runbook de produção → deployment.md

5. Mova ideias resolvidas para fora de ideas.md. Se uma alteração transformar uma entrada de ideas.md em uma decisão real, remova ou reescreva essa entrada em vez de deixar uma duplicata obsoleta.