Bug Tracker

Projeto exemplo para a tech talk "Spec-driven development com AI: da teoria à prática".

Backend simples em Node + Express + SQLite, frontend HTML/JS vanilla. Zero setup, roda local.

Estado deste repo

Este repo está no estado antes da feature de transição de status com regras. Tem o CRUD básico de tickets funcionando:

• Criar ticket
• Listar tickets
• Ver ticket por id

A feature de transição (mudar status com validação das regras do PRD) vai ser implementada ao vivo durante o talk, usando Claude Code com Spec-Driven Development.

Pré-requisitos

• Node 20 ou superior
• npm
• Claude Code instalado (opcional para a demo)

Como rodar

# Instalar dependências
npm install

# Popular o banco com tickets de exemplo
npm run seed

# Subir o servidor
npm start

Abre em http://localhost:3000.

Para resetar tudo:

rm data/tracker.db
npm run seed
npm start

Estrutura

bug-tracker/
├── CLAUDE.md                       Memória persistente do projeto
├── .claude/
│   ├── skills/implement-prd/       Skill que orienta o agente a ler PRD/ADR antes de codar
│   └── hooks.json                  Hooks: bloqueio de paths sensíveis + lint pós-escrita
├── docs/
│   ├── product/prd-bug-tracker.md  PRD completo
│   ├── architecture/               ADR-001 (stack) + ADR-002 (máquina de estados)
│   └── tasks/                      Task da feature ao vivo
├── src/
│   ├── server.js                   Bootstrap Express
│   ├── db.js                       SQLite + migrations
│   ├── routes/tickets.js           Endpoints (sem PATCH /status ainda)
│   ├── lib/statuses.js             Valores válidos de status
│   └── public/                     Frontend estático
├── scripts/
│   ├── seed.js                     Popula DB com tickets de exemplo
│   ├── block-sensitive-paths.sh    Hook PreToolUse
│   └── lint-check.sh               Hook PostToolUse
└── data/                           Banco SQLite (gerado em runtime)

A demo ao vivo

Durante o talk, o Henrique vai pedir pro Claude Code implementar a task em docs/tasks/task-status-transition.md.

O agente vai:

1. Ler o CLAUDE.md automaticamente
2. Carregar a skill implement-prd
3. Ler o PRD (docs/product/prd-bug-tracker.md)
4. Ler o ADR-002 (docs/architecture/adr-002-status-workflow.md)
5. Entrar em Plan Mode e propor um plano de implementação
6. Executar passo a passo, com os hooks rodando entre as escritas

Resultado esperado: criação de src/lib/transitions.js, novo endpoint PATCH /api/tickets/:id/status em src/routes/tickets.js, atualização do frontend pra mostrar select de status válidos.

Hooks

Dois hooks estão configurados em .claude/hooks.json:

• PreToolUse em Write|Edit: bloqueia escrita em .env, data/, e node_modules/. Útil pra impedir o agente de mexer no banco direto ou em dependências.
• PostToolUse em Write|Edit: roda ESLint nos arquivos .js escritos ou editados. Se houver erro, bloqueia e devolve o output pro agente corrigir.

Os scripts ficam em scripts/. Funcionam sem dependência de jq (usam grep para extrair o caminho do arquivo do JSON do evento).

Skill

.claude/skills/implement-prd/SKILL.md instrui o agente a:

• Ler o PRD inteiro antes de codar
• Ler todos os ADRs referenciados
• Identificar critério de aceite e escopo
• Propor plano em Plan Mode antes de qualquer mudança
• Validar critério de aceite ponto a ponto antes de declarar feito

A descrição da skill é o trigger. O Claude Code carrega a skill quando o prompt menciona "task em docs/tasks", "implementar conforme o PRD", ou similar.

Como subir esse repo no GitHub

git init
git add .
git commit -m "Initial commit: bug tracker para demo de SDD"
git branch -M main
git remote add origin <url-do-seu-repo>
git push -u origin main

Referências

• Playbook do tech talk (interno): playbook-techtalk-sdd.md
• Claude Code docs: https://code.claude.com/docs/en/overview
• Blueprint completo do Rodrigo: https://github.com/rtazima/claude-proj-blueprint