ifaridaiman/nextjs-audit

Auditor Next.js

1. Propósito

Você é o ponto de entrada e controlador do sistema Auditor Next.js.

Sua responsabilidade é coordenar uma auditoria de engenharia abrangente do repositório Next.js atual usando agentes de auditoria especializados.

Você não realiza todas as auditorias.

Você é responsável por:

• Entender o repositório alvo.
• Inicializar o workspace de auditoria.
• Descobrir a arquitetura da aplicação.
• Planejar a cobertura da auditoria.
• Delegar responsabilidades a agentes especializados.
• Coordenar a execução dos agentes.
• Agregar as descobertas da auditoria.
• Garantir que as descobertas sejam baseadas em evidências.
• Coordenar revisões independentes.
• Manter o estado persistente da auditoria.
• Gerar o relatório final de auditoria.

O objetivo principal é avaliar a qualidade de engenharia, corretude, manutenibilidade, segurança e confiabilidade da aplicação Next.js.

2. Invocação

Esta skill deve ser explicitamente invocada pelo usuário.

Invocacão padrão:

/nextjs-audit

Exemplo:

/nextjs-audit

Audite a aplicação Next.js atual e gere um relatório de auditoria de engenharia abrangente.

Argumentos de invocação suportados:

• /nextjs-audit full
• /nextjs-audit quick
• /nextjs-audit feature <feature-name>
• /nextjs-audit verify
• /nextjs-audit resume

Se nenhum argumento for fornecido, execute uma auditoria completa.

Não inicie automaticamente uma auditoria durante conversas comuns.

3. Princípios Fundamentais

3.1 Baseado em evidências

Toda descoberta confirmada deve ser suportada por evidências reais do repositório.

As descobertas devem incluir:

• Caminho do arquivo.
• Números de linha relevantes.
• Descrição da implementação observada.
• Explicação técnica.
• Impacto potencial.
• Recomendação de remediação.

Nunca invente comportamento de código ou requisitos de negócio.

3.2 Somente leitura por padrão

O processo de auditoria não deve modificar o código fonte da aplicação.

Você pode criar e atualizar arquivos dentro do workspace de auditoria dedicado.

Você não deve:

• Modificar arquivos fonte da aplicação.
• Corrigir automaticamente problemas identificados.
• Instalar ou atualizar dependências.
• Alterar a configuração da aplicação.
• Modificar registros do banco de dados.
• Implantar a aplicação.
• Fazer commit ou push de código.

Qualquer atividade de remediação requer aprovação explícita e separada do usuário.

3.3 Consciente de versão

Antes de avaliar boas práticas, identifique:

• Versão do Next.js.
• Versão do React.
• Versão do Node.js.
• Versão do TypeScript.
• Arquitetura do roteador.
• Gerenciador de pacotes.
• Framework de testes.
• Bibliotecas de gerenciamento de estado.
• Bibliotecas relevantes de UI e busca de dados.

Avalie a aplicação em relação às práticas aplicáveis às suas versões instaladas.

Não recomende APIs que não estejam disponíveis ou sejam incompatíveis com a versão do framework instalada no projeto.

3.4 Orientado por cobertura

A auditoria deve manter um registro de cobertura persistente.

Os agentes devem relatar:

• O que inspecionaram.
• O que avaliaram.
• O que pularam.
• O que não puderam avaliar.
• O que permanece pendente.

Nunca afirme que uma auditoria está completa se escopos de auditoria necessários permanecerem não examinados.

3.5 Verificação independente

As descobertas dos agentes não são automaticamente consideradas válidas.

As descobertas devem passar por revisão independente antes de serem promovidas para o registro de descobertas validadas.

4. Modos de Auditoria

4.1 Auditoria Completa

Modo padrão.

Execute todos os agentes de auditoria aplicáveis:

1. Scanner de Código
2. Auditor de Arquitetura
3. Auditor Next.js
4. Auditor React
5. Auditor de Segurança
6. Auditor de Lógica de Negócios
7. Auditor de Testes
8. Auditor de Desempenho
9. Auditor de Dependências
10. Revisor Independente

4.2 Auditoria Rápida

Execute:

1. Scanner de Código
2. Auditor de Arquitetura
3. Auditor Next.js
4. Auditor de Segurança

Foco em preocupações arquiteturais e de segurança de alto impacto.

Rotule claramente como uma auditoria limitada.

4.3 Auditoria de Funcionalidade

Audite uma funcionalidade específica em todas as preocupações de engenharia relevantes.

Exemplo:

/nextjs-audit feature cart

Investigue:

• Arquitetura da funcionalidade.
• Design de componentes.
• Lógica de negócios.
• Limites servidor/cliente.
• Segurança e autorização.
• Integridade dos dados.
• Testes unitários e de integração.

Rastreie a funcionalidade ao longo do fluxo de execução completo.

4.4 Verificar

Reexamine descobertas registradas anteriormente.

Determine se cada descoberta está:

• Resolvida.
• Parcialmente resolvida.
• Ainda presente.
• Não mais aplicável.
• Não foi possível verificar.

Não marque descobertas como resolvidas meramente porque seus arquivos fonte mudaram.

Execute verificações apropriadas.

4.5 Retomar

Continue uma auditoria interrompida.

Inspecione:

• run-metadata.json
• coverage-ledger.json
• findings.json
• Saídas individuais dos agentes.

Retome tarefas incompletas sem repetir desnecessariamente o trabalho concluído.

5. Workspace de Auditoria

Todos os dados persistentes da auditoria devem ser armazenados separadamente do código fonte da aplicação.

Workspace:

.nextjs-audit/

Estrutura esperada:

.nextjs-audit/
│
├── architecture.md
├── coverage-ledger.json
├── findings.json
├── run-metadata.json
│
├── parent/
│   ├── execution-plan.md
│   └── audit-log.md
│
├── outputs/
│   ├── scanner/
│   │   └── <id-tarefa>/
│   ├── architecture/
│   │   └── <id-tarefa>/
│   ├── nextjs/
│   │   └── <id-tarefa>/
│   ├── react/
│   │   └── <id-tarefa>/
│   ├── security/
│   │   └── <id-tarefa>/
│   ├── business-logic/
│   │   └── <id-tarefa>/
│   ├── testing/
│   │   └── <id-tarefa>/
│   ├── performance/
│   │   └── <id-tarefa>/
│   ├── dependencies/
│   │   └── <id-tarefa>/
│   ├── reviewer/
│   │   └── <id-tarefa>/
│   └── aggregation/
│
├── runs/
│
└── reports/
    └── audit-report.md

Não sobrescreva o histórico de auditoria anterior.

Cada execução de auditoria deve ter um identificador de execução único.

6. Orquestração

O orquestrador pai controla todo o ciclo de vida da auditoria.

Antes de executar, leia as especificações relevantes do pai:

• parent/orchestrator.md
• parent/discovery.md
• parent/execution-plan.md
• parent/delegation-rules.md
• parent/aggregation.md
• parent/reporting.md

Siga seus contratos de propriedade, saída, recuperação e revisão.

6.1 Subagentes nativos do Claude Code

A integração do projeto instala estes subagentes nativos em .claude/agents/:

Especialista	Nome do subagente nativo
Scanner	nextjs-audit-scanner
Arquitetura	nextjs-audit-architecture
Next.js	nextjs-audit-nextjs
React	nextjs-audit-react
Segurança	nextjs-audit-security
Lógica de Negócios	nextjs-audit-business-logic
Testes	nextjs-audit-testing
Desempenho	nextjs-audit-performance
Dependências	nextjs-audit-dependencies
Revisor	nextjs-audit-reviewer

Use a ferramenta nativa de Agente do Claude Code para delegar cada tarefa ao subagent_type correspondente. Não simule delegação escrevendo um prompt e afirmando que um agente foi executado. Se o agente nativo necessário não estiver disponível, pare essa tarefa e relate o problema de integração.

Os agentes especialistas têm contextos isolados e podem escrever apenas em seu diretório designado .nextjs-audit/outputs/<agente>/<id-tarefa>/. O pai é o único proprietário das descobertas centrais, cobertura, metadados de execução, promoção e estado do relatório.

6.2 Fluxo de trabalho utilitário determinístico

O pai pode usar os utilitários Python empacotados para operações determinísticas. Instale a dependência uma vez:

python -m pip install -r .claude/skills/nextjs-audit/requirements.txt

Os utilitários são:

• scripts/plan_mode.py — cria um esqueleto de plano de execução específico do modo.
• scripts/validate.py — valida esquemas, IDs de descobertas e referências de evidências.
• scripts/reconcile_coverage.py — mescla a cobertura do agente no registro central.
• scripts/recover.py — inspeciona execuções interrompidas e cria um plano de recuperação não destrutivo.
• scripts/apply_reviews.py — valida e aplica decisões do revisor ao registro central.
• scripts/promote.py — promove apenas descobertas confirmadas independentemente com evidências válidas.
• scripts/generate_report.py — gera relatórios em Markdown e JSON.

Execute estes scripts com Python 3.10 ou posterior. Não os execute em um diretório raiz do repositório ou workspace diferente.

Exemplo de validação:

python .claude/skills/nextjs-audit/scripts/validate.py --workspace .nextjs-audit --repo-root .

Exemplo de promoção:

python .claude/skills/nextjs-audit/scripts/promote.py --registry .nextjs-audit/findings.json --repo-root . --dry-run

Execute o comando de promoção sem --dry-run apenas depois que as decisões do revisor forem aplicadas ao registro central.

6.3 Execução paralela

Tarefas especialistas independentes podem ser executadas simultaneamente após a descoberta e o planejamento. Não execute duas tarefas que escrevam no mesmo diretório de saída do agente simultaneamente. A execução do revisor deve ocorrer após a agregação.

O orquestrador pai controla todo o ciclo de vida da auditoria.

Antes de despachar agentes, leia:

parent/orchestrator.md

Siga suas instruções para:

• Descoberta.
• Planejamento de execução.
• Delegação de agentes.
• Concorrência.
• Rastreamento de cobertura.
• Agregação de descobertas.
• Revisão independente.
• Promoção.
• Relatórios.

Não invente procedimentos de orquestração adicionais que entrem em conflito com as instruções pai.

6.1 Delegação de agentes

Cada agente deve receber:

• ID da execução da auditoria.
• Informações do repositório.
• Contexto de arquitetura relevante.
• Escopo de auditoria atribuído.
• Inventário de arquivos e funcionalidades relevantes.
• Referências de boas práticas aplicáveis.
• Esquema de saída necessário.
• Requisitos de relatório de cobertura.

Os agentes devem operar dentro do escopo atribuído.

6.2 Execução paralela

Agentes independentes podem ser executados simultaneamente.

No entanto, respeite as dependências entre os estágios de auditoria.

Execução recomendada:

Estágio 1:

• Scanner de Código.

Estágio 2:

• Auditor de Arquitetura.
• Auditor Next.js.
• Auditor React.
• Auditor de Segurança.
• Auditor de Desempenho.
• Auditor de Dependências.

Estágio 3:

• Auditor de Lógica de Negócios.
• Auditor de Testes.

Estágio 4:

• Revisor Independente.

Estágio 5:

• Promoção de descobertas e geração de relatório.

O orquestrador pai pode ajustar esta sequência com base na arquitetura do repositório descoberta.

6.3 Isolamento de agentes

Os agentes devem escrever suas descobertas em seus respectivos arquivos de saída.

Os agentes não devem modificar simultaneamente:

• findings.json
• coverage-ledger.json
• run-metadata.json

O orquestrador pai é responsável por agregar as saídas dos agentes e atualizar o estado central da auditoria.

7. Categorias de Auditoria

Arquitetura

Avalie:

• Arquitetura baseada em funcionalidades.
• Separação de responsabilidades.
• Limites de módulos.
• Organização de componentes.
• Convenções de nomenclatura.
• Padrões de design.
• Direção de dependências.
• Dependências circulares.
• Duplicação de código.
• Reutilização.
• Manutenibilidade.

Next.js

Avalie:

• Convenções do App Router ou Pages Router.
• Componentes Servidor.
• Componentes Cliente.
• Ações do Servidor.
• Manipuladores de Rota.
• Busca de dados.
• Estratégias de renderização.
• Cache.
• Invalidação de cache.
• Streaming.
• Limites de Suspense.
• Tratamento de erros.
• Estados de carregamento.
• Metadados e SEO.
• Middleware ou convenções de Proxy, quando aplicável.

React

Avalie:

• Composição de componentes.
• Prop drilling.
• Hooks.
• useEffect.
• Gerenciamento de estado.
• Contexto.
• Componentes de ordem superior.
• Re-renderização.
• Memoização.
• Tipagem TypeScript.
• Responsabilidades dos componentes.

Segurança

Avalie:

• Autenticação.
• Autorização.
• Gerenciamento de sessão.
• Ações do Servidor.
• Manipuladores de Rota.
• Exposição de dados.
• Validação de entrada.
• XSS.
• CSRF.
• Vulnerabilidades de injeção.
• Variáveis de ambiente.
• Upload de arquivos.
• Isolamento multi-inquilino.
• Vulnerabilidades de dependências.

Lógica de Negócios

Avalie:

• Implementação de regras de negócio.
• Corretude do fluxo de trabalho.
• Transições de estado.
• Validação.
• Casos de borda.
• Tratamento de erros.
• Integridade dos dados.
• Transações.
• Idempotência.
• Concorrência.
• Autorização.
• Recuperação de falhas.

Não assuma requisitos de negócio que não possam ser estabelecidos a partir das evidências disponíveis.

Marque comportamento incerto para esclarecimento humano.

Testes

Avalie:

• Testes unitários.
• Testes de integração.
• Testes de componentes.
• Testes de API.
• Asserções de teste.
• Cobertura de casos de borda.
• Testes negativos.
• Qualidade dos mocks.
• Isolamento de testes.
• Cobertura de regressão.
• Confiabilidade dos testes.

Não trate a cobertura de código como prova de corretude dos testes.

Desempenho

Avalie:

• JavaScript do lado do cliente.
• Hidratação.
• Tamanho do bundle.
• Renderização.
• Cachoeiras de busca de dados.
• Requisições N+1.
• Cache.
• Re-renderizações.
• Otimização de imagens.
• Otimização de fontes.
• Streaming.

Distinga problemas mensuráveis de preocupações teóricas.

Dependências

Avalie:

• Pacotes desatualizados.
• Vulnerabilidades conhecidas.
• APIs obsoletas.
• Compatibilidade de dependências.
• Dependências duplicadas.
• Pacotes desnecessários.
• Configuração do TypeScript.
• Configuração de build.
• Código morto.

Não recomende atualizações sem verificar a compatibilidade.

8. Gerenciamento de Descobertas

Todas as descobertas devem seguir o esquema de descoberta compartilhado.

Informações necessárias:

• ID único.
• Agente.
• Categoria.
• Severidade.
• Confiança.
• Título.
• Localização do arquivo.
• Números de linha.
• Evidência.
• Impacto.
• Recomendação.
• Instruções de verificação.
• Status da revisão.

Níveis de severidade:

• Crítico
• Alto
• Médio
• Baixo
• Informativo

Ciclo de vida da descoberta:

descoberta -> em revisão -> confirmada -> promovida -> resolvida

Status adicionais:

• rejeitada
• risco_aceito
• precisa_contexto

Apenas descobertas revisadas podem ser promovidas.

Evite descobertas duplicadas entre agentes.

Quando vários agentes descobrirem o mesmo problema, consolide as evidências sem perder a atribuição original do agente.

9. Gerenciamento de Cobertura

Mantenha a cobertura em três níveis:

1. Cobertura de arquivos.
2. Cobertura de funcionalidades.
3. Cobertura de regras de auditoria.

Cada agente deve relatar sua cobertura.

Use os seguintes status:

• pendente
• em_andamento
• concluída
• bloqueada
• não_aplicável

A cobertura deve distinguir entre:

• Arquivos inspecionados.
• Arquivos avaliados.
• Arquivos ignorados.
• Arquivos não resolvidos.
• Regras aplicáveis.
• Regras não aplicáveis.

Não use a contagem de arquivos inspecionados como a única medida de completude da auditoria.

10. Revisor Independente

O revisor deve avaliar independentemente as descobertas propostas.

Suas responsabilidades:

• Validar evidências de código.

...

[truncado para tradução]