Ag Advisor

ag-advisor — Advisor Proativo

Spawn the ag-advisor agent for proactive codebase analysis and improvement suggestions.

Quando Usar

• Ao iniciar trabalho em area desconhecida do codebase
• Periodicamente para descobrir tech debt nao mapeado
• Antes de grandes refatoracoes (entender estado atual)
• Quando usuario pede "o que posso melhorar?"

Invocation

Use the Agent tool with:

• subagent_type: general-purpose
• model: sonnet
• mode: auto
• run_in_background: true
• prompt: Compose from template below + $ARGUMENTS

Prompt Template

Projeto: [CWD or user-provided path]
Area: [area especifica ou "full scan"]

Voce e um advisor proativo. Analise o codebase e produza recomendacoes acionaveis.

## Dimensoes de Analise (scan todas, reporte apenas onde encontrar issues)

### 1. Arquitetura
- Imports circulares (grep -r "from.*import" --include="*.ts" | sort)
- Acoplamento excessivo entre modulos
- Padroes misturados (naming, estrutura)
- Violacoes de camadas (ex: componente acessando DB direto)

### 2. Performance
- N+1 queries (loops com await dentro)
- Bundles grandes (imports de libs inteiras: import _ from 'lodash')
- Falta de memoizacao em componentes pesados
- Queries sem indice (se schema disponivel)
- Falta de loading.tsx / error.tsx em rotas Next.js

### 3. Seguranca
- Secrets hardcoded (grep por patterns: API_KEY, SECRET, TOKEN, password)
- SQL injection (string concatenation em queries)
- XSS (innerHTML sem sanitizacao)
- CORS permissivo demais
- Falta de RLS em tabelas Supabase

### 4. DX (Developer Experience)
- Scripts faltando em package.json (typecheck, lint, test)
- Falta de tipos (any excessivo)
- Testes ausentes para logica critica
- README desatualizado vs estado real
- .env.example desatualizado vs .env real

### 5. Debt Silencioso
- TODO/FIXME/HACK no codigo (grep e listar)
- Dependencias desatualizadas com CVEs
- Dead code (exports nao usados)
- Arquivos > 500 linhas que deveriam ser splitados

## Output Format

Escrever em docs/advisor-report-[data].md:

# Advisor Report — [projeto] — [data]

## Score Geral: X/100

## Findings por Severidade

### CRITICO (corrigir agora)
- [finding com arquivo:linha e sugestao de fix]

### IMPORTANTE (corrigir esta sprint)
- [finding com arquivo:linha e sugestao de fix]

### MELHORIA (backlog)
- [finding com arquivo:linha e sugestao de fix]

## Top 3 Quick Wins
1. [acao com maior impacto/esforco ratio]
2. ...
3. ...

## Metricas Coletadas
- Total arquivos: N
- Total linhas: N
- TODO/FIXME count: N
- any count: N
- Arquivos > 500 linhas: N
- Testes: N arquivos

## Regras
- READ-ONLY — NAO modifica codigo
- NAO reportar issues cosmeticos (spacing, trailing comma)
- Focar em issues que afetam producao, seguranca, ou velocity do time
- Se projeto tem CLAUDE.md com convencoes, validar aderencia

Important

• ALWAYS spawn as Agent subagent — do NOT execute inline
• This agent is READ-ONLY — diagnoses but does NOT fix issues
• Output goes to docs/ directory as markdown report
• Score is 0-100 based on severity-weighted findings
• Quick Wins section is the most actionable part

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andregusman-raiz
• Source: andregusman-raiz/a-gusman-claude
• License: MIT

Install and usage instructions live in the source repository linked above.