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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+ 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.
+
+
+ auditor de contexto limpo
+
O fechamento e a auditoria
+
Com todas as tarefas prontas, rode /utf-issue 27de 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.
+
+
+
+
+
+ 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 400 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.
+
+
+ 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.
+
+
+
+ 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”.
+
+
+
+
+
+ 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.
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+ 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.
Um comando por fase. Nenhum deles decide alguma coisa por você: os de
+ documento são entrevistas — uma pergunta por vez, você responde, o agente organiza e
+ escreve.
+
+
Fase 0, uma vez por projeto
+
+
Seis comandos, nesta ordem. Cada linha termina numa decisão sua, e
+ cada passo só começa com o anterior commitado — os comandos conferem isso e
+ param se faltar.
+
+
+
+
+
Comando
O que produz
O que você faz
+
+
+
+
/utf-prd
+
docs/prd.md — glossário, atores, histórias, regras de negócio
+
Lê inteiro, ajusta e commita; leva o tema ao professor
+
+
+
/utf-backlog
+
Uma Issue por história Ready, mais o roteiro do Kanban
+
Aprova a lista antes de as Issues serem criadas
+
+
+
/utf-flows
+
docs/user-flows.md — as jornadas e os pontos de desistência
+
Decide o que acontece em cada ponto de desistência e commita
+
+
+
/utf-design
+
docs/design-tokens.md — paleta, espaçamento, tipografia e o protótipo
apps/ — o monorepo, com a suíte de testes verde e vazia de regras
+
Ratifica as decisões e abre o primeiro PR, com a etiqueta manutencao
+
+
+
+
+
+
+
O /utf-backlog roda mais de uma vez. A cada leva de
+ histórias promovidas a Ready no PRD, rode de novo para criar as Issues
+ correspondentes. Os outros cinco rodam uma vez só.
+
+
+
Uma vez por história
+
+
+
+
+
Comando
Quando
O que acontece
+
+
+
+
/utf-issue 27
+
No começo e no fim da história
+
Na primeira vez, cria a branch, faz as perguntas, escreve a spec e — depois da sua
+ aprovação — o plano. Rodado de novo com o plano terminado, atualiza os documentos e
+ despacha o auditor-final para o PR. Rodado no meio, retoma de onde parou.
+
+
+
/utf-task 1
+
Uma vez por tarefa do plano
+
Roda o ciclo inteiro da tarefa: tutor, implementador, dois revisores, triagem,
+ leitura do diff e commit. Devolve o controle a você no fim.
+
+
+
/utf-task
+
Sem número
+
Executa a próxima tarefa pendente do plan.md e avisa quando não houver
+ mais nenhuma.
+
+
+
+
+
+
O tutor, do começo ao fim
+
+
O tutor não escreve código, não corrige nada e não opina sobre qualidade. Ele tem uma
+ função só: te ensinar o que acabou de ser feito, para você chegar na defesa sem precisar
+ dele.
+
+
+
+
+
Comando
Quando
A pergunta que ele responde
+
+
+
+
/utf-tutor prd, flows, design, architecture
+
Na Fase 0, antes de commitar cada documento
+
O que essas decisões significam tecnicamente, no meu documento?
+
+
+
/utf-tutor setup
+
Depois do scaffold (o /utf-setup já chama sozinho)
+
O que são todos esses arquivos que eu não escrevi?
+
+
+
/utf-tutor spec
+
Antes de aprovar a spec
+
O que essa decisão me obriga a fazer depois?
+
+
+
automático
+
Antes de cada tarefa, dentro do /utf-task
+
O que essa tarefa vai construir, com quais conceitos, e o que eu procuro no diff?
+
+
+
/utf-tutor passo 3
+
Antes do commit (o /utf-task já chama sozinho)
+
A leitura do diff arquivo por arquivo, no seu ritmo.
+
+
+
/utf-tutor 3
+
Depois de uma tarefa
+
O que esse diff faz e por que assim? Ele também devolve o nome oficial dos
+ conceitos que apareceram e três perguntas que um professor poderia fazer.
+
+
+
/utf-tutor antes 3
+
Para reouvir
+
A explicação pré-implementação daquela tarefa, de novo.
+
+
+
/utf-tutor prova
+
Antes de escrever o PR
+
O simulado da defesa: uma pergunta por vez, com correção das suas respostas e a
+ lista de arquivos para reler.
+
+
+
+
+
+
+
O tutor não pode ser usado durante a defesa. Ele existe para você
+ chegar lá sem precisar dele. Se você não souber responder às três perguntas que ele faz no
+ fim, o trabalho daquela tarefa ainda não acabou.
+
+
+
O que precisa estar configurado
+
+
O /utf-backlog, o /utf-setup e cada /utf-issue
+ falam com o GitHub. Para eles funcionarem você precisa do gh autenticado, com
+ os escopos repo, workflow e project:
+
+
gh auth login
+
+
O MCP do GitHub resolve do mesmo jeito, se você preferir. Sem um dos dois, backlog,
+ etiquetas e Pull Requests não saem. Com o MCP Context7 disponível, os fluxos conferem as
+ versões das ferramentas na documentação atual antes de decidir a stack.
+
+
Falar também funciona
+
+
Dizer “vamos trabalhar na Issue 27” em português dispara o mesmo fluxo — as regras do
+ projeto mandam o agente abrir o workflow correspondente. Os comandos com barra são só o
+ caminho mais curto e o que menos deixa margem para o agente entender outra coisa.
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 400 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
+ 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” já passa dos 400 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 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.
+
+
+
+
+
+
+
+
diff --git a/site/index.html b/site/index.html
new file mode 100644
index 0000000..9ebf16e
--- /dev/null
+++ b/site/index.html
@@ -0,0 +1,182 @@
+
+
+
+
+
+UTF-SDD — a IA escreve o código, você decide nos portões
+
+
+
+
+
+
+
+
+
+
+
O UTF-SDD é o método da disciplina de Tópicos Especiais da UTFPR.
+ Ele existe para que, no fim do semestre, você consiga explicar cada linha que entrou
+ no seu projeto — inclusive as que não foi você que digitou.
+
+
+
+
Histórico de uma branch conduzida pelo método
+
+
commit
o que entrou
escreveu
autorizou
+
+
+
9c1e04a
spec e plano da issue 27
você
você
+
4b7ad12
spec: rascunho para aprovada
você
você
+
e30f8a6
tarefa 1: entidade Orçamento
IA
você
+
7fd2b90
tarefa 2: recusa orçamento vencido
IA
você
+
1a5c8e3
tarefa 3: aviso ao aprovar
IA
você
+
c02d7f5
docs: prd e arquitetura no mesmo commit
IA
você
+
+
+
+
+
O problema que o método resolve
+
+
Pedir código para uma inteligência artificial é fácil. Qualquer pessoa gera uma tela
+ funcionando em cinco minutos. O problema aparece semanas depois: o sistema faz coisas que
+ ninguém pediu, ninguém lembra por que uma regra existe e, quando é preciso mudar algo, a
+ vontade é apagar tudo e recomeçar.
+
+
Nesta disciplina você não é avaliado por gerar código rápido. Você é avaliado por
+ dirigir a IA, auditar o que ela gerou e explicar as decisões técnicas. Você é o engenheiro
+ e o arquiteto; a IA é a sua equipe de execução.
+
+
Se o Pull Request for a primeira vez que você olha o código, o método falhou.
+ A regra de ouro, do guia da disciplina
+
+
O que é um portão
+
+
O UTF-SDD é um SDD por portões (Gated Spec-Driven Development).
+ Portão é um ponto onde o trabalho para e espera por uma decisão sua — decisão que fica
+ registrada em algum lugar que outra pessoa consegue conferir depois. Neste site, um portão
+ aparece assim:
+
+
+
+
+ Você aprova a spec
+ Troque status: rascunho por status: aprovada e commite essa
+ linha. O commit fica no git log, com o seu nome. Nenhum agente mexe nesse campo.
+
+
+
+
São quatro portões por história, mais o Pull Request no fim. Nenhum deles é burocracia:
+ cada um existe porque, sem ele, alguma coisa que você deveria ter decidido seria decidida
+ pela IA no seu lugar, sem você perceber.
+
+
Três compromissos
+
+
Spec-Driven Development não é invenção desta disciplina. O que distingue a variante
+ daqui são três compromissos que o método não abre mão.
+
+
+
Nada avança sem uma decisão sua, registrada
+
Aprovar a spec, aceitar a explicação do tutor, triar cada apontamento da revisão,
+ autorizar cada commit. A decisão vira arquivo ou vira commit — memória de conversa não
+ conta, porque não sobrevive à sessão e não prova nada na defesa.
+
+
+
+
Quem revisa nunca é quem escreveu
+
O implementador começa com o contexto limpo. Dois revisores diferentes olham o
+ resultado, e nenhum dos dois tem permissão de escrita — eles apontam, não corrigem. Um
+ agente que corrige o próprio trabalho herda o próprio ponto cego e some com a evidência
+ do erro.
+
+
+
+
Todo artefato é evidência para a defesa
+
Specs, planos, pareceres, decisões de triagem e mensagens de commit não existem para
+ encher pasta. Eles existem para provar, no dia da arguição, que você entendeu o que
+ assinou.
+
+
+
Quem produz o quê
+
+
O método gira em torno de doze artefatos. Desses doze, a IA produz sozinha apenas três:
+ o código, o plano de tarefas e os pareceres de revisão. A ficha da disciplina já vem pronta
+ no template. Todo o resto precisa da sua direção.
+
+
+
+
+
Artefato
Onde fica
Quem dirige
+
+
+
README.md
raiz
você
+
docs/prd.md
o que o produto faz
você
+
docs/architecture.md
onde as coisas moram
você
+
docs/user-flows.md
o que a pessoa vive na tela
você
+
docs/design-tokens.md
cores, espaçamento, tipografia
você
+
docs/checklist.md
a ficha da disciplina
vem no template
+
Issue
GitHub Projects
você
+
spec.md
o que precisa existir
você aprova
+
plan.md
como será construído
IA
+
Pareceres
reviews/
IA
+
Código
apps/
IA
+
Pull Request
GitHub
você
+
+
+
+
+
Comece por aqui
+
+
Se você acabou de criar o seu repositório pelo Use this template, siga nesta
+ ordem:
+
+
+
Entenda o ciclo — a Fase 0, o ciclo de uma história e os quatro portões.
+
Veja os comandos — o que digitar em cada etapa e o que sai de cada um.
+
Conheça os papéis — quem escreve, quem revisa e por que a trava de escrita importa.
+
Leia docs/checklist.md no seu repositório — é a ficha da disciplina, com as regras e as entregas.
+
+
+
Este site ensina o método. A regra escrita, valendo como fonte da verdade,
+ está no guia
+ da disciplina e no tutorial,
+ dentro do repositório. Quando os dois divergirem, vale o que está no repositório.
A IA não é um agente só. São cinco, com permissões diferentes de
+ propósito — e é a diferença de permissão, não a boa vontade do modelo, que faz a revisão
+ valer alguma coisa.
+
+
Os cinco papéis
+
+
+
+
+
+
Agente
+
Escreve?
+
O que ele faz
+
+
+
+
+
implementador
+
sim
+
Faz uma tarefa do plano, com TDD, começando com o contexto limpo. É o único que
+ toca em arquivo de código.
+
+
+
revisor-conformidade
+
não
+
Compara o diff da tarefa contra os critérios de aceite da spec. Roda os testes
+ para saber se o critério é atendido de verdade.
+
+
+
revisor-codigo
+
não
+
Lê o mesmo diff contra o architecture.md: estrutura, camadas,
+ contratos, nomes do glossário.
+
+
+
auditor-final
+
não
+
No fim da história, compara o diff inteiro da branch contra a spec aprovada,
+ ignorando o plano.
+
+
+
tutor
+
não
+
Explica. Antes da tarefa, o que vai ser construído; depois, o que o diff faz e por
+ que assim. Não corrige e não opina sobre qualidade.
+
+
+
+
+
+
Quem chama o revisor é o fluxo, não o implementador. Nenhum agente decide que o próprio
+ trabalho dispensa revisão.
+
+
A trava
+
+
O revisor não pode ter permissão de escrita. Não porque ele foi instruído a
+ não escrever, mas porque a ferramenta não deixa.
+
+
Pedir “por favor, não corrija, apenas aponte” no prompt é uma sugestão. O modelo vai
+ obedecer na maioria das vezes e, na vez em que não obedecer, você não vai
+ saber: o apontamento que ele consertou sozinho nunca chega até você, e é justamente
+ esse que você precisava ver.
+
+
Por isso o revisor é somente leitura, e o parecer dele é gravado sem edição em
+ specs/<issue>-<slug>/reviews/. É esse arquivo que prova, na defesa,
+ que a revisão aconteceu — e é a listagem dele que conta as rodadas.
+
+
+
Cuidado com o terminal. Um agente somente leitura que tem acesso ao
+ shell consegue escrever com sed -i, com > ou com
+ git checkout, e a trava vira ficção. Só que os revisores precisam do terminal
+ para rodar git diff e a suíte de testes. Há duas saídas, nesta ordem de
+ preferência:
+
1. Se a sua ferramenta permite lista de comandos liberados, libere só
+ git diff e o comando de teste. É a trava de verdade.
+
2. Se ela só liga ou desliga o terminal inteiro, escreva a proibição no prompt do
+ agente: o terminal existe para git diff e para rodar os testes, e é proibido
+ usá-lo para alterar qualquer arquivo.
+
+
+
As três coisas que a ferramenta precisa saber fazer
+
+
O método é mais importante que a ferramenta. Ferramenta de IA envelhece rápido; o que
+ você leva da disciplina é o método. Se a sua ferramenta faz estas três coisas, o ciclo
+ roda.
+
+
+
Regras sempre ativas
+
Um arquivo carregado em toda mensagem, com as regras inegociáveis do projeto: não
+ codificar antes da spec aprovada, TDD obrigatório, a main é bloqueada, os
+ nomes vêm do glossário. Sem isso você repete as mesmas instruções todo dia e o agente
+ esquece na terceira mensagem.
+
+
+
+
Um comando de fluxo
+
Um arquivo de instruções que você dispara com uma linha e que executa o passo inteiro:
+ despacha o implementador, despacha os dois revisores, grava os pareceres, conta a rodada,
+ decide. Você digita /utf-task 3; a orquestração inteira é o arquivo.
+
+
+
+
Subagentes com ferramentas restritas
+
É aqui que mora a parte que não pode faltar. Quase toda ferramenta moderna deixa você
+ declarar quais ferramentas cada subagente recebe. É essa declaração que carrega a trava, e
+ é a única coisa que não dá para compartilhar entre ferramentas.
+
+
+
Um método, quatro ferramentas
+
+
O template já vem configurado para quatro ferramentas. O conteúdo de verdade vive uma vez
+ só, em .agents/; cada ferramenta tem apenas uma casca de poucas linhas que
+ aponta para lá, com a sintaxe de permissão dela. Trocar de ferramenta no meio do semestre
+ não reescreve nada.
+
+
+
+
+
+
Ferramenta
+
Regras
+
Comandos
+
Subagentes
+
+
+
+
Claude Code
CLAUDE.md
.claude/commands/
.claude/agents/
+
Cursor
.cursor/rules/
.cursor/commands/
.cursor/agents/
+
Antigravity
.agents/rules/
.agents/workflows/ — o nome do arquivo é o comando
.agents/agents/
+
OpenCode
AGENTS.md
.opencode/command/
.opencode/agents/
+
+
+
+
+
Nas quatro, os revisores e o tutor nascem sem poder de escrita. A força da trava é que
+ muda:
+
+
+
Claude Code, Cursor e Antigravity negam a ferramenta de edição, mas
+ precisam liberar o terminal para o revisor rodar git diff. Quem fecha a
+ brecha ali é a proibição escrita no prompt do agente.
+
OpenCode fecha por configuração. É o único que libera comandos
+ específicos em vez de ligar ou desligar o terminal inteiro. E funciona com modelos
+ gratuitos, o que faz dele o caminho de custo zero mais completo da disciplina.
+
+
+
+
Se você usa OpenCode, ajuste a lista de comandos de teste em
+ .opencode/agents/ à stack do seu architecture.md. Comando que não
+ estiver liberado não roda, e o parecer sai incompleto sem avisar.
+
E se o seu OpenCode não listar os agentes ou os comandos, é diferença de versão nos
+ nomes das pastas: renomeie .opencode/agents/ para
+ .opencode/agent/ e .opencode/command/ para
+ .opencode/commands/. O conteúdo é o mesmo.
+
+
+
Sem worktree, sem ambiente isolado
+
+
Você trabalha na branch da Issue, na sua IDE, com os arquivos à vista. Worktrees e
+ sandboxes existem para vários agentes que escrevem rodarem em paralelo sem pisar
+ uns nos outros. Aqui há um escritor por vez e dois revisores que não escrevem: não existe
+ colisão possível. E ver o arquivo aparecer no explorador, o teste ficar vermelho e depois
+ verde, é parte do que você está aqui para aprender.