felvieira/pattern-conformity

Pattern Conformity — Code Like the Codebase

Principio: Um agente que ignora as convencoes do projeto existente produz codigo tecnicamente correto mas arquiteturalmente dissonante — cria divida tecnica suave que se acumula silenciosamente. Esta skill impoe "codigo com sotaque do projeto".

Quando Usar

• ao iniciar feature em codebase existente com convencoes estabelecidas
• quando usuario diz "coda igual ao resto", "segue o padrao", "nao inventa"
• antes de gerar novo modulo, service, test, hook, componente, CLI command
• quando novo dev ou agente esta sendo integrado a um projeto consolidado
• como prerequisito de skills 01 (feature-development), 02 (frontend-components), 03 (api-design)

Quando NAO Usar

• projeto greenfield sem codigo existente (sem padrao pra detectar)
• task pontual de 1 arquivo onde o contexto local e obvio
• ja existe memory/patterns.md atualizado (<14 dias) e task e pequena
• quando usuario quer explicitamente divergir do padrao existente (ex: "vamos mudar o estilo")

Distincao de Skills Similares

| Skill | Foco | Output | |-------|------|--------| | 18 (repo-auditor) | Stack, frameworks, riscos, harnessability | docs/repo-audit/current.md — fotografia do repo | | 33 (detective-spec) | Regras de negocio implicitas no codigo | _detective_sdd/ — SDD retroativo | | 44 (zoom-out) | Mapa de modulos e callers | Mapa de bairro, orientacao topologica | | 47 (pattern-conformity) | Convencoes de codificacao concretas | memory/patterns.md — restricoes de estilo |

Skill 18 diz "o projeto usa NestJS + TypeORM". Esta skill diz "services injetam repositorios via constructor, metodos publicos sao sempre async, erros sao lancados como AppException(code, message)".

Governanca Global

Esta skill segue GLOBAL.md, policies/code-exploration.md, policies/token-efficiency.md, policies/persistence.md, policies/handoffs.md.

Protocolo

Fase 0 — Cache Hit (evitar retrabalho)

Antes de qualquer exploracao, verificar:

test -f memory/patterns.md && head -5 memory/patterns.md
# checar campo "last_extracted:" no frontmatter

Se memory/patterns.md existir e last_extracted < 14 dias, pular para Fase 3 (usar diretamente). Se usuario passou --update, ignorar cache e re-extrair.

Fase 1 — Coleta de Amostras Representativas

Coletar amostras de codigo existente por categoria. Estrategia: nao ler tudo — ler exemplos canonicos (arquivos grandes e centrais sao mais representativos que utilitarios).

1a. Ponto de entrada (entry points)

# Encontrar arquivos de entrada principais
find . -maxdepth 3 -name "index.*" -o -name "main.*" -o -name "app.*" -o -name "server.*" | head -10

Ler 1-2 arquivos centrais completos (sem pular).

1b. Modulos de dominio (services, usecases, handlers)

Buscar 3-5 arquivos representativos na camada de negocio:

# Services/usecases (adaptar ao projeto)
find . -path "*/services/*" -o -path "*/usecases/*" -o -path "*/handlers/*" | grep -v node_modules | grep -v dist | head -20

Ler 2-3 arquivos de tamanho medio (200-400 linhas) — sao os mais ricos em convencoes.

1c. Componentes ou modulos de interface (se houver)

find . -path "*/components/*" | grep -v node_modules | head -20

Ler 2-3 componentes que nao sejam atomicos demais (botoes) nem grandes demais (paginas).

1d. Testes

find . \( -name "*.test.*" -o -name "*.spec.*" -o -path "*/__tests__/*" \) | grep -v node_modules | head -20

Ler 2-3 arquivos de teste cobrindo diferentes camadas (unit + integration se existir).

1e. Utilitarios e helpers

find . -path "*/utils/*" -o -path "*/helpers/*" -o -path "*/lib/*" | grep -v node_modules | head -20

Ler 1-2 arquivos — revelam tratamento de erro e estilo funcional.

Fase 2 — Extracao de Padroes

Para cada categoria abaixo, analisar as amostras e extrair o padrao OBSERVADO (nao o ideal):

P1 — Naming Conventions

Extrair da leitura das amostras:

• Arquivos: camelCase.ts vs kebab-case.ts vs PascalCase.ts
• Classes: PascalCase? sufixos (Service, Repository, Controller, Handler)?
• Funcoes/metodos: camelCase? prefixos (get, fetch, handle, process, on)?
• Variaves: camelCase? constantes: SCREAMING_SNAKE_CASE?
• Tipos/interfaces: I prefix? T prefix? Type suffix? nenhum?
• Exportacoes: export default vs named? barrel (index.ts) ou direto?

P2 — Estrutura de Arquivos e Modulos

• Organizacao: feature-first vs type-first vs camadas (MVC/hexagonal/clean)?
• Co-location: testes junto com codigo ou em pasta separada?
• Imports: absolutos (@/services/...) vs relativos (../services/...)? aliases?
• Re-exports: usa barrel index.ts ou importa direto?

P3 — Async e Controle de Fluxo

• async/await vs .then()/.catch()?
• Promise.all vs chamadas sequenciais?
• Onde as funcoes sao async (todas? so as I/O-bound?)?

P4 — Tratamento de Erros

Este e critico e frequentemente o padrao mais especifico do projeto:

• Throw ou return? (throw new Error vs return { error, data } vs Result<T>)
• Classe de erro customizada? (ex: AppError, DomainException, ApiError)
• Try/catch no handler ou no service ou em middleware?
• Logging de erros: onde, como, com que nivel?
• Erros de validacao: Zod / Joi / class-validator / manual?

P5 — Estilo de Testes

• Framework: Jest, Vitest, pytest, go test, etc.
• Setup/teardown: beforeEach/afterEach? fixtures? factories?
• Mocking: jest.mock, vi.mock, sinon, manual mocks, DI?
• Naming de testes: "should ...", "it ...", "given ... when ... then ..."?
• Cobertura por camada: unitario so de domain? integration so de API?

P6 — Injecao de Dependencia e Composicao

• DI container (tsyringe, inversify, NestJS DI) vs manual vs closures?
• Constructor injection vs property vs function parameter?
• Composicao preferida sobre heranca?

P7 — API / Protocolo de Interface (se aplicavel)

• REST com response envelope {data, error, meta} vs flat?
• GraphQL: code-first ou schema-first? mutations nomeadas como?
• Validacao de input: middleware ou no handler?
• Paginacao: cursor ou offset? campo page/limit vs cursor/after?

P8 — Estado e Efeitos Colaterais

• (Frontend) State management: local state, context, Zustand, Redux?
• Side effects em hooks, services, ou handlers?
• Mutacoes: immer, spread, ou direto no state?

Fase 3 — Producao do Code Style Map

Salvar em memory/patterns.md (criar diretorio se necessario):

---
last_extracted: YYYY-MM-DD
source_sample: <N arquivos analisados>
confidence: high|medium|low
---

# Code Style Map — <nome do projeto>

> Gerado por skill 47 (pattern-conformity). Atualizar com `--update` se o projeto evoluir.

## P1 — Naming

- Arquivos: <padrao observado>
- Classes: <padrao>
- Funcoes: <padrao>
- Tipos: <padrao>
- Exportacoes: <padrao>
- **Exemplos canonicos:** `<arquivo1>`, `<arquivo2>`

## P2 — Estrutura de Modulos

- Organizacao: <feature-first|type-first|camadas>
- Co-location de testes: <junto|separado>
- Imports: <absoluto|relativo|alias>
- **Exemplos canonicos:** `<pasta1>`, `<pasta2>`

## P3 — Async

- Padrao: <async/await|promises|callback>
- Regra: <todas as I/O|so handlers|etc>

## P4 — Tratamento de Erros ⚠️

- Mecanismo: <throw|return Result|discriminated union>
- Classe customizada: <nome ou "nenhuma">
- Camada de captura: <middleware|handler|service>
- Logging: <padrao de log>
- **Exemplos canonicos:** `<arquivo com melhor exemplo>`

## P5 — Testes

- Framework: <jest|vitest|pytest|etc>
- Naming: <"should ..."|"it ..."|etc>
- Mocking: <padrao>
- Factories: <usa|nao usa>
- **Exemplos canonicos:** `<arquivo de teste representativo>`

## P6 — Dependencias e Composicao

- DI: <container|manual|closures>
- Composicao: <padrao observado>

## P7 — API/Interface (se houver)

- Envelope de resposta: <padrao>
- Validacao: <onde e como>
- Paginacao: <padrao>

## P8 — Estado (se frontend)

- State management: <padrao>
- Efeitos: <padrao>

## Alertas de Anti-padrao

> Padroes que existem mas devem ser EVITADOS (legado, inconsistencia):
- <ex: arquivos antigos ainda usam `var` em vez de `const` — ignorar>
- <ex: `UserService.ts` usa `.then()` — estilo antigo, nao copiar>

## Restricoes para Geracao de Novo Codigo

Ao gerar qualquer novo arquivo neste projeto:

1. <restricao especifica 1>
2. <restricao especifica 2>
3. <restricao especifica 3>
...

Nivel de confianca:

• high: padrao absolutamente consistente em >90% das amostras
• medium: padrao predominante (>70%) com algumas excecoes
• low: padrao sugerido mas com inconsistencias — notar na secao "Alertas"

Fase 4 — Gate de Conformidade (Inline)

Quando esta skill esta ativa E o agente vai gerar codigo, antes de escrever:

1. Ler memory/patterns.md (ou o que foi extraido nesta execucao)
2. Para cada bloco de codigo a ser escrito, verificar:
   • naming segue P1?
   • estrutura de arquivo segue P2?
   • erros seguem P4?
   • se e teste, segue P5?
3. Se houver desvio intencional (padrao do projeto e ruim/legado), comentar o desvio com justificativa

Exemplo de comentario de desvio intencional:

// [pattern-conformity] desvio: projeta usa throw AppError mas aqui
// retornamos Result<T> porque esta funcao e usada em contexto de pipeline
// onde propagar excecao quebraria o fluxo. Ver patterns.md P4.

Output Minimo

Ao final da skill, reportar:

Pattern Conformity — <projeto>
Arquivos analisados: <N>
Padroes extraidos: P1-P8 (ou subset)
Confianca: high|medium|low
Salvo em: memory/patterns.md
Cache valido por: 14 dias

Restricoes ativas para proximo codigo:
1. <mais importante>
2. <segundo mais importante>
3. <terceiro mais importante>

Handoffs

• Input pra skill 01 (feature-development): passar memory/patterns.md como restricao
• Input pra skill 02 (frontend-components): estilo de componentes (P2, P8)
• Input pra skill 03 (api-design): envelope de resposta, validacao, paginacao (P7)
• Input pra skill 05 (test-engineer): framework, naming, mocking, factories (P5)
• Input pra skill 09 (orchestrator): orquestrador sabe que patterns.md existe e deve referencia-lo no plano
• Alimentado por skill 18 (repo-auditor): usa docs/repo-audit/current.md pra saber onde olhar

Anti-padroes

• ❌ Inventar restricoes "ideais" que nao estao no codigo — so extrair o que EXISTE
• ❌ Reportar tudo que viu em vez de extrair o padrao — patterns.md deve ser conciso (<150 linhas)
• ❌ Ignorar inconsistencias — seccao "Alertas" existe pra isso
• ❌ Reextrair a cada task — verificar cache primeiro (Fase 0)
• ❌ Tratar patterns.md como substituicao do CLAUDE.md — e complemento; ambos devem ser lidos
• ❌ Forcar padrao legado ruim quando usuario quer evolucao — skill descreve o que existe, usuario decide se segue