fluxo-de-trabalho-de-desenvolvimento-de-projeto

Disciplina de desenvolvimento para agentes de IA de codificação. Reformule a solicitação e obtenha confirmação antes de codificar; divida o trabalho em camadas com critérios de conclusão verificáveis e verifique cada camada antes da próxima (verificador independente quando necessário); ataque decisões-chave com revisão adversarial ou autorrefutação explícita antes de se comprometer com elas; avance dentro do escopo confirmado e proponha qualquer coisa fora dele; registre cada armadilha em PITFALLS.md assim que for resolvida. Use ao iniciar ou continuar trabalhos de desenvolvimento não triviais — recursos de várias etapas, bugs que abrangem várias etapas, refatorações, escolhas de arquitetura ou abordagem — mesmo que o usuário não nomeie esta habilidade. Use também para solicitações independentes como "siga o fluxo de trabalho", "execute isso corretamente", "verifique isso", "critique este plano", "registre esta armadilha", "atualize as armadilhas" executando apenas a seção correspondente. Pule para perguntas e respostas puras e edições triviais de uma linha.

O que é fluxo-de-trabalho-de-desenvolvimento-de-projeto?

O fluxo de trabalho de desenvolvimento de projeto (Project Dev Workflow) é uma disciplina de trabalho sistemática projetada para agentes de IA de codificação em ferramentas como Claude Code, Cursor e Codex. Ela aborda falhas comuns de IA, como começar a codificar com base em uma solicitação mal interpretada, validar o próprio trabalho sem verificação externa, defender um design a partir de um único ponto de vista e repetir armadilhas anteriores. O fluxo de trabalho é dividido em seções: pré-voo (leitura de logs de armadilhas e regras do projeto), entendimento e confirmação da solicitação, planejamento em camadas com critérios de conclusão verificáveis, execução e verificação camada por camada, relatório final, revisão adversarial, execução proativa e registro em tempo real de armadilhas. Ele suporta camadas leve e padrão, modo autônomo e invocação de seção única para solicitações específicas. É útil para recursos de várias etapas, bugs complexos, refatorações e decisões de arquitetura, pois garante que o agente entenda corretamente a solicitação, divida o trabalho em incrementos verificáveis, verifique cada camada de forma independente (por meio de autoverificação ou um subagente verificador), avance apenas dentro do escopo confirmado e registre cada problema encontrado para evitá-lo no futuro. Para iniciar, o usuário pode solicitar 'siga o fluxo de trabalho' ou usar um comando como '/workflow'.

Funciona com✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/svd748xyz/project-dev-workflow/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 dizExecute
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 corretamenteo 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.md ou arquivos de regras semelhantes, siga-os também.
  • Estado do espaço de trabalho: se o projeto for um repositório git, verifique git status primeiro. 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:

ItemRequisito
SaídaO que especificamente existe no final desta camada
Critérios de conclusãoCondiçõ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çãoAutoverificaçã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 commit ou git push sem 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 diff ou 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 --filter e 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...

Habilidades Relacionadas