first-plan-pattern-extraction

Pattern Extraction

Como transformar observações do código em "padrões" registráveis em .first-plan/02-conventions/, 06-rationale/do.md, 06-rationale/dont.md.

Princípio

Sem exemplo do código, sem padrão. Toda regra extraída precisa de pelo menos 1 exemplo concreto (path:line). Sem exemplo, vira pergunta em 08-meta/questions.md ou é descartada.

Algoritmo de extração

1. Amostragem

Para cada categoria (errors, naming, testing, etc), amostre arquivos representativos:

• Top 10 arquivos por linhas de código (não-teste)
• Top 5 arquivos modificados nos últimos 30 dias
• 3 arquivos de teste de cada pasta principal

Limite: máx 50 arquivos lidos por categoria. Se ficar muito ruidoso, abortar com confidence baixa.

2. Identificação de padrão candidato

Em cada arquivo amostrado, busque:

• Repetição estrutural (5+ ocorrências da mesma forma)
• Imports comuns (mesmo símbolo importado em N+ arquivos)
• Receitas (e.g., "todo handler começa com func Handle...(ctx Context, req Request) (Response, error)")
• Comentários proibitivos (// don't use X, // use Y instead)
• Código deletado em commits recentes (sinal de anti-padrão)

3. Confidence scoring

Cada padrão candidato ganha confidence baseado em sinais convergentes:

Sinal	Peso
5+ ocorrências consistentes	+0.3
10+ ocorrências consistentes	+0.5
Mesmo padrão em testes e código de produção	+0.2
Comentário no codebase explicitamente preferindo o padrão	+0.2
Documentado em README/CLAUDE.md/docs/	+0.2
Ocorre em código recente (últimos 90 dias)	+0.1
Não tem variantes inconsistentes	+0.2
Tem variantes inconsistentes (alguns fazem A, outros B)	-0.3
Apenas 1-2 ocorrências	-0.4
Apenas em código antigo (>1 ano sem update)	-0.2
Conflita com outro padrão extraído	-0.3

Soma final clamped em [0.0, 1.0]. Threshold default 0.7.

4. Anti-padrões (o que o projeto evita)

Detectar via:

• Ausência consistente de algo comum em outros projetos similares (e.g., zero any em projeto TS estrito = sinal forte de "evitar any")
• Comentários // don't, // avoid, // nao usar, // removed because
• Commits/PRs com mensagens "remove", "deprecate", "migrate away from"
• Padrão substituído por outro (e.g., todos os console.log foram trocados por logger.info em commits recentes)

Confidence para anti-padrão tem regra extra: requerer pelo menos 2 sinais distintos para considerar válido.

5. Exemplificação obrigatória

Cada padrão extraído gera entrada no formato:

### Padrão: <nome>

- **Resumo:** <1 linha>
- **Por que existe (inferido):** <opcional, se houver evidência>
- **Exemplo:**
  ```<lang>
  <trecho real do código>

Visto em: <path>:<line>

• Quando aplicar:
• Confidence:

Sem o exemplo, **descartar o padrão ou rebaixar a pergunta**.

## Categorias e onde escrever

| Categoria | Arquivo de saída |
|-----------|------------------|
| Naming | `02-conventions/naming.md` |
| Errors | `02-conventions/errors.md` |
| Testing | `02-conventions/testing.md` |
| Logging | `02-conventions/logging.md` |
| DI | `02-conventions/di.md` |
| Security | `02-conventions/security.md` |
| Padrões positivos cross-cutting | `06-rationale/do.md` |
| Anti-padrões | `06-rationale/dont.md` |
| Decisões inferidas | `06-rationale/why.md` |

## Quando virar pergunta em vez de padrão

Se confidence < 0.7 mas o tópico é importante (e.g., naming convention é crítico):
1. Não escrever o padrão como verdade
2. Adicionar entrada em `08-meta/questions.md` com hipóteses A/B/C
3. Anotar em `02-conventions/<category>.md` que "convenção indeterminada - ver questions.md"

## Cuidados

- **Não inventar regras genéricas.** Se o projeto não tem padrão claro, o output é "indeterminado", não "use snake_case porque é a convenção da linguagem".
- **Não impor best practices externas.** Se o projeto usa `var` em vez de `let` em todo lugar, o padrão extraído é "use `var`", não "deveria usar `let`".
- **Variantes inconsistentes** são sinal de migração em curso ou de equipes desalinhadas. Reportar ambas, com nota de "variante minoritária possivelmente em migração".