Fluxo de Trabalho de Design e Implementação de Soluções
Princípio Central
Discuta primeiro e depois escreva o código. Este fluxo de trabalho força a separação entre "pensar" e "fazer":
- Fase de Discussão: Apenas diálogo, sem escrever código. Todas as conclusões são registradas no Documento de Comunicação.
- Fase de Design: Consolide o consenso em um Documento de Design, que será a única fonte da verdade.
- Fase de Implementação: Gere um Documento de Implementação com base no documento de design e execute os passos.
Se a discussão não tiver conclusão ou o usuário não disser explicitamente "pode começar a implementação", nunca toque no código. Se houver dúvidas, continue discutindo até que ambas as partes estejam satisfeitas.
Estrutura do Diretório de Documentos
Fixo no diretório docs/design/ na raiz do projeto. Cada tarefa tem sua própria subpasta:
Raiz do Projeto/
└── docs/design/
├── README.md ← Visão geral global das tarefas (ponto de entrada para múltiplas tarefas, leia primeiro)
├── 01-Módulo de Autenticação de Usuário/
│ ├── 00-Status da Tarefa.md ← Ponto de ancoragem de memória entre contextos
│ ├── 01-Comunicação.md
│ ├── 02-Design.md ← Inclui critérios de aceitação
│ ├── 03-Implementação.md
│ └── 04-Testes.md ← Conjunto de casos de teste (gerado na fase de planejamento da implementação)
└── 02-Reestruturação de Pagamentos/
└── ...
Regras de Nomenclatura:
- Pastas de tarefas: Número sequencial global de dois dígitos + Nome da tarefa, ex:
01-Módulo de Autenticação de Usuário,02-Reestruturação de Pagamentos. Os números são sequenciais entre tarefas para garantir a ordenação por criação. - Documentos dentro da tarefa: Prefixo de fase fixo:
00-Status da Tarefa/01-Comunicação/02-Design/03-Implementação/04-Testes. O prefixo fixo permite localizar o mesmo tipo de documento em qualquer tarefa.
Como determinar o número ao entrar em uma tarefa pela primeira vez: Verifique o maior número de pasta existente em docs/design/ e adicione +1. Se o diretório não existir, comece com 01.
Primeiros Passos em Cada Novo Diálogo (Mecanismo de Memória Multi-Contexto)
Este fluxo de trabalho pode ser executado em vários contextos de diálogo. Para evitar ter que reler todo o código ou perder a memória a cada novo diálogo, siga esta ordem para recuperar o contexto:
- Leia
docs/design/README.md— Visão geral global das tarefas, confirme quais tarefas existem e em que fase estão. Se o usuário já especificou uma tarefa, vá diretamente para ela. - Leia
00-Status da Tarefa.md— Ponto de ancoragem de memória da tarefa atual, confirme o próximo passo. - Leia o documento correspondente à fase atual (ex: na fase de design, leia
02-Design.md; na fase de implementação, leia03-Implementação.md). - Leia o código apenas quando for necessário verificar, e não como primeiro meio de recuperação de contexto.
O 00-Status da Tarefa.md deve manter: resumo da tarefa em uma frase, fase atual, resumo de decisões importantes, pendências e dúvidas, índice de documentos, log de troca de contexto, registro de alterações (cobrindo modificações e reversões, veja a seção "Alterações durante a Implementação").
As Quatro Fases do Fluxo de Trabalho e seus Documentos
Fase Um: Discussão (Saída → Documento de Comunicação)
Gatilho: O usuário propõe uma nova demanda, funcionalidade, módulo, ou tem dúvidas sobre um plano existente.
Restrições de Comportamento:
- Nesta fase, apenas discuta, não escreva nenhum código de negócio.
- Registre cada troca significativa (decisão chave, alternativa rejeitada, consenso alcançado) no
01-Comunicação.md. - Rastreamento de Dúvidas Pendentes: Mantenha uma lista de "Dúvidas Pendentes" no topo do
01-Comunicação.md. Atualize-a ao final de cada discussão — quais perguntas ainda estão abertas, quais surgiram, quais foram respondidas. O critério para avançar para a fase de design é se esta lista está vazia ou não. Isso torna o progresso da discussão visível. - As discussões podem acontecer em várias rodadas e em múltiplos diálogos.
- Quando o usuário disser "está bom", "vamos definir assim", "pode começar o design", e a lista de dúvidas estiver vazia, vá para a Fase Dois.
Quando continuar discutindo em vez de avançar: Enquanto houver dúvidas de design não resolvidas, divergências técnicas ou limites não claros, continue na Fase Um. É melhor fazer mais uma rodada de perguntas do que avançar com suposições vagas.
Fase Dois: Design (Saída → Documento de Design)
Gatilho: A discussão chegou a um consenso, a lista de dúvidas pendentes está vazia e o usuário concordou em formalizar a solução.
Restrições de Comportamento:
- Organize as conclusões da comunicação em um
02-Design.mdestruturado. O documento de design é a única fonte da verdade. - O documento de design deve ser o mais completo possível: Deve ser uma solução determinística e executável, sem resquícios de "a definir" ou "decidir na implementação". A completude é garantida por duas coisas: comunicação exaustiva e leitura do código existente para confirmar fatos sobre implementações existentes (formas de interface, estrutura de tabelas, formas de chamada, etc.). A restrição "na fase de design só discutir, não escrever código" se aplica ao código de negócio; ler código existente para o design é pesquisa, não implementação, e não viola a restrição. É melhor gastar mais tempo refinando o design do que entrar na implementação com lacunas — qualquer lacuna resultará em retrabalho ou desvios.
- Os critérios de aceitação são parte do design: Além de "o que fazer" e "por que", o documento de design deve definir "o que significa estar pronto" — ou seja, critérios de aceitação abstratos (em nível de regra, ex: "palavras de alto risco devem ser bloqueadas, o artigo não é salvo"). Os critérios de aceitação definem os limites da demanda e são a última peça da completude do design. Um documento de design sem critérios de aceitação não tem uma definição objetiva de "pronto". Os casos de teste específicos (nível de instância) não vão no documento de design, e sim no
04-Testes.md, que será gerado durante a fase de planejamento da implementação traduzindo os critérios de aceitação em casos de teste. - Registro de Alterações de Design: Mantenha um bloco "Registro de Alterações de Design" no documento de design. Cada alteração importante deve ser registrada em uma linha (data, o que mudou, por que). Isso complementa o
01-Comunicação.md— o registro de comunicação é um histórico cronológico, o documento de design contém as conclusões, e o registro de alterações é o histórico da evolução das conclusões. Isso torna a regra de ouro "mudanças de design vão no documento de design, não no de implementação" executável sem perder o histórico. - Após concluir o documento de design, atualize o
00-Status da Tarefa.mdpara "design concluído, aguardando implementação" e sincronize a fase da tarefa nodocs/design/README.md.
Fase Três: Planejamento da Implementação (Saída → Documento de Implementação)
Gatilho: O documento de design está finalizado.
Restrições de Comportamento:
- Gere o
03-Implementação.mdcom base no documento de design, dividindo a solução em uma lista de passos executáveis e marcáveis. - Ao mesmo tempo, traduza os "critérios de aceitação" do documento de design em casos de teste específicos e gere o
04-Testes.md: Os casos de teste são a instanciação dos critérios de aceitação (ex: critério "palavras de alto risco devem ser bloqueadas" → caso de teste "Inserir texto com palavra de alto risco, esperar retorno 40901, artigo não salvo"). Os casos de teste são divididos em quatro camadas: Funcional (T-F), Exceção (T-EX), Regressão (T-R), API (T-API). Formato de numeraçãoT-{Tipo}-{Número de dois dígitos}. Modelo emassets/test.md. - O documento de implementação é "como fazer", o documento de teste é "o que testar e qual o resultado esperado", o documento de design é "o que e por que fazer". Eles têm responsabilidades diferentes. Não copie detalhes do design para o documento de implementação nem inclua mudanças de solução no documento de implementação.
- O documento de implementação é puramente uma decomposição de passos. Cada passo é apenas "implementar de acordo com a parte X do documento de design" e não tem a responsabilidade de "completar o design". Se, ao decompor os passos, você perceber que um passo exige "confirmar a forma da interface" ou "decidir um campo" primeiro, significa que o design não está completo — você deve voltar para a Fase Dois e completar o design, em vez de colocar um passo "completar o design" no documento de implementação. Em suma: o documento de implementação não deve conter nenhuma ação do tipo "ler código para determinar a solução", apenas ações do tipo "implementar de acordo com a solução definida".
- As ações de teste no documento de implementação devem apenas referenciar os números dos casos de teste, não repetir o conteúdo dos casos. Após cada passo, para verificar, escreva "Verificar de acordo com o caso de teste T-XX-XX". Os casos de teste em si ficam centralizados no
04-Testes.md. - Os passos de implementação são divididos em passos grandes e passos pequenos, ambos com suas próprias marcas de conclusão independentes.
- Após concluir o documento de implementação, atualize o
00-Status da Tarefa.mdpara "aguardando implementação".
Fase Quatro: Implementação (Executar os Passos do Documento de Implementação)
Gatilho: O usuário diz "pode começar a implementação", "mãos à obra", "siga o documento".
Restrições de Comportamento:
- Siga rigorosamente os passos do
03-Implementação.md. Após concluir cada passo, atualize a marca no documento e registre brevemente o resultado. - Após cada passo, verifique de acordo com os casos de teste referenciados no
04-Testes.md; se um caso de teste falhar, o passo não está concluído. Identifique o problema (é um bug de implementação ou um problema no design/caso de teste? Se for o último, siga o mecanismo de modificação/reversão). Após todos os passos, execute o conjunto de testes de regressão (T-R). - Se você encontrar algo inconsistente com o documento de design, pare: Primeiro, atualize o
02-Design.md(incluindo o registro de alterações), depois sincronize as revisões no03-Implementação.mde04-Testes.md(os casos de teste mudam com a solução), e então continue. Nunca se desvie do plano enquanto implementa. - Quaisquer lacunas de design, novas restrições ou mudanças de API descobertas durante a implementação devem ser registradas no bloco "Registro de Alterações de Design" do
02-Design.md, mantendo o documento de design atualizado. - Em cada transição de fase e em cada marco importante, atualize o
00-Status da Tarefa.mde odocs/design/README.md.
Alterações durante a Implementação: Mecanismo de Modificação vs. Mecanismo de Reversão
O fluxo de trabalho é nominalmente Discussão → Design → Planejamento da Implementação → Implementação, mas descobrir desvios entre o plano, os requisitos e a realidade durante a implementação é esperado e normal, não uma exceção — mesmo o design mais completo não pode prever 100% dos detalhes da implementação.
Existem dois tipos de desvio, com naturezas completamente diferentes, que devem ser tratados com processos distintos:
| Modificação | Reversão | |
|---|---|---|
| Natureza | A solução está no geral correta, mas há lacunas/omissões a serem preenchidas | A parte da solução está fundamentalmente errada e precisa ser refeita |
| Solução principal | Permanece | É descartada |
| Produtos já concluídos | Não são invalidados | São parcialmente invalidados |
| Frequência | Normal | Raro |
| Cenário típico | Campo faltando, branch faltando, valor de dicionário faltando, um novo ponto de demanda esquecido | Direção errada, suposição central não se confirma, inconsistente com o negócio real |
Primeiro, determine a qual categoria o desvio pertence (veja as seções correspondentes para a responsabilidade pela determinação) e, em seguida, siga o processo correspondente. Se não tiver certeza, incline-se para tratar como "modificação" e confirme com o usuário. Só siga o processo de "reversão" se houver um erro fundamental claro.
Mecanismo de Modificação (Normal, Leve, Incremental)
Três condições para determinação (todas devem ser satisfeitas para ser considerado uma modificação):
- A direção da solução principal está correta.
- Não requer invalidar os produtos já concluídos.
- É apenas uma complementação/ajuste fino (adicionar campo, branch, valor de dicionário, um novo ponto de demanda que foi esquecido, etc.).
Fluxo do Processo (ordem estrita, não invertível):
- Pare a implementação atual
- Primeiro, atualize o documento de design: Adicione o conteúdo ao bloco correspondente do documento de design e registre uma linha no registro de alterações do design
- Aguarde a confirmação do usuário sobre esta modificação (não pode decidir e implementar sozinho)
- Após a confirmação do usuário, revisão sincronizada do documento de implementação
- Continue a implementação
Princípio chave: Primeiro atualize o design, depois implemente — a ordem não pode ser invertida. É proibido "implementar primeiro e depois atualizar o documento de design", pois isso faria o documento de design degenerar para um registro posterior, em vez de ser a fonte da verdade. Mesmo que seja apenas adicionar um campo, este fluxo deve ser seguido.
Mecanismo de Reversão (Raro, Pesado, Descartar)
Três condições para determinação (todas devem ser satisfeitas para ser considerado uma reversão):
- A direção da solução principal está problemática.
- Os produtos já concluídos precisam ser invalidados.
- Requer nova discussão/design.
Responsabilidade pela Determinação: A decisão final de reverter é do usuário. Quando a IA suspeitar de um erro fundamental, ela só pode sugerir uma possível reversão e explicar os motivos; a decisão final de reverter ou não é do usuário. A IA não pode decidir reverter por conta própria.
Fluxo do Processo:
- Pare a implementação atual
- A IA sugere uma possível reversão, explicando os motivos (qual parte da direção está errada, por que não é válida)
- Aguarde a decisão final do usuário sobre reverter ou não
- Se o usuário confirmar a reversão, registre uma linha no
00-Status da Tarefa.md: Fase de onde para onde reverteu, motivo, quais produtos foram invalidados - Volte para a fase de discussão/design para realinhamento
- A nova solução gerada deve ser depositada seguindo o fluxo original: novas dúvidas vão para a lista de dúvidas pendentes do
01-Comunicação.md; mudanças de solução vão para o02-Design.mdcom registro de alterações - Sincronize a revisão do
03-Implementação.md
Regras de Ouro Comuns aos Dois Mecanismos
- Mudanças de solução sempre alteram o documento de design, não o documento de implementação diretamente
- Primeiro atualize o design, depois implemente — a ordem não pode ser invertida (não fazer e depois corrigir)
- Qualquer alteração deve ser registrada no documento de status da tarefa (modificações no registro de alterações do design; reversões com um registro de reversão adicional)
- A confirmação do usuário é um checkpoint obrigatório para todas as alterações (modificações precisam de confirmação da complementação da solução; reversões precisam de confirmação da determinação em si)
Mentalidade: Desvios não são o problema; o problema é implementar teimosamente com o desvio ou desviar-se silenciosamente do plano. Torne as "modificações" leves e de baixo atrito (o normal deve ser fluido), torne as "reversões" cuidadosas (refazer do zero precisa da aprovação do usuário), e documente ambas de forma padronizada. O custo do retrabalho será o menor possível.
Especificação de Marcação de Passos no Documento de Implementação
Os passos de implementação são divididos em dois níveis: passos grandes e passos pequenos. Ambos devem ter marcas de conclusão independentes. Passos grandes são divididos em blocos com títulos e contagem de progresso; passos pequenos usam checkboxes de quatro estados.
Marcação de Quatro Estados:
- [ ] Não iniciado
- [~] Em andamento
- [x] Concluído
- [!] Bloqueado (razão indicada abaixo)
Exemplo de Organização:
### 1. Camada de Banco de Dados ✅ 1/3
- [x] 1.1 Criar tabela users (com script de migração)
- [~] 1.2 Criar índices
- [ ] 1.3 Escrever dados de seed
### 2. Camada de API ⬜ 0/2
- [ ] 2.1 Implementar POST /api/users
- [ ] 2.2 Integrar middleware de autenticação
Símbolos de Estado do Passo Grande:
⬜Não iniciado (0/N concluído)🌗Em andamento (parcialmente concluído)✅Totalmente concluído (N/N)
Formato de contagem de progresso: Concluídos/Total, colocado no final do título do passo grande. Isso permite ver o progresso geral e localizar em qual passo pequeno está o gargalo.
Tratamento Especial para Projetos Backend
Se o projeto atual for puramente backend (sem código frontend ou com repositórios backend e frontend separados):
- O documento de design e o documento de implementação cobrem apenas o conteúdo do backend, sem envolver a implementação do frontend.
- Qualquer nova interface ou alteração em interface antiga (URL, método, parâmetros de entrada/saída, códigos de erro, requisitos de autenticação, etc.) deve ter um bloco dedicado chamado "Lista de Alterações de Interface" no
02-Design.md. - O formato da lista de interfaces deve permitir que a equipe de frontend a use diretamente para integração. Sugestões de campos: Caminho da interface, Método de requisição, Exemplo de corpo de requisição, Exemplo de resposta de sucesso, Tabela de códigos de erro, Requisitos de autenticação, Observações.
- Esta lista de interfaces é um entregável para o frontend e deve ser autocontida e legível de forma independente.
- A lista de interfaces deve fornecer conclusões determinísticas durante a fase de design, sendo proibido adiar a decisão para a fase de implementação. Qualquer fato que dependa do código existente para ser determinado (ex: "esta interface é nova ou uma alteração?", "o caminho permanece o mesmo ou muda?", "os parâmetros de entrada seguem qual estrutura existente?") deve ser definido durante a fase de design, lendo o código existente, e as conclusões devem ser escritas na lista de interfaces. A restrição "na fase de design só discutir, não escrever código" se aplica ao código de negócio — ler o código existente para confirmar a forma da interface é pesquisa de design, não implementação, e não viola a restrição. Frases vagas como "depende do código existente" ou "a confirmar na implementação" são proibidas no documento de design. Também não é permitido o uso de tags como [A Confirmar na Implementação] para legitimar a incerteza. A lista de interfaces deve ser completamente determinística quando entregue ao frontend, caso contrário, o frontend não pode integrar.
Critérios de Aceitação e Testes (Três Camadas de Responsabilidade)
Os testes não são improvisados na fase de implementação; eles fazem parte de um sistema que permeia desde o design até a implementação. As três camadas têm responsabilidades estritamente separadas:
| Camada | Veículo | Conteúdo | Natureza | Fase de Produção |
|---|---|---|---|---|
| Regra | 02-Design.md | Critério de aceitação abstrato | "O que significa estar pronto para os requisitos" | Design |
| Instância | 04-Testes.md | Casos de teste específicos | "Com qual entrada, qual saída esperada" | Planejamento da Implementação |
| Ação | 03-Implementação.md | Passos + Referência a casos de teste | "Qual ação executar, qual caso de teste usar para verificar" | Planejamento da Implementação |
Por que essa separação? O critério de aceitação define o limite dos requisitos (pertence ao design), o caso de teste é a instanciação desse limite, e a implementação é a ação de execução. Com as três camadas separadas, se a regra mudar, vá para o documento de design; se o caso de teste mudar, vá para o documento de teste; se a ação mudar, vá para o documento de implementação — cada um tem sua fonte da verdade, sem contaminação mútua.
Camadas e Numeração de Casos de Teste:
| Prefixo | Tipo | Uso |
|---|---|---|
T-F- | Caso Funcional | Fluxo positivo |
T-EX- | Caso de Exceção | Fluxo negativo, casos limite, branches de erro |
T-R- | Caso de Regressão | Caminhos críticos a serem testados após modificação/reversão (selecionados de F/EX, para evitar que uma mudança em A quebre B) |
T-API- | Caso de Interface | Corresponde a cada interface na "Lista de Alterações de Interface" do documento de design |
Todas as tarefas devem obrigatoriamente gerar o 04-Testes.md: Esta habilidade é destinada a tarefas de médio a grande porte; demandas pequenas não acionariam a habilidade. Portanto, não é feita uma avaliação de complexidade — uma vez que a tarefa entra na fase de planejamento da implementação, o documento de teste é obrigatório.
Relação entre Modificação/Reversão e Testes: Após passar pelo mecanismo de modificação ou reversão, a solução muda → os casos de teste são atualizados de acordo (primeiro altere o critério de aceitação no design, depois altere os casos de teste) e execute pelo menos uma vez o conjunto de regressão (T-R) para evitar que uma modificação local cause uma regressão global.
Modo de Extensão A: Divisão de Tarefas (Tarefas Grandes com Múltiplos Módulos)
Quando ativar: Quando uma tarefa grande contém naturalmente vários submódulos semi-independentes (ex: "Sistema de Revisão = Filtro de Palavras Sensíveis + Revisão de Imagens + Workstation de Revisão Manual") e um único contexto não é suficiente. Ative quando o usuário declarar explicitamente na fase de discussão que "esta é uma tarefa grande, vou dividir em módulos". Não determine automaticamente o tamanho da tarefa; o usuário deve acionar explicitamente.
Mecanismo Central: A tarefa pai é responsável pelo design geral + divisão em módulos + contratos de interface entre módulos + orquestração. As subtarefas seguem o fluxo completo de 4 fases dentro dos limites definidos pela tarefa pai.
A.1 Estrutura de Documentos de Tarefas Pai e Filhas (Aninhada)
Raiz do Projeto/docs/design/
├── README.md ← Visão geral global das tarefas
├── 01-Sistema de Revisão/ ← Tarefa pai
│ ├── 00-Status da Tarefa.md ← Usa o modelo parent-task-status.md, com lista de subtarefas
│ ├── 01-Comunicação.md ← Discussão geral em nível de tarefa pai
│ ├── 02-Design.md ← Arquitetura geral + divisão em módulos + contratos de interface entre módulos
│ ├── 03-Implementação.md ← Apenas orquestração da tarefa pai (testes de integração, alinhamento), não escreve detalhes internos dos módulos
│ ├── 04-Testes.md ← Apenas testes de integração entre módulos
│ └── Subtarefas/
│ ├── 01-1-Filtro de Palavras Sensíveis/ ← Subtarefa (documentos completos das 4 fases, usando modelo comum)
│ ├── 01-2-Revisão de Imagens/
│ └── 01-3-Workstation de Revisão Manual/
└── 02-Outras Tarefas/
As subtarefas usam o modelo comum (task-status / communication / design / implementation / test), sem nenhuma alteração. A tarefa pai usa o modelo assets/parent-task-status.md, que possui um bloco adicional "Lista de Subtarefas". O documento de design da tarefa pai, além do modelo de design comum, deve conter obrigatoriamente dois blocos adicionais:
- Divisão em Módulos: Liste em quais subtarefas será dividido, com limites de responsabilidade de cada uma.
- Contratos de Interface entre Módulos: Acordos de interface entre as subtarefas (assinatura da interface, formato de dados, método de chamada, etc.). Esta é a chave para as subtarefas poderem ser executadas de forma independente e deve ser definida durante a fase de design.
A.2 Progressão das Fases da Tarefa Pai (Estritamente Sequencial)
- A tarefa pai primeiro passa por "Discussão + Design", e deve produzir a Divisão em Módulos + Contratos de Interface entre Módulos.
- Após o design da tarefa pai ser confirmado pelo usuário, as subtarefas podem ser iniciadas.
- Ao iniciar as subtarefas, a ordem de início deve respeitar as dependências: A fase de design da tarefa pai deve definir claramente as dependências entre as subtarefas (ex: "a Workstation de Revisão Manual depende da interface do Filtro de Palavras Sensíveis"). As subtarefas das quais outras dependem devem ser concluídas primeiro, antes das dependentes.
- Cada subtarefa segue seu próprio ciclo completo de 4 fases (podem ser paralelas, desde que as dependências sejam satisfeitas). Como iniciar múltiplas subtarefas em paralelo depende do framework de agente utilizado (geralmente através de subtarefas em segundo plano/assíncronas). Para referência de implementação concreta, veja B.5.
- Após todas as subtarefas serem concluídas, a tarefa pai executa um encerramento com "Testes de Integração entre Módulos".
Por que a tarefa pai e as subtarefas não podem ser paralelas? O principal produto da tarefa pai são os contratos de interface entre módulos, que são o pré-requisito para as subtarefas serem independentes. Se as subtarefas forem iniciadas antes de o design da tarefa pai estar definido, elas inevitavelmente entrarão em conflito.
A.3 Subtarefas não Podem Alterar os Contratos de Interface Definidos pela Tarefa Pai por Conta Própria
Os contratos de interface são o consenso entre vários módulos. Se qualquer subtarefa os alterar por conta própria, as outras subtarefas ficarão fora de controle. Se uma subtarefa descobrir um problema com o contrato de interface da tarefa pai:
- Não pode modificar o contrato de interface por conta própria.
- Precisa voltar para a tarefa pai e seguir o mecanismo de modificação: Atualizar o
02-Design.mdda tarefa pai (com registro de alterações) → Aguardar confirmação do usuário → Notificar todas as subtarefas que dependem desta interface → As subtarefas afetadas devem revisar seus próprios documentos de design/implementação/testes.
A.4 Limite de Profundidade de Aninhamento: Apenas Um Nível
Tarefa pai → Subtarefa. Não é permitido aninhar mais níveis (subtarefas não podem ter suas próprias subtarefas). Motivo: Muitos níveis de aninhamento tornam as relações entre tarefas extremamente complexas. Se uma subtarefa ainda precisar ser subdividida, geralmente significa que a granularidade da divisão da tarefa está errada — ela deve ser replanejada como uma tarefa pai independente, em vez de ser colocada em uma estrutura de múltiplos níveis existente.
A.5 Uso dos Modelos para a Tarefa Pai
- Documento de status da tarefa pai: Use
assets/parent-task-status.md(não use o modelo comum de task-status). - Outros documentos da tarefa pai (comunicação/design/implementação/testes): Use o modelo comum, mas o documento de design deve incluir adicionalmente os dois blocos descritos em A.1.
- Todos os documentos das subtarefas: Use o modelo comum, sem nenhuma alteração.
Modo de Extensão B: Implementação com Agente Duplo (Segmentação da Implementação)
Quando ativar: Dentro de uma única tarefa, a combinação das fases de implementação e teste torna o contexto muito longo. Ative quando o usuário declarar explicitamente no início da fase de implementação "usar modo de agente duplo para implementação". Não determine automaticamente; o usuário deve acionar explicitamente.
Mecanismo Central: A fase de implementação é dividida internamente em duas etapas seriais — Agente de Implementação (escreve código de acordo com o 03-Implementação.md) + Agente de Teste (valida de acordo com o 04-Testes.md). Eles são dois agentes fisicamente independentes (dois contextos independentes) que se comunicam através do documento de status da tarefa. O valor central do modo B é o isolamento de contexto: o agente de implementação não carrega o contexto de teste, e o agente de teste não carrega os detalhes da implementação.
B.1 Limites de Responsabilidade entre Implementação e Teste
- Agente de Implementação: Executa apenas os passos do
03-Implementação.md(escrever código). Após a conclusão, não executa os testes por conta própria, mas declara no bloco "Estado da Segmentação da Implementação" do00-Status da Tarefa.mdque "Implementação concluída, versão X, pode entrar em teste". - Agente de Teste: Executa a validação com base no
03-Implementação.md+04-Testes.mdmais recentes. Sua responsabilidade é estritamente limitada a "executar casos, julgar falhas, relatar". Não é responsável por corrigir código (mesmo que encontre um bug de implementação, não corrige por conta própria).
B.2 Tratamento de Falhas Encontradas pelo Agente de Teste
Quando o agente de teste encontra uma falha em um caso de teste, ele deve primeiro julgar a causa raiz da falha (o agente de teste vê o comportamento real, tem a melhor informação para fazer o julgamento inicial):
- Determinação como bug de implementação (o código está errado, o design está correto) → Relatar para o agente de implementação, que fará a correção. Após a correção, o caso de teste deve ser reexecutado pelo agente de teste para confirmar a aprovação antes de prosseguir (a declaração unilateral do agente de implementação de que "está corrigido" não fecha o ciclo).
- Determinação como bug de design (o código foi escrito conforme o design, mas o design em si está problemático) → Não pode alterar o design por conta própria, dispara o mecanismo de modificação: Parar → Atualizar o design → Aguardar confirmação do usuário → Alterar a implementação → Alterar os testes → Voltar para o agente de teste para reexecução.
Se o julgamento estiver errado, o usuário corrigirá. Mas "alterar o design" tem um grande impacto e requer a aprovação do usuário.
B.3 Bloco de Estado da Segmentação da Implementação
O 00-Status da Tarefa.md ganha um bloco opcional (preenchido apenas quando o modo B está ativo; vazio no modo normal):
## Estado da Segmentação da Implementação (Modo B apenas; deixe vazio no modo normal)
- Etapa atual: Implementação / Teste
- Versão da Implementação: (incrementada pelo agente de implementação a cada conclusão ou correção)
- Declaração de Conclusão da Implementação: YYYY-MM-DD, o agente de implementação declarou que pode entrar em teste
- Progresso dos Testes:
- Aprovados: T-F-01, T-F-02, ...
- Falhos Aguardando Correção: T-EX-03 (bug de implementação, relatado ao agente de implementação), ...
- Aguardando Reexecução: T-EX-03 (agente de implementação corrigiu, aguardando reexecução pelo agente de teste)
Tanto o agente de implementação quanto o agente de teste leem e escrevem neste bloco. Ele é o único ponto de passagem entre os dois.
B.4 Combinação com A (A+B)
A e B são ortogonais e podem ser combinados: Tarefa grande dividida em subtarefas com A, e cada subtarefa internamente dividida em implementação + teste com B. Na combinação, nenhum mecanismo adicional é necessário — porque as subtarefas são tarefas comuns (A.1 já explicou que subtarefas usam o modelo comum), portanto, as subtarefas suportam naturalmente o modo B. Forma de ativação: Design da tarefa pai + após as subtarefas serem iniciadas, cada subtarefa decide, no início de sua fase de implementação, se ativa ou não o modo B.
B.5 Diretrizes de Orquestração de Agentes
O modo B exige dois agentes fisicamente independentes (agente de implementação e agente de teste) que se comunicam indiretamente através do bloco "Estado da Segmentação da Implementação" e não se comunicam diretamente um com o outro. A forma exata de fazer a alternância depende do framework de agente que você está usando.
Independentemente do framework, siga o mesmo padrão de orquestração geral:
- Um orquestrador (que pode ser o agente principal, um script externo de orquestração, ou o próprio usuário) lê o bloco "Estado da Segmentação da Implementação" para determinar a etapa atual.
- O orquestrador inicia o agente de implementação e passa os caminhos dos documentos de design/implementação, instruindo-o a avançar de acordo com o
03-Implementação.mde, ao concluir, atualizar o bloco de estado. - Após a etapa de implementação terminar, o orquestrador inicia o agente de teste e passa os caminhos dos documentos de teste, instruindo-o a executar os casos de teste de acordo com o
04-Testes.mde escrever os resultados (incluindo o julgamento de falha) no bloco de estado. - Com base nos resultados de teste no bloco de estado, o orquestrador decide o próximo passo: se for bug de implementação, volta para o agente de implementação corrigir e reexecutar; se for bug de design, para e relata ao usuário para seguir o mecanismo de modificação; se todos passarem, finaliza.
Pontos-chave gerais:
- O agente de implementação e o agente de teste cada um estabelece seu próprio contexto de forma independente, sem contaminação mútua — este é o núcleo do isolamento de contexto do modo B.
- Os dois agentes não se percebem diretamente; eles se comunicam indiretamente apenas através do documento compartilhado "Estado da Segmentação da Implementação".
- O orquestrador apenas "lê o estado → julga → despacha", sem participar da implementação ou dos testes em si.
Referência de implementação para clientes específicos: Diferentes frameworks de agente têm diferentes capacidades de subagentes, tarefas em segundo plano, ou múltiplas janelas. Este documento não trava uma implementação específica. Ao usar o ZCode, veja assets/references/zcode-scheduling.md (carregue sob demanda: leia apenas quando o modo B estiver ativado e instruções operacionais específicas forem necessárias). Outros clientes podem se referir ao raciocínio desse arquivo e fazer adaptações de acordo com suas próprias capacidades.
Limite importante: A habilidade não trava a implementação de orquestração específica
A habilidade define o protocolo de passagem (formato e semântica do bloco de estado da segmentação da implementação) e as responsabilidades dos papéis (o que cada agente faz), mas não trava como a orquestração é feita. Qualquer framework que possa "ler arquivos, iniciar subtarefas, escrever arquivos" pode implementar o modo B.
Princípio de Confirmação para Transições de Fase
As transições entre fases não são automáticas; requerem um sinal explícito:
| Condição de Entrada | Condição Satisfeita |
|---|---|
| Entrada em Discussão | (A habilidade é ativada manualmente) |
| Discussão → Design | O usuário concorda explicitamente em formalizar a solução E a lista de dúvidas pendentes está vazia |
| Design → Planejamento da Implementação | O documento de design está concluído e aprovado pelo usuário |
| Planejamento da Implementação → Implementação | O usuário solicita explicitamente para começar |
| Implementação → Design (Modificação) | Uma lacuna na solução é descoberta durante a implementação, pare e modifique o design seguindo o "Mecanismo de Modificação", aguardando confirmação do usuário |
| Implementação → Discussão/Design (Reversão) | Um erro fundamental é descoberto durante a implementação; a IA sugere reversão; após a decisão final do usuário, reverte |
Se você não tem certeza se deve fazer a transição, pare na fase atual e continue discutindo, perguntando ativamente ao usuário. Não tome a decisão pelo usuário de que "a solução já está boa o suficiente, pode começar a escrever".
Uso de Modelos
Ao criar um novo documento, leia o modelo correspondente do diretório assets/:
assets/readme.md→docs/design/README.md(Visão geral global das tarefas)assets/task-status.md→00-Status da Tarefa.md(Tarefas comuns / Subtarefas)assets/parent-task-status.md→00-Status da Tarefa.md(Dedicado à tarefa pai, ativado quando o modo A está ativo)assets/communication.md→01-Comunicação.mdassets/design.md→02-Design.md(inclui bloco de critérios de aceitação; a tarefa pai precisa adicionalmente incluir blocos de divisão de módulos + contratos de interface)assets/implementation.md→03-Implementação.mdassets/test.md→04-Testes.md(gerado na fase de planejamento da implementação)
Leia o modelo, preencha com o conteúdo real e escreva na pasta da tarefa. Não invente estruturas de documentos.
Iteração da Habilidade e Documentos de Tarefas Antigas
A habilidade será iterada continuamente; os modelos e especificações serão atualizados, mas os documentos de tarefas antigas já em uso não serão migrados automaticamente para a nova especificação. Isso é intencional — para proteger a memória existente do usuário sobre a estrutura dos documentos e manter a estabilidade do mecanismo de memória multi-contexto. A estrutura do documento é a âncora de memória que permite ao usuário se localizar rapidamente após trocar de contexto; uma âncora não pode ser deformada com frequência devido a atualizações da habilidade.
Princípios de tratamento:
- Não migrar ativamente: A IA não escaneia tarefas antigas por conta própria, não alinha especificações por conta própria, mesmo que descubra que o formato do documento antigo difere da nova especificação (ex: documento antigo tem um bloco "Registro de Reversão" enquanto a nova especificação exige "Registro de Alterações"). No máximo, mencione a diferença em um comentário ou no diálogo, mas não faça alterações por conta própria.
- Migrar apenas sob instrução explícita do usuário: Execute a migração apenas quando o usuário solicitar ativamente, como "alinhar o documento da tarefa X com a especificação atual da habilidade" ou "migrar a tarefa X para o novo formato". A IA não julga por si mesma se "esta tarefa antiga deve ser migrada".
- Priorizar complementação incremental: A migração, por padrão, deve apenas complementar/modificar as partes que não estão de acordo com a nova especificação, preservando a estrutura geral e o conteúdo do documento original. Não reescreva tudo. Isso garante que, quando o usuário trocar de contexto e voltar, não precise reler e entender o documento inteiro — a estrutura não mudou, a âncora de memória ainda está lá.
- Quando o usuário solicitar explicitamente uma reescrita, faça o backup do arquivo original antes de gerar o novo arquivo:
- Não sobrescreva o arquivo original.
- Adicione ao arquivo de backup um sufixo de data ou versão, ex:
00-Status da Tarefa.md.bak.20260617. - O novo arquivo mantém o nome original e carrega o conteúdo reescrito.
- O arquivo original é a âncora de memória histórica do usuário. Mesmo que seja reescrito, a versão original deve ser preservada para comparação ou reversão.
- Antes da migração/reescrita, explique o escopo: Antes de começar, informe ao usuário quais pontos serão alterados (incremental) ou quais arquivos serão reescritos (completo). Após a conclusão, descreva brevemente o que foi feito para manter a previsibilidade.
Anti-Padrões (A Evitar)
- ❌ Começar a escrever código de negócio durante a fase de discussão — colocar o carro na frente dos bois.
- ❌ Escrever mudanças de solução diretamente no documento de implementação sem atualizar o documento de design — quebrar a fonte única da verdade.
- ❌ Em um novo diálogo, não ler o documento de status e o README, fazendo o usuário repetir o progresso — desperdiçar contexto.
- ❌ Ao encontrar desvios durante a implementação, corrigi-los silenciosamente sem atualizar o design — o documento de design gradualmente se torna impreciso.
- ❌ Em um projeto backend, escrever detalhes de implementação do frontend ou não registrar alterações de interface na lista de interfaces — o frontend não tem base para integração.
- ❌ Avançar fases sem um sinal explícito — tirar o poder de decisão do usuário.
- ❌ Ao encontrar uma lacuna na solução durante a implementação (campo/branch/valor de dicionário faltando, etc.), corrigir diretamente o documento de implementação sem atualizar o documento de design e sem aguardar a confirmação do usuário — deve-se seguir o "mecanismo de modificação": parar → primeiro alterar o design → aguardar confirmação → alterar a implementação → continuar.
- ❌ Ao encontrar um erro fundamental durante a implementação, teimosamente corrigir o documento de implementação, ou a IA decidir reverter por conta própria — deve-se seguir o "mecanismo de reversão": a IA só pode sugerir, o usuário decide, registrar o histórico de reversão e depois voltar para discussão/design para realinhamento.
- ❌ Marcar um passo grande como concluído enquanto seus passos pequenos ainda estão pendentes — passos grandes e pequenos devem ter marcas independentes.
- ❌ Discussão divergente que não converge, com dúvidas pendentes sendo soterradas por novos tópicos — usar a lista de dúvidas pendentes para forçar a convergência.
- ❌ Na lista de interfaces, usar frases vagas como "depende do código existente" ou "a confirmar na implementação", ou usar tags como [A Confirmar na Implementação] para legitimar a incerteza — fatos que dependem do código existente devem ser confirmados lendo o código durante a fase de design; a lista de interfaces deve ser completamente determinística quando entregue, caso contrário o frontend não pode integrar.
- ❌ Após a iteração da habilidade, migrar ou alinhar documentos de tarefas antigas por conta própria — quebrar a âncora de memória do usuário. Migrar apenas sob instrução explícita do usuário; por padrão, complementar incrementalmente, não reescrever tudo; se o usuário solicitar reescrita, primeiro fazer backup do arquivo original e depois gerar o novo.
- ❌ O documento de design conter apenas a solução, sem critérios de aceitação — o critério de aceitação define o limite dos requisitos; sem ele, não há definição objetiva de "pronto", e a aceitação na implementação será baseada em feeling.
- ❌ No documento de implementação, escrever ações genéricas como "cobrir com testes unitários XXX" sem referenciar números de casos de teste específicos — as ações de teste devem apontar para casos de teste específicos no
04-Testes.md(ex: "Verificar de acordo com T-EX-03"), caso contrário, o que testar e qual o resultado esperado não são claros. - ❌ Após passar pelo mecanismo de modificação/reversão, não reexecutar os casos de teste de regressão (T-R) — alterações locais podem causar regressão global; os caminhos críticos devem ser retestados.
- ❌ No modo A, iniciar as subtarefas antes de o design da tarefa pai estar definido (divisão em módulos ou contratos de interface não produzidos) — as subtarefas inevitavelmente entrarão em conflito. O design da tarefa pai deve ser aprovado pelo usuário primeiro.
- ❌ No modo A, uma subtarefa alterar o contrato de interface definido pela tarefa pai por conta própria — o contrato de interface é o consenso entre vários módulos; deve-se voltar para a tarefa pai e seguir o mecanismo de modificação, e notificar todas as subtarefas que dependem da interface.
- ❌ No modo A, uma subtarefa aninhar outra subtarefa (mais de um nível) — geralmente isso indica que a granularidade da divisão está errada; essa subtarefa deve ser replanejada como uma tarefa pai independente.
- ❌ No modo A, a tarefa pai não definir as dependências entre as subtarefas e deixar todas paralelas — as dependentes ficarão bloqueadas se as dependidas não forem concluídas; as dependências devem ser definidas durante a fase de design da tarefa pai.
- ❌ No modo B, o agente de teste corrigir bugs de implementação por conta própria — as responsabilidades devem ser separadas: o teste apenas aponta problemas, a correção volta para o agente de implementação; e após a correção, o agente de teste deve reexecutar o teste; o agente de implementação não pode declarar o fechamento unilateralmente.
- ❌ No modo B, usar o mesmo agente para atuar sequencialmente como "implementação" e "teste" — o valor central do modo B é o isolamento de contexto; fisicamente, devem ser dois agentes independentes, caso contrário o contexto não está isolado e o modo B é inútil.
- ❌ No modo B, o agente de teste alterar o design por conta própria ao encontrar um bug de design — as alterações de design têm um grande escopo de impacto; deve-se acionar o mecanismo de modificação e obter a confirmação do usuário; o agente de teste só pode fazer um julgamento inicial e relatar.