Code Review Laravel — Full-Stack

Revisão sistemática de projetos Laravel full-stack com 24 verificações classificadas por severidade. Adapta-se dinamicamente às guidelines de cada projeto.

Stack suportada: Laravel + FilamentPHP + Livewire + Blade + APIs REST + Pest

Referências Internas

Arquivos de referência disponíveis nesta skill. Carregar sob demanda conforme necessário em cada fase:

Para padrões de detecção dos batches (Fase 4), consulte detection-patterns.md
Para detalhes e exemplos de checks críticos, consulte checks-critico.md
Para detalhes e exemplos de checks importantes, consulte checks-importante.md
Para detalhes e exemplos de checks menores, consulte checks-menor.md
Para o formato do relatório (Fase 7), consulte report-template.md
Para guidelines built-in (fallback), consulte guidelines/ — 11 arquivos com regras padrão por domínio

Fase 1 — Detectar Guidelines do Projeto

Antes de qualquer análise, detectar se o projeto possui guidelines próprias:

Algoritmo de detecção (executar em ordem):

Buscar {raiz_do_projeto}/.ai/guidelines/*.md
- Se encontrar → GUIDELINES_PATH = .ai/guidelines/
Senão, buscar {raiz_do_projeto}/.ai/docs/*.md
- Se encontrar → GUIDELINES_PATH = .ai/docs/
Senão → GUIDELINES_PATH = null (usar apenas regras built-in da skill)

Mapeamento check → guideline:

Guideline	Checks que referenciam
`enums.md`	C01
`performance.md`	C03, C05
`architecture.md`	C02, C04, C06, I01, I02, I03, M03, M04, M05
`livewire.md`	C07
`soft-deletes.md`	C08
`api.md`	C09, I08, I09
`testing.md`	I04, I07
`queues.md`	I05
`events.md`	I06
`factories-seeders.md`	I10
`pint.md`	M02

Quando GUIDELINES_PATH é encontrado:

Ler cada guideline referenciada pelos checks (não todas)
Usar as regras da guideline para enriquecer a análise
Citar a guideline específica em cada issue do relatório

Quando GUIDELINES_PATH é null:

Usar as guidelines built-in da skill em references/guidelines/ como fallback
Carregar sob demanda: só ler a guideline quando um check relacionado flagar uma issue
No relatório, marcar como "Regra built-in ({nome}.md)" ao invés de citar guideline do projeto

Fase 2 — Determinar Escopo

Se argumentos foram fornecidos via $ARGUMENTS, usar diretamente:

uncommitted → Modo 1
branch → Modo 2
full-project → Modo 3

Se nenhum argumento foi fornecido, perguntar ao usuário qual escopo deseja revisar.

Modo 1: Arquivos não-commitados

git diff --name-only
git diff --cached --name-only
git ls-files --others --exclude-standard

Modo 2: Branch atual vs main/master

git symbolic-ref --short HEAD              # branch atual
git merge-base main HEAD                   # ponto de divergência
git log main..HEAD --oneline               # commits
git diff main...HEAD --name-only           # arquivos alterados

Se main não existir, tentar master. Se nenhum existir, perguntar ao usuário.

Modo 3: Projeto inteiro

Usar a ferramenta Glob para listar arquivos PHP do projeto:

Glob: pattern="app/**/*.php"
Glob: pattern="database/**/*.php"
Glob: pattern="tests/**/*.php"
Glob: pattern="routes/**/*.php"
Glob: pattern="config/**/*.php"
Glob: pattern="resources/views/**/*.blade.php"

Limitar a 500 arquivos no total.

Filtro de pastas:

Incluir: app/, database/, tests/, routes/, config/, resources/views/
Ignorar sempre: vendor/, node_modules/, storage/, .git/

Após determinar o escopo, informar ao usuário: "{N} arquivos no escopo da revisão."

Fase 3 — Tabela de Verificações (24 checks)

Verificações Críticas (9)

#	Verificação	Alvo	Guideline
C01	`$table->enum()` proibido	migrations/	enums.md
C02	Form/Table inline no Resource Filament	Filament/*/Resource.php	architecture.md
C03	SQL/queries em Resources Filament	Filament/	performance.md
C04	Falta `declare(strict_types=1)`	*.php	architecture.md
C05	N+1 queries (falta eager loading)	Tables/, Controllers/	performance.md
C06	Lógica de negócio em Controllers	Controllers/	architecture.md
C07	HTML raw em views Livewire	views/livewire/	livewire.md
C08	`cascadeOnDelete()` com SoftDeletes	migrations/	soft-deletes.md
C09	Validação inline no Controller	Controllers/	api.md

→ Detalhes: references/checks-critico.md

Verificações Importantes (10)

#	Verificação	Alvo	Guideline
I01	Falta type hints / return types	app/	architecture.md
I02	Métodos > 30 linhas	app/	architecture.md
I03	Lógica duplicada	app/	architecture.md
I04	Lógica de negócio sem teste	Services/, Actions/	testing.md
I05	Falta `$tries`/`$timeout`/`failed()` em Jobs	Jobs/	queues.md
I06	Events fora da camada Service	Controllers/, Models/	events.md
I07	Resources Filament sem testes	Filament/ vs tests/	testing.md
I08	API retornando Model diretamente	Controllers/Api/	api.md
I09	Falta anotações Swagger/OpenAPI	Controllers/Api/	api.md
I10	Factory/Seeder não idempotente	factories/, seeders/	factories-seeders.md

→ Detalhes: references/checks-importante.md

Verificações Menores (5)

#	Verificação	Alvo	Guideline
M01	Código comentado	app/	—
M02	Ordem de imports incorreta	app/	pint.md
M03	Falta `final` em classes	app/	architecture.md
M04	Falta `readonly` em propriedades imutáveis	app/	architecture.md
M05	Nomes genéricos ($data, $temp)	app/	architecture.md

→ Detalhes: references/checks-menor.md

Fase 4 — Execução em Batches

Carregar detection-patterns.md e executar os 7 batches definidos.

Processo por batch:

Executar padrões Grep/Glob em paralelo (conforme detection-patterns.md)
Coletar arquivos flagados
Fazer leitura profunda dos arquivos flagados para confirmar ou descartar
Durante a leitura profunda, verificar também: I02, I03, I10, M01–M05
- Para detalhes desses checks, carregar o arquivo de referência correspondente à severidade

Importante: Filtrar resultados pelo escopo definido na Fase 2. Se o modo é "branch atual", só analisar arquivos que foram alterados nessa branch.

Fase 5 — Pontos Positivos

Durante a análise, identificar e anotar padrões positivos:

Uso consistente de DTOs e Value Objects
Boa cobertura de testes
Services/Actions bem decompostos
Eager loading correto
Uso de Form Requests
Enums bem implementados
Código limpo e bem organizado
Bom uso de type hints
Migrations bem estruturadas

Listar no mínimo 3 pontos positivos no relatório. Se o código é de boa qualidade, destacar isso.

Fase 6 — Métricas de Qualidade

Avaliar 6 aspectos com nota de 1 a 5:

Aspecto	Critério para 5/5	Critério para 1/5
Arquitetura	Camadas bem definidas, SOLID, DTOs	God classes, lógica em controllers
Qualidade de Código	strict_types, final, readonly, nomes claros	Sem types, nomes genéricos
Testes	>80% cobertura em Services/Actions	Sem testes em lógica de negócio
Segurança	Sem XSS, SQL injection, mass assignment	HTML raw, queries sem binding
Performance	Eager loading, sem N+1, queries otimizadas	N+1 frequente, queries em loops
Conformidade	Segue guidelines do projeto	Ignora guidelines

Nota geral = média aritmética das 6 notas.

Fase 7 — Gerar Relatório

Path do relatório

mkdir -p .claude/reviews/{branch-name}/
# Arquivo: .claude/reviews/{branch-name}/YYYY-MM-DD_HH-mm_review.md

Se não houver branch (detached HEAD ou modo projeto inteiro), usar projeto como nome.

Formato

Seguir o template completo em references/report-template.md.

Regras de formatação:

Cada issue deve ter Arquivo: com path e linha
Cada issue deve ter Verificação: com o código (C01, I05, etc.)
Issues críticas DEVEM ter Impacto: e code blocks antes/depois
Issues importantes DEVEM ter code blocks
Issues menores podem ser texto simples
Pontos Positivos são obrigatórios (mínimo 3)
Métricas são obrigatórias (6 aspectos)
Próximos Passos priorizados: URGENTE → ALTO → MÉDIO → BAIXO

Fase 8 — Finalizar

Após salvar o relatório:

Exibir caminho do relatório para o usuário
Resumo quantitativo: "X críticos, Y importantes, Z menores"
NUNCA auto-corrigir — apenas reportar. Perguntar ao usuário antes de qualquer correção
Recomendação baseada nos resultados:
- 0 críticos → "Pode commitar/mergear"
- 1-3 críticos → "Corrigir críticos antes do merge"
- 4+ críticos → "Precisa review mais profundo"

Regras Importantes

NUNCA auto-corrigir código — apenas reportar e sugerir. Perguntar antes de qualquer modificação
Output em português — todo o relatório em pt-BR
Salvar relatório em .claude/reviews/ — sempre persistir, nunca só exibir no chat
Referenciar guidelines — quando existirem, citar o arquivo específico da guideline violada
Sem falsos positivos — na dúvida, fazer leitura profunda para confirmar antes de reportar
Escopo restrito — analisar apenas arquivos do escopo definido na Fase 2
Parallelizar — usar Grep/Glob em paralelo nos batches quando possível
Pontos positivos — sempre incluir, review equilibrado
Carregar referências sob demanda — ler guidelines e arquivos de referência apenas quando necessários para a fase atual
Ser específico — sempre incluir arquivo:linha nos issues reportados

code-review-laravel