From 9a4e849c8b70c2d178389b0bece949332da4d5fc Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:48:15 -0300 Subject: [PATCH 01/14] manutencao: Portao de Entendimento de 400 para 250 caracteres MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Alinha o limite ao utf-sdd-template, que baixou o mesmo numero. Os 400 pediam um paragrafo longo mesmo em PR de manutencao de uma linha, e o efeito era texto inflado para passar no CI em vez de explicacao. Toca o workflow do CI, o guia (secao 9 e Apendice B), o CONTRIBUTING e o template de PR — os quatro lugares que afirmavam o numero. Co-Authored-By: Claude Opus 5 (1M context) --- .github/pull_request_template.md | 2 +- .github/workflows/portao-de-entendimento.yml | 6 +++--- CONTRIBUTING.md | 4 ++-- docs/guia-sdd.md | 10 +++++----- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 76c348d..ace4c22 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,7 +3,7 @@ Closes # ## O que este PR faz e por quê diff --git a/.github/workflows/portao-de-entendimento.yml b/.github/workflows/portao-de-entendimento.yml index 10582a7..f540f21 100644 --- a/.github/workflows/portao-de-entendimento.yml +++ b/.github/workflows/portao-de-entendimento.yml @@ -18,8 +18,8 @@ jobs: | sed '/^##/,$d' \ | perl -0pe 's///gs') TAMANHO=$(printf '%s' "$TEXTO" | tr -d '[:space:]' | wc -c) - echo "Caracteres na explicação: $TAMANHO (mínimo 400)" - if [ "$TAMANHO" -lt 400 ]; then - echo "::error::Escreva a seção 'O que este PR faz e por quê' com pelo menos 400 caracteres. Encontrei $TAMANHO." + echo "Caracteres na explicação: $TAMANHO (mínimo 250)" + if [ "$TAMANHO" -lt 250 ]; then + echo "::error::Escreva a seção 'O que este PR faz e por quê' com pelo menos 250 caracteres. Encontrei $TAMANHO." exit 1 fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9f510f..9dc26ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,12 +61,12 @@ O que é **norma inegociável** deste repositório são os cinco portões humano Se o Pull Request for a primeira vez que você olha o código, o método falhou. Todo PR passa por uma verificação automática antes de ser mesclado, e ela confere **uma regra só**: -**O PR será REPROVADO se** a descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos **400 caracteres** (não cole o _diff_ nem a saída da IA; explique com suas palavras). Vale para **todos** os PRs, inclusive os de manutenção. +**O PR será REPROVADO se** a descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos **250 caracteres** (não cole o _diff_ nem a saída da IA; explique com suas palavras). Vale para **todos** os PRs, inclusive os de manutenção. A documentação anda junto do código, mas quem cobra isso não é o CI: PR de história que muda comportamento atualiza `docs/` e `specs/` no mesmo commit — é o **auditor-final** (antes do PR) e o colega que revisa que conferem. **Exceção (Manutenção puramente técnica):** -Se a mudança não afeta o produto (ex: atualizar versão, refatorar código, arrumar formatação), você não precisa criar um `spec.md`. Abra o PR direto e aplique a etiqueta `manutencao` — a explicação de 400 caracteres continua valendo. +Se a mudança não afeta o produto (ex: atualizar versão, refatorar código, arrumar formatação), você não precisa criar um `spec.md`. Abra o PR direto e aplique a etiqueta `manutencao` — a explicação de 250 caracteres continua valendo. --- diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index f61d5a8..a375c8d 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -1035,13 +1035,13 @@ você travou para escrever, volte e leia o código antes de insistir no texto. ## 9. 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** — o que dá, na prática, um parágrafo de +preenchida com pelo menos **250 caracteres** — o que dá, na prática, um parágrafo de verdade. Uma verificação automática confere isso e reprova o PR se faltar. É uma regra só, e ela vale para **todos** os PRs, inclusive os de manutenção. Se a mudança é pequena, a explicação é curta e específica — *"o formulário não desabilitava o submit enquanto inválido, então dava para enviar solicitação sem data; liguei a -validação no botão e ajustei dois testes que dependiam do comportamento antigo"* já passa dos 400 +validação no botão e ajustei dois testes que dependiam do comportamento antigo"* já passa dos 250 caracteres e diz algo. A etiqueta `manutencao` **não dispensa a explicação**. Ela decide outra coisa: se o PR @@ -1229,9 +1229,9 @@ jobs: | sed '/^##/,$d' \ | perl -0pe 's///gs') TAMANHO=$(printf '%s' "$TEXTO" | tr -d '[:space:]' | wc -c) - echo "Caracteres na explicação: $TAMANHO (mínimo 400)" - if [ "$TAMANHO" -lt 400 ]; then - echo "::error::Escreva a seção 'O que este PR faz e por quê' com pelo menos 400 caracteres. Encontrei $TAMANHO." + echo "Caracteres na explicação: $TAMANHO (mínimo 250)" + if [ "$TAMANHO" -lt 250 ]; then + echo "::error::Escreva a seção 'O que este PR faz e por quê' com pelo menos 250 caracteres. Encontrei $TAMANHO." exit 1 fi ``` From fd6ede8ba4ba444063b46db4fce0b31b5e29f0aa Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:48:15 -0300 Subject: [PATCH 02/14] docs: tira as datas fixas da ficha Prazo de entrega vive no Moodle, nao no repositorio: data em arquivo versionado envelhece sem ninguem perceber, e o template e reusado a cada semestre. A tabela das tres entregas perde a coluna Data e ganha a nota dizendo onde a data esta. Co-Authored-By: Claude Opus 5 (1M context) --- docs/checklist.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/checklist.md b/docs/checklist.md index d1b6de0..808487b 100644 --- a/docs/checklist.md +++ b/docs/checklist.md @@ -110,13 +110,16 @@ ## 📦 As três entregas -| Entrega | O quê | Data | -| --- | --- | --- | -| **E1 — Concepção e Planejamento** | Escopo da equipe sobre o tema do semestre, repositório com Gitflow, README com o checklist, Design System, framework CSS, protótipo navegável no Figma | **20 de setembro** | -| **E2 — Estrutura Funcional (MVP)** | Aplicação com a estrutura funcional mínima, consumindo dados do **json-server** | **25 de outubro** | -| **E3 — Aplicação Completa e Apresentação** | Dados e autenticação migrados para o **BaaS** (ex.: Supabase), app completo em produção (Vercel/Render) + **vídeo** apresentando inspiração, design system, protótipo e o projeto contra o checklist | **06 de dezembro** | +| Entrega | O quê | +| --- | --- | +| **E1 — Concepção e Planejamento** | Escopo da equipe sobre o tema do semestre, repositório com Gitflow, README com o checklist, Design System, framework CSS, protótipo navegável no Figma | +| **E2 — Estrutura Funcional (MVP)** | Aplicação com a estrutura funcional mínima, consumindo dados do **json-server** | +| **E3 — Aplicação Completa e Apresentação** | Dados e autenticação migrados para o **BaaS** (ex.: Supabase), app completo em produção (Vercel/Render) + **vídeo** apresentando inspiração, design system, protótipo e o projeto contra o checklist | + +> 📅 **As datas de entrega estão no Moodle.** Elas mudam a cada semestre, e +> data em arquivo do repositório envelhece sem ninguém perceber — a do Moodle é +> a que vale. > 🎥 Se o vídeo for insuficiente, a apresentação é síncrona ao Professor > (presencial ou remota). O detalhamento de cada entrega está no Guia do -> Projeto no Notion: [link no Moodle]. *(Datas valem para 2026/2 — atualize a -> cada semestre.)* +> Projeto no Notion: [link no Moodle]. From 85edd759eee125befe11ccd1d2d9a4e4ba4a67ef Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:49:24 -0300 Subject: [PATCH 03/14] =?UTF-8?q?feat:=20portao=20de=20commit=20na=20Fase?= =?UTF-8?q?=200=20=E2=80=94=20o=20documento=20anterior=20precisa=20estar?= =?UTF-8?q?=20commitado?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cada etapa da Fase 0 passa a rodar `git status --porcelain` no documento que a antecede e a PARAR se houver alteracao pendente. Sem isso o portao da Fase 0 existia so como texto no guia: nada no fluxo impedia seguir com quatro documentos por commitar, que acabavam empilhados num commit unico no fim — e ai o `git log` nao prova mais qual decisao foi de quem. Cadeia coberta: /utf-design confere o prd, /utf-architecture confere prd e design-tokens, /utf-setup confere docs/ inteiro. O /utf-backlog ja exigia o commit do PRD em prosa; agora a exigencia tem comando que a verifica. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/workflows/utf-architecture.md | 11 ++++++++--- .agents/workflows/utf-backlog.md | 4 +++- .agents/workflows/utf-design.md | 5 +++++ .agents/workflows/utf-setup.md | 5 +++++ 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/.agents/workflows/utf-architecture.md b/.agents/workflows/utf-architecture.md index 4be7fe1..c2d8fff 100644 --- a/.agents/workflows/utf-architecture.md +++ b/.agents/workflows/utf-architecture.md @@ -15,9 +15,14 @@ Você é o entrevistador técnico. O aluno é o Arquiteto: **ele decide; você a ## Passo 0 — Pré-condições -0. `docs/design-tokens.md` tem os tokens, os breakpoints e a identidade PWA, e o link público do protótipo está registrado. Se não tiver, **PARE** e mande rodar `/utf-design`: o protótipo e as decisões de abandono revelam estados e telas que este documento precisa mapear — descobri-los depois é retrabalho na primeira spec. -1. `docs/prd.md` existe, com glossário, atores e stories. Sem ele, **PARE**: este documento responde *onde moram* as coisas que o PRD nomeia — sem PRD não há o que mapear. Mande rodar `/utf-prd` antes. -2. Leia `docs/checklist.md` **inteiro** — a seção *Regras da disciplina* diz o que é stack fixa e o que é escolha do aluno, e vários IDs são padrões estruturais que este documento precisa declarar. +0. **Os documentos anteriores estão commitados.** Rode + `git status --porcelain docs/prd.md docs/design-tokens.md`: se a saída **não** estiver + vazia, ou se algum deles não estiver versionado, **PARE** e peça o commit ao aluno. + O commit é o que põe o nome dele na decisão; sem ele a autoria da Fase 0 some num + commit único no fim. +1. `docs/design-tokens.md` tem os tokens, os breakpoints e a identidade PWA, e o link público do protótipo está registrado. Se não tiver, **PARE** e mande rodar `/utf-design`: o protótipo e as decisões de abandono revelam estados e telas que este documento precisa mapear — descobri-los depois é retrabalho na primeira spec. +2. `docs/prd.md` existe, com glossário, atores e stories. Sem ele, **PARE**: este documento responde *onde moram* as coisas que o PRD nomeia — sem PRD não há o que mapear. Mande rodar `/utf-prd` antes. +3. Leia `docs/checklist.md` **inteiro** — a seção *Regras da disciplina* diz o que é stack fixa e o que é escolha do aluno, e vários IDs são padrões estruturais que este documento precisa declarar. ## Passo 1 — As decisões, uma por vez diff --git a/.agents/workflows/utf-backlog.md b/.agents/workflows/utf-backlog.md index 51a6124..2fb4131 100644 --- a/.agents/workflows/utf-backlog.md +++ b/.agents/workflows/utf-backlog.md @@ -15,7 +15,9 @@ fica velha, e a IA lê a versão errada. (`gh auth status`). Sem um dos dois, **PARE** e oriente: instalar o `gh`, `gh auth login`, escopos `repo` e `project`. 2. `docs/prd.md` preenchido e **commitado pelo aluno**, com o tema já - **aceito pelo professor**. + **aceito pelo professor**. Confira o commit com + `git status --porcelain docs/prd.md`: saída não vazia significa que ainda há + alteração pendente — **PARE** e peça o commit antes de criar Issue nenhuma. 3. Existe ao menos uma story com `Status: Ready`. Story `Draft` não vira Issue — regra indefinida não entra na fila de implementação. diff --git a/.agents/workflows/utf-design.md b/.agents/workflows/utf-design.md index f4ea12c..d18f814 100644 --- a/.agents/workflows/utf-design.md +++ b/.agents/workflows/utf-design.md @@ -19,6 +19,11 @@ não consegue guardar — os tokens, os breakpoints e as decisões de abandono. ## Passo 0 — Pré-condições +0. **O documento anterior está commitado.** Rode `git status --porcelain docs/prd.md`: + se a saída **não** estiver vazia, ou se o arquivo não estiver versionado, **PARE** e + peça o commit ao aluno. Não é burocracia: cada documento da Fase 0 é decisão dele, e + o commit é o que põe o nome dele nessa decisão. Seguir sem commitar empilha os + documentos num commit só, no fim, e a autoria some. 1. `docs/prd.md` preenchido, com stories e critérios. Sem ele, **PARE** e mande rodar `/utf-prd` — design sem requisito é decoração. 2. Se `docs/design-tokens.md` já tem conteúdo real, **PARE** e pergunte: revisar ou diff --git a/.agents/workflows/utf-setup.md b/.agents/workflows/utf-setup.md index f01ea9e..e55fd5e 100644 --- a/.agents/workflows/utf-setup.md +++ b/.agents/workflows/utf-setup.md @@ -14,6 +14,11 @@ que foi decidida. O que não estiver escrito lá, você pergunta; não escolhe. ## Passo 0 — Pré-condições (PARE se qualquer uma falhar) +0. **Os documentos da Fase 0 estão commitados.** Rode `git status --porcelain docs/`: + se a saída **não** estiver vazia, **PARE** e peça o commit. O scaffold vai nascer a + partir do `architecture.md`; se ele ainda não está no histórico, o repositório não tem + como provar qual decisão gerou qual arquivo — e é essa rastreabilidade que a avaliação + cobra. 1. `docs/prd.md` e `docs/architecture.md` existem e declaram: o framework do frontend (versão e padrões), a fonte de dados de cada fase, a estrutura de pastas e como rodar os testes. From 33db14366c9222497ccd851849d99e497053053c Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:49:45 -0300 Subject: [PATCH 04/14] feat: retomada da Issue no /utf-issue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sem essa regra, rodar /utf-issue numa historia ja em andamento fazia o fluxo recomecar do Passo 1 e reescrever uma spec que o usuario ja tinha aprovado — apagando o commit de aprovacao dele como referencia. Agora o fluxo descobre o estado pela pasta specs/ e entra no passo certo, o que tambem e o mecanismo que fecha a Issue depois da ultima tarefa. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/workflows/utf-issue.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.agents/workflows/utf-issue.md b/.agents/workflows/utf-issue.md index fb16d39..f0f6e43 100644 --- a/.agents/workflows/utf-issue.md +++ b/.agents/workflows/utf-issue.md @@ -9,6 +9,7 @@ Sempre que o usuário pedir para trabalhar em uma Issue (Feature), você atuará **Passo 0: Pré-condições** - Acesso ao GitHub: MCP do GitHub disponível **ou** `gh` autenticado (`gh auth status`). Sem um dos dois, **PARE** — este fluxo lê Issues e prepara PR. - A Issue existe no GitHub. Se as Issues das stories ainda não foram criadas, mande rodar `/utf-backlog` primeiro. +- **Retomada.** Se `specs/-/` já existe, **não recomece**: descubra o estado e entre no passo certo — spec `rascunho` → a pausa do Passo 1, esperando a aprovação; `aprovada` sem `plan.md` → Passo 2; plano com tarefa pendente → Passo 3; todas as tarefas feitas → Passo 4. É assim que `/utf-issue ` fecha a Issue depois da última tarefa, e é o que impede reescrever uma spec que o usuário já aprovou. **Passo 1: Entendimento e Brainstorming** - Leia a Issue apontada e busque no `docs/prd.md` os critérios e o Glossário Ubíquo. From c6a6deb05781e4b9e2adf1f8e889a915c4b4e654 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:53:16 -0300 Subject: [PATCH 05/14] feat: modos passo, documento e setup no tutor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O tutor do Angular tinha 4 modos; o do utf-sdd-template tem 9. Portados os que fazem sentido aqui (o modo `flows` fica de fora: neste template a jornada vive no prototipo, nao num docs/user-flows.md): - `passo ` — le o diff da tarefa um arquivo por vez, no ritmo do aluno. E onde se aprende sintaxe: inject(), signal(), async aparecem pela primeira vez com cinco linhas na frente, nao no PR com quarenta arquivos. - `prd | design | architecture` — explica um documento da Fase 0 em cima do documento do aluno, antes de ele commitar uma decisao que nao sabe defender na arguicao. - `setup` — explica o scaffold: o app, a fonte de dados, e por que a suite nasce verde e vazia. O /utf-setup despacha sozinho, sem perguntar, porque e o unico momento do semestre em que o aluno recebe dezenas de arquivos que nao viu nascer. Cada etapa da Fase 0 passa a oferecer o tutor no portao. O modo `depois` tambem ganhou o caso da tarefa ainda nao commitada e um grep de commit que nao confunde `tarefa 1` com `tarefa 10`. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/agents/tutor.md | 114 ++++++++++++++++++++++++++ .agents/workflows/utf-architecture.md | 1 + .agents/workflows/utf-design.md | 2 + .agents/workflows/utf-prd.md | 1 + .agents/workflows/utf-setup.md | 10 ++- .agents/workflows/utf-tutor.md | 13 ++- .claude/agents/tutor.md | 2 +- .claude/commands/utf-tutor.md | 4 +- .cursor/agents/tutor.md | 2 +- .cursor/commands/utf-tutor.md | 2 +- .opencode/agents/tutor.md | 2 +- .opencode/command/utf-tutor.md | 2 +- docs/tutorial-sdd.md | 12 ++- 13 files changed, 155 insertions(+), 12 deletions(-) diff --git a/.agents/agents/tutor.md b/.agents/agents/tutor.md index 77eccb4..032e8aa 100644 --- a/.agents/agents/tutor.md +++ b/.agents/agents/tutor.md @@ -62,6 +62,12 @@ Devolva markdown exatamente nesta forma: +## Arquivo por arquivo, o que vai aparecer +| Arquivo | O que vai ser escrito nele | O que você precisa reconhecer ali | + + ## Roteiro para conferir o diff na IDE <3 a 6 itens, na ordem de leitura: "abra tal arquivo e procure X; se estiver Y, entenda Z"> @@ -124,3 +130,111 @@ O gabarito é para quem conduz o simulado, **não** para o aluno ver antes de re --- > ⚠️ Você existe para o aluno chegar à defesa **sem precisar de você**. Nunca entregue texto pronto para ele colar no PR ou decorar — entregue entendimento. + +## Modo `passo` — a leitura do diff, um arquivo por vez + +O aluno acabou de receber o diff de uma tarefa e ele passou rápido demais. Aqui você não resume: **destrincha, arquivo por arquivo**, na ordem em que faz sentido ler — o teste primeiro, depois aquilo que ele obriga a existir. + +Este é o momento em que se aprende **sintaxe**. O aluno está vendo um `inject()`, um `signal()`, um `async`, um `expect(...).rejects` pela primeira vez, e a chance de perguntar é agora, com cinco linhas na frente dele, não no PR com quarenta arquivos. + +O despacho traz o número da tarefa e o comando de diff. Rode-o e leia tudo. Devolva **um bloco por arquivo**, e nada além — quem conduz a conversa é quem te despachou, e vai entregar um bloco de cada vez: + +``` +# Tutor — Tarefa , arquivo por arquivo + +## Arquivo 1 de — `caminho/do/arquivo` + +**Por que este arquivo entra nesta tarefa:** + +**O que foi escrito:** + +**A sintaxe que aparece aqui pela primeira vez** +| No código | Como se chama | O que faz | +(só o que ainda não apareceu nos arquivos anteriores desta tarefa) + +**Se este arquivo não existisse:** + +**Pergunta:** + +## Arquivo 2 de — `...` +``` + +**Um arquivo por bloco, sem exceção** — mesmo o de três linhas. Arquivo pequeno (um `app.config.ts`, um export, uma rota) costuma ser o que passa despercebido e o que o professor pergunta. + +--- + +## Modo `documento` — explicar um artefato da Fase 0 + +O despacho diz **qual** documento (`prd`, `design` ou `architecture`) e o caminho dele. Leia o documento **do aluno** e explique em cima dele: exemplo genérico não ensina, porque o aluno não se reconhece ali. + +Ele acabou de responder a uma entrevista e aceitou termos que talvez não conheça. Sua pergunta é: *ele saberia defender cada decisão deste documento sozinho, na arguição?* + +``` +# Tutor — + +## O que este documento decide + + +## Os conceitos que aparecem nele +### + +(3 a 6 blocos: os conceitos que ele provavelmente não domina, não todos) + +## O que cada decisão obriga depois + + +## O que ainda está em aberto + + +## Três perguntas de professor +1. ... +(sem as respostas) + +## Para pesquisar +<2 a 4 termos exatos> +``` + +--- + +## Modo `setup` — explicar o scaffold recém-gerado + +Despachado automaticamente pelo `/utf-setup`, antes do primeiro Pull Request. É o **único momento do semestre em que o aluno recebe dezenas de arquivos que ele não escreveu e não viu nascer**. Trate cada arquivo e cada palavra como novidade. + +``` +# Tutor — o scaffold do projeto + +## O que o gerador criou, e por que essa forma + + +## O app e a fonte de dados +### O app `apps/web` — Angular + +### A fonte de dados — + + + +## Os arquivos que você não escreveu +| Arquivo ou pasta | Para que serve | Quando você vai mexer nele | +(só os que importam: o `package.json`, `angular.json`, `tsconfig.json`, a configuração +do runner de teste, `.gitignore`, `.gitattributes`, `.github/`) + +## Por que a suíte nasce verde e vazia + + +## Três perguntas de professor +1. ... +(sem as respostas) + +## Para pesquisar +<2 a 4 termos exatos> +``` diff --git a/.agents/workflows/utf-architecture.md b/.agents/workflows/utf-architecture.md index c2d8fff..6bd86b0 100644 --- a/.agents/workflows/utf-architecture.md +++ b/.agents/workflows/utf-architecture.md @@ -48,6 +48,7 @@ Antes de fechar, confira que o documento declara **explicitamente** as quatro co 1. Percorra o `docs/checklist.md` e confira o documento contra **todo ID que dependa de uma declaração de arquitetura** — o que faltar vira pergunta, não texto inventado. 2. Grave `docs/architecture.md`. **PARE.** O aluno lê fora do chat; o commit é dele. Próximo passo: `/utf-setup`. + Este é o documento mais técnico da Fase 0, e o aluno acabou de decidir coisas que talvez não conheça. Ofereça, sem enfeite: *"Antes de commitar, rode `/utf-tutor architecture` — ele explica standalone, injeção de dependência, signals e o modelo de dados do BaaS em cima das suas escolhas, não em exemplo genérico."* ## Proibições diff --git a/.agents/workflows/utf-design.md b/.agents/workflows/utf-design.md index d18f814..8e721f3 100644 --- a/.agents/workflows/utf-design.md +++ b/.agents/workflows/utf-design.md @@ -65,6 +65,8 @@ vira documento novo — vira **regra de negócio ou critério de aceite no `prd. link do protótipo). 2. **PARE.** A equipe revisa fora do chat; o commit é dela. Próximo passo: `/utf-architecture`. + Ofereça: *"Rode `/utf-tutor design` se quiser entender por que nome semântico de cor, + escala de espaçamento e estados de botão mudam o que a IA vai gerar em cada tela."* ## Proibições diff --git a/.agents/workflows/utf-prd.md b/.agents/workflows/utf-prd.md index b5ab4b5..a480396 100644 --- a/.agents/workflows/utf-prd.md +++ b/.agents/workflows/utf-prd.md @@ -48,6 +48,7 @@ Percorra o `docs/checklist.md` e confira o rascunho contra **todo ID cuja sement 1. Grave `docs/prd.md` completo. 2. **PARE.** O aluno lê o documento inteiro, fora do chat. Ajuste agora custa uma conversa; depois, custa uma spec. + Ofereça, com estas palavras: *"Se algum termo do documento for novo — user story, critério de aceite, MoSCoW, glossário ubíquo — rode `/utf-tutor prd` antes de commitar, que eu explico cada um em cima do seu documento."* 3. O commit do `prd.md` é **dele**. Próximos passos, nesta ordem: com o **aceite do professor** e stories `Ready`, `/utf-backlog` leva as stories para o GitHub (Issues + Kanban); depois `/utf-design`, que fecha tokens, protótipo e os pontos de desistência; e só então `/utf-architecture`. ## Proibições diff --git a/.agents/workflows/utf-setup.md b/.agents/workflows/utf-setup.md index e55fd5e..ad07e79 100644 --- a/.agents/workflows/utf-setup.md +++ b/.agents/workflows/utf-setup.md @@ -176,12 +176,18 @@ motivo, **PARE** e relate. Não tente uma terceira abordagem. 1. Commits pequenos e nomeados por passo (apps, raiz, ferramentas do método) — **cada um proposto ao usuário antes** ("commit do passo X: ?"), nenhum sem o OK dele. -2. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o +2. **Despache o tutor em modo `setup`, antes do PR.** Este é o único momento do + semestre em que o aluno recebe um monte de arquivos que ele não escreveu e não + viu nascer — se ninguém explicar, ele abre o primeiro PR sem saber o que tem + dentro do próprio repositório. Não pergunte se ele quer: despache, apresente a + explicação na íntegra e só então siga. O despacho leva `docs/architecture.md`, a + lista de arquivos gerados e a saída dos testes. +3. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o `architecture.md` não cobria (Passo 2) para ele ratificar no documento. **Ratificação aprovada pelo usuário = atualize o `architecture.md` na mesma branch**, antes do PR — documento e scaffold entram juntos, contando a mesma história. -3. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task, +4. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task, não história. O corpo já vem preenchido pelo `.github/pull_request_template.md`, que está na `main` desde o template. Explique o detalhe que ninguém adivinha: diff --git a/.agents/workflows/utf-tutor.md b/.agents/workflows/utf-tutor.md index cb4e1c1..f68d210 100644 --- a/.agents/workflows/utf-tutor.md +++ b/.agents/workflows/utf-tutor.md @@ -1,5 +1,5 @@ --- -description: Despacha o agente tutor no modo certo — explicar uma tarefa já feita (número), as decisões da spec (spec) ou conduzir o simulado pré-PR (prova). O modo "antes" é despachado automaticamente pelo fluxo utf-task. +description: Despacha o agente tutor no modo certo — explicar uma tarefa já feita (número ou passo), um documento da Fase 0 (prd, design, architecture), o scaffold (setup), as decisões da spec (spec) ou conduzir o simulado pré-PR (prova). O modo "antes" é despachado automaticamente pelo fluxo utf-task. --- # Fluxo do tutor @@ -16,6 +16,11 @@ Argumento recebido: **$1** | `antes ` | `antes` — explica a tarefa antes da implementação (normalmente quem chama isso é o fluxo utf-task) | | `spec` | `spec` — explica as consequências técnicas da spec em rascunho | | `prova` | `prova` — simulado interativo sobre o diff inteiro da branch | +| `passo ` | `passo` — lê o diff da tarefa `` **um arquivo por vez**, no ritmo do aluno | +| `prd` | `documento` — explica o `docs/prd.md` que o aluno acabou de escrever | +| `design` | `documento` — explica o `docs/design-tokens.md` | +| `architecture` | `documento` — explica o `docs/architecture.md` | +| `setup` | `setup` — explica o scaffold gerado: o app, a fonte de dados e a configuração | Sem argumento, pergunte ao usuário qual modo ele quer. @@ -24,13 +29,17 @@ Sem argumento, pergunte ao usuário qual modo ele quer. 1. Descubra a pasta `specs/-/` da branch atual. 2. Todo despacho leva os caminhos completos de `spec.md`, `plan.md` e `docs/architecture.md`, além do **modo**. 3. Conforme o modo, acrescente: - - **`depois`**: número e texto literal da tarefa, e o comando de diff. Encontre o commit da tarefa com `git log --oneline --grep "tarefa "` (convenção de commit do fluxo utf-task) e monte `git diff ^..`. Se a tarefa tiver mais de um commit ou o commit não for encontrado, monte o intervalo à mão e confirme com o usuário antes de despachar. + - **`depois`**: número e texto literal da tarefa, e o comando de diff. Encontre o commit da tarefa com `git log --oneline --grep "^tarefa :"` (convenção de commit do fluxo utf-task; o `^` e o `:` impedem que `tarefa 1` case com `tarefa 10`) e monte `git diff ^..`. Se a tarefa **ainda não foi commitada** (o aluno quer a aula antes de autorizar o commit), o diff é o working tree: `git add -A && git diff HEAD`. Se a tarefa tiver mais de um commit ou o commit não for encontrado, monte o intervalo à mão e confirme com o usuário antes de despachar. - **`antes`**: número e texto literal da tarefa, e os critérios de aceite ligados a ela, transcritos. - **`prova`**: o comando do diff completo da branch: `git diff develop..HEAD` (no Gitflow a feature branch nasce da `develop` — diff contra a `main` traria trabalho de outras histórias já integradas). + - **`passo`**: número da tarefa e o comando de diff — o mesmo do modo `depois` se a tarefa já foi commitada; `git add -A && git diff HEAD` se ela ainda está no working tree, esperando o portão do commit. + - **`documento`**: qual documento (`prd`, `design` ou `architecture`) e o caminho dele. O tutor lê o documento do aluno, não um exemplo. + - **`setup`**: a lista de arquivos e pastas gerados (`git diff --stat develop..HEAD` ou `git show --stat`), o comando de teste do `architecture.md` e a saída da suíte. ## Entregar - **Modos `antes`, `depois` e `spec`:** apresente a resposta do tutor ao usuário **na íntegra, sem resumir** — resumo seu é exatamente a contaminação que o tutor existe para evitar. Depois, coloque-se à disposição para dúvidas: repasse cada dúvida ao tutor em novo despacho se ela exigir olhar o código de novo. +- **Modo `passo`:** o tutor te devolve um bloco por arquivo. **Entregue um bloco por vez** e espere o usuário dizer que entendeu ou perguntar. Não emende dois arquivos na mesma mensagem, mesmo que o segundo seja curto — o ponto do modo é o ritmo. Dúvida sobre um arquivo volta ao tutor em novo despacho, se exigir olhar o código de novo. No fim, pergunte se ele quer rever algum. - **Modo `prova`:** o tutor te devolve as questões **com gabarito**. O gabarito é seu, não do aluno: 1. Faça **uma pergunta por vez** e espere a resposta do usuário. 2. Compare com o gabarito e dê o retorno de forma didática: o que acertou, o que faltou, onde está a evidência (`arquivo:linha`). diff --git a/.claude/agents/tutor.md b/.claude/agents/tutor.md index 9ed8da4..90fb338 100644 --- a/.claude/agents/tutor.md +++ b/.claude/agents/tutor.md @@ -1,6 +1,6 @@ --- name: tutor -description: Ensina o aluno em nível bem didático — explica a tarefa antes da implementação (modo antes), o diff depois (modo depois), as decisões da spec (modo spec) e gera o simulado pré-PR (modo prova). Não escreve código, não corrige, não opina sobre qualidade. +description: Ensina o aluno em nível bem didático — explica a tarefa antes da implementação (modo antes), o diff depois (modo depois ou passo, arquivo por arquivo), os documentos da Fase 0 (modo documento), o scaffold (modo setup), as decisões da spec (modo spec) e gera o simulado pré-PR (modo prova). Não escreve código, não corrige, não opina sobre qualidade. tools: Read, Grep, Glob, Bash --- diff --git a/.claude/commands/utf-tutor.md b/.claude/commands/utf-tutor.md index cc80cd7..d7105df 100644 --- a/.claude/commands/utf-tutor.md +++ b/.claude/commands/utf-tutor.md @@ -1,6 +1,6 @@ --- -description: Chama o agente tutor — /utf-tutor explica a tarefa n já implementada; /utf-tutor antes explica antes de implementar; /utf-tutor spec explica a spec em rascunho; /utf-tutor prova conduz o simulado pré-PR. -argument-hint: | spec | prova> +description: Chama o agente tutor — /utf-tutor explica a tarefa n já implementada; /utf-tutor passo destrincha o diff dela um arquivo por vez; /utf-tutor antes explica antes de implementar; /utf-tutor prd | design | architecture explica um documento da Fase 0; /utf-tutor setup explica o scaffold; /utf-tutor spec explica a spec em rascunho; /utf-tutor prova conduz o simulado pré-PR. +argument-hint: | antes | spec | prova | prd | design | architecture | setup> --- Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. diff --git a/.cursor/agents/tutor.md b/.cursor/agents/tutor.md index 59cc9e6..99abf4c 100644 --- a/.cursor/agents/tutor.md +++ b/.cursor/agents/tutor.md @@ -1,6 +1,6 @@ --- name: tutor -description: Ensina o aluno — explica a tarefa antes, o diff depois, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. +description: Ensina o aluno em nível bem didático — explica a tarefa antes da implementação (modo antes), o diff depois (modo depois ou passo, arquivo por arquivo), os documentos da Fase 0 (modo documento), o scaffold (modo setup), as decisões da spec (modo spec) e gera o simulado pré-PR (modo prova). Não escreve código, não corrige, não opina sobre qualidade. readonly: true --- Leia `.agents/agents/tutor.md` e siga-o integralmente antes de qualquer outra ação. diff --git a/.cursor/commands/utf-tutor.md b/.cursor/commands/utf-tutor.md index 2068d83..a52babd 100644 --- a/.cursor/commands/utf-tutor.md +++ b/.cursor/commands/utf-tutor.md @@ -1,5 +1,5 @@ --- -description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; prova conduz o simulado pré-PR. +description: Chama o agente tutor — /utf-tutor explica a tarefa n já implementada; /utf-tutor passo destrincha o diff dela um arquivo por vez; /utf-tutor antes explica antes de implementar; /utf-tutor prd | design | architecture explica um documento da Fase 0; /utf-tutor setup explica o scaffold; /utf-tutor spec explica a spec em rascunho; /utf-tutor prova conduz o simulado pré-PR. --- Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. diff --git a/.opencode/agents/tutor.md b/.opencode/agents/tutor.md index da5d4b3..f160d7a 100644 --- a/.opencode/agents/tutor.md +++ b/.opencode/agents/tutor.md @@ -1,5 +1,5 @@ --- -description: Ensina o aluno — explica a tarefa antes, o diff depois, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. +description: Ensina o aluno — explica a tarefa antes, o diff depois (inteiro ou arquivo por arquivo), os documentos da Fase 0, o scaffold, a spec e o simulado pré-PR. Não escreve código, não corrige, não opina sobre qualidade. mode: subagent tools: write: false diff --git a/.opencode/command/utf-tutor.md b/.opencode/command/utf-tutor.md index 9785651..8ad9401 100644 --- a/.opencode/command/utf-tutor.md +++ b/.opencode/command/utf-tutor.md @@ -1,5 +1,5 @@ --- -description: Chama o agente tutor: explica a tarefa já implementada; antes explica antes de implementar; spec explica a spec em rascunho; prova conduz o simulado pré-PR. +description: Chama o agente tutor — /utf-tutor explica a tarefa n já implementada; /utf-tutor passo destrincha o diff dela um arquivo por vez; /utf-tutor antes explica antes de implementar; /utf-tutor prd | design | architecture explica um documento da Fase 0; /utf-tutor setup explica o scaffold; /utf-tutor spec explica a spec em rascunho; /utf-tutor prova conduz o simulado pré-PR. --- Leia `.agents/workflows/utf-tutor.md` e execute-o integralmente. diff --git a/docs/tutorial-sdd.md b/docs/tutorial-sdd.md index 76ad371..437f900 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -27,6 +27,13 @@ Cinco comandos, nesta ordem, cada um fechando num portão seu: Pré-requisito dos passos 2 e 5: `gh` autenticado ou MCP do GitHub. O `/utf-backlog` pode rodar de novo mais tarde, a cada leva de stories promovidas a `Ready`. +> 🎓 **O tutor também vale na Fase 0.** Cada documento é decisão sua, e decisão que +> você não sabe explicar não sobrevive à arguição. Antes de commitar, rode +> `/utf-tutor prd`, `design` ou `architecture` — ele explica os conceitos em cima do +> **seu** documento, não em exemplo genérico. Depois do `/utf-setup` você não precisa +> pedir: o fluxo chama o tutor sozinho, porque ali é o único momento em que você +> recebe dezenas de arquivos que não escreveu. + --- ## Antes de começar (uma vez por história) @@ -80,7 +87,7 @@ Dentro do comando acontece o ciclo completo, com as suas paradas: | Revisão em paralelo | revisor-conformidade + revisor-codigo | nada — quem despacha é o fluxo | | Pareceres gravados em `reviews/` | orquestrador | nada | | **Triagem** (se houve apontamentos) | orquestrador apresenta a lista | **🚪 aceita ou recusa cada um** — recusa exige justificativa, registrada em `reviews/tarefa-NN-decisoes-rN.md` | -| Commit `tarefa 1: ...` | orquestrador apresenta o diff e os pareceres | **🚪 confere o diff na IDE e autoriza** ("pode commitar"); `/utf-tutor 1` se quiser a aula | +| Commit `tarefa 1: ...` | orquestrador apresenta o diff e os pareceres | **🚪 confere o diff na IDE e autoriza** ("pode commitar"); `/utf-tutor passo 1` destrincha o diff arquivo por arquivo, e `/utf-tutor 1` dá a aula depois do commit | Repita para cada tarefa: `/utf-task 2`, `/utf-task 3`… — ou apenas `/utf-task`, que pega a próxima pendente do `plan.md` e avisa quando não @@ -118,7 +125,10 @@ palavras, lista os apontamentos aceitos e recusados (saem dos arquivos | `/utf-setup` | Fase 0, etapa 5 — gera o scaffold do projeto | | `/utf-issue ` | Uma vez, para iniciar o ciclo da Issue (spec → plano) | | `/utf-task [n]` | Uma vez **por tarefa** do plano — sem número, executa a próxima pendente | +| `/utf-tutor prd` · `design` · `architecture` | Na Fase 0, antes de commitar cada documento | +| `/utf-tutor setup` | Depois do scaffold — o app, a fonte de dados e os arquivos que você não escreveu (o `/utf-setup` já chama sozinho) | | `/utf-tutor spec` | Antes de aprovar a spec | +| `/utf-tutor passo ` | A leitura do diff arquivo por arquivo, no seu ritmo | | `/utf-tutor ` | Depois de uma tarefa, para a aula sobre aquele diff | | `/utf-tutor antes ` | Para reouvir a explicação pré-implementação de uma tarefa | | `/utf-tutor prova` | Antes de escrever o PR — o ensaio da defesa | From 1e09da96f0ef4bd8140752b880ffa0acf5736c6b Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:54:38 -0300 Subject: [PATCH 06/14] docs: modelos comentados de spec e plano MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O /utf-issue descrevia a spec e o plano em prosa, e o formato saia diferente a cada historia — o que faz o revisor de conformidade procurar criterio numerado onde nao ha e o /utf-task nao achar a proxima tarefa. Agora a forma esta escrita, com um comentario em cada secao dizendo por que ela existe: o teste que prova um criterio de aceite, o "Fora de escopo" que segura o inchaco da spec, o "Assume que" que exige TODO e Issue, e as "Duvidas em aberto" que precisam estar vazias antes da aprovacao. Os modelos moram em docs/ de proposito: specs/ so tem spec de verdade. Adaptados ao template: dependencia contra a develop (Gitflow), o teste e um .spec.ts, o contrato e com o json-server ou o BaaS, e o caso de "Assume que" mais comum aqui e a colecao que so migra para o BaaS na E3. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/workflows/utf-issue.md | 4 +- CONTRIBUTING.md | 1 + docs/guia-sdd.md | 4 +- docs/modelo-plan.md | 44 ++++++++++++++++++++ docs/modelo-spec.md | 76 ++++++++++++++++++++++++++++++++++ 5 files changed, 125 insertions(+), 4 deletions(-) create mode 100644 docs/modelo-plan.md create mode 100644 docs/modelo-spec.md diff --git a/.agents/workflows/utf-issue.md b/.agents/workflows/utf-issue.md index f0f6e43..2088517 100644 --- a/.agents/workflows/utf-issue.md +++ b/.agents/workflows/utf-issue.md @@ -15,7 +15,7 @@ Sempre que o usuário pedir para trabalhar em uma Issue (Feature), você atuará - Leia a Issue apontada e busque no `docs/prd.md` os critérios e o Glossário Ubíquo. - Faça perguntas ao usuário de forma proativa. Questione sobre casos de borda, caminhos tristes (ex: falhas de rede, dados inválidos) e como validar os critérios de aceite. - Após sanar as dúvidas, **crie a branch da história a partir da `develop`** (`git switch develop && git pull && git switch -c -`). Ela nasce agora, antes da aprovação, porque no Gitflow `main` e `develop` são bloqueadas — e o commit de aprovação do usuário precisa de um lugar para viver. -- Redija o documento e salve no caminho `specs/-/spec.md`, commitando o rascunho na branch, com este frontmatter: +- Redija o documento e salve no caminho `specs/-/spec.md`, commitando o rascunho na branch. **A estrutura é a de `docs/modelo-spec.md`** — copie-a e preencha; os comentários dela explicam cada seção e são apagados no caminho. Não invente seções novas nem pule as existentes. O frontmatter: ```yaml --- @@ -30,7 +30,7 @@ status: rascunho # rascunho | aprovada - Com o `spec.md` aprovado, quebre o trabalho em tarefas curtas e encadeadas — cada uma prova **um critério de aceite inteiro**, ou é um passo técnico que sozinho não prova nada mas destrava o próximo. - Cada tarefa deve prever a criação de testes primeiro (TDD). - Se o plano passar de **10 tarefas**, pare: a história é grande demais. Proponha dividi-la em duas Issues antes de continuar. -- Salve o resultado no caminho `specs/-/plan.md`. +- Salve o resultado no caminho `specs/-/plan.md`, na forma de `docs/modelo-plan.md`: checklist `- [ ] **Tarefa N — **`, cada uma citando o critério de aceite que cobre e o teste que nasce primeiro. Tarefa feita vira `- [x]`: é essa marcação que o `/utf-task` sem número lê. A seção *Critérios sem tarefa* precisa terminar vazia. - **PAUSA OBRIGATÓRIA:** Peça a aprovação do usuário para o plano. Com o OK, commite o `plan.md` na branch da história. **Passo 3: Execução (uma tarefa por vez)** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9dc26ce..612ac6f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,7 @@ Nada é duplicado neste projeto. Informação repetida diverge. | **Ficha** | `docs/checklist.md` | As regras da disciplina, os IDs e as entregas — a régua dos workflows. | | **Design** | `docs/design-tokens.md` | Tokens, breakpoints, identidade PWA e o link do protótipo navegável. | | **Especificação** | `specs/-/` | O `spec.md` (o que fazer), o `plan.md` (tarefas técnicas) e `reviews/` (pareceres e triagem). | +| **Modelos** | `docs/modelo-spec.md` e `docs/modelo-plan.md` | A forma do `spec.md` e do `plan.md`, comentada. Não são specs — são a régua. | | **Leis da IA** | `.agents/` | `rules/utf-rules.md` (constituição, carregada via `CLAUDE.md`), `workflows/` (ciclos) e `agents/` (prompts dos subagentes). | --- diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index a375c8d..87793b8 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -70,8 +70,8 @@ Todo trabalho gira em torno de onze artefatos. Eles são a matéria-prima da sua | **`checklist.md`** | `docs/` | A ficha da disciplina: regras do projeto, IDs e entregas — a régua dos workflows. | | **`design-tokens.md`** | `docs/` | Cores, espaçamento, tipografia — para a IA não inventar um botão por tela. | | **Issue** | GitHub Projects | A unidade de trabalho. Uma história de usuário. | -| **`spec.md`** | `specs/-/` | O que precisa existir e como saber que ficou pronto. | -| **`plan.md`** | `specs/-/` | Como será construído, em tarefas pequenas. | +| **`spec.md`** | `specs/-/` | O que precisa existir e como saber que ficou pronto. A forma dele, comentada, está em `docs/modelo-spec.md`. | +| **`plan.md`** | `specs/-/` | Como será construído, em tarefas pequenas. A forma, em `docs/modelo-plan.md`. | | **Pareceres de revisão** | `specs/-/reviews/` | O que cada revisor apontou, sem edição. É a prova de que a revisão aconteceu. | | **Código** | `apps/web/` | O que a IA escreve seguindo o plano. | | **Pull Request** | GitHub | Onde você explica, com suas palavras, o que foi feito. | diff --git a/docs/modelo-plan.md b/docs/modelo-plan.md new file mode 100644 index 0000000..dd288e5 --- /dev/null +++ b/docs/modelo-plan.md @@ -0,0 +1,44 @@ + + +# Plano — Issue #00 + +## Decisões técnicas + + + +- + +## Tarefas + + + +- [ ] **Tarefa 1 — [título curto, um verbo]** + - Cobre: CA1 + - Teste primeiro: [o que o `.spec.ts` vai provar, e por que ele falha antes do código] + - Arquivos previstos: [caminhos] + +- [ ] **Tarefa 2 — [título]** + - Cobre: CA2 + - Teste primeiro: + - Arquivos previstos: + + + +## Critérios sem tarefa + + + +- diff --git a/docs/modelo-spec.md b/docs/modelo-spec.md new file mode 100644 index 0000000..1a6782e --- /dev/null +++ b/docs/modelo-spec.md @@ -0,0 +1,76 @@ +--- +issue: 00 +status: rascunho # rascunho | aprovada +--- + + + +# US00 — [título da história] + +## O problema + + + +## A história + +**Como** [perfil], **eu quero** [ação] **para que** [objetivo]. + + + +## Critérios de aceite + + + +- [ ] **CA1 — Dado** [contexto], **quando** [ação], **então** [resultado verificável]. +- [ ] **CA2 — Dado** [o caminho triste: erro, lista vazia, dado inválido], **quando** …, **então** … +- [ ] **CA3 — Dado** [abandono: fechou a aba, sessão expirou, rede caiu], **quando** …, **então** … + + + +## Fora de escopo + + + +- + +## Abandono no meio + + + +## Assume que + + + +| Premissa | Issue que fecha | +| --- | --- | +| | | + +## Depende de + + + +## Dúvidas em aberto + + + +| # | Dúvida | Quem responde | +| --- | --- | --- | From bf7373d997db77596d970f9c16a40e713943200e Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 13:55:18 -0300 Subject: [PATCH 07/14] docs: caminho de bug e tarefa tecnica MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bug e tarefa tecnica nao passam pelo /utf-issue e nao tem spec, mas ate agora o template nao dizia como eles entram: a Issue nascia em branco e o aluno escrevia uma linha, que e justamente o oposto do que se precisa — sem spec, a descricao da Issue E a especificacao. Dois modelos de Issue com a etiqueta manutencao ja aplicada, e a secao do tutorial que amarra as quatro regras do caminho curto. A que mais importa e a terceira: no bug, o primeiro commit e um teste que reproduz a falha e falha de verdade — sem ele nada prova que o bug foi embora nem que nao volta. E se o PRD nunca disse o que deveria acontecer ali, nao era bug: e historia nova, e volta para o ciclo completo. Co-Authored-By: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/bug.md | 43 ++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/tarefa-tecnica.md | 28 +++++++++++++++ docs/tutorial-sdd.md | 22 ++++++++++++ 3 files changed, 93 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.md create mode 100644 .github/ISSUE_TEMPLATE/tarefa-tecnica.md diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..20466e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,43 @@ +--- +name: 🔴 Bug +about: Um comportamento que já deveria funcionar e não funciona +labels: manutencao +--- + + + +## O que acontece + +## O que deveria acontecer + + + +## Passos para reproduzir + +1. +2. +3. + +## Evidência + + + +``` +``` + +## Ambiente + +- Onde: local / produção +- Navegador e versão: +- Fonte de dados: json-server / BaaS + +--- + + diff --git a/.github/ISSUE_TEMPLATE/tarefa-tecnica.md b/.github/ISSUE_TEMPLATE/tarefa-tecnica.md new file mode 100644 index 0000000..82d02ca --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tarefa-tecnica.md @@ -0,0 +1,28 @@ +--- +name: 🟡 Tarefa técnica +about: Trabalho que não muda o comportamento do produto para o usuário +labels: manutencao +--- + + + +## O que precisa ser feito + +## Por que agora + + + +## Como saber que ficou pronto + + + +--- + + diff --git a/docs/tutorial-sdd.md b/docs/tutorial-sdd.md index 437f900..7edf770 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -138,6 +138,28 @@ Dizer "vamos trabalhar na Issue 12" em linguagem natural também dispara o fluxo --- +## Fora do ciclo — bug e tarefa técnica + +Nem todo trabalho é história. **Bug** (algo que já deveria funcionar e não funciona) e +**tarefa técnica** (subir versão, refatorar, configurar a esteira) não têm `spec.md` +e não passam pelo `/utf-issue`. O caminho é mais curto, e mesmo assim tem regras: + +1. **Abra a Issue direto no GitHub**, escolhendo o modelo (🔴 Bug ou 🟡 Tarefa técnica). + Aqui a descrição é detalhada — passos, erro do console, evidência. É ela que faz o + papel da spec. +2. **Branch a partir da `develop`**, como sempre no Gitflow. +3. **No bug, o primeiro commit é um teste que reproduz a falha e falha de verdade.** + Sem esse teste, nada prova que o bug foi embora nem que ele não volta. Só depois vem + a correção. É o mesmo RED → GREEN do ciclo, sem a papelada. +4. **PR para a `develop` com a etiqueta `manutencao`**, `Closes #` e a explicação de + 250 caracteres. A etiqueta dispensa a spec, **nunca** o Portão de Entendimento. + +Se, ao investigar, você descobrir que o `docs/prd.md` nunca disse o que o sistema +deveria fazer ali, então não era bug: é história nova. Feche a Issue, escreva a story +no PRD e volte para o ciclo normal. + +--- + ## Quando algo dá errado - **Estourou as 2 rodadas de revisão:** o ciclo para sozinho e te chama, com os From b690e3d74be7d69a553aa685416d2a539429989f Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:01:17 -0300 Subject: [PATCH 08/14] site: adiciona o site didatico do metodo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. Escrito para este template, nao copiado do utf-sdd-template: Gitflow com a branch nascendo da develop antes da aprovacao da spec, Angular e BaaS no lugar de NestJS, a jornada vivendo no prototipo, o portao em 250 e os onze artefatos deste metodo. Co-Authored-By: Claude Opus 5 (1M context) --- site/.nojekyll | 0 site/assets/estilo.css | 440 +++++++++++++++++++++++++++++++++++++++++ site/assets/portao.svg | 6 + site/ciclo.html | 309 +++++++++++++++++++++++++++++ site/comandos.html | 223 +++++++++++++++++++++ site/duvidas.html | 188 ++++++++++++++++++ site/index.html | 177 +++++++++++++++++ site/papeis.html | 207 +++++++++++++++++++ 8 files changed, 1550 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..2f708d9 --- /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); } + +/* --- 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; } +.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); } + +/* --- 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; } +} + +/* --- 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; } + +/* --- 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; +} + +/* --- 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; +} 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..00983e2 --- /dev/null +++ b/site/ciclo.html @@ -0,0 +1,309 @@ + + + + + +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, como ele se + parece e onde as coisas moram. Não é burocracia de início de semestre. É que o ciclo por + Issue amplifica o contexto que existe: com um PRD e um documento de + arquitetura, cada especificação nasce coerente com o resto do sistema. Sem eles, cada Issue + vira um projeto novo — o agente inventa o nome da entidade, escolhe sozinho onde a regra + mora, decide um formato de resposta diferente. Na quinta Issue você tem três jeitos de + fazer a mesma coisa, e nenhum deles está errado isoladamente.

+ +
    +
  1. + entrevista conduzida pela IA +

    Requisitos

    +

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

    +
    + +

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

    +
    +
    2. +
  2. + IA propõe, GitHub recebe +

    Backlog

    +

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

    +
    + +

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

    +
    +
    3. +
  3. + entrevista conduzida pela IA +

    Design e protótipo

    +

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

    +
    + +

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

    +
    +
    4. +
  4. + entrevista conduzida pela IA +

    Arquitetura

    +

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

    +
    + +

    Você lê e commita.

    +
    +
    5. +
  5. + IA gera +

    Scaffold

    +

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

    +
    + +

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

    +
    +
    6. +
+ +

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

+ +

O ciclo de uma história

+ +

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

+ +
    +
  1. + IA pergunta, você responde +

    A conversa antes do código

    +

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

    +
    2. +
  2. + IA escreve +

    A branch e a especificação

    +

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

    +
    3. +
+ +
+
+ + 1Você aprova a spec + Leia o arquivo inteiro, 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. +
+
+ +
    +
  1. + IA escreve, você aprova na conversa +

    O plano

    +

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

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

    A auditoria do diff inteiro

    +

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

    +
    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ê” e liste os apontamentos que você aceitou e os que recusou. O PR vai para a develop. 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 — 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 develop

    +

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

    +
    3. +
+ +

Dentro de uma tarefa

+ +

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

+ +
    +
  1. + tutor, contexto limpo +

    O tutor explica antes

    +

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

    +
    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 .spec.ts 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/27-reserva-de-carona/reviews/ — é esse arquivo que prova, + na apresentação, 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. +
+ +
+
+ + 4Você confere o diff e autoriza o commit + Na sua IDE, seguindo o roteiro que o tutor deu antes. Se o diff passou rápido demais, /utf-tutor passo 1 destrincha arquivo por arquivo, no seu ritmo — é ali que se aprende sintaxe, com cinco linhas na frente e não com quarenta arquivos 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/27-reserva-de-carona/reviews/tarefa-03-*

+ +

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

+ +
+

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..d35e074 --- /dev/null +++ b/site/comandos.html @@ -0,0 +1,223 @@ + + + + + +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

+ +

Nesta ordem. Cada linha termina numa decisão sua.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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 Kanban no ProjectsAprova a lista antes de as Issues serem criadas
/utf-designdocs/design-tokens.md, o framework CSS, a identidade PWA e o link do protótipo navegávelDecide com a equipe e commita
/utf-architecturedocs/architecture.md — estrutura, componentes, estados, modelo de dadosLê e commita
/utf-setupapps/web — o app Angular, com a suíte de testes verde e vazia de regrasRatifica as decisões e abre o primeiro PR para a develop, 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 quatro rodam uma vez só.

+
+ +

Uma vez por história

+ +
+ + + + + + + + + + + + + + + + + + + + + +
ComandoQuandoO que acontece
/utf-issue 27Uma vez, para começarO agente lê a Issue e o PRD, faz perguntas sobre casos de borda, cria a branch a + partir da develop, escreve a spec em rascunho e para. Depois da sua + aprovação, gera o plano. Rodado de novo numa história em andamento, ele retoma do + passo certo em vez de recomeçar.
/utf-task 1Uma vez por tarefa do planoRoda o ciclo inteiro da tarefa: tutor, implementador, dois revisores, triagem 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 apresentação sem + precisar dele.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComandoQuandoA pergunta que ele responde
/utf-tutor prd
design
architecture		Na Fase 0, antes de commitar cada documentoO que este documento decide, quais conceitos aparecem nele e o que cada decisão me + obriga a fazer depois — em cima do seu documento, não em exemplo + genérico.
/utf-tutor setupDepois do scaffold (o /utf-setup já chama sozinho)O que o gerador criou, para que serve cada arquivo que você não escreveu, e por + que a suíte nasce verde e vazia.
/utf-tutor specAntes de aprovar a specO que essa decisão significa tecnicamente, e o que ela me obriga a fazer depois?
automáticoAntes de cada tarefa, dentro do /utf-taskO que essa tarefa vai construir, com quais conceitos, quais arquivos, e o que eu + procuro no diff?
/utf-tutor passo 3Quando o diff passou rápido demaisO diff da tarefa um arquivo por vez, no seu ritmo, com a sintaxe + nova lida em voz alta. É aqui que se aprende inject(), + signal() e async.
/utf-tutor 3Depois de uma tarefaO que esse diff faz e por que assim? Devolve também o nome oficial dos conceitos 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 na apresentação. 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

+ +

Dois comandos falam com o GitHub: o /utf-backlog, que cria Issues, e o + /utf-setup, que abre o primeiro PR. 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 — foi assim que se + descobriu que o gerador atual do Angular entrega Vitest, e não Karma.

+ +

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..412e355 --- /dev/null +++ b/site/duvidas.html @@ -0,0 +1,188 @@ + + + + + +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 os primeiros commits 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.
Protótipo desatualizadoDocumentação que mente é pior que documentação ausenteO link do protótipo vive no design-tokens.md e acompanha a mudança.
+
+ +

O Portão de Entendimento

+ +

Todo Pull Request precisa ter, no corpo, a seção “O que este PR faz e por + quê” preenchida com pelo menos 250 caracteres. Uma verificação + automática confere isso e reprova o PR se faltar. É uma regra só, e vale para todos os PRs, + inclusive os de manutenção.

+ +

Se a mudança é pequena, a explicação é curta e específica. Algo como “o formulário + de reserva não desabilitava o botão durante o envio, e clique duplo criava duas reservas; + passei o botão a depender de um signal enviando e ajustei o teste que + dependia do comportamento antigo” já passa dos 250 caracteres e diz alguma coisa.

+ +
+

Não cole o diff nem a saída da IA nessa explicação. O texto precisa + ser seu. Na apresentação o professor pode sortear qualquer PR e pedir que você explique ao + vivo o que escreveu ali, e é fácil perceber quando o texto não é de quem está falando.

+
+ +

Precisa de spec para qualquer mudança?

+ +

Não. A regra é o impacto no produto.

+ +
+

Precisa de spec toda mudança que cria um recurso novo, altera uma + regra de negócio ou conserta um bug de comportamento — por exemplo, “o passageiro não + consegue cancelar a reserva”. Essas nascem como Issue no GitHub Projects e o ciclo + completo é obrigatório.

+
+ +
+

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

+

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

+
+ +

Checklist antes de abrir o Pull Request

+ +
    +
  • Existe uma Issue e o PR referencia ela, com Closes #27.
    • +
  • O PR vai para a develop, e a branch nasceu dela.
    • +
  • O spec.md está com status: aprovada, e o commit que trocou esse campo é seu.
    • +
  • Spec e plano são os primeiros commits da branch, antes de qualquer código.
    • +
  • Os testes cobrem os critérios de aceite e os casos de abandono, e passam.
    • +
  • Os pareceres estão em reviews/, um por revisor por rodada.
    • +
  • A revisão foi feita por agentes diferentes do que implementou, e nenhum deles tinha permissão de escrita.
    • +
  • Os apontamentos aceitos e recusados estão registrados no PR, com motivo.
    • +
  • Todo Assume que da spec tem um // TODO #<issue> no código e uma Issue aberta.
    • +
  • O architecture.md reflete o comportamento atual.
    • +
  • O status da história no prd.md está correto.
    • +
  • A seção “O que este PR faz e por quê” está escrita, com as suas palavras.
    • +
  • Você consegue explicar cada trecho do diff sem consultar a IA.
    • +
+ +

O último item é o único que ninguém verifica automaticamente, e é o que sustenta a maior + parte da sua nota individual.

+ +

Perguntas frequentes

+ +
+
Posso usar a IA para escrever a especificação?
+
Sim, e é o esperado. O que não pode é aprovar sem ler e sem discordar de nada.
+ +
E se eu discordar do agente revisor?
+
Ótimo. Recuse o apontamento e escreva o motivo no PR. Recusa fundamentada é sinal de + que você entendeu; aceitar tudo é sinal contrário.
+ +
O ciclo travou nas duas rodadas de revisão. O que faço?
+
Quase sempre significa que a spec está ambígua ou a história é grande demais. Leia os + dois pareceres da rodada 2 lado a lado: se eles discordam entre si, ou apontam o mesmo + trecho por motivos diferentes, o problema está na spec. Volte um passo em vez de insistir + na correção.
+ +
O implementador disse que a tarefa é maior do que o plano previa. E agora?
+
Ele está certo com mais frequência do que se imagina. Pare, volte ao + plan.md e quebre aquela tarefa em duas. Não mande ele fazer assim mesmo — é o + começo do estouro das rodadas.
+ +
Descobri um problema novo no meio da história. Aproveito e conserto?
+
Não. Não inche a spec: registre como comentário na Issue e abra uma Issue nova. O + escopo do PR é o escopo da spec, e é contra ela que o auditor final vai comparar o diff.
+ +
Por que este projeto não tem backend próprio?
+
Porque o foco da disciplina é o front. Os dados vêm de um BaaS, que + entrega autenticação, banco e API prontos — na E2 pelo json-server, na E3 pelo + BaaS de verdade. A pasta apps/api existe vazia só para guardar lugar, caso um + dia exista uma API própria.
+ +
Posso usar o tutor na apresentação?
+
Não. Ele existe justamente para você não precisar dele lá.
+ +
Trabalho em equipe. Como fica a nota?
+
As entregas são avaliadas por equipe. A defesa técnica é individual, e cada integrante + recebe a nota que a própria arguição sustentar.
+ +
Existem outros SDDs por aí?
+
Sim. As duas outras famílias mais conhecidas são o GitHub Spec Kit, que faz o mesmo por + comandos explícitos, e a família GSD. Você não precisa conhecê-las para cursar a + disciplina, e conhecer as três ao mesmo tempo atrapalha mais do que ajuda: são a mesma + ideia com vocabulários diferentes. Se experimentar o Spec Kit, não use o + /implement de forma massiva para todas as tarefas de uma vez — o método daqui + exige uma branch e um Pull Request por Issue.
+
+ +
+

Ainda com dúvida?

+

O guia da disciplina tem a discussão inteira, com + os desvios do ciclo e os apêndices. E dentro do projeto, /utf-tutor responde + sobre o seu código.

+
+ +
+ + + + + diff --git a/site/index.html b/site/index.html new file mode 100644 index 0000000..ce79f09 --- /dev/null +++ b/site/index.html @@ -0,0 +1,177 @@ + + + + + +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 Angular 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: service de caronasIAvocê
7fd2b90tarefa 2: esconde carona lotadaIAvocê
1a5c8e3tarefa 3: aviso ao reservarIAvocê
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 na branch da história. 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 apresentação, que você entendeu o que + assinou.

+
+ +

Quem produz o quê

+ +

O método gira em torno de onze artefatos. Desses onze, 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/design-tokens.mdtokens, PWA e o link do protótipovocê
docs/architecture.mdonde as coisas moramvocê
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/web/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, os Indicadores de Desempenho 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..937a197 --- /dev/null +++ b/site/papeis.html @@ -0,0 +1,207 @@ + + + + + +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: componentes, services, + rotas, estado e os 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. Os documentos da Fase 0, o scaffold, o que a tarefa vai construir e o que + o diff fez. 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 + apresentação, 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, main e develop + bloqueadas, 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 tutor, o implementador e 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/.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 086a530dc34364d4e35d9dd705bc784ec9da5a18 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:01:17 -0300 Subject: [PATCH 09/14] ci: publica o site no GitHub Pages, com guarda de repositorio O job so roda quando github.repository e utfpr-gp/utf-angular-template. Como o repositorio e um template, sem essa guarda o repositorio de cada equipe 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..3723a02 --- /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 equipe. Sem a guarda abaixo, o repositório + # de cada uma tentaria publicar o site do método — e falharia se o Pages não + # estiver habilitado lá. No repositório da equipe o job simplesmente não roda. + if: github.repository == 'utfpr-gp/utf-angular-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 3112dc2c49e896d2b1248c4318229dfc606b9180 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:01:17 -0300 Subject: [PATCH 10/14] docs: aponta o README para o site do metodo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O link fica acima da linha de corte, na parte que a equipe apaga ao dar nome ao projeto — e conteudo do template, nao da vitrine dela. 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 37188a5..8954963 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ 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 apresentação final. +> 📖 **Entenda o método antes de começar:** +> **[utfpr-gp.github.io/utf-angular-template](https://utfpr-gp.github.io/utf-angular-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). @@ -62,6 +66,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-angular-template/). Pré-requisitos das integrações: **`gh` autenticado (`gh auth login`, escopos `repo`, `workflow` e `project`) ou MCP do GitHub** — sem isso, backlog, etiquetas From c021dc58124036f735621127f0c84ed59ac1a818 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:09:44 -0300 Subject: [PATCH 11/14] fix: quatro correcoes no ciclo da tarefa MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Duas delas sao defeitos que faziam o ciclo mentir: 1. **O revisor recebia diff vazio.** O Passo 3 mandava `git diff ..HEAD`, mas nesse ponto o trabalho ainda nao esta commitado — esta no working tree. Com `..HEAD` o comando compara o SHA com ele mesmo e devolve nada, entao os dois revisores vinham emitindo parecer sobre diff vazio e "APROVADO" nao significava nada. Faltava tambem um `git add -A` depois do implementador: arquivo novo nao rastreado nao aparece em `git diff`, e componente e teste recem-criados sao o miolo de quase toda tarefa. 2. **O caminho dos pareceres tinha tres formas no mesmo arquivo** — `specs//reviews/tarefa-$1-...` para contar as rodadas e para gravar, `specs/-/...` para as decisoes. Como a contagem de rodadas E a listagem do diretorio, gravar num caminho e contar noutro faz o ciclo achar que esta sempre na rodada 1 — e o limite de 2 rodadas, que e o freio contra loop infinito de correcao, deixa de existir. Agora ha uma forma so, com um passo explicito de normalizacao do numero. E duas lacunas: 3. O tutor em modo `passo` passa a ser despachado antes do portao do commit, conduzindo a leitura do diff um arquivo por vez. O modo existia desde o commit c6a6deb, mas nada o chamava. 4. No estouro das 2 rodadas, os pareceres sao commitados antes de qualquer limpeza (sem isso o `git clean` leva a prova junto), e na retomada da tarefa eles sao arquivados em vez de apagados. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/workflows/utf-task.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/.agents/workflows/utf-task.md b/.agents/workflows/utf-task.md index 6e9d6eb..635ce47 100644 --- a/.agents/workflows/utf-task.md +++ b/.agents/workflows/utf-task.md @@ -14,10 +14,12 @@ Tarefa a executar: **$1** 1. Descubra a pasta `specs/-/` da branch atual. 2. Abra o `spec.md` e confira `status: aprovada` no frontmatter. **Se não estiver, PARE** e diga: *"A spec ainda não foi aprovada por você. O portão de aprovação da spec (Passo 3 do guia) não passou."* -3. **Se o comando veio sem número**, resolva-o pelo `plan.md`: a tarefa é a **primeira ainda não marcada como feita**, na ordem do plano. Anuncie ao usuário qual número foi resolvido (ex.: *"Próxima pendente: tarefa 3 — "*) antes de seguir — daqui em diante, esse número é o `$1` em tudo (pareceres, decisões, commit). **Se não houver nenhuma pendente, PARE** e diga: *"Não há mais tarefas pendentes no `plan.md`. O próximo passo é o auditor final e o Pull Request, pelo fluxo da Issue."* Não invente tarefa nova. -4. Extraia do `plan.md` o **texto literal** da tarefa `$1`. -5. Guarde o ponto de partida: `git rev-parse HEAD`. Ele é a base de todos os diffs desta tarefa. -6. Descubra em que **rodada de revisão** você está: conte os arquivos `specs//reviews/tarefa-$1-conformidade-r*.md`. **Nenhum = rodada 1.** Não confie na sua memória para isso; o disco é a fonte da verdade. +3. **Se o comando veio sem número**, resolva-o pelo `plan.md`: a tarefa é a **primeira ainda não marcada como feita**, na ordem do plano. Anuncie ao usuário qual número foi resolvido (ex.: *"Próxima pendente: tarefa 3 — "*) antes de seguir — daqui em diante, esse número é o `$1` em tudo (pareceres, decisões, commit). **Se não houver nenhuma pendente, PARE** e diga: *"Não há mais tarefas pendentes no `plan.md`. O próximo passo é o auditor final e o Pull Request: rode `/utf-issue ` de novo — ele detecta que o plano acabou e retoma no fechamento."* Não invente tarefa nova. +4. **Se o comando veio com número e a tarefa `$1` já está marcada como feita** (`- [x]`), **PARE** e diga isso — não há o que executar; `/utf-tutor $1` explica o que foi feito. +5. Extraia do `plan.md` o **texto literal** da tarefa `$1`. +6. Normalize o número: nos **nomes de arquivo** ele tem dois dígitos (`` = `03` para a tarefa 3); na **mensagem de commit**, sem zero à esquerda (`tarefa 3: `). Misturar os dois formatos faz a contagem do item 8 não enxergar a rodada anterior — e sem enxergá-la o ciclo acha que está sempre na rodada 1, e o limite de 2 rodadas deixa de existir. +7. Guarde o ponto de partida: `git rev-parse HEAD`. Ele é a base de todos os diffs desta tarefa. +8. Descubra em que **rodada de revisão** você está: conte os arquivos `specs/-/reviews/tarefa--conformidade-r*.md`. **Nenhum = rodada 1.** Não confie na sua memória para isso; o disco é a fonte da verdade. ## Passo 1 — Ensinar antes de implementar (só na rodada de revisão 1) @@ -42,6 +44,8 @@ Despache o subagente **implementador**. O único canal entre vocês é a string - os critérios de aceite da spec ligados a esta tarefa, transcritos - "toque apenas nos arquivos desta tarefa" +Quando o implementador devolver o relatório, rode `git add -A` — só para pôr os arquivos novos no índice; **não commite**. Sem isso, arquivo novo não aparece no diff que os revisores vão ler. + Se for rodada de revisão 2, inclua também os apontamentos da rodada 1 **aceitos na triagem** (Passo 5), transcritos — os recusados não vão: a decisão sobre eles já foi tomada e registrada. E **despache um implementador novo** — não continue o anterior. ## Passo 3 — Revisar @@ -50,7 +54,7 @@ Despache **revisor-conformidade** e **revisor-codigo** na **mesma mensagem**, pa - caminho do `spec.md` - número e texto literal da tarefa -- o comando de diff exato: `git diff ..HEAD` +- o comando de diff exato: `git diff ` — **sem** `..HEAD`: o trabalho ainda não está commitado, está no working tree, e é ele que esse comando compara com o SHA - o comando para rodar os testes Antes de despachar, não emita opinião sobre o código. O parecer deles precisa ser independente do seu. @@ -60,8 +64,8 @@ Antes de despachar, não emita opinião sobre o código. O parecer deles precisa Grave o texto devolvido por cada revisor **sem editar**, em: ``` -specs//reviews/tarefa-$1-conformidade-r.md -specs//reviews/tarefa-$1-codigo-r.md +specs/-/reviews/tarefa--conformidade-r.md +specs/-/reviews/tarefa--codigo-r.md ``` O sufixo `r` é o contador de **rodadas de revisão** — por isso ele não precisa de arquivo de estado separado: a contagem *é* a listagem do diretório, e ela fica versionada no git como prova de que a revisão aconteceu e de quem a fez. @@ -74,7 +78,7 @@ Havendo apontamentos, **quem decide o destino de cada um é o usuário, não voc 1. Apresente ao usuário a lista numerada de **todos os apontamentos bloqueantes** dos dois pareceres, cada um com a evidência do revisor. Não emita recomendação de aceite ou recusa — a leitura é dele. (As *sugestões* do revisor de código não entram na triagem; relate-as, e o usuário pode promover uma a apontamento aceito se quiser.) 2. Para cada apontamento, o usuário decide: **aceitar** ou **recusar com justificativa** — recusa sem justificativa não existe. -3. Registre as decisões em `specs/-/reviews/tarefa-$1-decisoes-r.md`: +3. Registre as decisões em `specs/-/reviews/tarefa--decisoes-r.md`: ``` # Decisões — Tarefa $1, rodada @@ -90,7 +94,7 @@ Havendo apontamentos, **quem decide o destino de cada um é o usuário, não voc | Situação | O que fazer | | --- | --- | -| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente ao usuário: o resumo do diff (arquivos e o que mudou em cada um), o veredito dos dois revisores e o convite para **conferir o diff na IDE** (ofereça `/utf-tutor $1` para a explicação didática). Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff depois. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e o próximo passo é o auditor final e o PR. Espere ele pedir a próxima (`/utf-task` sem número já a pega). | +| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente o veredito dos dois revisores e, **antes de pedir o aceite**, despache o tutor em modo `passo` e conduza a leitura do diff **um arquivo por vez**, esperando o usuário a cada arquivo. É aqui que ele aprende a sintaxe, com a mudança fresca e pequena — o implementador escreve rápido demais para alguém acompanhar, e sem esta parada o aluno chega ao PR sem ter lido nada. Ele pode dispensar (*"pode pular a leitura"*), e aí você segue direto; **não pule por conta própria**. Convide-o a acompanhar pelo diff na IDE, com o roteiro que o tutor deu no Passo 1. Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` (`- [x]`) e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff. **Depois do commit**, ofereça `/utf-tutor $1` para a aula sobre o diff — antes dele o tutor não tem commit para localizar. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e o próximo passo é o auditor final e o PR. Espere ele pedir a próxima (`/utf-task` sem número já a pega). | | Algum apontamento **aceito**, rodada de revisão 1 | Volte ao Passo 2 com um implementador novo (sem repetir o tutor), transcrevendo **apenas os apontamentos aceitos**. | | Algum apontamento **aceito**, rodada de revisão 2 | **PARE. Não existe rodada 3.** | @@ -98,7 +102,7 @@ Havendo apontamentos, **quem decide o destino de cada um é o usuário, não voc Não tente de novo, não reformule, não peça "só mais uma". Escreva ao usuário: -> Estourei o limite de 2 rodadas de revisão na tarefa `$1`. Os pareceres estão em `specs//reviews/`. +> Estourei o limite de 2 rodadas de revisão na tarefa `$1`. Os pareceres estão em `specs/-/reviews/`. > Causas prováveis, em ordem de frequência: > 1. a spec está ambígua neste ponto — o revisor e o implementador leram coisas diferentes > 2. a tarefa é grande demais e deveria virar duas @@ -106,8 +110,12 @@ Não tente de novo, não reformule, não peça "só mais uma". Escreva ao usuár > > Meu palpite é . A decisão é sua. +Antes de qualquer limpeza, **salve a prova**: proponha um commit só com `specs/-/reviews/` (`tarefa $1: pareceres — estouro das 2 rodadas`), com o OK do usuário. Sem isso, o `git clean` que descarta o código leva os pareceres junto — e eles são a prova da rodada na apresentação. + E então **espere**. Contexto já sujo não melhora com mais uma tentativa: se o usuário decidir corrigir a spec, o certo é abrir sessão nova entregando só a spec corrigida e o plano. +Quando a spec corrigida for aprovada de novo (novo commit do usuário) e a tarefa recomeçar, ela recomeça **do zero**: mova os pareceres e decisões dela para `specs/-/reviews/arquivo//`, em commit próprio, e a contagem de rodadas volta a ser a listagem vazia. Não apague — arquive. + --- ## Proibições From 283efaa22e2abca7626cd7e0fa35806e9bb7f42a Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:09:44 -0300 Subject: [PATCH 12/14] fix: documentacao atualizada antes do auditor final MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O Passo 4 despachava o auditor e so depois mandava atualizar prd, architecture e specs/README.md. Duas das quatro coisas que o auditor confere sao exatamente essas atualizacoes — entao ele auditava um repositorio que ainda nao era o que ia para o PR, e as duas pendencias apareciam sempre. Invertida a ordem no fluxo e no guia, com o portao do commit valendo tambem para o commit de documentacao. Corrige junto a ultima ocorrencia de `specs//reviews/` no guia. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/workflows/utf-issue.md | 4 ++-- docs/guia-sdd.md | 13 ++++++++++--- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/.agents/workflows/utf-issue.md b/.agents/workflows/utf-issue.md index 2088517..d00a381 100644 --- a/.agents/workflows/utf-issue.md +++ b/.agents/workflows/utf-issue.md @@ -40,8 +40,8 @@ status: rascunho # rascunho | aprovada - Ao fim de cada tarefa, pare e devolva o controle ao usuário. Ele pede a próxima. **Passo 4: Auditoria final e Pull Request** -- Terminadas todas as tarefas, despache o subagente **auditor-final**, que compara o diff **inteiro** contra o `spec.md` original — nunca contra o `plan.md`. -- Atualize, no mesmo commit do comportamento: o status da história no `docs/prd.md`, os diagramas do `docs/architecture.md` que mudaram, e o `specs/README.md`. +- Terminadas todas as tarefas, atualize **primeiro** a documentação: o status da história no `docs/prd.md`, os diagramas do `docs/architecture.md` que mudaram, e a linha da spec no `specs/README.md`. Proponha o commit e faça-o **só com o "pode commitar" do usuário** — o portão do commit vale aqui como em cada tarefa. +- Despache **então** o subagente **auditor-final**, que compara o diff **inteiro** contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Auditar antes de atualizar os documentos é auditar um repositório que ainda não é o que vai para o PR. Se o veredito for NÃO PRONTO, cada pendência vira tarefa nova no `plan.md` (com o OK do usuário) e passa pelo `/utf-task`; depois o auditor roda de novo. - Antes de o usuário escrever o PR, sugira `/utf-tutor prova` — o simulado interativo sobre o diff inteiro, que é o ensaio da defesa presencial. - Prepare as alterações (commit) e lembre o usuário de abrir o Pull Request com `Closes #`. - A seção **"O que este PR faz e por quê"** é escrita **pelo usuário, com as palavras dele**. Ofereça os fatos do diff; não ofereça o texto pronto. diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index 87793b8..35ff9eb 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -578,8 +578,15 @@ Duas coisas, nessa ordem: ### Passo 6 — Auditoria do diff inteiro -Terminadas as tarefas, um último agente — o **auditor final** — compara o resultado -completo contra a **spec aprovada**, e deliberadamente **ignora o `plan.md`**. +Terminadas as tarefas, **primeiro você atualiza a documentação** — o status da história +no `docs/prd.md`, os diagramas do `docs/architecture.md` que mudaram e a linha da spec no +`specs/README.md` — e commita. Só então entra um último agente: o **auditor final**, que +compara o resultado completo contra a **spec aprovada** e deliberadamente **ignora o +`plan.md`**. + +A ordem importa. Duas das quatro coisas que ele confere (logo abaixo) são justamente +essas atualizações: auditar antes de fazê-las é auditar um repositório que ainda não é o +que vai para o Pull Request, e as duas pendências apareceriam sempre. A ênfase é essa: *spec, não plano*. O plano é meio, não fim. Se o plano omitiu um critério, comparar contra ele esconde exatamente o defeito que se está procurando. (Se @@ -603,7 +610,7 @@ Você lê o diff, escreve a explicação com suas palavras e abre o Pull Request `Closes #27`. No corpo do PR vão os **apontamentos aceitos e recusados**, com o motivo de cada recusa. -Eles estão em `specs//reviews/` — você não precisa lembrar de nada. +Eles estão em `specs/-/reviews/` — você não precisa lembrar de nada. O merge acontece depois que o Portão de Entendimento (§9) passa. **Você não mescla o próprio PR sem que ele tenha passado**; a `develop` (destino do PR de história) e a From 16f842c6f419d93df5b5c946782b4a0a1c91d253 Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:09:44 -0300 Subject: [PATCH 13/14] docs: o primeiro prompt no README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O aluno abre a IDE no primeiro dia sem saber se o metodo carregou — e nao ha como saber sem perguntar. O prompt colavel confirma que as regras foram lidas, diz em que fase o projeto esta e qual e o proximo comando. Serve tambem na volta depois de dias sem mexer, que e quando o contexto se perde. Se o agente nao souber recitar as regras, elas nao carregaram, e a tabela das quatro ferramentas logo abaixo diz onde conferir. Aproveita para apontar os modelos de spec e plano e o caminho de bug e tarefa tecnica, que ate agora so existiam no tutorial. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/README.md b/README.md index 8954963..2762ca4 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,42 @@ apresentação final. | Cada história | `/utf-issue ` → `/utf-task` | spec, plano e código, tarefa a tarefa | | Aprender | `/utf-tutor` | a explicação didática de cada passo | +Bug e tarefa técnica não entram nessa tabela: eles nascem como Issue direto no GitHub +(há um modelo para cada em `.github/ISSUE_TEMPLATE/`), não têm `spec.md` e o PR leva a +etiqueta `manutencao`. O tutorial tem o passo a passo. Os modelos comentados de +`spec.md` e `plan.md` ficam em `docs/modelo-spec.md` e `docs/modelo-plan.md`. + +### O primeiro prompt + +Abra o chat da sua IDE e **cole o texto abaixo**. Ele confirma que o método carregou, +diz em que ponto o projeto está e qual é o próximo passo — serve no primeiro dia e em +qualquer volta depois de dias sem mexer. + +```text +Sou aluno da disciplina e este repositório usa o método UTF-SDD. + +Antes de qualquer outra coisa: + +1. Leia `.agents/rules/utf-rules.md` — é a constituição deste repositório e vale + para tudo o que fizermos daqui em diante. +2. Leia `docs/checklist.md` — é a ficha da disciplina: regras, indicadores e entregas. +3. Olhe `docs/`, `specs/` e o `git log`, e me responda: + - as regras inegociáveis, uma linha cada; + - em que fase o projeto está agora, e como você chegou a essa conclusão; + - qual é o próximo comando que eu devo rodar, o que ele vai me perguntar e o que + eu vou ter que decidir nele; + - o que precisa estar commitado antes de eu rodá-lo. + +Explique como se eu nunca tivesse visto este método. Não escreva código nem crie +nenhum arquivo nesta resposta. +``` + +Se o agente não souber recitar as regras, **elas não carregaram** — confira, na tabela +abaixo, se as pastas da sua ferramenta são mesmo as que ele lê. E, a qualquer momento, +`/utf-tutor` explica o que estiver na sua frente: `prd`, `design`, `architecture` e +`setup` na Fase 0; `spec`, `antes `, `passo `, `` e `prova` durante as +histórias. + ### Um método, quatro ferramentas O conteúdo de verdade — constituição, fluxos e subagentes — vive uma vez só, em From 2b252637913e0a228fbab0fea60bfc6674e08b6d Mon Sep 17 00:00:00 2001 From: Roni Fabio Banaszewski Date: Tue, 8 Sep 2026 14:09:44 -0300 Subject: [PATCH 14/14] docs: diz a quem as regras de Gitflow se aplicam MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As regras falam em "a main reflete a producao" e "o deploy em producao acompanha": sao sobre o projeto que a equipe constroi, nao sobre este repositorio, que e o material didatico e nao tem producao nem release. A ambiguidade tem consequencia pratica — um agente rodando aqui le a constituicao e tenta abrir branch a partir de uma develop que nao existe. Fica dito: o template vive so na main, a manutencao dele entra por PR de branch curta direto para ela, e a develop do projeto do aluno e criada pelo /utf-setup no repositorio novo. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 612ac6f..c6b8ddb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,11 @@ Você é o Engenheiro e o Arquiteto; a IA é a sua equipe de execução. ## 🌳 Fluxo Git e Proteção da Produção (Gitflow) +> As regras desta seção valem para **o projeto que a equipe constrói**. Este +> repositório é o template da disciplina: ele não tem produção nem release, então vive +> só na `main`, e a manutenção dele entra por Pull Request de branch curta direto para +> ela. A `develop` do projeto de vocês é criada pelo `/utf-setup`, no repositório novo. + - **Duas branches permanentes e bloqueadas:** a `main` reflete a produção; a `develop` integra o trabalho da equipe. Commit direto em qualquer uma das duas é proibido. - **Trabalho:** Crie uma feature branch curta **a partir da `develop`** para cada Issue. - **Integração:** Ao finalizar, abra um Pull Request **para a `develop`** com `Closes #`. O CI (testes + lint) precisa passar antes do merge.