desenvolvimento-com-adr

Desenvolva com ADRs

Primeiro passo obrigatório: verificação de conflitos

Antes de perguntar pelo domínio, criar agentes, investigar código ou fazer alterações, execute o script somente-leitura incluso:

python3 <diretório-absoluto-da-skill>/scripts/check_conflicting_skills.py --project <caminho-do-repositório>

Resolva placeholders para caminhos reais e coloque caminhos entre aspas conforme necessário. Passe cada nome no catálogo de skills disponíveis da sessão com um argumento --available-skill repetido, incluindo nomes qualificados por plugin e somente-nuvem. Adicione diretórios de skill não padrão com --root; adicione explicitamente alvos de links simbólicos de diretório aninhados relevantes. O script descobre arquivos de skill locais e entradas de catálogo sem carregar suas instruções ou alterar instalações.

• Trate grill-me e spec-first como skills conflitantes, incluindo variações de maiúsculas, minúsculas, espaço, sublinhado e hífen, como Grill Me ou spec_first.
• Saída 0 significa nenhum conflito encontrado no escopo inspecionado. Saída 1 significa que conflitos foram encontrados, não falha do script. Saída 2 significa que a descoberta foi incompleta: relate os erros e a limitação de cobertura, resolva-os quando possível e execute novamente. Nunca afirme que todas as skills foram verificadas quando a cobertura estiver incompleta.
• Para quaisquer correspondências, desabilite seu uso dentro deste fluxo de trabalho e avise o usuário em seu idioma antes de continuar: nomeie as skills detectadas e explique que elas estão desabilitadas apenas para o fluxo de trabalho atual. Não implique desinstalação global ou alterações na configuração da conta. Nenhuma aprovação adicional é necessária para essas exclusões de fluxo de trabalho.
• Não invoque as skills excluídas, siga suas instruções ou delegue trabalho a elas. Aplique a exclusão ao coordenador, arquiteto e implementador; passe a lista de exclusão em cada passagem de agente. Use as próprias etapas de esclarecimento e aprovação deste fluxo de trabalho.
• O script detecta conflitos; o agente coordenador aplica as exclusões. Exclua também qualquer skill se o catálogo da sessão revelá-la, mesmo quando seus arquivos não estiverem acessíveis. Se o script não puder ser executado, relate essa limitação e aplique as exclusões conhecidas sem afirmar que houve uma varredura bem-sucedida.
• Execute novamente após retomar uma sessão ou fazer alterações nas skills disponíveis. Nunca delete, renomeie ou desabilite globalmente skills instaladas como parte desta verificação.

Entrada e papéis

1. Antes de iniciar o fluxo de trabalho, pergunte pelo domínio no qual o arquiteto deve se concentrar. Aceite domínios de negócio ou técnicos. Reutilize um domínio fornecido explicitamente sem perguntar novamente.
2. Crie um agente arquiteto separado para o domínio selecionado para toda a sessão. Forneça estas regras, o domínio, o caminho do repositório e o contexto conhecido. Peça ao arquiteto que pergunte ao usuário qual problema resolver; o agente principal pode repassar a pergunta e a resposta. Se o problema já foi fornecido, pergunte apenas por informações faltantes.
3. O agente principal deve coordenar diálogo, documentos e transferências de contexto. O arquiteto deve investigar, projetar, manter ADRs e verificar resultados de forma independente. Um agente implementador separado deve implementar as decisões aprovadas e preparar evidências. Não combine os papéis de arquiteto e implementador.
4. Use as capacidades nativas de agentes separados do ambiente: subagentes no Codex e capacidades de agente/tarefa disponíveis no Claude Code. Não invente APIs nem apresente um único agente alternando papéis como verificação independente. Se agentes separados não estiverem disponíveis, explique a limitação e peça ao usuário que escolha um ambiente adequado. A investigação pode continuar, mas a implementação sob este fluxo de trabalho não deve começar.
5. Após perda de contexto, restaure o estado a partir de documentos e código. Se um novo arquiteto precisar ser criado, não afirme que o agente original sobreviveu; restaure seu domínio e responsabilidades.

Investigação e decisão

• O arquiteto deve ler as instruções do projeto, código, ADRs relacionados e evidências, e esclarecer o problema e as restrições. Não crie um ADR antes de investigar o código e esclarecer o problema. Se ainda não houver código, registre esse fato e investigue os materiais disponíveis.
• Identifique conflitos com decisões atuais. Primeiro apresente o conflito ao usuário e solicite uma decisão; somente após a resposta prepare um novo ADR. A permissão para preparar uma substituição não é aprovação para implementá-la.
• Escreva um ADR em docs/adr/ usando os modelos. Inclua uma breve declaração do problema, solução proposta, justificativa e critérios de aceitação verificáveis com IDs estáveis. Defina o status inicial como accepted-for-discussion.
• Separe decisões independentes em ADRs distintos e registre explicitamente as dependências. Não introduza ciclos de dependência ou substituição.
• Apresente o ADR específico ou um conjunto enumerado de ADRs para aprovação explícita do usuário para implementação. Não infira aprovação a partir do silêncio, de um pedido genérico para construir algo ou de permissão para investigar.
• Registre a resposta do usuário, a data e a versão do documento aprovado. Defina accepted-for-work somente após aprovação explícita. Permita aprovação explícita de um conjunto enumerado de ADRs.

Implementação

• Comece a implementar um ADR somente depois que todos os ADRs dos quais ele depende estiverem concluídos, mesmo que o conjunto inteiro já esteja aprovado.
• Forneça ao implementador o ADR, os critérios, as dependências e as restrições. Exija implementação dentro do escopo da decisão aprovada.
• Se a implementação for impossível ou se a decisão ou critérios precisarem mudar, pare o trabalho afetado e retorne o problema ao arquiteto. Trabalho aprovado independente pode continuar.
• Nunca altere a descrição da solução ou os critérios de aceitação após a aprovação. Registre alterações em um novo ADR com aprovação separada.
• O implementador deve preparar evidências em docs/evidence/: resultados para cada critério, comandos e instruções de reprodução, e o commit verificado ou a versão exata do código. Não substitua um commit futuro pela versão testada. Para alterações não commitadas, inclua um diff salvo e identificadores ou hashes dos arquivos verificados.

Verificação independente e conclusão

• O arquiteto deve pessoalmente executar as verificações e comparar os resultados reais com cada critério de aceitação. O relatório do implementador e a inspeção de código não substituem a execução.
• Preserve comandos, ambiente, resultados, links de log e a versão verificada nas evidências. Marque honestamente as verificações que não foram executadas, foram bloqueadas ou falharam. Não conclua um ADR com critérios não verificados ou não atendidos.
• Se a implementação falhar na verificação, mas o ADR permanecer válido, primeiro apresente os resultados e o escopo concreto de correção ao usuário e solicite permissão. Não delegue nem realize correções antes da resposta. Após a permissão, o implementador deve corrigir o problema e o arquiteto verificar novamente. Outra falha de verificação exige nova permissão para o próximo ciclo de correção.
• Se a falha exigir uma nova decisão de arquitetura, retorne à investigação e ao procedimento de novo ADR.
• Permita apenas que o arquiteto defina completed após verificação independente bem-sucedida de cada critério. Exija um link para o documento de evidência. Nenhuma aprovação adicional do usuário é necessária para concluir o ADR.

Status e preservação do histórico

Use exatamente quatro valores canônicos de status. Os rótulos em russo abaixo identificam seus significados originais; preserve o histórico existente do projeto em vez de reescrever silenciosamente documentos legados.

Status	Rótulo original	Condição
accepted-for-discussion	принято к обсуждению	Proposta investigada aguardando discussão ou aprovação
accepted-for-work	принято к работе	Usuário aprovou explicitamente o ADR específico
completed	завершен	Arquiteto verificou independentemente todos os critérios; evidência está linkada
rejected	отклонено	Um novo ADR aprovado e justificativa/evidência de rejeição existem

• Nunca exclua documentos ADR ou de evidência nem reutilize seus IDs. Antes da aprovação, permita refinamento do rascunho enquanto registra alterações substanciais.
• Após a aprovação, mantenha o corpo da solução e os critérios imutáveis. Permita atualizações de status e links com entradas de histórico anexadas. Preserve entradas anteriores, evidências e resultados de verificação. Não sobrescreva uma verificação com falha com um resultado de sucesso.
• Rejeite o ADR antigo no momento em que o usuário aprovar explicitamente sua substituição para trabalho, inclusive quando o ADR antigo estiver concluído. Imediatamente linke o ADR antigo para sua substituição e um documento de justificativa de rejeição separado. Isso prova por que a decisão antiga foi rejeitada; não prova que a nova implementação funciona.
• Preserve a conclusão anterior, sua data, versão e evidência. Registre explicitamente que a substituição pode ainda não estar implementada. Rejeitar um documento não remove, por si só, o código funcional.
• Não rejeite um ADR sem uma nova decisão. Se o usuário não escolheu uma substituição, mantenha o status atual e anexe uma entrada de discussão. Não invente uma substituição apenas para permitir uma transição de status.
• Se uma dependência for rejeitada ou substituída, pause o trabalho afetado e peça ao arquiteto que avalie o impacto. Não reconecte silenciosamente decisões aprovadas.

Grafo de documentos

• Leia os modelos antes de criar documentos e as diretrizes de portabilidade ao usar um novo ambiente.
• Armazene ADRs como docs/adr/ADR-0001-slug-curto.md e evidências como docs/evidence/EVID-0001-slug-curto.md. Escolha o próximo número não utilizado considerando o histórico existente; não renumere documentos antigos.
• Use links Markdown relativos explícitos e tipos de relacionamento: replaces / replaced_by, depends_on / required_by, extends / extended_by e evidence / proves. Mantenha backlinks e identifique se a evidência comprova a implementação ou a razão para rejeição.
• Trate ADRs e evidências como os documentos do grafo; um banco de dados de grafo separado é desnecessário. Nas transferências, verifique destinos de links, backlinks, ausência de ciclos de dependência e condições de status.
• Ao final de cada etapa, relate o status do ADR, resultado, links do documento e a decisão específica necessária se estiver aguardando o usuário. Não descreva trabalho meramente aprovado ou implementado, mas não verificado, como concluído.