O ciclo, do começo ao Pull Request

O projeto tem dois momentos. A Fase 0 acontece uma vez e estabelece o entendimento compartilhado. Depois dela, cada história de usuário roda o mesmo ciclo, do mesmo jeito, até o fim do semestre.

Fase 0: o entendimento compartilhado

Antes de codificar a primeira Issue, você escreve o que o produto faz, como ele se parece e onde as coisas moram. Não é burocracia de início de semestre. É que o ciclo por Issue amplifica o contexto que existe: com um PRD e um documento de arquitetura, cada especificação nasce coerente com o resto do sistema. Sem eles, cada Issue vira um projeto novo — o agente inventa o nome da entidade, escolhe sozinho onde a regra mora, decide um formato de resposta diferente. Na quinta Issue você tem três jeitos de fazer a mesma coisa, e nenhum deles está errado isoladamente.

1. entrevista conduzida pela IA

   Requisitos

   O comando /utf-prd faz uma pergunta por vez e escreve docs/prd.md: glossário, atores, histórias de usuário com critérios verificáveis, regras de negócio e os pontos onde a pessoa desiste.

   Você lê o documento inteiro, ajusta e commita. O tema vai ao professor.

2. IA propõe, GitHub recebe

   Backlog

   /utf-backlog transforma cada história marcada como Ready em uma Issue e monta o Kanban no Projects. A descrição da Issue só aponta para o PRD — regra de negócio nunca é copiada para lá, senão passam a existir duas versões dela.

   Você aprova a lista antes de as Issues serem criadas.

3. entrevista conduzida pela IA

   Design e protótipo

   /utf-design fecha o framework CSS, os tokens em docs/design-tokens.md, o Mobile-First e a identidade PWA — e registra o link do protótipo navegável (Figma, Stitch ou equivalente). Aqui a jornada do usuário vive no protótipo; o que ela decide sobre abandono volta para o PRD como critério.

   A equipe decide, revisa fora do chat e commita. Decisão de design sem dono não existe: alguém vai explicá-la na apresentação.

4. entrevista conduzida pela IA

   Arquitetura

   /utf-architecture escreve docs/architecture.md: estrutura de pastas, componentes e services, estados, rotas e o modelo de dados do BaaS. Ele vem depois do design de propósito — o protótipo e os pontos de desistência revelam telas e estados que este documento precisa mapear.

   Você lê e commita.

5. IA gera

   Scaffold

   /utf-setup lê a stack do architecture.md e gera o app pelo gerador oficial, com a suíte de testes rodando e vazia de regras. Ele precisa vir antes da primeira Issue por um motivo do próprio método: o RED do TDD só significa alguma coisa num repositório onde os testes já rodam. Um teste que falha porque o critério não foi implementado é informação; um que falha porque não existe runner instalado é ruído.

   Você ratifica as decisões e abre o primeiro Pull Request para a develop, com a etiqueta manutencao. Antes disso o tutor explica o scaffold inteiro, sem você precisar pedir.

A Fase 0 é a Entrega 1. Depois dela a lógica se inverte: documentação deixa de ser etapa e passa a andar junto de cada PR, atualizada no mesmo commit que muda o comportamento. A Fase 0 é o único momento do semestre em que você descreve um sistema que ainda não existe.

O ciclo de uma história

A partir daqui, tudo se repete. Uma Issue, uma branch, um Pull Request. Como este projeto usa Gitflow, a branch nasce da develop e volta para ela — a main guarda só o que está em produção.

1. IA pergunta, você responde

   A conversa antes do código

   /utf-issue 27 faz o agente ler a Issue e o PRD e fazer perguntas sobre casos de borda e caminhos tristes. É o momento de descobrir o que ninguém tinha pensado — e é barato aqui, caro depois.

2. IA escreve

   A branch e a especificação

   A branch nasce agora, a partir da develop, antes da aprovação: no Gitflow main e develop são bloqueadas, e o commit de aprovação precisa de um lugar para viver. Nela o agente salva specs/27-reserva-de-carona/spec.md com status: rascunho — e para.

1. IA escreve, você aprova na conversa

   O plano

   O agente quebra a spec em tarefas de dois a cinco minutos cada. Se o plano passar de dez tarefas, a história é grande demais e ele propõe dividir. Spec e plano são os primeiros commits da branch, antes de qualquer código — é isso que prova que a especificação veio antes.

2. você conduz, uma por vez

   A execução, tarefa a tarefa

   /utf-task 1, /utf-task 2, e assim por diante. Cada tarefa roda o ciclo completo descrito na próxima seção e devolve o controle a você no fim. O ciclo nunca emenda duas tarefas.

3. auditor de contexto limpo

   A auditoria do diff inteiro

   Com todas as tarefas prontas, um último agente somente-leitura compara o diff completo da branch contra a spec aprovada, ignorando o plano. Ele existe para pegar o que passa entre as tarefas: um critério de aceite que ninguém cobriu, documentação que ficou para trás.

1. verificação automática

   O Portão de Entendimento

   Uma checagem no GitHub Actions confere se a seção “O que este PR faz e por quê” tem pelo menos 250 caracteres — um parágrafo de verdade. Vale para todos os PRs, inclusive os de manutenção. Não é burocracia: é o sintoma aparecendo cedo. Se você travou para escrever, volte e leia o código antes de insistir no texto.

2. você

   Merge na develop

   A develop integra o trabalho da equipe; a main recebe só o que vai para produção, num merge à parte. As duas são protegidas: nada entra sem Pull Request.

Dentro de uma tarefa

Um /utf-task parece um comando só, mas dentro dele acontece o ciclo inteiro — com duas paradas suas.

1. tutor, contexto limpo

   O tutor explica antes

   Bem mastigado: o que a tarefa vai construir, qual critério de aceite ela serve, quais conceitos vão aparecer com o nome oficial de cada um, os arquivos que vão ser tocados na ordem em que serão escritos, e um roteiro do que procurar no diff depois. O código nunca chega como surpresa.

1. implementador novo

   A implementação, com TDD

   Um agente que começa com o contexto limpo, faz uma tarefa só e segue RED, GREEN, REFACTOR — o .spec.ts antes da lógica.

2. dois revisores, em paralelo

   A revisão

   Um revisor confere o diff contra os critérios de aceite da spec; o outro confere contra o architecture.md. São agentes diferentes do que implementou, e nenhum dos dois tem permissão de escrita. Os pareceres são gravados sem edição em specs/27-reserva-de-carona/reviews/ — é esse arquivo que prova, na apresentação, que a revisão aconteceu.

1. implementador novo de novo

   A correção

   Os apontamentos aceitos vão para um implementador novo, com os apontamentos transcritos. Nunca para o mesmo agente que escreveu: ele herda o próprio ponto cego e defende a abordagem que propôs.

O limite de duas rodadas

O ciclo de correção tem um limite estrito: duas rodadas. A contagem não é a memória do agente, que se perde — é a listagem da pasta:

ls specs/27-reserva-de-carona/reviews/tarefa-03-*

Nenhum arquivo significa rodada 1. Um par terminado em -r1 significa que você está na rodada 2. Um par -r2 significa que acabou.