Fluxo de Trabalho de Desenvolvimento de Projeto
Uma disciplina de trabalho aplicada ao longo de um projeto de desenvolvimento. Ela aborda estas falhas: uma IA começa a codificar com base em uma solicitação mal interpretada; termina de escrever e então declara que seu próprio trabalho está bom; defende um design a partir de um único ponto de vista; faz apenas o que lhe foi dito; e repete uma armadilha que já havia encontrado da última vez.
O peso da disciplina deve corresponder ao peso da tarefa: tarefas pequenas assumem a camada leve — não execute um processo pelo processo.
O fluxo de trabalho completo:
Entrada: roteamento de seção única / decisão de camada (leve · padrão) / se deve trabalhar de forma autônoma
0. Pré-voo — leia o log de armadilhas e as regras do projeto, confirme o estado do espaço de trabalho
1. Entender — reformule a solicitação; aja somente após o usuário confirmar
2. Planejar — divida em camadas, cada uma com critérios de conclusão verificáveis
3. Executar e verificar — verifique cada camada pelos critérios, por si mesmo ou por meio de verificador; sem aprovação, sem próxima camada
4. Relatar — evidências, itens não verificados, críticas aceitas/rejeitadas, sugestões, novas armadilhas
Durante todo o processo: revisão adversarial (§5), execução proativa (§6), registro em tempo real de armadilhas (§7)
Entrada: decida como usar
Invocação de seção única
Quando o usuário nomeia apenas uma etapa, execute apenas essa seção; não execute o fluxo de trabalho completo:
| O usuário diz | Execute |
|---|---|
| critique / revise este plano / esta abordagem está OK | §5 apenas |
| verifique isso / confira se está correto | §3 verificação apenas. O objeto é o que o usuário especificou; se os critérios de conclusão não estiverem claros, alinhe-se com o usuário antes de verificar |
| registre esta armadilha / atualize as armadilhas | §7 apenas |
| siga o fluxo de trabalho / execute isso corretamente | o fluxo de trabalho completo (camada padrão) |
Camadas leve e padrão
Decida a camada antes de começar e indique qual você escolheu em uma linha na sua primeira resposta.
Camada leve — todas as três condições são válidas:
- a solicitação é inequívoca, com apenas uma leitura razoável;
- pode ser revertida facilmente, sem exclusão de dados, interfaces públicas ou impacto externo;
- a mudança é concentrada (um ponto de recurso, poucos arquivos) e uma única etapa de verificação decide o resultado.
A camada leve pula a reformulação, o particionamento em camadas e os subagentes, mas ainda observa §0 pré-voo, as regras de evidência da §3 e o registro de armadilhas da §7, e encerra com o relatório curto da §4.
Camada padrão: tudo o mais. Quando estiver em dúvida, use a camada padrão.
Se uma tarefa de camada leve se revelar mais complexa do que o previsto (arrasta outros módulos, surge ambiguidade, uma operação irreversível é necessária): atualize para a camada padrão imediatamente e faça a reformulação e confirmação retroativamente.
Modo autônomo
Quando o usuário disser explicitamente "apenas faça / não me pergunte / você decide", ou a tarefa for uma execução longa não supervisionada em um ambiente não interativo:
- §1 ainda escreve "meu entendimento", mas não aguarda confirmação. Cada item em "decisões que preciso de você" é decidido tomando a opção recomendada, registrada como uma suposição feita por si mesmo, e o trabalho prossegue;
- operações que são irreversíveis ou têm impacto externo (excluir dados, implantar, enviar, migração de dados, chamadas de API pagas) ainda não são realizadas; pule-as, liste-as no relatório e deixe-as para o usuário;
- o relatório final lista todas as suposições feitas por si mesmo juntas, para que o usuário possa corrigi-las posteriormente.
0. Pré-voo
- Log de armadilhas: se a raiz do projeto tiver
PITFALLS.md, leia-o antes de planejar; se o arquivo mantiver um índice no topo, leia o índice primeiro, depois as entradas relevantes para a tarefa atual. Se existir um log de nível de máquina em~/.agents/PITFALLS.local.md, leia-o também (veja §7 para escopo). Mencione as entradas relevantes para a tarefa pelo nome na reformulação ou no plano. - Regras do projeto: se o projeto tiver
AGENTS.md,CLAUDE.md,CONTRIBUTING.mdou arquivos de regras semelhantes, siga-os também. - Estado do espaço de trabalho: se o projeto for um repositório git, verifique
git statusprimeiro. Alterações não confirmadas que já existem pertencem ao usuário: lembre-se delas, não as sobrescreva e não as misture com suas próprias alterações. Se não for um repositório git e a mudança for arriscada, avise o usuário primeiro ou faça backup dos arquivos que você está prestes a modificar.
1. Entender e confirmar
A redação do usuário geralmente omite contexto, mistura objetivos com meios e deixa restrições não declaradas. Codificar com base na redação literal e errar custa muito mais do que uma rodada extra de perguntas.
Quando a reformulação e a confirmação são obrigatórias
Qualquer um destes torna a reformulação e a confirmação obrigatórias (exceto no modo autônomo):
- a solicitação tem duas ou mais leituras razoáveis, e as leituras levam a resultados materialmente diferentes;
- o usuário deu um objetivo em vez de uma instrução ("melhorar o login");
- o trabalho envolve operações irreversíveis, impacto externo, exclusão de dados ou alterações em interfaces públicas ou no modelo de dados;
- a mudança abrange vários módulos, ou é grande o suficiente para que ir na direção errada seja caro para desfazer.
Tarefas de camada leve podem ser feitas diretamente, com uma explicação posterior. Quando estiver em dúvida, trate como "confirmação necessária".
O que você pode fazer antes da confirmação
Você pode fazer pesquisa: ler código e documentação, executar comandos somente leitura (inspecionar o estado, executar testes existentes, verificar versões). Você não pode: modificar arquivos, instalar dependências, alterar a configuração ou executar qualquer comando com efeitos colaterais.
Formato da reformulação
Faça a pesquisa antes de reformular. Uma reformulação reconstrói o requisito com suas próprias palavras; não é uma recitação da frase do usuário. Exponha suas suposições para que o usuário possa ver rapidamente onde você pode estar errado.
**Meu entendimento**
- Objetivo: <o problema a resolver / o efeito a alcançar, uma ou duas frases>
- Entregáveis: <o que existirá no final: arquivos, funcionalidades, documentos…>
- No escopo: <o que você fará>
- Fora do escopo: <o que você explicitamente não fará, para evitar aumento de escopo>
- Restrições: <stack, estilo, áreas a não tocar, limites de tempo/recursos>
- Critérios de aceitação: <como o usuário decidirá que está pronto, o mais observável possível>
- Minhas suposições: <pontos não declarados que você inferiu>
**Decisões que preciso de você**
1. <pergunta>? Opção A: … / Opção B: … (estou inclinado a X porque …)
Se o ambiente fornecer uma ferramenta de pergunta de múltipla escolha, prefira-a para a parte "decisões que preciso", com uma opção recomendada.
Após a confirmação
- Trate a versão confirmada como a linha de base do requisito. Registre-a no plano ou na lista de tarefas; cada verificação posterior é julgada contra ela.
- Se a linha de base se revelar errada, ou o escopo precisar se expandir: pare, explique a mudança e seu impacto, re-confirme e continue. Não amplie ou reduza o escopo silenciosamente.
- Após o usuário confirmar, prossiga pelo plano sem voltar para perguntar "devo continuar?" a cada passo. Pare apenas para uma mudança de objetivo, uma operação irreversível ou uma compensação que o usuário deve decidir.
- Ao usar uma ferramenta de perguntas, um tempo limite ou uma pergunta não respondida não é consentimento: deixe esse item pendente, prossiga apenas com as partes que não dependem dele e liste os itens pendentes novamente no próximo relatório. Não prossiga silenciosamente com a opção recomendada.
2. Plano em camadas
Divida a tarefa em camadas (etapas); cada camada é um incremento que pode ser verificado por conta própria. Cada camada declara três coisas:
| Item | Requisito |
|---|---|
| Saída | O que especificamente existe no final desta camada |
| Critérios de conclusão | Condições verificáveis, por exemplo, "npm test está verde", "a interface X retorna Z para a entrada Y", "sem rolagem horizontal em 375px de largura", "o arquivo A não referencia mais B". Descrições que não podem ser verificadas — "boa qualidade de código", "basicamente funciona" — são proibidas |
| Método de verificação | Autoverificação ou um verificador independente (veja os critérios na §3) |
- Se o plano envolver compensações significativas (escolha de tecnologia, arquitetura, modelo de dados), execute uma rodada de revisão adversarial da §5 antes de finalizá-lo.
- Mostre o plano ao usuário de forma resumida. Para um plano pequeno já confirmado durante a reformulação, comece diretamente após mostrá-lo.
- Para tarefas longas, escreva o plano e o progresso em uma lista de tarefas ou arquivo de tarefas e mantenha-o atualizado, para que o trabalho possa ser retomado a partir do ponto de interrupção se a sessão for interrompida.
- Pontos de verificação: cada camada verificada é um ponto de verificação. Não execute
git commitougit pushsem o consentimento do usuário. Se o usuário concordar em confirmar por camada, confirme uma vez após cada camada ser aprovada, seguindo o estilo de mensagem de commit existente do projeto.
3. Execução e verificação camada por camada
Verifique cada camada antes de iniciar a próxima. Se a verificação falhar, corrija e verifique novamente. Se o mesmo critério falhar duas vezes seguidas, pare e analise a causa raiz primeiro (e considere registrar uma armadilha) em vez de corrigir no local.
Autoverificação ou um verificador independente
Qualquer um destes significa que você deve passar a verificação para um verificador independente:
- a camada é voltada para o usuário, a superfície de mudança é grande ou o risco é alto;
- os critérios de conclusão exigem realmente executar, operar ou comparar coisas para julgar, e não um único comando;
- é a entrega final de uma tarefa de camada padrão;
- você está profundamente investido em sua própria implementação e provavelmente verá tudo como correto.
A autoverificação é aceitável para: tarefas de camada leve; ou pequenas alterações cujos critérios são decididos por um único comando, com um resultado óbvio.
Usando o verificador
O valor do verificador reside em sua independência: ele não deve herdar o raciocínio ou a autojustificativa do implementador.
- Forneça a ele: a linha de base do requisito, os critérios de conclusão desta camada, os caminhos de arquivo relevantes, como executar as coisas e o intervalo de alterações (
git diffou um intervalo de commits). O intervalo de alterações é um fato, não uma linha de raciocínio, e ajuda o verificador a encontrar lugares que deveriam ter mudado, mas não mudaram. - Não forneça a ele: seu raciocínio de implementação, suas justificativas de compensação ou qualquer coisa como "acho que está bom agora".
- Permissões: ele não pode modificar código-fonte, configuração ou documentação. Ele pode executar comandos de verificação local (testes, builds, linters), e os artefatos de build resultantes são aceitáveis. Comandos com efeitos colaterais externos são proibidos — implantar, migração de dados,
git commit/git push, excluir dados, chamar APIs de produção ou pagas. - Exija que ele verifique cada critério de verdade (execute o comando, leia o código, inspecione a saída) e relate aprovado / reprovado / não é possível verificar por item com evidências, além de quaisquer problemas que encontrar fora dos critérios, ordenados por gravidade.
- As correções são suas para fazer, para que o verificador e o implementador não se tornem a mesma pessoa novamente.
- Se a implementação foi feita por um agente de codificação CLI (omp / codex / claude-code), verifique de acordo com a seção Verificação da habilidade
omp: leia o diff que ele produziu, procure especificamente por branches de condição que cobrem apenas o caminho feliz, execute o menor subconjunto independentemente com--filtere envie o retrabalho como "arquivo:linha + critério aprovado/reprovado + asserção esperada". - Modelos de prompt estão na seção "Subagente verificador" de references/subagent-prompts.md.
Se o ambiente atual não tiver capacidade de subagente, ou o usuário ou as regras do host proibirem subagentes: mude você mesmo para o papel de verificador, verifique cada critério com o mesmo modelo e escreva as evidências, em vez de marcar caixas de memória.
Lidando com resultados de verificação
- Critérios reprovados: corrija e verifique novamente (continue com o mesmo verificador ou despache um novo).
- Você acredita que o verificador está errado: você deve produzir contra-evidências (um comando e sua saída, um arquivo:linha) para anular o veredito e declarar no relatório qual veredito você anulou e com base em quê. Não se convença disso apenas por argumentação.
- Problemas encontrados fora dos critérios: apenas os "graves" — falhar a linha de base do requisito, dados errados, travamentos, problemas de segurança — bloqueiam a próxima camada. Registre o restante e liste-os no relatório, ou mova-os para sugestões fora do escopo.
Regras de evidência
- Qualquer coisa que não foi realmente executada ou inspecionada não pode ser chamada de "pronta" ou "aprovada". A única frase permitida é "implementado, não verificado".
- Testes locais aprovados não são aceitação do usuário. Testes de unidade aprovados não são um recurso funcional. Declare qual nível você realmente verificou.
4. Relatório final
Camada padrão, um relatório após todas as camadas estarem concluídas:
**Conclusão**: <cada item da linha de base do requisito, abordado por vez>
**Evidências de verificação**: <o que foi executado e o que retornou; quais itens um verificador verificou; quais vereditos de verificação você anulou e com base em quê>
**Não verificado / limitações conhecidas**: <caminhos não exercitados, lacunas conhecidas>
**Suposições feitas por si mesmo**: <modo autônomo apenas: o que você decidiu, quais operações irreversíveis você pulou>
**Resultado da crítica**: <quais críticas as decisões-chave receberam, quais foram aceitas e quais rejeitadas, e por quê>
**Sugestões fora do escopo**: <propostas da §6 que precisam da decisão do usuário, com valor e custo>
**Novas / armadilhas atualizadas**: <títulos das entradas escritas>
A linha "Não verificado / limitações conhecidas" é obrigatória; quando realmente não houver nenhuma, escreva "nenhuma" e explique por que você está confiante. As outras linhas podem ser omitidas quando vazias.
Camada leve, o formato curto:
**O que foi feito**: <uma ou duas frases>
**Como foi verificado**: <comando + resultado>
**Limitações conhecidas**: <apenas se houver>
O relatório declara apenas fatos e evidências. Sem autoavaliação como "perfeitamente implementado", "muito elegante", "melhoria massiva".
O que os usuários mais reclamam em projetos longos é o progresso em caixa-preta: relatar apenas este incremento os deixa incapazes de julgar onde está o todo. Periodicamente — ou sempre que for solicitado — entregue um panorama do zero até agora: cronograma de etapas e cada um...