convez.ai
SkillProdutividadeIntermediário
kyoon3

Clean Code Audit

kyoon3/clean-code-audit-plugin

Audita código legado e identifica refatoração de alto impacto

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que audita sua base de código em busca de degradação técnica — arquivos longos, funções complexas, violações DRY, magic literals — e gera relatório markdown priorizado. Funciona read-only e é agnóstico ao tipo de projeto, configurável via JSON.

Instalação

$npx convez-ai kyoon3/clean-code-audit-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Identificar arquivos e funções acima de limites de legibilidade
  • Detectar violações de DRY e complexidade ciclomática
  • Priorizar backlog técnico com evidências AST
  • Avaliar saúde de codebase antes de grandes refatorações

Veredito

Ferramenta sólida e bem arquitetada para diagnosticar qualidade de código em repositórios maduros. Oferece insights acionáveis com thresholds baseados em pesquisa (SmartBear/Cisco), mas requer integração manual em workflows de refatoração — é um detector, não um solucionador.

README

A tradução para o português deste README ainda está na fila.

clean-code-audit

A read-only Claude Code skill that scans your whole codebase for clean-code drift — long files, long functions, high cyclomatic complexity, low-quality comments, magic literals, oversized test files, and DRY violations — and produces a prioritized markdown report.

Why use this when the official code-review plugin exists? That plugin reviews PR diffs. This one reviews the codebase you've already merged. Different problem.

What you get

  • A /clean-code-audit skill the model invokes when you ask "find long files" / "리팩토링 후보" / "where's the worst code?".
  • A small Python script (scripts/length_check.py) that uses Python's ast module + a TS/JS regex heuristic + file-level LOC to emit JSON findings.
  • A configurable severity ladder you can tune via clean-code-audit.config.json.
  • Optional opt-ins for backlog cross-reference (mark findings already in your tech-debt list) and Korean placement check (for projects that mix Korean canonical labels into source).

Read-only by design. The skill never edits files. Refactor PRs follow separately, ideally guided by a planning skill.

Quick start

  1. Install the plugin (path depends on your Claude Code version — see "Install" below).
  2. (Optional) Drop a clean-code-audit.config.json at your project root. Without it, sensible defaults assume src/ and tests/ directories.
  3. Ask Claude: "Run the clean code audit on this repo" or invoke /clean-code-audit directly.

Default thresholds

UnitMEDIUMHIGH
Function> 50 LOC> 100 LOC
Class> 200 LOC> 400 LOC
Cyclomatic complexity (Python only)> 10> 20
Source module> 500 LOC> 1000 LOC
Test file> 600 LOC(none — split signal)

All configurable. Rationale: SmartBear/Cisco research shows defect detection drops sharply past ~400 LOC per change; functions past 50 LOC typically require re-reading; past 100 are unreadable for non-authors.

Configuration

Optional clean-code-audit.config.json at the project root. Full schema in skills/clean-code-audit/references/configuration.md. Real-world example in examples/taleweavers.config.json (a dual-stack Python + Next.js project).

{
  "scopes": {
    "all": ["src", "tests", "frontend/app", "frontend/lib"],
    "backend": ["src", "tests"],
    "frontend": ["frontend/app", "frontend/lib"]
  }
}

What it scans, what it doesn't

LayerCoverage
Function / class / module length (Python)✅ AST-based, precise
Cyclomatic complexity (Python)✅ McCabe approximation
Function / class length (TS/JS)✅ regex + brace heuristic — see references/typescript-support.md for limits
Cyclomatic complexity (TS/JS)❌ requires real AST parser, integrate ts-morph if needed
File-level LOC (any language in source_extensions)✅
Comment qualitymanual sampling, grep-driven
Magic literalsmanual spot-check, grep-driven
DRY (3+ duplication)manual spot-check; jscpd integration optional

Why read-only

Refactoring is high-leverage when targeted, harmful when sprayed. This plugin produces evidence, not changes. The user decides which findings deserve PRs and uses standard refactor tools (TDD, pair review, superpowers:writing-plans) to execute.

If you want auto-simplify, see Anthropic's official code-simplifier plugin (operates on recently modified code, not the whole repo).

Install

The exact install path depends on Claude Code's plugin loader version. Common patterns:

Local development: clone this repo and symlink the clean-code-audit/ directory into your Claude Code plugins location:

ln -s "$(pwd)/clean-code-audit" "$HOME/.claude/plugins/clean-code-audit"

Marketplace (when published): /plugin install clean-code-audit@<marketplace-name>.

License

MIT. See LICENSE.

Background

Built for and dogfooded on a Korean SNS pre-validation product (Taleweavers). The first audit pass on that codebase found 3 HIGH + 59 MEDIUM findings, of which ~6 had already been logged in the project backlog and ~5 were new — exactly the kind of inventory you want before a cleanup sprint.

Ver o original no GitHub

Bom para

Relacionados