Clean Code

Clean Code Lifecycle

"Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch

When to Use

• Writing new code: To ensure high quality from the start.
• Reviewing Pull Requests: To provide constructive, principle-based feedback.
• Refactoring legacy code: To identify and remove code smells.
• Improving team standards: To align on industry-standard best practices.

Prerequisites

Phase 0 — Project Context Discovery

Before applying any clean code principle, understand the project you're working in. Refactoring or deduplicating without context leads to wrong abstractions, broken conventions, and wasted effort.

Discovery Commands

# 1. Find project documentation — README, ADRs, contributing guides
fd -t f -i '(README|CONTRIBUTING|ADR|ARCHITECTURE|CONVENTIONS|STYLE_GUIDE)' .

# 2. Find configuration files that reveal conventions and tooling
fd -t f '(\.eslintrc|\.prettierrc|\.editorconfig|\.golangci|pyproject\.toml|biome\.json)' .

# 3. Check for a CLAUDE.md or similar AI-agent instructions
fd -t f 'CLAUDE.md' .

# 4. Read the project's commit style to match refactoring commits
git log --oneline -20

# 5. Check for existing shared utilities — avoid creating duplicates
fd -t f -i '(utils|helpers|shared|common|lib)' src/

Key Questions

Decision Rules

• If a style guide exists → follow it, even if it contradicts Clean Code principles. Project consistency wins over theoretical purity.
• If shared utils already exist → add to them instead of creating parallel helpers.
• If ADRs document a decision to keep duplication → respect it. Not all duplication is accidental.
• If no tests exist → write characterization tests before any refactoring (see Phase 3).
• If no documentation exists → read code structure, git history, and CI config to infer conventions.

Rule: context before cleanup. A "clean" refactoring that ignores project conventions creates more mess than the duplication it removed.

Phase 1 — Code Quality Audit

Scan the codebase for code smells. Each smell includes a description and detection method.

Principle Checks

For each file under review, verify against the core principles. See references/PRINCIPLES.md for full details.

• Names: Intention-revealing, searchable, pronounceable?
• Functions: Small (<30 lines), do one thing, ≤2 arguments?
• Comments: Can any comment be eliminated by making the code clearer?
• Formatting: Newspaper metaphor — high-level at top, details at bottom?
• Objects: Law of Demeter respected? No a.getB().getC().doSomething()?
• Error Handling: Exceptions over return codes? No null returns/passes?
• Tests: F.I.R.S.T. principles followed?
• Classes: Single Responsibility Principle?

Language-Specific Checks

For language-specific smells, idioms, and detection commands:

• Go: See references/GOLANG.md — stuttering names, empty interface abuse, init() side effects, naked returns, oversized interfaces, functional options
• Rust: See references/RUST.md — unwrap() abuse, unnecessary clone(), stringly typed APIs, Arc<Mutex<>> overuse, monolithic error enums, boolean parameters
• TypeScript: See references/TYPESCRIPT.md — any abuse, excessive type assertions, enum vs union, barrel file bloat, god interfaces, class overuse
• Bun: See references/BUN.md — Node.js APIs vs Bun natives, unnecessary polyfills, dotenv/jest/express replacements, Bun.file/Bun.serve/Bun.password
• Python: See references/PYTHON.md — dict-as-object, if/elif dispatch chains, **kwargs soup, boolean flag params, stateless classes, import-time side effects, sync/async twins

Phase 2 — Duplication & Dead Code Detection

Duplication is the same knowledge, logic, or intent expressed in more than one place. Dead code is a symbol nothing reaches. Both inflate the change surface — find them before Phase 3 touches anything.

2.1 Duplication

Detection commands per class, how to read the Structural signal from commit history, and the when NOT to deduplicate rules: references/DUPLICATION.md.

Rule of Three. Tolerate two copies. Extract on the third. A premature abstraction — the shared function that needs 4 parameters and 2 boolean flags to serve every caller — is worse than the duplication it removed.

2.2 Dead Code

Command matrix per language, plus the twelve false-positive guardrails that must clear before any deletion: references/DEAD_CODE.md.

Rule: two independent signals before deleting. A tool finding plus a manual sweep of non-source assets. Reflection, DI registries, framework decorators, serialization, and string-based routing are invisible to every dead-code tool — deleting a live symbol passes the test suite and breaks production.

Phase 3 — Safe Refactoring

Apply refactoring patterns to resolve the issues found in Phases 1 and 2. For concrete before/after diffs, see references/PATTERNS.md.

Available Patterns

Step 1 — Secure the starting point

# Ensure all tests pass BEFORE you start
go test ./...          # Go
cargo test             # Rust
bun test               # Bun
npm test               # Node/TS
pytest                 # Python

# Ensure a clean git state
git status             # should be clean, or stash first
git stash              # if needed

# Create a dedicated branch
git checkout -b refactor/describe-the-change

Rule: never refactor on a dirty working tree. Mixing feature changes with refactoring makes rollback impossible.

Step 2 — One transformation at a time

Each refactoring step must be atomic — a single, small, independently verifiable change.

Never batch multiple extractions into a single step.

# After EACH small change:
go test ./...  # or your project's test command
git add -p     # stage only the relevant change
git commit -m "refactor: step N — description"

Step 3 — Verify behavior preservation

# Go: check exported symbols haven't changed
go doc ./pkg/handlers
go vet ./...
golangci-lint run ./...

# Rust: clippy + format + test
cargo clippy -- -W clippy::pedantic
cargo fmt -- --check
cargo test

# TypeScript / Bun: type check + lint
bunx tsc --noEmit          # or: npx tsc --noEmit
bunx biome check .         # or: npx eslint .
bun test                   # or: npx vitest run

# Python: type check + lint + test
ruff check .
ruff format --check .
mypy --strict .
pytest -q

# Find unused exports and dependencies (TypeScript / Bun)
bunx knip

# Run integration/e2e tests if available
npm run test:e2e

# Check for unused imports/variables introduced by refactoring
go vet ./...                                            # Go
cargo machete                                           # Rust
bunx knip                                               # TypeScript / Bun
npx eslint --rule '{"no-unused-vars": "error"}' src/    # TypeScript (eslint)
ruff check --select=F401,F841,ARG .                     # Python — unused imports/vars/params
vulture src/ tests/ --min-confidence 90                 # Python — dead symbols

Step 4 — Rollback strategy

# Undo current uncommitted change (keep committed steps)
git checkout -- .

# Revert just one committed step
git revert <commit-hash>

# Abandon the entire refactoring branch
git checkout main
git branch -D refactor/describe-the-change

The branch-per-refactoring approach means you never risk main.

Common Pitfalls

• Changing behavior during refactoring: Resist the urge to "fix that bug while I'm here." Refactoring and behavior changes are separate commits — always.
• Refactoring without tests: If the code has no tests, write characterization tests first — tests that capture current behavior, even if that behavior has bugs.
• Big-bang refactoring: Rewriting an entire module at once. Prefer the Strangler Fig pattern — replace piece by piece.
• Skipping the test run: "It's just a rename." Type aliases, reflection, serialization, string-based routing — all break on renames.

Plan-only mode

Composing /clean-code /only-plan suppresses every write in Phase 3 — no branch, no commits, no edits. Phases 0–2 run normally, and each planned transformation becomes a numbered step in the single IMPLEMENTATION_PLAN.md at the project root, following @only-plan's section contract. This skill writes no file of its own in either mode.

Related Skills

• @only-plan — compose as /clean-code /only-plan for a refactor plan at the project root instead of applied edits.
• @ponytail-review — the complementary lens: what to delete (speculative abstractions, dependencies the stdlib replaces, config nobody sets) rather than what to restructure.
• @code-optimization — when duplication or a smell has a measurable performance cost; it grades Impact and writes OPTIMIZATION_REPORT.md.
• @code-review — broad severity-ranked review; its Rule-of-Three findings hand off here for the refactor mechanics.
• @code-debugger — a smell that is actually a live defect belongs there first. Refactor after the fix is green.

References

• PRINCIPLES — the eight Clean Code principle families
• PATTERNS — six refactoring patterns with before/after diffs
• DUPLICATION — taxonomy, detection probes, when NOT to deduplicate
• DEAD_CODE — per-language detection, false-positive guardrails, removal protocol
• GOLANG · RUST · TYPESCRIPT · BUN · PYTHON — language-specific smells and idioms

Implementation Checklist

• Is this function smaller than 30 lines?
• Does this function do exactly one thing?
• Are all names searchable and intention-revealing?
• Have I avoided comments by making the code clearer?
• Am I passing too many arguments?
• Is there a failing test for this change?
• Is there duplicated logic that could be extracted into a shared function?
• Are magic strings/numbers extracted into named constants?
• Did I check for existing utilities before writing a new helper?
• If I extracted a shared abstraction, is it used in 3+ places (Rule of Three)?
• Did two independent signals confirm each dead symbol before deleting it (tool finding + non-source sweep)?
• Did I clear the false-positive guardrails (reflection, DI, framework decorators, serialization, entry points, published API)?
• Is each deletion in its own commit, separate from any refactor?
• Did I run all tests before AND after refactoring?
• Is each refactoring step in its own commit (one transformation per commit)?
• Did I avoid mixing behavior changes with structural refactoring?
• If the code had no tests, did I write characterization tests before refactoring?