Projeto final: feature completa com IA no loop, diffs auditáveis, PR limpo

# AI Loop Report - [nome-da-feature]

## TL;DR

- Feature: [nome]
- AI tool: Claude Code / Cursor / Copilot
- Tempo economizado: X horas (vs sem IA)
- Sub-tarefas: 5
- Prompts: 5 (em prompts/)
- AI_NOTES.md: incluído no PR
- Mutation score: 85%
- Bugs pegos em review: 3

## Spec (resumo)

- **Objetivo:** [1 linha]
- **Casos de uso:** 3 principais
- **Constraints:** [lista]
- **Edge cases:** 5 cobertos

## Decomposição

1. Sub-tarefa 1 (3h)
   - Acceptance: [criteria]
   - Tests: [quantidade]
   - Prompt: prompts/sub-1.md
2. Sub-tarefa 2 (2h)
   - ...
3. ...

## Prompts

(prompts/sub-1.md, prompts/sub-2.md, ...)

## AI_NOTES.md

```markdown
# AI Notes

## What was generated
- src/feature/Component.tsx (full)
- src/feature/types.ts (full)
- tests/feature/Component.test.tsx (partial)

## What I wrote manually
- src/feature/config.ts (env vars)
- src/feature/secret-handling.ts (security)

## What I reviewed
- [x] Read all generated code
- [x] Audited with checklist
- [x] Tests run locally
- [x] Type check passes
- [x] ESLint passes
- [x] Stryker mutation score 80%+
- [x] Security review (auth/payment)
- [x] Performance check

## Desafios extras (stretch goals)

- [ ] **2-pass review com 2 LLMs** (Claude
  gera, GPT revisa, ou vice-versa).
- [ ] **AI_NOTES.md** auto-gerado por
  ferramenta (Cursor/Claude Code).
- [ ] **Property-based testing** com
  fast-check.
- [ ] **Visual regression** com Playwright.
- [ ] **Storybook** com stories geradas
  por IA.
- [ ] **Documentation** auto-gerada
  (typedoc, JSDoc) por IA.
- [ ] **Performance profiling** (Sentry
  profiling) - IA ajuda a identificar
  hot paths.
- [ ] **MCP integration** (DB query, file
  system access).
- [ ] **Self-hosted LLM** pra feature
  privacity-sensitive.
- [ ] **Test plan generation** - IA
  gera test plan antes de código.

## Dicas

**Por onde comecar:**

1. **Escolher feature pequena.** Algo
   que daria 4-8h sem IA. **Evite
   feature grande** (refactor de
   auth, novo sistema de pagamento)
   pra primeiro projeto.
2. **Escrever spec.** 1-2 páginas
   com objetivo, casos de uso,
   constraints, edge cases. **Sem
   spec, IA gera genérico**.
3. **Decompor em 3-5 sub-tarefas.**
   Cada uma com acceptance criteria
   testável.
4. **Escrever testes primeiro** (TDD).
   Pra cada sub-tarefa, escreva
   teste vermelho, depois peca IA
   pra implementar.
5. **Salvar prompt em arquivo.**
   `prompts/sub-1.md` etc. **Auditável**.
6. **Auditar cada sub-tarefa** com
   checklist.
7. **Commits atômicos.** 1 sub-tarefa
   = 1-2 commits. Prompt no commit
   message.
8. **PR com AI_NOTES.md** e
   checklist completo.

**Armadilhas comuns:**

- **Spec vaga** = IA gera genérico.
  **Solução**: spec detalhada com
  exemplos.
- **Decomposição em 1 feature
  monolítica** = IA falha em algum
  lugar. **Solução**: 3-5 sub-tarefas.
- **Teste escrito por IA sem
  validação** = "teatro". **Solução**:
  mutation testing.
- **Prompt não salvo** = impossível
  reproduzir/audit. **Solução**:
  sempre `prompts/<sub-tarefa>.md` ou
  no commit.
- **AI_NOTES.md ausente** = reviewer
  não sabe o que revisar. **Solução**:
  sempre incluir.
- **Commit "feat: add feature"** =
  impossível auditar o que IA
  fez. **Solução**: prompt no
  commit message.
- **Review "LGTM"** = perde bugs.
  **Solução**: checklist AI-aware,
  30-60 min.
- **Vibe coding** (aceitar tudo) =
  AI slop. **Solução**: TDD +
  decomposição + audit.

**Como validar que terminou:**

- [ ] Spec existe é detalhada.
- [ ] 3-5 sub-tarefas cada uma com
  teste, prompt, AI_NOTES.
- [ ] Mutation score >= 70%.
- [ ] Coverage >= 80%.
- [ ] Type check + ESLint passam.
- [ ] PR com AI_NOTES.md e prompts.
- [ ] Reviewer aprovou em <= 30 min.
- [ ] Zero bugs em prod (1 semana).
- [ ] Tempo economizado: feature
  equivalente em 50% do tempo sem
  IA (medição informal).

**Leituras que ajudam durante o projeto:**

- [Claude Code - Workflows](https://docs.claude.com/en/docs/claude-code/common-workflows) - patterns comuns, sub-tasks, multi-file.
- [Cursor - Best practices](https://docs.cursor.com/guides/best-practices) - composer, agent, codebase context.
- [Conventional Commits](https://www.conventionalcommits.org/) - format de commit message.

> O projeto final é onde a trilha
> vira "sua". A escolha de **qual
> feature** é o caminho feliz. Os
> principios - spec, decomposição,
> prompts reproduzíveis, audit,
> tests, AI_NOTES - aplicam a
> qualquer feature AI-assisted. O
> esqueleto dado é o caminho feliz,
> desvie quando precisar e anote as
> decisões no `editorial-decisions.md`
> da trilha.

<Checkpoint
  challenge="Implemente a função `avaliarFluxoIA(checklist)` que avalia se um workflow de AI-assisted development segue os patterns corretos. Recebe: checklist = { temSpec: boolean, decomposicaoEmSubTarefas: boolean, testesPorSubTarefa: boolean, promptsSalvos: boolean, aiNotes: boolean, mutationScore: number (0-100, ou 0 se não mediu), commitsAtomicos: boolean, reviewComChecklist: boolean }. Calcule score baseado em: cada boolean true = 10 pontos, mutationScore (0-100) = 1 ponto por % (cap 25). max(0, min(100, score)). Retorna: { score, qualidade: 'excelente' | 'boa' | 'media' | 'fraca' }. qualidade: score >= 90 'excelente', >= 70 'boa', >= 50 'media', senão 'fraca'. Apenas inclua chaves para critérios presentes no input."
  starterCode={`// ImplementeavaliarFluxoIA(checklist) que avalia se um workflow
// de AI-assisted development segue os patterns corretos.
//
// Schema de entrada:
//   checklist = {
//     temSpec?: boolean,
//     decomposicaoEmSubTarefas?: boolean,
//     testesPorSubTarefa?: boolean,
//     promptsSalvos?: boolean,
//     aiNotes?: boolean,
//     mutationScore?: number,
//     commitsAtomicos?: boolean,
//     reviewComChecklist?: boolean
//   }
//
// Schema de saída:
//   { score: number, qualidade: 'excelente' | 'boa' | 'media' | 'fraca' }
//
// Calculo:
// - Cada boolean true: +10 pontos
// - mutationScore (0-100): 1 ponto por % (max 25)
// - max(0, min(100, score))
//
// Qualidade:
// - score >= 90: 'excelente'
// - score >= 70: 'boa'
// - score >= 50: 'media'
// - senão: 'fraca'
functionavaliarFluxoIA(checklist) {
  return { score: 0, qualidade: 'fraca' };
}

const _r1 =avaliarFluxoIA({
  temSpec: true, decomposicaoEmSubTarefas: true, testesPorSubTarefa: true,
  promptsSalvos: true, aiNotes: true, mutationScore: 85, commitsAtomicos: true,
  reviewComChecklist: true
});
console.log(JSON.stringify(_r1));

const _r2 =avaliarFluxoIA({
  temSpec: true, decomposicaoEmSubTarefas: true, testesPorSubTarefa: true,
  promptsSalvos: false, aiNotes: false, mutationScore: 60, commitsAtomicos: true,
  reviewComChecklist: true
});
console.log(JSON.stringify(_r2));

const _r3 =avaliarFluxoIA({
  temSpec: false, decomposicaoEmSubTarefas: false, testesPorSubTarefa: false,
  promptsSalvos: false, aiNotes: false, mutationScore: 0, commitsAtomicos: false,
  reviewComChecklist: false
});
console.log(JSON.stringify(_r3));

const _r4 =avaliarFluxoIA({
  temSpec: true, decomposicaoEmSubTarefas: true, testesPorSubTarefa: false,
  promptsSalvos: true, aiNotes: true, mutationScore: 50, commitsAtomicos: true,
  reviewComChecklist: false
});
console.log(JSON.stringify(_r4));`}
  expected='{"score":100,"qualidade":"excelente"}
{"score":65,"qualidade":"media"}
{"score":0,"qualidade":"fraca"}
{"score":75,"qualidade":"boa"}'
  slug="engenharia-ia"
  nodeId="projeto-final"
/>