caohaotiantian/three-loop-workflow

Fluxo de Três Loops

Planejar → Construir → Fechar, em uma profundidade escolhida com base nos riscos.

Assuma a responsabilidade pela implementação atribuída: seu plano, alterações, evidências, revisão e reparos. O implementador pode ser o pai ou um executor designado. Quando houver um coordenador, deixe a alocação de tarefas, dependências, interfaces compartilhadas e propriedade da integração com ele. Solicite as funções necessárias ou mudanças de agendamento a esse coordenador. Não coordene recursivamente outras tarefas. Encaminhe solicitações de decisão do usuário através do coordenador. Sem um coordenador, gerencie a mudança e as funções necessárias diretamente. A profundidade da implementação e o modo de execução são separados. A execução direta não remove a revisão necessária.

Restrições rígidas, as únicas regras que não são padrão:

1. Uma alteração acima de Direta é revisada por um contexto que não a escreveu; somente quando nenhum estiver disponível, o hand-off informa isso (seção 5).
2. Execute as verificações do projeto. Uma verificação que não pôde ser executada não é uma verificação que passou.
3. O hand-off relata o que foi observado, não o que foi pretendido.
4. Uma alteração em quem pode acessar o quê (autenticação, autorização, segredos, um novo caminho para entrada não confiável) nunca é Direta.
5. Uma ação fora do repositório que não pode ser desfeita aguarda o usuário: enviar para um branch compartilhado, implantar, escrever dados reais, enviar qualquer coisa.

Todo o resto é um padrão: abandone um apenas por um motivo declarado. O guia do projeto substitui qualquer padrão, e os meios são seus.

Leia o guia do projeto (AGENTS.md, CLAUDE.md) para seus comandos de verificação e os arquivos que trata como contratos; onde não nomear nenhum, derive-os do repositório e diga o que inferiu. As verificações vêm da configuração de build e CI; contratos são o que é consumido fora deste repositório ou persistido: APIs públicas, esquemas, CLIs, formatos de rede, dados armazenados.

Aplique as regras de tipo de texto, idioma e visuais em references/writing.md a esta tarefa de escrita.

1. Profundidade

Escolha a profundidade mais leve que se encaixa.

• Direta: uma pequena edição óbvia cuja correção é visível ou coberta por uma verificação existente. Uma mudança de comportamento não trivial é Padrão ou Profunda, mesmo com testes. Uma correção de digitação pode ser Direta. Um valor padrão alterado não pode. Faça a alteração e execute as verificações. Nenhum plano ou revisor é necessário. Relate a alteração, verificações, resultados e ausência de revisão em uma linha.

• Padrão: o padrão para mudanças de comportamento.

• Profunda: apenas quando um gatilho dispara:

  1. uma mudança interruptiva em um contrato consumido fora deste repositório;
  2. um efeito irreversível fora do repositório: uma migração de dados persistidos, dinheiro, qualquer coisa enviada a terceiros;
  3. uma regra alterada em um arquivo que o projeto trata como contrato;
  4. alternativas que comprometem estruturas diferentes.

  Então leia references/deep.md.

Um canto arriscado eleva sua própria profundidade, nunca a profundidade de toda a alteração. Eleve a profundidade você mesmo, inclusive quando o build revelar um gatilho; apenas o usuário a reduz. Antes de reduzi-la, recomende sua profundidade. Para alguém novo neste fluxo de trabalho, mostre o que essa alteração pularia e a falha deixada em aberto. Se insistirem, siga-os sem abrir mão de uma restrição rígida.

2. Planejar

Nos modos Padrão e Profundo, antes da primeira edição, escreva o Objetivo, os Não-objetivos pelos quais você foi tentado, e Aceitar, a evidência (seção 4).

Dimensione o plano e a revisão para a alteração.

Adicione Decisões apenas em bifurcações reais: as opções, incluindo a menor, e por que a vencedora venceu.

Escreva em .agent/<tarefa>/plan.md, um diretório por tarefa, e envie os arquivos com a alteração, a menos que o projeto tenha sua própria convenção. Se .agent estiver em .gitignore, deixe essa entrada e não force a adição dos arquivos.

Para trabalho atribuído, use o caminho do plano fornecido e referencie o escopo compartilhado e os critérios de aceitação. Mantenha os detalhes de implementação lá. Deixe registros globais de tarefas com o coordenador. Preserve os diretórios de tarefas canônicos existentes. Para planos delegados, o padrão é .agent/<tarefa>/tasks/<id-do-slice>/plan.md.

Quando duas leituras da solicitação exigirem trabalhos diferentes, declare a sua no Objetivo, mostre-a e o Aceitar ao usuário, e aguarde; se ninguém puder responder, prossiga com sua leitura e marque-a como não confirmada no hand-off. Pergunte sobre decisões reais de produto, escopo ou risco com opções, uma recomendação e uma justificativa, nunca decidindo silenciosamente; registre a resposta no plano.

Quando a causa de um defeito for desconhecida, encontrá-la é a tarefa: seu Aceitar é uma reprodução; planeje a correção depois dela.

3. Construir

• Cada linha alterada remete ao Objetivo ou a uma Decisão. Nenhuma abstração, configuralidade ou tratamento de erro que ninguém precise.
• Se o código, ou uma correção, contradisser o plano, pare e corrija o plano abertamente, não no final.
• Mantenha-se dentro dos arquivos e interfaces atribuídos. Se estes precisarem de alterações, pause o trabalho afetado e solicite uma atribuição revisada.
• Leitura paralela, escrita isolada. Use uma árvore de trabalho separada para cada escritor concorrente (references/parallel.md).
• Para trabalho de integração, execute verificações e revisão contra a alteração mesclada. Verificações de slice aprovadas não estabelecem aceitação integrada.
• Onde um documento citar uma figura que um comando produz, cite o comando ao lado da figura, ou tenha uma verificação que a recalcule.

Para trabalho durável, armazene os resultados da verificação em evidence/checks.md ao lado do plano. Registre critérios, comandos, revisões, resultados, links de evidência e condições de invalidação. Armazene descobertas, triagem, identidade do revisor e rodadas de reparo em evidence/review.md.

4. Evidência

• Aceitar nomeia a evidência real mais barata que falharia sem a alteração: uma verificação existente que fica verde, um novo teste ou o resultado observado. Diga como a falha se parece.
• Nenhum novo teste de unidade é exigido por padrão. Escreva um onde o comportamento é uma lógica que um teste fixa de forma barata e uma regressão vale a pena proteger. É a verificação errada para renderização e layout de UI, fiação e cola, configuração, chamadas finas para serviços externos, scripts únicos e prosa: observe o resultado.
• Onde uma pessoa clica, digita ou chama, um contexto que não escreveu a alteração a conduz e relata o que viu. Dê a ele o caminho e a falha, não o diff ou seu relato. Uma contradição é uma descoberta. Nenhum contexto desse tipo: conduza você mesmo e cole o que viu. Conduza uma superfície proibida em algum lugar seguro e nomeie a lacuna. Não conduzido significa não verificado.
• Onde a saída é lida em vez de executada (documentos, texto de ajuda, uma especificação), a evidência é uma leitura fria dos arquivos finais por um leitor sem o contexto da alteração: leia como um produto, não como um diff.
• Uma falha intermitente é ela própria uma reprodução e a evidência discriminatória. Não reexecute a falha desta alteração até que passe, e não exija uma reprodução determinística antes de tratá-la como tal. Uma que esta alteração não causou é um acompanhamento nomeado, não corrigido dentro desta alteração.
• Execute as verificações antes da revisão, aquelas que cobrem a alteração após cada correção, e o conjunto completo uma vez antes do hand-off. Cole as linhas de aprovação/reprovação, não logs inteiros. Tudo que foi pulado, ou aprovado ao enfraquecer um teste, não é uma aprovação.

5. Revisão

O revisor recebe a alteração completa (ou, para uma alteração construída em fases, a fase completa), o plano e o repositório, não seu resumo ou raciocínio. Completa significa todos os arquivos que a alteração adiciona, modifica ou exclui, incluindo novos arquivos não rastreados; uma revisão de um diff vazio ou incompleto não é uma revisão limpa. Direta não precisa de revisor; Padrão precisa de um.

Revisões ou leituras independentes indisponíveis: use contextos independentes disponíveis primeiro. Para funções ausentes, inspecione os artefatos completos especificados acima, não sua recordação do trabalho. Aplique os briefs das funções ausentes em uma passagem de auto-revisão. Rotule-a como "auto-revisão, não independente" e relate as funções independentes ausentes. Ofereça ao usuário os briefs para executar em outro lugar. Este fallback não substitui requisitos mais rigorosos do usuário, projeto ou host.

Entregue este brief literalmente:

Revise esta alteração em relação ao seu plano. Relate cada descoberta com arquivo:linha,
marcada como bloqueante (comportamento errado, contrato quebrado, trabalho fora do plano)
ou não bloqueante. Não modifique o código.
1. Onde ela quebra? Entrada inesperada, entrada hostil onde toca a confiança,
   falhas do que ela chama, fatos assumidos de fora do diff.
2. Os testes existentes foram enfraquecidos?
3. O novo comportamento é demonstrado por evidência, um teste ou um resultado
   observado, que falha sem a alteração? Não peça nada mais.
4. Algo está fora do Objetivo ou dentro de um Não-objetivo?
5. O plano em si está errado?

Triagem antes de corrigir. Confirme cada descoberta em relação ao código citado. Rejeite leituras incorretas e descobertas que pedem trabalho que um Não-objetivo exclui, uma linha cada. Um teste ausente é não bloqueante a menos que proteja um bug de correção confirmado. A alteração é encerrada quando nenhuma descoberta bloqueante confirmada permanece.

Revisando a alteração de outra pessoa: o mesmo brief, com sua descrição como plano; Não-objetivos ausentes são uma descoberta. Faça a triagem, depois entregue as descobertas confirmadas ao autor; não as corrija.

6. Corrigir e parar

• Uma correção repara o que uma descoberta confirmada cita, em sua causa raiz, em todos os lugares onde o mesmo defeito ocorre.
• Novo maquinário é novo trabalho: uma nova verificação, harness, guarda, abstração ou arquivo de teste torna-se um acompanhamento nomeado, não parte da correção. Adicione um teste com falha apenas para um bug de correção confirmado, e estenda um arquivo de teste existente.
• Após cada correção, o revisor verifica novamente apenas a correção: as descobertas citadas foram resolvidas e a correção introduziu algo? Uma correção mais sua nova verificação é uma rodada.

Pare e pergunte ao usuário quando uma rodada deixar as descobertas confirmadas inalteradas, uma correção crescer em arquivos ou maquinário que o plano não cobriu, ou descobertas bloqueantes permanecerem após a terceira rodada. Traga as descobertas não resolvidas literalmente, o que foi tentado, onde quebra com saída real, as opções (revisar o plano, aceitar um risco documentado, descartar o item como acompanhamento, separar o maquinário) e sua recomendação. Nunca abaixe a barra silenciosamente.

7. Fechar: o hand-off

O hand-off é a descrição final da alteração. Um HANDOFF.md de um coordenador fornece instruções de retomada. Aplique leituras seletivas e regras de ciclo de vida do registro em references/writing.md. Com um coordenador, retorne candidatos a memória originados e deixe atualizações compartilhadas com ele.

Nos modos Padrão e Profundo, a descrição da alteração carrega:

• o Objetivo, como o que um usuário pode agora fazer, e os Não-objetivos;
• Aceitar, e o que a evidência realmente mostrou;
• o que não pôde ser verificado, e por quê;
• quem revisou, ou "auto-revisão, não independente", ou que nenhuma revisão ocorreu, e o mesmo para um caminho que uma pessoa conduz;
• uma profundidade que o usuário reduziu, e o que você mostrou a eles antes de insistirem;
• descobertas não bloqueantes não corrigidas, uma linha cada;
• risco residual;
• no modo Profundo, o rollback como está agora.

Para trabalho atribuído, retorne caminhos de artefato e revisões, evidências, estado da revisão, solicitações não resolvidas e comandos modificadores ativos ou desconhecidos. Relate a conclusão local ao coordenador. Não reivindique conclusão da tarefa geral.

Ferramentas de revisão, segurança ou orquestração que o usuário adiciona suplementam a revisão independente, nunca a substituem.