7. Padrões · versão 2.0.0

Auditoria de projeto

manifesto/architecture/13-auditoria.md

Diagnóstico periódico do código para revelar dívida técnica. Não é refatoração — é levantamento. O resultado é uma lista priorizada de achados que viram ADRs de refatoração: melhorar o que já existe mexe no código e, como tudo o que mexe no código, é ADR (princípio 2).

Quando rodar:

A cada 2–4 semanas em projeto ativo.
Antes de uma entrega importante.
Quando o código começa a degradar (regressões, lentidão, confusão de pastas).

A auditoria não mexe no código, então ela própria é uma tarefa (no Gestor, quando o projeto o usa): abre-se a tarefa, rodam-se os eixos, o relatório vai anexo a ela, e os achados CRÍTICO e ALTO viram novas ADRs que citam a auditoria. Ela só vira ADR quando o relatório é um estudo que outras ADRs vão seguir (ver Tarefa ou ADR).

Severidade

Severidade	Significado	Ação
CRÍTICO	Quebra produção ou segurança	Corrigir já (nova ADR imediata)
ALTO	Dívida acumulando	ADR de refatoração próxima
MÉDIO	Melhoria de qualidade	Pendência priorizada
BAIXO	Seria bom ter	Pendência

Os 11 eixos

Cada eixo tem um prompt para copiar e colar. Rode todos (auditoria completa) ou um isolado (auditoria focada).

1. Validade das ADRs

Leia todas as ADRs em .specs/adr/. Para cada uma:
1. A decisão ainda está implementada como descrito no 003-plan?
2. O status no 001-executive está correto (Em planejamento / Em execução / Concluído)?
3. Alguma ADR concluída foi contrariada na prática sem uma ADR nova que a substitua?
4. As alternativas descartadas continuam marcadas com clareza (memória técnica)?
5. Há trabalho no código sem ADR (commits sem `ADR:` no rodapé, numa versão 2.x do Manifesto)?
6. Há ADR que não mexe no código (roadmap, deploy, organização) aberta depois da 2.0.0?
Liste as divergências com severidade.

2. Tipagem total (princípio 6)

Busque em todo o código-fonte:
1. Usos de `any` (explícito ou implícito) — proibidos.
2. Funções exportadas sem tipo de retorno claro.
3. Props de componente sem tipo.
4. Conversões forçadas desnecessárias (`as unknown as X`).
Confirme que os tipos fluem do Prisma e do Zod até a interface, sem buracos.

3. Validação e contrato de API (princípio 7)

Analise as rotas (app/api/**/route.ts ou equivalente):
1. Toda entrada é validada com Zod antes de qualquer processamento?
2. O OpenAPI cobre todos os endpoints e é derivado do Zod (sem contrato escrito à mão)?
3. O Scalar está servido e atualizado?
4. O formato de resposta e os códigos de status são consistentes entre rotas?

4. Autorização por escopo / anti-IDOR (eixo crítico)

Para cada rota que lê ou modifica dados (manifesto/architecture/10-seguranca.md):
1. Há checagem de ESCOPO além da autenticação (esta pessoa pode este recurso)?
2. O filtro do dono está no `where` do Prisma (where: { id, userId }), e não na resposta?
3. As listagens são filtradas no servidor pelo escopo (e não "tudo + esconder na tela")?
4. O papel vem da sessão no servidor, nunca do cliente?
5. As rotas de admin checam o papel explicitamente?
Rota sem checagem de escopo é achado CRÍTICO.

5. Estado do frontend (Zustand)

Analise as stores em stores/ e os componentes:
1. Toda store tem store.ts + sync.tsx?
2. A lógica de negócio mora na store (e não no componente)?
3. Há fetch direto em componente (deveria passar pela store e pelo sync)?
4. lib/ está dividida em server/, client/ e shared/?
5. Há stores sem uso?

6. Componentes

Analise os componentes:
1. Componentes com mais de ~150 linhas, ou misturando lógica de negócio com interface.
2. Componentes duplicados (props, desenho e nomes parecidos) que poderiam ser um só.
3. A fronteira entre a base shadcn/ui (packages/ui) e os componentes próprios está clara?
Para cada achado, sugira a divisão (átomos → moléculas → organismos).

7. Design System e tokens

Busque nos componentes e estilos:
1. Valores escritos na UI que deveriam ser token: cores fora das CSS vars, medidas fora da escala,
   raios e sombras literais.
2. Componentes que ignoram o tema (não usam --primary, --destructive etc.).
3. Acessibilidade: foco visível (--ring), contraste, teclado, ARIA, prefers-reduced-motion.
4. Estados de tela (vazio / carregando / erro) e de componente (desabilitado / hover / foco / ativo).
Compare com .specs/design/tokens.md, se existir (manifesto/03-stack/06-design-system.md).

8. Cobertura de testes (princípio 8)

Liste os domínios e as rotas do projeto. Para cada um:
1. A rota tem teste contra o contrato Zod?
2. O domínio tem smoke cobrindo os fluxos críticos de ponta a ponta?
3. O smoke está pronto para rodar?
Priorize por criticidade: acesso > dados sensíveis e pagamentos > cadastro comum.

9. Desempenho

Analise:
1. Consultas do Prisma com risco de N+1 (findMany sem include/select adequado).
2. Componentes que renderizam demais (store sem seletor, falta de memo onde mede diferença).
3. Imports que poderiam ser carregados sob demanda.
4. Imagens e arquivos grandes sem otimização.

10. Pastas e excesso de camadas (princípio 1)

Compare a estrutura com manifesto/architecture/05-backend.md e 03-stack/02-frontend-zustand.md:
1. Pastas e arquivos fora do padrão; imports circulares.
2. Camadas vazias criadas por hábito (service, repository ou controller que só repassam).
3. Regras de negócio espalhadas que deveriam estar num service.
A régua é complexidade real, não estética: nem camada a menos, nem a mais.

11. Documentação

Verifique:
1. ADRs concluídas com status correto e os relatórios (005 e 006) presentes.
2. .specs/design/ (se existir) reflete os tokens, componentes, telas e fluxos reais?
3. .specs/stack/ registra as escolhas técnicas próprias do projeto?
4. O CLAUDE.md está com comandos, setup e portas corretos?
5. As bibliotecas instaladas estão no 004-tasks das ADRs (nome + versão + porquê)?
6. manifesto/VERSION está na versão que o projeto pretende seguir?
7. O .specs/readme.md e o CLAUDE.md estão sem "a próxima ADR é a…" (o número vem da reserva)?
8. Com o Gestor: as ADRs abertas estão vinculadas às tarefas que as implementam?

Saída esperada

Relatório por eixo — achados com severidade.
As 10 ações principais, priorizadas.
ADRs sugeridas para os achados CRÍTICO e ALTO.

O relatório fica anexo à tarefa de auditoria (ou no 005 da ADR, quando ela é um estudo). Os achados que mexem no código abrem novas ADRs que citam a auditoria.