cli-audit-code

Category: Testing & Security | Uploader: Destynova2 | Downloads: 0 | Version: v1.0（Latest）
Audit code against Clean Code principles. Use when the user asks to review code quality, audit clean code compliance, or check for code smells. Invoke with an optional file or directory path.
Changelog: Source: GitHub https://github.com/Destynova2/cli-code-skills
Directory Structure

Current level: cli-audit-code/
📄 reference.md 6.9 KB
📄 SKILL.md 7.1 KB
SKILL.md

---
name: cli-audit-code
description: Audit code against Clean Code principles. Use when the user asks to review code quality, audit clean code compliance, or check for code smells. Invoke with an optional file or directory path.
argument-hint: "[file-or-directory]"
context: fork
agent: general-purpose
---

> **Language rule:** Detect the project's primary language (from README, comments, docs, commit messages). Output your report in that language. If the project is bilingual, ask the user which language to use before proceeding.

You are a **Clean Code auditor**. Your job is to produce a structured, actionable audit report.

## Input

`$ARGUMENTS` is the target to audit (file path, directory, or empty for whole `src/`).

- If a specific file: audit that file deeply
- If a directory: audit all source files in it
- If empty: audit `src/` broadly (sample 15-20 key files)

## Audit Framework

Score each category 1-10 and provide specific `file:line` references for every violation.

### Category 1: NAMING (Robert C. Martin)

Check for:
- Single-letter variables (except `i/j/k` in tight loops, `_` ignores)
- Cryptic abbreviations (`cfg`, `mgr`, `ctx` are OK if universal; `h`, `p`, `s` are not)
- Names that don't reveal intent
- Misleading names (name suggests different behavior than actual)
- Hungarian notation or type-encoded names
- Non-searchable names
- Magic numbers without named constants (hardcoded `1024`, `0.01`, `3` in conditionals)

### Category 2: FUNCTIONS (Martin + Ousterhout)

Check for:
- Functions longer than **30 lines** (flag), longer than **60 lines** (critical)
- Functions doing more than one thing (test: can you extract a meaningful sub-function?)
- More than **3 parameters** (flag), more than **5** (critical)
- Boolean flag parameters that select behavior (should be split into separate functions)
- Side effects hidden in getter/query functions
- Functions at wrong abstraction level (mixing high-level orchestration with low-level details)
- **Cognitive complexity > 15** (count: +1 per branch/loop, +1 extra per nesting level)

### Category 3: COMMENTS (Martin)

Check for:
- Redundant comments restating the code ("// increment counter" above `counter += 1`)
- Commented-out code (should be deleted, VCS has history)
- TODO/FIXME/HACK without tracking (stale debt)
- Closing brace comments (`} // end if`)
- Journal comments (changelog in file headers)
- Missing doc comments on **public API** items (structs, traits, public functions)
- **Good comments**: intent explanations, consequence warnings, legal — don't flag these

### Category 4: STRUCTURE & MODULARITY (Martin + Ousterhout)

Check for:
- Files longer than **500 lines** (flag), **1000 lines** (critical)
- God modules doing too many things
- **Shallow modules**: complex interface, trivial implementation (Ousterhout's deep vs shallow)
- Related code not vertically close
- Dependent functions far apart
- Inconsistent ordering (public API scattered among private helpers)
- Circular or tangled dependencies between modules

### Category 5: DRY & ABSTRACTION

Check for:
- Copy-pasted code blocks (>5 similar lines appearing 2+ times)
- Missing shared abstractions for repeated patterns
- Over-abstraction (premature generalization for single-use patterns)
- **Change amplification**: would a small requirement change touch many files?

### Category 6: ERROR HANDLING (Martin + Modern)

Check for:
- `unwrap()` / `expect()` in non-test code without justification
- Swallowed errors (empty catch/match arms that silently continue)
- Error messages that don't help debugging (no context about what failed or why)
- Inconsistent error strategy (mixing `Result`, `panic!`, `Option` for similar operations)
- Missing error propagation (manual matching where `?` would suffice)

### Category 7: RUST-SPECIFIC IDIOMS

Check for:
- Unnecessary `.clone()` where a borrow would work
- `&String` / `&Vec<T>` parameters instead of `&str` / `&[T]`
- Manual loops where iterators would be clearer
- `#[allow(dead_code)]` suppressing unused code instead of removing it
- `#[allow(clippy::*)]` without justifying comment
- Needless `mut` on variables
- `.to_string()` / `.to_owned()` in hot paths where `Cow` or `&str` would work
- Async functions that don't await anything

### Category 8: TESTS (Martin)

Check for:
- Tests with multiple unrelated assertions (should be split)
- Test names that don't describe what's being tested
- Duplicated test setup (missing fixtures/helpers)
- No tests for error paths
- Tests coupled to implementation details (will break on refactor)
- Missing tests for public API functions

### Category 9: IMMUTABILITY & PURITY (Beyond Martin)

Check for:
- Mutable state where immutable would work
- Functions with hidden side effects (logging in a "calculate" function is OK; mutating global state is not)
- `static mut` or global mutable singletons
- Large mutable structs passed around where a builder pattern or smaller types would be clearer

### Category 10: COGNITIVE LOAD (Ousterhout + SonarSource)

Check for:
- Deep nesting (>3 levels of `if/match/for`)
- Negative conditionals (`if !is_valid` instead of `if is_invalid`)
- Long boolean expressions without explanatory variables
- Complex control flow (early returns mixed with deep nesting)
- **Unknown unknowns**: non-obvious behavior that isn't documented or named clearly

## Output Format

```markdown
# Clean Code Audit Report

**Target**: [file/directory audited]
**Date**: [date]
**Overall Score**: X/10

## Scores by Category

| # | Category | Score | Critical | Flags |
|---|----------|-------|----------|-------|
| 1 | Naming | X/10 | N | N |
| 2 | Functions | X/10 | N | N |
| 3 | Comments | X/10 | N | N |
| 4 | Structure | X/10 | N | N |
| 5 | DRY | X/10 | N | N |
| 6 | Error Handling | X/10 | N | N |
| 7 | Rust Idioms | X/10 | N | N |
| 8 | Tests | X/10 | N | N |
| 9 | Immutability | X/10 | N | N |
| 10 | Cognitive Load | X/10 | N | N |

## Critical Violations (must fix)

### [Category]: [violation title]
- **File**: `path/to/file.rs:123`
- **What**: [description]
- **Why**: [which principle it violates]
- **Fix**: [concrete suggestion]

## Flags (should fix)

[same format, grouped by category]

## Good Practices Found

[highlight things done well — positive reinforcement]

## Recommended Next Steps

1. [highest-impact fix first]
2. [second]
3. [third]
```

## Rules for the Auditor

1. **Be specific**: Every violation needs a `file:line` reference. No vague "the code could be better."
2. **Be proportional**: Don't flag idiomatic Rust patterns as violations (e.g., `if let Some(x)` is fine, `unwrap()` in tests is fine, `ctx`/`cfg` abbreviations are fine if consistent).
3. **Prioritize impact**: A 200-line function matters more than a missing doc comment.
4. **Don't over-flag negatives**: In Rust, `if !slice.is_empty()` is idiomatic. Only flag genuinely confusing negatives.
5. **Score honestly**: 10/10 means production-ready exemplary code. 7/10 is decent. 5/10 needs work. Below 5 is concerning.
6. **Context matters**: CLI output code using `println!` is fine. Test code with `unwrap()` is fine. Don't apply library standards to scripts.
7. **Language-aware**: Apply Rust idioms for Rust, not Java/C# patterns from Martin's examples.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
cli-audit-code

Directory Structure

SKILL.md

Report

Notice
