UTF-SDD

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, o que a pessoa vive na tela 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.

São seis comandos, nesta ordem, cada um fechando num portão seu.

  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.

    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 roteiro do 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

    Jornadas

    /utf-flows desenha as jornadas em Mermaid, cada uma com um nó vermelho: o ponto onde a pessoa trava, espera ou desiste. Sai docs/user-flows.md.

    Você decide o que o sistema faz em cada ponto de desistência e commita.

  4. entrevista conduzida pela IA

    Design

    /utf-design escreve docs/design-tokens.md: paleta com nome semântico, escala de espaçamento, tipografia, estados de botão — e o link do protótipo. Existe para a IA não inventar um botão diferente a cada tela.

    Você decide paleta, espaçamento e tipografia e commita.

  5. entrevista conduzida pela IA

    Arquitetura

    /utf-architecture escreve docs/architecture.md: estrutura de pastas, entidades, estados, contratos de API. Ele vem depois das jornadas de propósito — um nó vermelho quase sempre revela um estado que faltava, e estado é matéria deste documento. Desenhar a jornada depois seria descobrir o estado com o documento já fechado.

    Você lê e commita.

  6. IA gera

    Scaffold

    /utf-setup lê a stack do architecture.md e gera o monorepo 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, com a etiqueta manutencao. Esse é o único PR que não fecha Issue.

Cada passo só começa com o anterior commitado. Os comandos conferem isso e param se faltar. Não é burocracia: o commit é o que põe o seu nome na decisão. Sem ele, os documentos da Fase 0 caem todos num commit só no fim, e a autoria some.

O tutor também vale aqui: /utf-tutor prd, flows, design ou architecture explica os conceitos em cima do seu documento, não em exemplo genérico. Decisão que você não sabe explicar não sobrevive à arguição.

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.

  1. IA pergunta, você responde

    A branch e a conversa antes do código

    /utf-issue 27 cria a branch a partir da main, lê a Issue e o PRD e faz 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 especificação

    Da conversa sai specs/027-orcamento/spec.md com status: rascunho, commitado na branch com o seu OK — e o agente para. A spec diz o que precisa existir e como saber que ficou pronto. Ela não é documentação: documentação descreve o que existe, spec descreve o que deve passar a existir.

1Você aprova a spec e o plano Leia a spec inteira, fora do chat. Discorde de alguma coisa — sempre tem o que ajustar. Aprovar é trocar status: rascunho por status: aprovada e commitar essa linha na branch, com o seu nome no git log. Em dúvida sobre uma decisão técnica, rode /utf-tutor spec antes. Depois o agente gera o plano, e você dá o OK nele também.
  1. IA escreve, você aprova na conversa

    O plano

    O agente quebra a spec em tarefas pequenas, um critério de aceite cada. Se o plano passar de dez tarefas, a história é grande demais e ele propõe dividir. Com o seu OK, ele commita o plano: 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

    O fechamento e a auditoria

    Com todas as tarefas prontas, rode /utf-issue 27 de novo. O orquestrador detecta que o plano acabou, atualiza os documentos e despacha o auditor-final: um agente somente-leitura que 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.

PRVocê escreve e abre o Pull Request Antes, rode /utf-tutor prova: o simulado da defesa, uma pergunta por vez sobre o diff. Depois, escreva com as suas palavras a seção “O que este PR faz e por quê”, liste os apontamentos que você aceitou e os que recusou, e abra o PR com Closes #27. Nunca cole o diff nem a saída da IA nesse texto.
  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 — três frases de verdade. Vale para todos os PRs, inclusive os de manutenção, e a proteção da main exige esse check: reprovado, o PR não mescla. 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 main

    A main é sagrada: nada entra nela sem passar por um Pull Request.

Dentro de uma tarefa

Um /utf-task parece um comando só, mas dentro dele acontece o ciclo inteiro — com três 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, e um roteiro do que procurar no diff depois. O código nunca chega como surpresa.

2Você aceita a explicação Tire dúvidas primeiro. O implementador só roda depois do seu “pode implementar”.
  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 teste 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/027-orcamento/reviews/ — é esse arquivo que prova, na defesa, que a revisão aconteceu.

3Você tria os apontamentos Um por um: aceita ou recusa. Recusar exige justificativa, e a decisão fica registrada em reviews/tarefa-01-decisoes-r1.md. Recusa fundamentada vale mais do que aceitar tudo — aceitar tudo revela que você não leu.
  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.

  2. tutor, modo passo

    A leitura do diff, arquivo por arquivo

    Antes do commit, o fluxo chama o tutor para percorrer o diff com você, um arquivo por vez, no seu ritmo. É aqui que a sintaxe entra e onde você pergunta. Se não quiser, diga “pode pular a leitura”.

4Você confere o diff e autoriza o commit Na sua IDE, seguindo o roteiro que o tutor deu antes. Depois do commit, /utf-tutor 1 amarra a tarefa inteira. O diff de uma tarefa cabe na tela: entender ali custa cinco minutos. Deixar acumular até o PR significa encarar quarenta arquivos de uma vez, na véspera.

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/027-orcamento/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.

Estourou as duas rodadas? Não tente de novo. Quando o ciclo trava, o problema quase nunca está no código — está na spec ambígua, na tarefa grande demais ou numa dependência que ninguém declarou. Insistir na mesma conversa é a pior coisa a fazer: a janela de contexto está contaminada e o agente passa a defender a abordagem errada.

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. Corrija a spec e comece uma sessão nova, entregando só a spec e o plano.

Próximo

Os comandos, um por fase

Quem escreve, quem revisa e por quê