# Ag 13 Limpar Codigo

> Maquina autonoma de limpeza de dead code (Knip + AST + bundle, confidence tiers, PRs atomicos). Use para tech debt, hand-off, reducao de bundle, cleanup pos-spike, auditoria de saude. Modo --target=harness audita dead skills/hooks/MCPs do proprio Claude Code.

- **Type:** Skill
- **Install:** `agentstack add skill-andregusman-raiz-a-gusman-claude-ag-13-limpar-codigo`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andregusman-raiz](https://agentstack.voostack.com/s/andregusman-raiz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** https://github.com/andregusman-raiz/a-gusman-claude/tree/main/skills/ag-13-limpar-codigo

## Install

```sh
agentstack add skill-andregusman-raiz-a-gusman-claude-ag-13-limpar-codigo
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# LIMPAR CODIGO — Maquina Autonoma de Dead Code Cleanup

## Invocacao

```
/ag-13-limpar-codigo                          # Diagnostico + plano (default report-only) — target=code
/ag-13-limpar-codigo --triage-only            # So lista, sem plano nem fix
/ag-13-limpar-codigo --apply-quick-wins       # P0+P1 high-confidence auto-aplicados (PRs atomicos)
/ag-13-limpar-codigo --full-pipeline          # Todos os Ps com gates entre PRs (max ciclos = 2)
/ag-13-limpar-codigo --create-issues          # Cria GitHub issues por P do plano
/ag-13-limpar-codigo --resume                 # Retoma de limpar-codigo-state.json
/ag-13-limpar-codigo --target=harness         # Limpa dead skills/hooks/MCPs do proprio harness Claude Code
/ag-13-limpar-codigo categoria:components     # So componentes nunca renderizados
/ag-13-limpar-codigo categoria:imports        # So unused imports
/ag-13-limpar-codigo categoria:state          # So useState/useReducer morto
/ag-13-limpar-codigo categoria:comments       # So comentarios sem explicacao
/ag-13-limpar-codigo categoria:duplicacao     # So duplicacao de codigo (jscpd)
```

## Targets

| Target | Escopo | Delega para |
|---|---|---|
| `code` (default) | Codigo da aplicacao no CWD | Pipeline 5-fases proprio |
| `harness` | `~/Claude/.claude/skills/, hooks/, rules/`, MCPs instalados | `ag-otimizar-harness` |

### --target=harness — comportamento

1. Spawna `ag-otimizar-harness` (mesmo modo: triage / apply-quick-wins / full)
2. Para `--apply-quick-wins` em harness:
   - Aplica markers `cache_control: ephemeral` em skills elegiveis (delega `ag-otimizar-cache`)
   - Marca `metadata.deprecated: true` em skills com 0 invocacoes em 90 dias
   - Sinaliza MCPs com ratio  MULTI-TOOL SCAN -> AST CUSTOM -> CONFIDENCE RANKING -> APPLY FIXES -> SHIP
                                                                          ↑          │
                                                                          └──────────┘
                                                                        (max 2 cycles)
```

1. **DISCOVERY**: detecta stack (Next/Vite/Astro/Remix), entry points, monorepo, instala Knip + jscpd se ausentes, gera `knip.json` + `.jscpd.json` com ignores conservadores
2. **MULTI-TOOL SCAN**: paralelo via Team — Knip + ts-prune + depcheck + ESLint --no-fix + Madge + bundle analyzer + jscpd. Output JSON unificado
3. **AST CUSTOM**: TS Compiler API para 4 categorias do pedido especifico:
   - Componentes nunca renderizados (JSX traversal a partir de entry points)
   - State morto (useState/useReducer com setter sem call ou value sem leitura)
   - Props nao usados (bonus DX)
   - Comentarios com codigo sem prefixo WHY/TODO/FIXME/HACK/NOTE/JSDoc/SPDX
   - Blocos duplicados (jscpd cross-arquivo, threshold > 50 tokens)
4. **CONFIDENCE RANKING**: combina sinais (tools que concordam + bundle confirmation + git churn + cobertura). HIGH (3+ tools) / MEDIUM (1-2) / LOW (suspeita, review humano)
5. **APPLY FIXES**: aplica fixes em PRs atomicos por categoria, com quality gates entre batches (typecheck + lint + test + build + bundle delta). Se gate falha -> revert + alternativa

## Modos (auto-detectados se nao especificados)

| Modo | Sinais / flag | Comportamento |
|------|---------------|---------------|
| triage | `--triage-only` ou primeiro run | So scan + report. NAO aplica fix. NAO gera plano |
| diagnostico | default (sem flag) | Scan + report + plano P0-P5. NAO aplica fix |
| quick-wins | `--apply-quick-wins` | Aplica P0 (setup) + P1 (high-confidence) automaticamente |
| full | `--full-pipeline` | Aplica P0-P5 com user approval gates em P2/P3/P4 |
| issues | `--create-issues` | Cria GitHub issues do plano (1 issue por P, sub-issues por T) |
| categoria | `categoria:X` | Scan + fix so da categoria especificada |

## Categorias detectadas

| Categoria | Tool primaria | Cross-check | Confidence default |
|-----------|---------------|-------------|--------------------|
| Unused imports | ESLint `unused-imports` | Knip | HIGH (auto-fix em P1) |
| Unused exports | Knip | ts-prune | HIGH |
| Unused npm deps | Knip / depcheck | manual review | MEDIUM (cuidado peer deps) |
| Componentes nunca renderizados | Knip + AST custom | bundle analyzer + react-scanner | MEDIUM (review por feature) |
| useState morto (setter sem call) | AST custom | ESLint | LOW (refs/closures) |
| useState morto (value sem leitura) | AST custom | ESLint | LOW |
| Props nunca usados | AST custom | TS LSP | MEDIUM |
| Comentarios sem WHY | regex + AST | manual review | LOW |
| Arquivos orfaos | Knip + Madge | bundle | MEDIUM |
| Types nunca usados | Knip | ts-prune | HIGH |
| Branches de feature flag morta | grep `if (false)` + env vars antigas | manual | LOW |
| Blocos duplicados (DRY) | jscpd (> 50 tokens, > 5 linhas) | AST diff + manual review | MEDIUM (refactor humano) |

## Confidence tiers (regras de auto-fix)

- **HIGH** (3+ tools concordam, sem dynamic refs, no bundle): pode auto-fix em modo `--apply-quick-wins`
- **MEDIUM** (1-2 tools, alguma ambiguidade): requer user approval per-batch antes de aplicar
- **LOW** (suspeita, review humano obrigatorio): nunca auto-fix, so listar no plano

## Whitelist de protecao (NUNCA tocar)

```
**/*.test.*          **/*.spec.*           **/__tests__/**
**/__fixtures__/**   **/*.stories.*        **/*.generated.*
**/__generated__/**  prisma/client/**      **/codegen/**
**/*.d.ts (publicos) **/index.ts (barrels) **/middleware.ts
**/page.tsx          **/layout.tsx         **/route.ts
**/error.tsx         **/not-found.tsx      **/loading.tsx
**/template.tsx      **/global.css         **/globals.css
LICENSE              SPDX headers          Copyright headers
```

## Framework awareness (Next.js App Router exemplo)

Plugin Knip do framework SEMPRE ativo. Conhece convencoes:
- `app/**/page.tsx` -> entry point implicito
- `app/**/layout.tsx`, `error.tsx`, `not-found.tsx`, `loading.tsx`, `template.tsx` -> framework files
- `app/**/route.ts` -> API route
- `middleware.ts` -> entry point
- `next.config.{js,ts,mjs}` -> config
- Server Actions (`"use server"`)
- `generateStaticParams`, `generateMetadata` -> framework exports

Para Vite/Remix/Astro: plugins equivalentes em `knip.json`.

## Pipeline detalhado

### Fase 1 — Discovery
```bash
# Detectar stack
- ler package.json -> dependencies/devDependencies
- detectar Next/Vite/Astro/Remix/CRA/SvelteKit
- detectar monorepo (workspaces, turbo.json, nx.json)
- detectar entry points (app/, pages/, src/index.ts, scripts em package.json)

# Instalar Knip se ausente
$PM add -d knip @types/node

# Gerar knip.json conservador
- include entry points detectados
- ignores defensivos (whitelist acima)
- plugins do framework detectado

# Capturar baseline
- LOC total (cloc ou wc -l em src/)
- bundle size atual ($PM run build && du -sh .next/ ou dist/)
- test coverage atual (se houver)
- git churn (ultimos 12m por arquivo)
```

### Fase 2 — Multi-tool Scan (paralelo via Team)

Spawnar `ag-escanear-morto-codigo` com `isolation: "worktree"`. Sub-tarefas paralelas:
- `bunx knip --reporter json > knip-output.json`
- `bunx ts-prune --json > tsprune-output.json` (cross-check)
- `bunx depcheck --json > depcheck-output.json` (cross-check)
- `bunx eslint --ext .ts,.tsx --no-fix --format json > eslint-output.json`
- `bunx madge --circular --json src > madge-circular.json`
- `bunx madge --orphans --json src > madge-orphans.json`
- `$PM run build && bunx @next/bundle-analyzer` ou `bunx rollup-plugin-visualizer`
- `bunx jscpd --reporters json --min-tokens 50 --min-lines 5 --gitignore src/ app/ components/ > jscpd-output.json` (DRY/duplicacao)

Unificar em `dead-code-findings-raw.json`.

### Fase 3 — AST Custom Scan

Spawnar agente com TS Compiler API. Para cada arquivo `.tsx`:

**A — Componentes nunca renderizados:**
```ts
// Pseudocodigo
const components = collectExportedComponents(srcFiles)
const usages = traverseJsxFromEntryPoints(entryPoints)
const orphans = components.filter(c => !usages.has(c.name))
// Cross-check: dynamic imports, lazy(), next/dynamic
```

**B — useState morto:**
```ts
// Para cada chamada de useState/useReducer:
const [state, setState] = useState(initial)
// Verificar:
// - setState e chamado em alguma posicao? (escopo do componente + closures)
// - state e lido em algum lugar? (JSX, callbacks, useEffect deps)
// Se um dos dois eh false -> candidato (LOW confidence)
```

**C — Props nao usados:**
```ts
// Para cada componente com Props interface:
// - listar props declarados
// - listar props acessados no body
// - diff = props nao usados
```

**D — Comentarios sem WHY:**
```ts
// Regex: ^\s*//.*[(){};=].*$ (parece codigo)
// AND nao tem prefixo: TODO|FIXME|HACK|NOTE|XXX|@param|@returns|SPDX|Copyright|eslint-disable
// AND bloco > 2 linhas consecutivas
// -> candidato comentario sem explicacao
```

Output: `ast-custom-findings.json` mergeado em `dead-code-findings.json`.

### Fase 4 — Confidence Ranking

Combinar sinais em `dead-code-findings.json`:
```json
{
  "category": "component-orphan",
  "file": "src/components/UnusedCard.tsx",
  "name": "UnusedCard",
  "signals": {
    "knip": true,
    "ts-prune": true,
    "ast-custom": true,
    "bundle-absent": true,
    "git-churn": "0 commits in 14 months",
    "test-coverage": 0
  },
  "confidence": "HIGH",
  "recommendation": "delete",
  "loc": 87
}
```

Gerar:
- `docs/diagnosticos/dead-code-YYYY-MM-DD.md` (relatorio com tabelas, contagens, exemplos)
- `docs/plans/dead-code-refactor-plan-YYYY-MM-DD.md` (arvore P0-P5)
- `dead-code-findings.json` (machine-readable)
- `limpar-codigo-state.json` (state para `--resume`)

### Fase 5 — Apply Fixes

So executa se modo for `--apply-quick-wins` ou `--full-pipeline`.

Spawnar `ag-aplicar-fix-codigo` para cada P em sequencia (NUNCA paralelo entre Ps):

**P0 — Setup baseline (1 PR pequeno, no-op funcional)**
- `chore(deadcode): add knip + baseline report`

**P1 — Quick wins HIGH confidence**
- PR 1: `chore(deadcode): remove unused imports` (eslint --fix)
- PR 2: `chore(deadcode): remove unused exports` (Knip + ts-prune cross-validated)
- PR 3: `chore(deadcode): remove orphan deps`
- Quality gate apos cada PR. Falha -> revert + alternativa.

**P2 — Componentes nunca renderizados** (user approval per batch de 5)
- PR por feature area: `chore(deadcode): remove orphan components in `
- Confirma com user antes de cada batch via TaskUpdate

**P3 — useState morto** (LOW confidence, user approval per item)
- PR por componente afetado, commits pequenos

**P4 — Comentarios sem WHY** (review manual, LOW confidence)
- PR consolidado: `chore(deadcode): remove dead code comments`

**P4.5 — Duplicacao (DRY refactor)** (jscpd findings, MEDIUM confidence, user approval per cluster)
- PR por cluster de duplicacao: `refactor(dry): extract  shared by N occurrences`
- jscpd identifica blocos; humano decide a abstracao (util, hook, component)
- NUNCA auto-aplica — apenas sugere fix proposto (snippet + suggested location)
- Cross-check: garantir que abstracao nao quebra tests; quality gate completo

**P5 — Hardening (preventivo)**
- PR: adicionar Knip ao CI em modo warning
- PR: `eslint-plugin-unused-imports` em pre-commit (lint-staged)
- PR: ADR documentando politica

### Quality Gates entre PRs

```bash
# Apos CADA PR de fix:
$PM run typecheck && $PM run lint && $PM run test && $PM run build

# Bundle delta:
echo "Bundle: $(du -sh .next/static)" >> dead-code-progress.md

# Se algum gate falha:
git revert HEAD
echo "Gate failed at $CATEGORY, reverted. Logs: ..." >> dead-code-progress.md
# Continua com proxima categoria
```

## Propriedades MERIDIAN

- **Autonomo**: scan + plano sem perguntar; aplicacao gated por modo
- **Convergente**: SCAN -> APPLY -> VERIFY loop ate green (max 2 cycles)
- **State persistente**: `limpar-codigo-state.json` — resume de onde parou
- **Self-healing**: regressao em quality gate -> revert + alternativa
- **Artifacts**: PRs atomicos, diagnostico, plano, JSON, issues opt-in
- **Confidence-aware**: nunca auto-fix LOW; gated approval para MEDIUM

## Output

```
LIMPAR CODIGO COMPLETO
  Modo: [triage|diagnostico|quick-wins|full|issues|categoria:X]
  Stack detectada: [Next 16 / Vite 5 / etc.]
  Findings totais: [N]
    HIGH: [X] | MEDIUM: [Y] | LOW: [Z]
  Por categoria:
    Unused imports: [N]
    Unused exports: [N]
    Orphan components: [N]
    Dead state: [N]
    Dead comments: [N]
    Orphan files: [N]
    Unused deps: [N]
    Blocos duplicados: [N clusters / N% codebase]
  Diagnostico: docs/diagnosticos/dead-code-YYYY-MM-DD.md
  Plano: docs/plans/dead-code-refactor-plan-YYYY-MM-DD.md
  PRs aplicados: [N] (se modo apply)
  GitHub issues: [N] (se --create-issues)
  LOC removidas: [N]
  Bundle delta: [-XXX KB]
  Build time delta: [-Ys]
  Ciclos: [N]
  Status: GREEN | PARTIAL | NEEDS_REVIEW
```

## Riscos e mitigacoes (resumo)

| Risco | Mitigacao |
|-------|-----------|
| Deletar API publica | Whitelist `**/index.ts` + entries explicitos |
| Dynamic imports perdidos | Knip `ignoreDependencies` + manual review de strings `import()` |
| Convencao de framework deletada | Plugin Knip do framework sempre ativo |
| State usado via ref/closure | Confidence LOW por default — review humano |
| License/SPDX header removido | Regex exclui `/*!`, `// SPDX-`, `Copyright` |
| Test fixtures deletadas | Glob exclude robusto na whitelist |
| Codigo gerado | Glob exclude `*.generated.*`, `prisma/`, `__generated__/` |
| Falso positivo causa regressao | Quality gate completo + smoke E2E + revert automatico |

## Comparacao com plugins / outras machines

| | ag-13-limpar-codigo | code-simplifier (plugin) | ag-2-corrigir debt |
|---|---|---|---|
| Foco | Dead code elimination | Simplificacao de logica | Tech debt geral |
| Tools | Knip + AST + bundle | Manual reasoning | grep + manual |
| Output | PRs atomicos por categoria | 1 PR de simplificacao | 1 PR de cleanup |
| Confidence tiers | Sim (HIGH/MED/LOW) | Nao | Nao |
| GitHub issues | Sim (`--create-issues`) | Nao | Nao |
| Quando usar | "tem coisa morta no codigo" | "esse codigo esta complicado" | "tem debt acumulado" |

## Sub-agents internos

- `ag-escanear-morto-codigo` — executor de scan multi-tool (read-only, paralelo)
- `ag-aplicar-fix-codigo` — applier com gates e PR atomization (escrita, sequencial entre Ps)

## Helper scripts

- `~/Claude/.claude/scripts/dead-code/scan-orchestrator.sh` — orquestra Knip + ts-prune + ESLint + bundle
- `~/Claude/.claude/scripts/dead-code/ast-custom-scan.ts` — TS Compiler API para 4 categorias custom
- `~/Claude/.claude/scripts/dead-code/apply-fix-batch.sh` — aplica fixes em batches com quality gates

## Referencias

- Knip docs: https://knip.dev
- "Software Design X-Rays" (Adam Tornhill) — code health, churn analysis
- "Working Effectively with Legacy Code" (Michael Feathers) — characterization tests
- ESLint plugin unused-imports: https://github.com/sweepline/eslint-plugin-unused-imports
- Mikado Method: https://mikadomethod.info/

## 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](https://github.com/andregusman-raiz)
- **Source:** [andregusman-raiz/a-gusman-claude](https://github.com/andregusman-raiz/a-gusman-claude)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andregusman-raiz-a-gusman-claude-ag-13-limpar-codigo
- Seller: https://agentstack.voostack.com/s/andregusman-raiz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.