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 os primeiros commits 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.
Protótipo desatualizado	Documentação que mente é pior que documentação ausente	O link do protótipo vive no `design-tokens.md` e acompanha a 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. Uma verificação automática confere isso e reprova o PR se faltar. É 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 formulário de reserva não desabilitava o botão durante o envio, e clique duplo criava duas reservas; passei o botão a depender de um signal enviando e ajustei o teste que dependia do comportamento antigo” já passa dos 250 caracteres e diz alguma coisa.

Não cole o diff nem a saída da IA nessa explicação. O texto precisa ser seu. Na apresentação 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, altera uma regra de negócio ou conserta um bug de comportamento — por exemplo, “o passageiro não consegue cancelar a reserva”. Essas nascem como Issue no GitHub Projects e o ciclo completo é obrigatório.

Não precisa de spec a mudança puramente técnica: subir a versão do Angular, corrigir erro de digitação, extrair um componente repetido, ajustar regras de formatação. Abra a Issue pelo modelo Tarefa técnica, e o PR com a etiqueta manutencao.

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

Checklist antes de abrir o Pull Request

Existe uma Issue e o PR referencia ela, com Closes #27.
O PR vai para a develop, e a branch nasceu dela.
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.
O architecture.md reflete 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.
Por que este projeto não tem backend próprio?: Porque o foco da disciplina é o front. Os dados vêm de um BaaS, que entrega autenticação, banco e API prontos — na E2 pelo json-server, na E3 pelo BaaS de verdade. A pasta apps/api existe vazia só para guardar lugar, caso um dia exista uma API própria.
Posso usar o tutor na apresentação?: Não. Ele existe justamente para você não precisar dele lá.
Trabalho em equipe. 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.