Clean Code Audit
kyoon3/clean-code-audit-plugin
Audita código legado e identifica refatoração de alto impacto
Ver no GitHubSkill 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-plugin1 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
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-auditskill 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'sastmodule + 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
- Install the plugin (path depends on your Claude Code version — see "Install" below).
- (Optional) Drop a
clean-code-audit.config.jsonat your project root. Without it, sensible defaults assumesrc/andtests/directories. - Ask Claude: "Run the clean code audit on this repo" or invoke
/clean-code-auditdirectly.
Default thresholds
| Unit | MEDIUM | HIGH |
|---|---|---|
| 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
| Layer | Coverage |
|---|---|
| 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 quality | manual sampling, grep-driven |
| Magic literals | manual 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.