LaiAnTan/agentic-setup

Projete antes de construir

Agentes são rápidos para implementar e ruins em notar que o design está se deteriorando. A solução é concordar com as decisões antes de existir código, para que cada PR seja rápido de revisar porque corresponde ao que já foi aprovado. Você redige cada etapa; o usuário revisa e aprova.

1. Dimensione o trabalho e escolha as etapas

Trabalho	Etapas
Funcionalidade média, refatoração contida	design de programa → fatias
Funcionalidade grande, refatoração transversal	arquitetura → design de programa → fatias
Novo projeto, multi-repositório ou problema indefinido	produto → arquitetura → design de programa → fatias

Diga qual tamanho você escolheu e porquê em uma linha. O usuário pode adicionar ou pular etapas.

2. Reúna contexto primeiro

Antes de redigir qualquer coisa: leia docs/README.md e a documentação viva para a qual ele aponta, quaisquer designs abertos em docs/designs/, o código relevante e o histórico do git para a área. Para escolhas entre ferramentas ou abordagens, pesquise (documentação, benchmarks, problemas conhecidos) e dê opções concretas com fontes. Não projete com base em suposições.

3. Execute cada etapa

Crie o arquivo de design docs/designs/YYYY-MM-DD-<slug>.md a partir de template.md (primeiro, configure o layout de docs/ a partir das regras globais, se o repositório não o tiver). Para cada etapa, leia seu arquivo de etapa abaixo (na pasta desta skill), redija aquela seção do arquivo de design, então pare:

• product.md: problema, usuários, comportamento, fora do escopo
• architecture.md: componentes, contratos, modelo de dados, restrições
• program-design.md: tipos, assinaturas, estrutura de arquivos, fluxo de chamadas
• slices.md: ordem de construção, repositórios, PRs e a verificação para cada fatia

Ao parar, mostre ao usuário:

• um diagrama onde for útil, além de um breve resumo (não o documento inteiro colado no chat)
• as decisões que você tomou e as perguntas em aberto, numeradas para que eles possam responder "2: sim"

Não comece a próxima etapa até que o usuário aprove esta. Se eles alterarem algo, atualize o arquivo de design, não apenas o chat.

4. Construa fatia por fatia

Após o plano de fatias ser aprovado:

• Construa uma fatia de cada vez; cada uma termina com sua verificação acordada sendo aprovada e a evidência mostrada.
• Um PR (ou commit, se o usuário não usar PRs) por fatia, descrito de acordo com as regras globais.
• Se a implementação mostrar que o design está errado, pare e proponha a alteração ao design em vez de se afastar silenciosamente dele. Atualize o arquivo de design quando uma alteração for acordada.
• Marque as fatias como concluídas no arquivo de design à medida que forem entregues, para que uma sessão posterior possa continuar a partir dele.

5. Finalize

Quando a última fatia for entregue, consolide o resultado para que a documentação viva permaneça a fonte da verdade:

• Atualize docs/product.md, docs/architecture.md e quaisquer documentos de tópico do repositório (não os arquivos de etapa desta skill) para descrever o sistema como ele agora está, seguindo as regras de escrita de documentação das regras globais.
• Adicione quaisquer termos novos, difíceis ou específicos do projeto a docs/glossary.md.
• Transforme cada decisão significativa em uma nota docs/decisions/NNNN-<slug>.md.
• Marque o arquivo de design como concluído e adicione-o a docs/README.md. Não o reescreva depois.
• Mostre ao usuário o que mudou na documentação viva.