From d9c68fc8e511b85557af34e32c6aec7367c04765 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Thu, 3 Sep 2026 19:15:54 -0300 Subject: [PATCH 1/3] site: adiciona o site didatico do metodo Cinco paginas estaticas, sem build e sem dependencia de runtime: inicio, o ciclo, os comandos, os papeis e as duvidas. O conteudo e a explicacao do metodo com links para docs/guia-sdd.md, docs/tutorial-sdd.md e docs/checklist.md, que seguem sendo a fonte da verdade - o site ensina e remete, nunca duplica regra. O elemento estrutural e a faixa de portao: ela atravessa a pagina inteira exatamente onde o metodo interrompe o trabalho, de modo que a leitura encena o ciclo em vez de so descreve-lo. Co-Authored-By: Claude Opus 5 (1M context) --- site/.nojekyll | 0 site/assets/estilo.css | 440 +++++++++++++++++++++++++++++++++++++++++ site/assets/portao.svg | 6 + site/ciclo.html | 351 ++++++++++++++++++++++++++++++++ site/comandos.html | 224 +++++++++++++++++++++ site/duvidas.html | 245 +++++++++++++++++++++++ site/index.html | 182 +++++++++++++++++ site/papeis.html | 219 ++++++++++++++++++++ 8 files changed, 1667 insertions(+) create mode 100644 site/.nojekyll create mode 100644 site/assets/estilo.css create mode 100644 site/assets/portao.svg create mode 100644 site/ciclo.html create mode 100644 site/comandos.html create mode 100644 site/duvidas.html create mode 100644 site/index.html create mode 100644 site/papeis.html diff --git a/site/.nojekyll b/site/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/site/assets/estilo.css b/site/assets/estilo.css new file mode 100644 index 0000000..c6bb271 --- /dev/null +++ b/site/assets/estilo.css @@ -0,0 +1,440 @@ +/* ========================================================================== + UTF-SDD — sistema visual + Conceito: carimbo em papel. O método produz registro assinado; a barra de + portão é o elemento estrutural — ela interrompe a leitura exatamente onde + o método interrompe o trabalho. + ========================================================================== */ + +:root { + --papel: #FBFAF8; + --papel-fundo: #F3F0F5; + --tinta: #1A1B2E; + --tinta-suave: #4A4B63; + --carimbo: #5B2E8F; + --carimbo-fraco:#EDE6F6; + --alerta: #A32218; + --alerta-fraco: #FBEAE8; + --verde: #15654A; + --verde-fraco: #E3F2EC; + --linha: #DED7E7; + --nevoa: #F1ECF7; + + --barra-fundo: #5B2E8F; + --barra-texto: #FBFAF8; + --barra-numero: #C9A9F2; + --barra-suave: #DFCDF8; + + --display: "Familjen Grotesk", "Segoe UI", system-ui, sans-serif; + --corpo: "Source Serif 4", Georgia, "Times New Roman", serif; + --mono: "JetBrains Mono", ui-monospace, "SFMono-Regular", Consolas, monospace; + + --medida: 68ch; + --largo: 96ch; + color-scheme: light dark; +} + +@media (prefers-color-scheme: dark) { + :root { + --papel: #14121C; + --papel-fundo: #0E0C15; + --tinta: #EFEBF4; + --tinta-suave: #A9A3BC; + --carimbo: #C4A5F0; + --carimbo-fraco:#241B36; + --alerta: #F0918A; + --alerta-fraco: #2A1614; + --verde: #6FD3AC; + --verde-fraco: #10241D; + --linha: #322C42; + --nevoa: #1C1828; + + --barra-fundo: #33195C; + --barra-texto: #F3EDFB; + --barra-numero: #B98CF0; + --barra-suave: #D3BBF5; + } +} + +*, *::before, *::after { box-sizing: border-box; } + +html { -webkit-text-size-adjust: 100%; } + +body { + margin: 0; + background: var(--papel); + color: var(--tinta); + font-family: var(--corpo); + font-size: 1.125rem; + line-height: 1.65; + font-synthesis-weight: none; +} + +/* --- grade: coluna de leitura + sangria total ---------------------------- */ + +.pagina { + display: grid; + grid-template-columns: + [borda-esq] 1fr + [medida-inicio] minmax(0, var(--medida)) + [medida-fim] 1fr + [borda-dir]; + padding-inline: 1.5rem; + padding-bottom: 5rem; +} +.pagina > * { grid-column: medida-inicio / medida-fim; } +.pagina > .sangra { grid-column: borda-esq / borda-dir; margin-inline: -1.5rem; } +.pagina > .largo { + grid-column: borda-esq / borda-dir; + width: min(var(--largo), 100%); + margin-inline: auto; +} + +/* --- tipografia ---------------------------------------------------------- */ + +h1, h2, h3, h4 { + font-family: var(--display); + font-weight: 700; + letter-spacing: -0.02em; + line-height: 1.1; + text-wrap: balance; +} + +h1 { font-size: clamp(2.25rem, 6.5vw, 3.75rem); margin: 0 0 1rem; } +h2 { font-size: clamp(1.6rem, 3.6vw, 2.125rem); margin: 3.5rem 0 0.75rem; } +h3 { font-size: 1.3125rem; margin: 2.25rem 0 0.5rem; letter-spacing: -0.01em; } +h4 { font-size: 1.0625rem; margin: 1.75rem 0 0.25rem; } + +p { margin: 0 0 1.15rem; } +p:last-child { margin-bottom: 0; } + +.abertura { + font-size: 1.3125rem; + line-height: 1.5; + color: var(--tinta-suave); + max-width: 54ch; +} + +a { color: var(--carimbo); text-underline-offset: 0.18em; text-decoration-thickness: 1px; } +a:hover { text-decoration-thickness: 2px; } + +:focus-visible { + outline: 3px solid var(--carimbo); + outline-offset: 3px; + border-radius: 2px; +} + +code { + font-family: var(--mono); + font-size: 0.86em; + background: var(--nevoa); + border: 1px solid var(--linha); + border-radius: 3px; + padding: 0.1em 0.35em; + overflow-wrap: break-word; +} + +strong { font-weight: 600; } + +/* --- cabeçalho de navegação ---------------------------------------------- */ + +.topo { + position: sticky; + top: 0; + z-index: 10; + background: var(--papel); + border-bottom: 1px solid var(--linha); +} +.topo-interno { + width: min(var(--largo), 100% - 3rem); + margin-inline: auto; + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 0.75rem 1.5rem; + padding: 0.7rem 0; +} +.selo { + display: inline-flex; + align-items: center; + gap: 0.5rem; + font-family: var(--display); + font-weight: 700; + font-size: 1.0625rem; + letter-spacing: -0.01em; + color: var(--tinta); + text-decoration: none; + margin-right: auto; +} +.selo:hover { color: var(--carimbo); } + +.marca { width: 1.5rem; height: 1.125rem; flex: none; stroke: var(--carimbo); stroke-width: 2.4; fill: none; stroke-linecap: round; } + +.topo nav { display: flex; flex-wrap: wrap; gap: 0.25rem 1.25rem; font-family: var(--display); font-size: 0.9375rem; } +.topo nav a { color: var(--tinta-suave); text-decoration: none; padding: 0.15rem 0; border-bottom: 2px solid transparent; } +.topo nav a:hover { color: var(--tinta); } +.topo nav a[aria-current="page"] { color: var(--carimbo); border-bottom-color: var(--carimbo); } + +/* --- barra de portão: o elemento estrutural ------------------------------ */ + +.portao { + background: var(--barra-fundo); + color: var(--barra-texto); + padding: 1.15rem 1.5rem; + margin-block: 2.25rem; +} +.portao-interno { + width: min(var(--medida), 100%); + margin-inline: auto; + display: grid; + grid-template-columns: auto 1fr; + gap: 0.35rem 1rem; + align-items: baseline; +} +.portao .marca { stroke: var(--barra-numero); grid-row: span 2; align-self: start; margin-top: 0.35rem; } +.portao b { + font-family: var(--display); + font-weight: 700; + font-size: 1.1875rem; + letter-spacing: -0.01em; + line-height: 1.25; +} +.portao span { + grid-column: 2; + font-size: 0.9375rem; + line-height: 1.5; + color: var(--barra-suave); +} +.portao code { background: rgba(255,255,255,0.1); border-color: rgba(255,255,255,0.22); color: var(--barra-texto); } + +/* --- numeral do portão: o número é informação, não enfeite ---------------- */ + +.portao b i { + font-style: normal; + display: inline-grid; + place-items: center; + min-width: 1.65rem; + height: 1.65rem; + padding: 0 0.4rem; + margin-right: 0.6rem; + font-size: 0.8125rem; + border-radius: 3px; + background: var(--barra-numero); + color: var(--barra-fundo); + vertical-align: 0.08em; +} + +/* --- portão leve: dentro de uma lista, onde a faixa não cabe ------------- */ + +.decide { + display: flex; + gap: 0.65rem; + align-items: flex-start; + border-left: 3px solid var(--carimbo); + background: var(--carimbo-fraco); + padding: 0.65rem 0.9rem; + margin: 0.75rem 0 0; + font-size: 0.9375rem; + line-height: 1.5; +} +.decide .marca { margin-top: 0.28rem; } +.decide p { margin: 0; color: var(--tinta); } +.decide b { font-family: var(--display); font-weight: 700; } + +/* --- destaques ----------------------------------------------------------- */ + +.regra { + font-family: var(--display); + font-weight: 700; + font-size: clamp(1.375rem, 3.4vw, 1.875rem); + line-height: 1.22; + letter-spacing: -0.015em; + border-left: 6px solid var(--carimbo); + padding: 0.25rem 0 0.25rem 1.25rem; + margin: 2.75rem 0; + text-wrap: balance; +} +.regra cite { display: block; font-family: var(--corpo); font-style: normal; font-weight: 400; font-size: 0.9375rem; color: var(--tinta-suave); letter-spacing: 0; margin-top: 0.6rem; } + +.nota, .pare, .ok { + border-left: 4px solid var(--carimbo); + background: var(--carimbo-fraco); + padding: 1rem 1.25rem; + margin: 1.75rem 0; + font-size: 1rem; +} +.pare { border-left-color: var(--alerta); background: var(--alerta-fraco); } +.ok { border-left-color: var(--verde); background: var(--verde-fraco); } +.nota p:first-child, .pare p:first-child, .ok p:first-child { margin-top: 0; } +.pare strong { color: var(--alerta); } +.ok strong { color: var(--verde); } + +/* --- listas -------------------------------------------------------------- */ + +ul, ol { padding-left: 1.35rem; margin: 0 0 1.15rem; } +li { margin-bottom: 0.4rem; } +li::marker { color: var(--carimbo); } + +.lista-limpa { list-style: none; padding: 0; } +.lista-limpa li::marker { content: none; } + +/* --- os compromissos: rail espesso, sem card ----------------------------- */ + +.compromisso { + border-left: 6px solid var(--carimbo); + padding-left: 1.25rem; + margin: 2rem 0; +} +.compromisso h3 { margin-top: 0; } +.compromisso p { color: var(--tinta-suave); font-size: 1.0625rem; } + +/* --- tabelas ------------------------------------------------------------- */ + +.rolagem { overflow-x: auto; margin-block: 1.75rem; } +/* em tela estreita, rolar na horizontal é melhor que espremer a coluna */ +.rolagem table { min-width: 32rem; } +table { border-collapse: collapse; width: 100%; font-size: 0.9375rem; line-height: 1.45; } +caption { text-align: left; font-family: var(--display); font-weight: 700; font-size: 1rem; padding-bottom: 0.6rem; } +th, td { text-align: left; padding: 0.7rem 1rem 0.7rem 0; border-bottom: 1px solid var(--linha); vertical-align: top; } +th { font-family: var(--display); font-weight: 700; border-bottom-width: 2px; border-bottom-color: var(--tinta); } +td:last-child, th:last-child { padding-right: 0; } +tbody tr:last-child td { border-bottom: none; } +.voce { color: var(--carimbo); font-weight: 600; } +.ia { color: var(--tinta-suave); } +.nao { color: var(--alerta); font-weight: 600; } +.sim { color: var(--verde); font-weight: 600; } + +/* --- o registro assinado (hero) ------------------------------------------ */ + +.registro { + font-family: var(--mono); + font-size: 0.8125rem; + line-height: 1.9; + background: var(--nevoa); + border: 1px solid var(--linha); + border-radius: 4px; + padding: 1.25rem 1.35rem; + margin: 2.5rem 0 0; + overflow-x: auto; +} +.registro table { font-size: inherit; line-height: inherit; min-width: 0; } +.registro th, .registro td { border: none; padding: 0 1.25rem 0 0; white-space: nowrap; } +.registro th { font-family: var(--mono); font-weight: 400; color: var(--tinta-suave); font-size: 0.6875rem; padding-bottom: 0.5rem; letter-spacing: 0.04em; } +.registro .hash { color: var(--tinta-suave); } +.registro .assina { color: var(--carimbo); font-weight: 700; } +.registro tbody tr { opacity: 1; } + +@media (prefers-reduced-motion: no-preference) { + .registro tbody tr { opacity: 0; animation: escreve 0.45s ease-out forwards; } + .registro tbody tr:nth-child(1) { animation-delay: 0.15s; } + .registro tbody tr:nth-child(2) { animation-delay: 0.27s; } + .registro tbody tr:nth-child(3) { animation-delay: 0.39s; } + .registro tbody tr:nth-child(4) { animation-delay: 0.51s; } + .registro tbody tr:nth-child(5) { animation-delay: 0.63s; } + .registro tbody tr:nth-child(6) { animation-delay: 0.75s; } + .registro tbody tr:nth-child(7) { animation-delay: 0.87s; } +} +@keyframes escreve { from { opacity: 0; transform: translateY(0.4rem); } to { opacity: 1; transform: none; } } + +/* --- o fluxo do ciclo ---------------------------------------------------- */ + +.fluxo { list-style: none; padding: 0; margin: 2rem 0; counter-reset: etapa; } +.fluxo > li { + position: relative; + padding: 0 0 1.75rem 3.25rem; + margin: 0; + counter-increment: etapa; +} +.fluxo > li::before { + content: counter(etapa); + position: absolute; + left: 0; top: 0; + width: 2.25rem; height: 2.25rem; + display: grid; place-items: center; + font-family: var(--display); font-weight: 700; font-size: 1rem; + color: var(--papel); background: var(--tinta); + border-radius: 50%; +} +.fluxo > li::after { + content: ""; + position: absolute; + left: 1.125rem; top: 2.6rem; bottom: 0.25rem; + width: 2px; background: var(--linha); +} +.fluxo > li:last-child::after { display: none; } +.fluxo > li.e-portao::before { background: var(--carimbo); } +.fluxo > li.e-pare::before { background: var(--alerta); content: "!"; } +.fluxo h3 { margin: 0.1rem 0 0.35rem; } +.fluxo p { font-size: 1rem; color: var(--tinta-suave); margin-bottom: 0.6rem; } +.fluxo .quem { + font-family: var(--display); + font-size: 0.8125rem; + font-weight: 700; + color: var(--carimbo); + display: block; + margin-bottom: 0.15rem; +} +.fluxo .quem.eh-ia { color: var(--tinta-suave); } + +/* --- definições (dúvidas) ------------------------------------------------ */ + +.perguntas { margin: 2rem 0 0; } +.perguntas dt { + font-family: var(--display); + font-weight: 700; + font-size: 1.125rem; + letter-spacing: -0.01em; + margin-top: 2rem; + padding-top: 1.25rem; + border-top: 1px solid var(--linha); +} +.perguntas dd { margin: 0.5rem 0 0; } + +/* --- checklist ----------------------------------------------------------- */ + +.conferir { list-style: none; padding: 0; margin: 1.75rem 0; } +.conferir li { + position: relative; + padding-left: 2.25rem; + margin-bottom: 0.85rem; + border-bottom: 1px solid var(--linha); + padding-bottom: 0.85rem; +} +.conferir li:last-child { border-bottom: none; } +.conferir li::before { + content: ""; + position: absolute; + left: 0; top: 0.28rem; + width: 1.1rem; height: 1.1rem; + border: 2px solid var(--carimbo); + border-radius: 3px; +} + +/* --- rodapé -------------------------------------------------------------- */ + +.adiante { + border-top: 2px solid var(--tinta); + margin-top: 4.5rem; + padding-top: 1.5rem; +} +.adiante h2 { margin-top: 0; font-size: 1.3125rem; } + +.rodape { + border-top: 1px solid var(--linha); + background: var(--papel-fundo); + padding: 2.5rem 1.5rem; + font-size: 0.9375rem; + color: var(--tinta-suave); +} +.rodape-interno { width: min(var(--largo), 100%); margin-inline: auto; } +.rodape p { margin-bottom: 0.5rem; } + +/* --- ajustes de tela pequena --------------------------------------------- */ + +@media (max-width: 40rem) { + body { font-size: 1.0625rem; } + .pagina { padding-inline: 1.25rem; } + .pagina > .sangra { margin-inline: -1.25rem; } + .topo-interno { width: 100%; padding-inline: 1.25rem; } + .rodape { padding-inline: 1.25rem; } + .portao { padding-inline: 1.25rem; } +} diff --git a/site/assets/portao.svg b/site/assets/portao.svg new file mode 100644 index 0000000..f7250c8 --- /dev/null +++ b/site/assets/portao.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/site/ciclo.html b/site/ciclo.html new file mode 100644 index 0000000..8cc1f06 --- /dev/null +++ b/site/ciclo.html @@ -0,0 +1,351 @@ + + + + + +O ciclo — UTF-SDD + + + + + + + + + +
+
+ + + 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. +
  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. +
  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. +
  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. +
  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. +
  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.

    +
    +
    7. +
+ +
+

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. +
  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.

    +
    3. +
+ +
+
+ + 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. +
  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. +
  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.

    +
    4. +
+ +
+
+ + 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 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.

    +
    2. +
  2. + você +

    Merge na main

    +

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

    +
    3. +
+ +

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.

    +
    2. +
+ +
+
+ + 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. +
  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.

    +
    3. +
+ +
+
+ + 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. +
  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”.

    +
    3. +
+ +
+
+ + 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ê

+
+ +
+ + + + + diff --git a/site/comandos.html b/site/comandos.html new file mode 100644 index 0000000..c27a644 --- /dev/null +++ b/site/comandos.html @@ -0,0 +1,224 @@ + + + + + +Os comandos — UTF-SDD + + + + + + + + + +
+
+ + + UTF-SDD + + +
+
+ +
+ +

Os comandos

+ +

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.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComandoO que produzO que você faz
/utf-prddocs/prd.md — glossário, atores, histórias, regras de negócioLê inteiro, ajusta e commita; leva o tema ao professor
/utf-backlogUma Issue por história Ready, mais o roteiro do KanbanAprova a lista antes de as Issues serem criadas
/utf-flowsdocs/user-flows.md — as jornadas e os pontos de desistênciaDecide o que acontece em cada ponto de desistência e commita
/utf-designdocs/design-tokens.md — paleta, espaçamento, tipografia e o protótipoDecide os tokens e commita
/utf-architecturedocs/architecture.md — estrutura, entidades, estados, contratosLê e commita
/utf-setupapps/ — o monorepo, com a suíte de testes verde e vazia de regrasRatifica 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

+ +
+ + + + + + + + + + + + + + + + + + + + + +
ComandoQuandoO que acontece
/utf-issue 27No começo e no fim da históriaNa 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 1Uma vez por tarefa do planoRoda o ciclo inteiro da tarefa: tutor, implementador, dois revisores, triagem, + leitura do diff e commit. Devolve o controle a você no fim.
/utf-taskSem númeroExecuta 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.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComandoQuandoA pergunta que ele responde
/utf-tutor prd, flows, design, architectureNa Fase 0, antes de commitar cada documentoO que essas decisões significam tecnicamente, no meu documento?
/utf-tutor setupDepois do scaffold (o /utf-setup já chama sozinho)O que são todos esses arquivos que eu não escrevi?
/utf-tutor specAntes de aprovar a specO que essa decisão me obriga a fazer depois?
automáticoAntes de cada tarefa, dentro do /utf-taskO que essa tarefa vai construir, com quais conceitos, e o que eu procuro no diff?
/utf-tutor passo 3Antes do commit (o /utf-task já chama sozinho)A leitura do diff arquivo por arquivo, no seu ritmo.
/utf-tutor 3Depois de uma tarefaO 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 3Para reouvirA explicação pré-implementação daquela tarefa, de novo.
/utf-tutor provaAntes de escrever o PRO 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.

+ +
+

Próximo

+

Quem escreve, quem revisa e por que a trava importa

+
+ +
+ + + + + diff --git a/site/duvidas.html b/site/duvidas.html new file mode 100644 index 0000000..cced758 --- /dev/null +++ b/site/duvidas.html @@ -0,0 +1,245 @@ + + + + + +Dúvidas e erros comuns — UTF-SDD + + + + + + + + + +
+
+ + + UTF-SDD + + +
+
+ +
+ +

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

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ErroPor que dóiO que fazer
Aprovar a spec sem lerO sistema constrói, com perfeição, uma ideia erradaLeia inteira. Discorde de alguma coisa: sempre tem o que ajustar.
Deixar o agente trocar o status da specA aprovação deixa de ser sua e o git log deixa de provar qualquer coisaSó você troca esse campo, e num commit seu.
Commitar a spec junto com o código, no fimO histórico não prova que a especificação veio antesSpec e plano são o primeiro commit da branch.
Histórias grandes demaisO agente se perde, estoura as rodadas e consome muito tokenSe o plano tem mais de dez tarefas, quebre a história em duas e reescreva a spec.
Critérios de aceite vagosNada é verificável, e o revisor inventa critério a cada rodadaEscreva pensando no teste que provaria aquilo.
Deixar o caso de abandono só na prosaNão vira teste, e volta no dia da apresentaçãoTodo caso de abandono também é critério de aceite.
Deixar rodar e olhar só no fimVira uma pilha de código estranho para julgar em cinco minutosAcompanhe. Chame o tutor a cada tarefa. Interrompa quando algo parecer errado.
Deixar o mesmo agente corrigir o que ele escreveuEle herda o próprio ponto cego e defende a abordagem que propôsImplementador novo a cada rodada, com os apontamentos transcritos.
Insistir na mesma conversa depois de várias tentativas falhasA janela de contexto está contaminada: o agente repete e defende a abordagem erradaDescarte o working tree e a conversa. Comece de novo com a spec corrigida.
Aceitar todos os apontamentos do revisorRevela que você não leuRecusar com justificativa vale mais do que aceitar tudo.
Inchar a spec com o que apareceu no caminhoO plano aprovado é abandonado e o auditor compara o diff com uma spec que não descreve mais o trabalhoPare e divida: Issue nova para o que foi descoberto.
Documentar depoisNunca aconteceO auditor final confere antes do PR.
Diagrama desatualizadoDocumentação que mente é pior que documentação ausenteMermaid 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 + + + + + + + + + +
+
+ + + 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.

+ +
+ + + + + + + + + + + + + +
commito que entrouescreveuautorizou
9c1e04aspec e plano da issue 27vocêvocê
4b7ad12spec: rascunho para aprovadavocêvocê
e30f8a6tarefa 1: entidade OrçamentoIAvocê
7fd2b90tarefa 2: recusa orçamento vencidoIAvocê
1a5c8e3tarefa 3: aviso ao aprovarIAvocê
c02d7f5docs: prd e arquitetura no mesmo commitIAvocê
+
+ +

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.

+ +
+ + + + + + + + + + + + + + + + + + +
ArtefatoOnde ficaQuem dirige
README.mdraizvocê
docs/prd.mdo que o produto fazvocê
docs/architecture.mdonde as coisas moramvocê
docs/user-flows.mdo que a pessoa vive na telavocê
docs/design-tokens.mdcores, espaçamento, tipografiavocê
docs/checklist.mda ficha da disciplinavem no template
IssueGitHub Projectsvocê
spec.mdo que precisa existirvocê aprova
plan.mdcomo será construídoIA
Pareceresreviews/IA
Códigoapps/IA
Pull RequestGitHubvocê
+
+ +

Comece por aqui

+ +

Se você acabou de criar o seu repositório pelo Use this template, siga nesta + ordem:

+ +
    +
  1. Entenda o ciclo — a Fase 0, o ciclo de uma história e os quatro portões.
    2. +
  2. Veja os comandos — o que digitar em cada etapa e o que sai de cada um.
    3. +
  3. Conheça os papéis — quem escreve, quem revisa e por que a trava de escrita importa.
    4. +
  4. Leia docs/checklist.md no seu repositório — é a ficha da disciplina, com as regras e as entregas.
    5. +
+ +

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.

+ +
+

Próximo

+

O ciclo, do começo ao Pull Request

+
+ +
+ + + + + diff --git a/site/papeis.html b/site/papeis.html new file mode 100644 index 0000000..aac9353 --- /dev/null +++ b/site/papeis.html @@ -0,0 +1,219 @@ + + + + + +Os papéis — UTF-SDD + + + + + + + + + +
+
+ + + UTF-SDD + + +
+
+ +
+ +

Quem escreve, quem revisa

+ +

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

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AgenteEscreve?O que ele faz
implementadorsimFaz uma tarefa do plano, com TDD, começando com o contexto limpo. É o único que + toca em arquivo de código.
revisor-conformidadenãoCompara 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-codigonãoLê o mesmo diff contra o architecture.md: estrutura, camadas, + contratos, nomes do glossário.
auditor-finalnãoNo fim da história, compara o diff inteiro da branch contra a spec aprovada, + ignorando o plano.
tutornãoExplica. 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.

+ +
+ + + + + + + + + + + + + + + +
FerramentaRegrasComandosSubagentes
Claude CodeCLAUDE.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/
OpenCodeAGENTS.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.

+ +
+

Próximo

+

Erros comuns, o checklist de bolso e as dúvidas frequentes

+
+ +
+ + + + + From 5d8527efe08d58164baa8a05c90054988864eba3 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Thu, 3 Sep 2026 19:16:03 -0300 Subject: [PATCH 2/3] ci: publica o site no GitHub Pages, com guarda de repositorio O job so roda quando github.repository e utfpr-gp/utf-sdd-template. Como o repositorio e um template, sem essa guarda o repositorio de cada aluno tentaria publicar o site do metodo e falharia com o Pages desabilitado. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/site.yml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/workflows/site.yml diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml new file mode 100644 index 0000000..33ab0ce --- /dev/null +++ b/.github/workflows/site.yml @@ -0,0 +1,37 @@ +name: Site do método + +on: + push: + branches: [main] + paths: + - "site/**" + - ".github/workflows/site.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + publicar: + # Este template é clonado por cada aluno. Sem a guarda abaixo, o repositório + # de cada um tentaria publicar o site do método — e falharia se o Pages não + # estiver habilitado lá. No repositório do aluno o job simplesmente não roda. + if: github.repository == 'utfpr-gp/utf-sdd-template' + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.publicacao.outputs.page_url }} + steps: + - uses: actions/checkout@v4 + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: site + - id: publicacao + uses: actions/deploy-pages@v4 From 60a7bd52002e7299f8905830f5427253bdb7978a Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Thu, 3 Sep 2026 19:16:03 -0300 Subject: [PATCH 3/3] docs: aponta o README para o site do metodo O link fica acima da linha de corte, na parte que o aluno apaga ao dar nome ao projeto - e conteudo do template, nao da vitrine dele. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index aa110b4..956637e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,10 @@ projeto com **UTF-SDD**, um **SDD por Portões** (*Gated Spec-Driven Development*): a IA escreve o código; **você decide nos portões**, quem revisa nunca é quem escreveu, e todo artefato é evidência para a defesa. +> 📖 **Entenda o método antes de começar:** +> **[utfpr-gp.github.io/utf-sdd-template](https://utfpr-gp.github.io/utf-sdd-template/)** +> — o ciclo, os portões, os comandos e os papéis, explicados passo a passo. + ## 🚀 Como começar 1. Clique em **Use this template → Create a new repository** (não faça fork). @@ -97,6 +101,8 @@ implementador escreve. A trava tem forças diferentes, e vale saber qual você t O passo a passo detalhado está em [`docs/tutorial-sdd.md`](docs/tutorial-sdd.md); o porquê de cada regra, em [`docs/guia-sdd.md`](docs/guia-sdd.md). +A versão navegável dos dois é o +[site do método](https://utfpr-gp.github.io/utf-sdd-template/). Pré-requisitos das integrações: **`gh` autenticado (`gh auth login`, escopos `repo`, `workflow` e `project`) ou MCP do GitHub** — sem isso, backlog, etiquetas