Dúvidas e erros comuns

Quase todo problema no ciclo cai em uma destas linhas. Vale ler antes de travar, e reler quando travar.

Os erros que mais aparecem

Erro	Por que dói	O que fazer
Aprovar a spec sem ler	O sistema constrói, com perfeição, uma ideia errada	Leia inteira. Discorde de alguma coisa: sempre tem o que ajustar.
Deixar o agente trocar o `status` da spec	A aprovação deixa de ser sua e o `git log` deixa de provar qualquer coisa	Só você troca esse campo, e num commit seu.
Commitar a spec junto com o código, no fim	O histórico não prova que a especificação veio antes	Spec e plano são o primeiro commit da branch.
Histórias grandes demais	O agente se perde, estoura as rodadas e consome muito token	Se o plano tem mais de dez tarefas, quebre a história em duas e reescreva a spec.
Critérios de aceite vagos	Nada é verificável, e o revisor inventa critério a cada rodada	Escreva pensando no teste que provaria aquilo.
Deixar o caso de abandono só na prosa	Não vira teste, e volta no dia da apresentação	Todo caso de abandono também é critério de aceite.
Deixar rodar e olhar só no fim	Vira uma pilha de código estranho para julgar em cinco minutos	Acompanhe. Chame o tutor a cada tarefa. Interrompa quando algo parecer errado.
Deixar o mesmo agente corrigir o que ele escreveu	Ele herda o próprio ponto cego e defende a abordagem que propôs	Implementador novo a cada rodada, com os apontamentos transcritos.
Insistir na mesma conversa depois de várias tentativas falhas	A janela de contexto está contaminada: o agente repete e defende a abordagem errada	Descarte o working tree e a conversa. Comece de novo com a spec corrigida.
Aceitar todos os apontamentos do revisor	Revela que você não leu	Recusar com justificativa vale mais do que aceitar tudo.
Inchar a spec com o que apareceu no caminho	O plano aprovado é abandonado e o auditor compara o diff com uma spec que não descreve mais o trabalho	Pare e divida: Issue nova para o que foi descoberto.
Documentar depois	Nunca acontece	O auditor final confere antes do PR.
Diagrama desatualizado	Documentação que mente é pior que documentação ausente	Mermaid no repositório, atualizado no mesmo commit da mudança.

O Portão de Entendimento

Todo Pull Request precisa ter, no corpo, a seção “O que este PR faz e por quê” preenchida com pelo menos 250 caracteres, sem contar espaços — o que dá, na prática, três frases de verdade. Uma verificação automática confere isso e, como a proteção da main exige esse check, o PR reprovado não mescla. É uma regra só, e vale para todos os PRs, inclusive os de manutenção.

Se a mudança é pequena, a explicação é curta e específica. Algo como “o ValidationPipe estava sem whitelist: true, então campos extras no body passavam direto para o service; ativei a flag e ajustei dois testes que dependiam do comportamento antigo” é o começo — sozinho ele tem 152 caracteres e não passa. Acrescente o que você conferiu e o que poderia ter quebrado, e os 250 vêm naturalmente, dizendo alguma coisa.

Não cole o diff nem a saída da IA nessa explicação. O texto precisa ser seu. Na defesa presencial o professor pode sortear qualquer PR e pedir que você explique ao vivo o que escreveu ali, e é fácil perceber quando o texto não é de quem está falando.

Precisa de spec para qualquer mudança?

Não. A regra é o impacto no produto.

Precisa de spec toda mudança que cria um recurso novo ou altera uma regra de negócio — ou seja, toda história. Essas nascem no docs/prd.md, viram Issue pelo /utf-backlog, e o ciclo completo é obrigatório.

Não precisa de spec o bug nem a tarefa técnica de manutenção. O bug é um desvio do que o PRD já descreve: a Issue, aberta direto no GitHub, traz os passos para reproduzir, os logs e a justificativa técnica — isso é a especificação dele. Manutenção é atualizar a versão de uma dependência, corrigir erro de digitação, renomear variáveis ou pastas, ajustar regras de formatação. Abra o PR e aplique a etiqueta manutencao.

A etiqueta decide só isso. Ela não dispensa a explicação — todo PR explica o que faz e por quê.

Se, ao investigar um bug, você descobrir que o PRD não dizia o que o sistema deveria fazer, não é bug. É história nova, e volta para o ciclo com spec.

Checklist antes de abrir o Pull Request

Existe uma Issue e o PR referencia ela, com Closes #27 — exceto o PR do setup, que não fecha Issue.
O spec.md está com status: aprovada, e o commit que trocou esse campo é seu.
Spec e plano são os primeiros commits da branch, antes de qualquer código.
Os testes cobrem os critérios de aceite e os casos de abandono, e passam.
Os pareceres estão em reviews/, um por revisor por rodada.
A revisão foi feita por agentes diferentes do que implementou, e nenhum deles tinha permissão de escrita.
Os apontamentos aceitos e recusados estão registrados no PR, com motivo.
Todo Assume que da spec tem um // TODO #<issue> no código e uma Issue aberta.
Os diagramas do architecture.md refletem o comportamento atual.
O status da história no prd.md está correto.
A seção “O que este PR faz e por quê” está escrita, com as suas palavras.
Você consegue explicar cada trecho do diff sem consultar a IA.

O último item é o único que ninguém verifica automaticamente, e é o que sustenta a maior parte da sua nota individual.

Perguntas frequentes

Posso usar a IA para escrever a especificação?: Sim, e é o esperado. O que não pode é aprovar sem ler e sem discordar de nada.
E se eu discordar do agente revisor?: Ótimo. Recuse o apontamento e escreva o motivo no PR. Recusa fundamentada é sinal de que você entendeu; aceitar tudo é sinal contrário.
O ciclo travou nas duas rodadas de revisão. O que faço?: Quase sempre significa que a spec está ambígua ou a história é grande demais. Leia os dois pareceres da rodada 2 lado a lado: se eles discordam entre si, ou apontam o mesmo trecho por motivos diferentes, o problema está na spec. Volte um passo em vez de insistir na correção.
O implementador disse que a tarefa é maior do que o plano previa. E agora?: Ele está certo com mais frequência do que se imagina. Pare, volte ao plan.md e quebre aquela tarefa em duas. Não mande ele fazer assim mesmo — é o começo do estouro das rodadas.
Descobri um problema novo no meio da história. Aproveito e conserto?: Não. Não inche a spec: registre como comentário na Issue e abra uma Issue nova. O escopo do PR é o escopo da spec, e é contra ela que o auditor final vai comparar o diff.
Posso usar o tutor na defesa?: Não. Ele existe justamente para você não precisar dele lá.
Trabalho em dupla. Como fica a nota?: As entregas são avaliadas por equipe. A defesa técnica é individual, e cada integrante recebe a nota que a própria arguição sustentar.
Existem outros SDDs por aí?: Sim. As duas outras famílias mais conhecidas são o GitHub Spec Kit, que faz o mesmo por comandos explícitos, e a família GSD. Você não precisa conhecê-las para cursar a disciplina, e conhecer as três ao mesmo tempo atrapalha mais do que ajuda: são a mesma ideia com vocabulários diferentes. Se experimentar o Spec Kit, não use o /implement de forma massiva para todas as tarefas de uma vez — o método daqui exige uma branch e um Pull Request por Issue.

Ainda com dúvida?

O guia da disciplina tem a discussão inteira, com os desvios do ciclo e os apêndices. E dentro do projeto, /utf-tutor responde sobre o seu código.