Code Simplifier

Community Code Simplification Best Practices

Comprehensive code simplification guide for AI agents and LLMs. Contains 47 rules across 8 categories, prioritized by impact from critical (context discovery, behavior preservation) to incremental (language idioms). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

Core Principles

1. Context First: Understand project conventions before making any changes
2. Behavior Preservation: Change how code is written, never what it does
3. Scope Discipline: Focus on recently modified code, keep diffs small
4. Clarity Over Brevity: Explicit, readable code beats clever one-liners

When to Apply

Reference these guidelines when:

• Simplifying or cleaning up recently modified code
• Reducing nesting, complexity, or duplication
• Improving naming and readability
• Applying language-specific idiomatic patterns
• Reviewing code for maintainability issues

Rule Categories by Priority

Quick Reference

1. Context Discovery (CRITICAL)

• ctx-read-claude-md [blocked] - Always read CLAUDE.md before simplifying
• ctx-detect-lint-config [blocked] - Check for linting and formatting configs
• ctx-follow-existing-patterns [blocked] - Match existing code style in file and project
• ctx-project-over-generic [blocked] - Project conventions override generic best practices

2. Behavior Preservation (CRITICAL)

• behave-preserve-outputs [blocked] - Preserve all return values and outputs
• behave-preserve-errors [blocked] - Preserve error messages, types, and handling
• behave-preserve-api [blocked] - Preserve public function signatures and types
• behave-preserve-side-effects [blocked] - Preserve side effects (logging, I/O, state changes)
• behave-no-semantics-change [blocked] - Forbid subtle semantic changes
• behave-verify-before-commit [blocked] - Verify behavior preservation before finalizing

3. Scope Management (HIGH)

• scope-recent-code-only [blocked] - Focus on recently modified code only
• scope-minimal-diff [blocked] - Keep changes small and reviewable
• scope-no-unrelated-refactors [blocked] - No unrelated refactors
• scope-no-global-rewrites [blocked] - Avoid global rewrites and architectural changes
• scope-respect-boundaries [blocked] - Respect module and component boundaries

4. Control Flow Simplification (HIGH)

• flow-early-return [blocked] - Use early returns to reduce nesting
• flow-guard-clauses [blocked] - Use guard clauses for preconditions
• flow-no-nested-ternaries [blocked] - Never use nested ternary operators
• flow-explicit-over-dense [blocked] - Prefer explicit control flow over dense expressions
• flow-flatten-nesting [blocked] - Flatten deep nesting to maximum 2-3 levels
• flow-single-responsibility [blocked] - Each code block should do one thing
• flow-positive-conditions [blocked] - Prefer positive conditions over double negatives
• flow-optional-chaining [blocked] - Use optional chaining and nullish coalescing
• flow-boolean-simplification [blocked] - Simplify boolean expressions

5. Naming and Clarity (MEDIUM-HIGH)

• name-intention-revealing [blocked] - Use intention-revealing names
• name-nouns-for-data [blocked] - Use nouns for data, verbs for actions
• name-avoid-abbreviations [blocked] - Avoid cryptic abbreviations
• name-consistent-vocabulary [blocked] - Use consistent vocabulary throughout
• name-avoid-generic [blocked] - Avoid generic names
• name-string-interpolation [blocked] - Prefer string interpolation over concatenation

6. Duplication Reduction (MEDIUM)

• dup-rule-of-three [blocked] - Apply the rule of three
• dup-no-single-use-helpers [blocked] - Avoid single-use helper functions
• dup-extract-for-clarity [blocked] - Extract only when it improves clarity
• dup-avoid-over-abstraction [blocked] - Prefer duplication over premature abstraction
• dup-data-driven [blocked] - Use data-driven patterns over repetitive conditionals

7. Dead Code Elimination (MEDIUM)

• dead-remove-unused [blocked] - Delete unused code artifacts
• dead-delete-not-comment [blocked] - Delete code, never comment it out
• dead-remove-obvious-comments [blocked] - Remove comments that state the obvious
• dead-keep-why-comments [blocked] - Keep comments that explain why, not what
• dead-remove-todo-fixme [blocked] - Remove stale TODO/FIXME comments

8. Language Idioms (LOW-MEDIUM)

• idiom-ts-strict-types [blocked] - Use strict types over any (TypeScript)
• idiom-ts-const-assertions [blocked] - Use const assertions and readonly (TypeScript)
• idiom-rust-question-mark [blocked] - Use ? for error propagation (Rust)
• idiom-rust-iterator-chains [blocked] - Use iterator chains when clearer (Rust)
• idiom-python-comprehensions [blocked] - Use comprehensions for simple transforms (Python)
• idiom-go-error-handling [blocked] - Handle errors immediately (Go)
• idiom-prefer-language-builtins [blocked] - Prefer language and stdlib builtins

Workflow

1. Discover context: Read CLAUDE.md, lint configs, examine existing patterns
2. Identify scope: Focus on recently modified code unless asked to expand
3. Apply transformations: Use rules in priority order (CRITICAL first)
4. Verify behavior: Ensure outputs, errors, and side effects remain identical
5. Keep diffs minimal: Small, focused changes that are easy to review

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions [blocked] - Category structure and impact levels
• Rule template [blocked] - Template for adding new rules

Reference Files