---
id: extract-patterns
agent: analyst
title: Extrair e documentar padrões de código do codebase
inputs: [codebase, objetivo (story/spec/área-alvo)]
outputs: [catálogo de padrões rastreáveis (docs/research/patterns.md)]
elicit: false
modes: [interactive, yolo]
---

# Extrair e documentar padrões de código do codebase

**Objetivo:** mapear os padrões recorrentes de um codebase existente (convenções, estruturas,
abordagens de erro, camadas) e documentá-los como catálogo acionável — cada padrão rastreando a
ocorrências reais no código, nunca a um palpite.

**Pré-condições:**
- Há um codebase acessível e um objetivo que define o recorte: a área/story/spec para a qual os
  padrões importam. Sem recorte, eu **paro e elícito** (`*elicit`) — varrer o repositório inteiro
  sem pergunta é tempo queimado.
- Existe um destino de saída em `docs/research/`. Se não existir, eu crio o diretório antes de
  escrever.

## Passos

1. **Aperto o recorte até doer.** Qual decisão estes padrões precisam destravar? (ex.: o @dev vai
   implementar uma story e precisa seguir a convenção da casa; o @architect vai decidir reuso). Se o
   recorte não estiver claro, paro e elícito — não invento o escopo.
2. **Divirjo: coleto largo.** Uso `Grep`/`Glob` para varrer a área-alvo e levanto candidatos a padrão
   sem julgar ainda — nomenclatura, estrutura de pastas, tratamento de erro, camadas (controller/
   service/repo), imports, formato de teste, validação, logging. Nesta fase só coleto e mapeio onde
   cada candidato aparece.
3. **Convirjo: filtro por evidência.** Um padrão só entra no catálogo se aparece em **2+ ocorrências
   reais** no código. Ocorrência única é exceção, não padrão — registro como nota, não como regra.
   Cada padrão sobrevivente carrega os arquivos:linha onde foi observado.
4. **Classifico cada padrão** em: convenção forte (consistente em toda a área), convenção parcial
   (coexiste com variações — sinalizo o conflito) ou anti-padrão recorrente (aparece, mas viola boa
   prática — marco explicitamente). Não maquio inconsistência como consistência.
5. **Sintetizo o "portanto".** Para cada padrão documento: nome, descrição, exemplo mínimo do próprio
   código, ocorrências rastreáveis e a ação acionável — "ao implementar nesta área, siga X / evite Y".
6. **Escrevo o catálogo** em `docs/research/patterns.md` com fonte ao lado de cada item. O que é
   suposição minha (sem ocorrência verificável) vai marcado como hipótese, nunca como fato.
7. **Faço o handoff limpo.** Roteio o catálogo a quem consome: implementação → @dev (para seguir a
   convenção da casa), decisão de reuso/arquitetura → @architect. Eu municio; eles decidem.

## Critério de pronto (DoD)

- [ ] O recorte (área/story/spec) está explícito no topo do catálogo
- [ ] Todo padrão documentado tem 2+ ocorrências reais rastreadas (arquivo:linha)
- [ ] Cada padrão tem exemplo do próprio código + ação acionável ("portanto")
- [ ] Conflitos e anti-padrões estão sinalizados, não maquiados
- [ ] Suposições sem fonte estão marcadas como hipótese, não como fato
- [ ] Catálogo salvo em `docs/research/patterns.md` e roteado ao consumidor (@dev/@architect)

## Falha / recuperação

- **O recorte não está claro / objetivo ausente** → paro e elícito (`*elicit`); não varro o repo
  inteiro nem invento o escopo.
- **Nenhum padrão atinge 2+ ocorrências** → reporto que a área não tem convenção estabelecida (achado
  válido por si) em vez de promover ruído a regra.
- **Padrões conflitam entre si** → documento ambos os lados com suas ocorrências e sinalizo o conflito
  ao consumidor; não escolho o "certo" — isso é decisão do @architect.
- **A extração exige rodar/mover código ou subir algo** → não é meu papel; delego ao @dev (mudança) ou
  ao @devops (subida/MCP). Eu observo e documento, não administro.