Escrever primeiro a especificação e depois programar em pequenos passos com testes primeiro

## Registrar requisitos pouco claros como perguntas e esperar respostas antes de planejar Não planeje nem implemente enquanto um requisito importante estiver indefinido. Identifique os requisitos pendentes, as expectativas não funcionais, o comportamento, a telemetria, as políticas e os critérios de aceitação antes de propor mudanças. Antes de solicitar uma decisão, registre cada esclarecimento de alto impacto e cada incerteza de impacto médio no registro de questões em aberto designado pelo repositório. Dê a cada questão um identificador estável e mantenha a especificação principal, o plano e a lista de tarefas limitados a esse identificador até que ela seja resolvida. Ao apresentar alternativas, armazene primeiro as mesmas opções e depois as resuma diretamente para o usuário. Coloque a opção recomendada em primeiro lugar, apresente vantagens e desvantagens concisas, cite o identificador da questão e pare até que a resposta necessária esteja disponível. Depois da resolução, incorpore a resposta às seções normativas da especificação e encerre a entrada no registro. ## Ler a especificação e o mapa de arquitetura antes de planejar Trabalhe a partir da raiz do repositório e aplique tanto as instruções para todo o repositório quanto todas as regras aninhadas pertinentes. Antes de planejar, leia o roteiro atual, a especificação principal da funcionalidade, o mapa de módulos ou de conhecimento, as convenções de código e as decisões arquitetônicas vinculadas à funcionalidade afetada. Mapeie os módulos, os contratos e os limites de responsabilidade que a mudança pode afetar. Use o panorama de arquitetura mantido pelo repositório em vez de inferir relações apenas a partir de um arquivo próximo e atualize esse mapa quando os módulos, as dependências ou os contratos mudarem. Use os modelos aprovados para especificações, planos, tarefas e decisões arquitetônicas, de modo que os metadados, as notas de verificação e as referências cruzadas permaneçam consistentes. ## Atualizar primeiro a especificação e depois o plano e a lista de tarefas Crie ou atualize a especificação da funcionalidade antes da implementação. Defina os requisitos, os requisitos não funcionais, os detalhes de comportamento ou de interface, a telemetria e as políticas, as ramificações de aceitação e um esboço da interface quando o comportamento visual mudar. Resolva todas as questões de impacto alto e médio antes de gerar o plano de implementação. Depois de atualizar a especificação, registre os resultados arquitetonicamente relevantes em um registro de decisão arquitetônica e mantenha os esclarecimentos resolvidos nas seções normativas, em vez de uma lista legada de esclarecimentos separada. Somente então atualize o plano e a lista de verificação de tarefas. Coloque os testes antes da implementação, divida o trabalho em incrementos lógicos que devem caber em 90 minutos e execute a porta de análise do repositório depois que a especificação, o plano e as tarefas estiverem de acordo. Não invente comportamentos alternativos nem de compatibilidade, a menos que o usuário os solicite explicitamente. ## Retomar a sessão a partir de um único registro salvo e atualizá-lo antes da passagem Ao iniciar uma sessão sem contexto, siga o procedimento do repositório para redefinição ou transferência. Resuma o estado do roteiro, o progresso do plano ativo e as questões pendentes antes de iniciar um novo trabalho de implementação. Mantenha um único panorama designado da sessão atual como o estado ativo entre sessões. Antes da transferência, atualize-o com a funcionalidade ativa, o trabalho concluído, as questões pendentes, o estado da verificação e a próxima ação segura. Não crie registros de progresso concorrentes. Mantenha explícitas as responsabilidades de cada funcionalidade e módulo para que a documentação, a automação, a segurança, a persistência e o trabalho de interface sejam atualizados em seus respectivos locais principais. ## Escrever primeiro um teste que falhe para cada comportamento Atualize a especificação principal e o plano antes de mudar o código. Para cada comportamento, escreva ou amplie primeiro um teste executável unitário, de comportamento, de contrato ou de cenário e confirme que ele falha pelo motivo pretendido. Durante o planejamento, liste as ramificações de sucesso, validação e falha e acrescente um teste mínimo que falhe para cada caminho. Implemente somente o código necessário para fazer os testes passarem e depois refatore mantendo-os aprovados. Depois de encerrar o ciclo, registre as mudanças de cobertura, os aprendizados e o trabalho posterior no plano ou no roteiro, para que o raciocínio permaneça auditável. ## Fazer mudanças pequenas e completas e marcar cada tarefa como feita na hora Mantenha cada incremento autocontido e siga as convenções de linguagem, estrutura de desenvolvimento, documentação e testes do repositório. Prefira uma orquestração linear composta por pequenos auxiliares de validação e normalização a ramificações em linha profundamente aninhadas. Sincronize o roteiro, a especificação, o plano e a lista de verificação de tarefas à medida que o comportamento mudar. Marque cada tarefa verificada como concluída imediatamente, em vez de agrupar atualizações de estado, e atualize o mapa de arquitetura sempre que uma relação entre módulos ou um contrato mudar. Use registros de decisão apenas para decisões arquitetônicas confirmadas. Evite refatorações não relacionadas, formatação em massa ou trabalho especulativo de compatibilidade e mantenha a implementação alinhada ao incremento aprovado. ## Rodar as verificações dos tipos de arquivo alterados e investigar falhas em vez de pulá-las Durante as iterações, execute o formatador, o analisador de estilo, a análise estática, a verificação de tipos e os testes direcionados no menor escopo aplicável. Antes de concluir, execute todas as portas exigidas pelo repositório para os tipos de arquivo modificados e para qualquer limite de integração diretamente afetado. Trate uma verificação local ou de integração contínua que falhe como um defeito a investigar, não como uma porta a contornar. Se a política do repositório permitir explicitamente uma dispensa temporária de teste, desative apenas o teste afetado, acrescente um `TODO` claro com o motivo e registre o acompanhamento no plano principal. Acrescente ou atualize testes para cada comportamento modificado. Analise as diferenças finais, confirme que a documentação e a cobertura dos testes correspondem à implementação e não declare o incremento concluído enquanto alguma verificação obrigatória continuar falhando. ## Pedir aprovação antes de adicionar dependências ou fazer operações arriscadas no Git Adicione à área de preparação somente os arquivos que pertencem ao incremento. Não use uma preparação ampla quando puderem existir saídas geradas, artefatos de banco de dados ou trabalho paralelo. Prepare uma descrição de commit atômico e convencional, incluindo o impacto na especificação quando a documentação e o código mudarem juntos, mas deixe que o operador designado faça o commit, a menos que a execução tenha sido explicitamente delegada. Obtenha aprovação explícita antes de adicionar ou atualizar dependências, excluir arquivos ou diretórios específicos, reescrever o histórico, enviar mudanças ou criar uma revisão externa. Registre no plano da funcionalidade a justificativa de uma dependência aprovada e reserve tempo suficiente para os hooks gerenciados e os processos de qualidade. Nunca inclua segredos em um commit nem use uma limpeza destrutiva como atalho. Apresente para revisão os arquivos rastreados ou não rastreados que surgirem inesperadamente e mantenha intacto o trabalho não relacionado. ## Não adicionar alternativas de compatibilidade sem pedido e propor antes as mudanças arriscadas Siga a postura de compatibilidade declarada pelo repositório. Quando as interfaces forem tratadas como uma criação nova, não acrescente comportamentos alternativos, camadas de adaptação nem verificações legadas, a menos que o usuário os solicite explicitamente para a tarefa atual. Registre os resumos dos prompts, as sequências de comandos relevantes e as justificativas no plano ativo ou em um apêndice vinculado. Proponha refatorações arriscadas, mudanças de persistência, alterações na estratégia de segurança e grandes concessões não funcionais antes de editar e depois registre as decisões arquitetônicas aprovadas no registro de decisões correto. Acompanhe em planos os futuros testes de contrato, a análise de mutações e os exercícios de segurança até que existam portas automatizadas. Mantenha a orientação operacional próxima do fluxo de trabalho oficial e evite duplicar instruções mutáveis entre documentos. ## Testar só no banco de dados de teste e confirmar a conexão antes de resetá-lo Nunca execute uma redefinição, uma limpeza total ou um comando de migração do zero em um banco de dados por meio de uma conexão não verificada. Antes de qualquer migração ou redefinição, confirme o ambiente ativo, o destino da conexão e se a operação está restrita a um banco de dados de teste descartável. Execute os testes da aplicação no banco de dados de teste isolado do repositório e use a configuração documentada de transações ou migrações. Redefina somente o banco de dados de teste identificado explicitamente quando necessário; não presuma que um comando de teste e um comando interativo da aplicação compartilhem a mesma conexão. Crie novas migrações como arquivos e exercite-as por meio do fluxo de testes. Se o escopo do banco de dados for ambíguo, pare e obtenha confirmação em vez de colocar em risco os dados de desenvolvimento ou produção. ## Fechar cada etapa com uma passagem do que mudou e do que foi verificado Depois que um incremento autocontido passar pelas portas aplicáveis, confirme que as tarefas concluídas, o estado do roteiro, as mudanças na especificação, os registros de decisão e o panorama da sessão atual estejam sincronizados. Forneça uma transferência concisa que liste os arquivos modificados, as verificações executadas e seus resultados, os impedimentos pendentes, o trabalho posterior e quaisquer comandos prontos para copiar destinados ao operador. Diferencie o trabalho implementado daquele que está apenas planejado ou aguardando autorização. Prepare rapidamente o commit da funcionalidade após a verificação, mas execute-o somente dentro da política de delegação do repositório. Preserve evidências suficientes para que a próxima sessão retome o trabalho sem repetir a investigação.