Community Code Simplification Best Practices

Comprehensive code simplification guide for AI agents and LLMs. Contains 45 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 - Always read CLAUDE.md before simplifying
• •ctx-detect-lint-config - Check for linting and formatting configs
• •ctx-follow-existing-patterns - Match existing code style in file and project
• •ctx-project-over-generic - Project conventions override generic best practices
• •ctx-identify-scope - Identify recently modified code as default scope

2. Behavior Preservation (CRITICAL)

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

3. Scope Management (HIGH)

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

4. Control Flow Simplification (HIGH)

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

5. Naming and Clarity (MEDIUM-HIGH)

• •name-intention-revealing - Use intention-revealing names
• •name-nouns-for-data - Use nouns for data, verbs for actions
• •name-avoid-abbreviations - Avoid cryptic abbreviations
• •name-consistent-vocabulary - Use consistent vocabulary throughout
• •name-avoid-generic - Avoid generic names

6. Duplication Reduction (MEDIUM)

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

7. Dead Code Elimination (MEDIUM)

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

8. Language Idioms (LOW-MEDIUM)

• •idiom-ts-strict-types - Use strict types over any (TypeScript)
• •idiom-ts-const-assertions - Use const assertions and readonly (TypeScript)
• •idiom-rust-question-mark - Use ? for error propagation (Rust)
• •idiom-rust-iterator-chains - Use iterator chains when clearer (Rust)
• •idiom-python-comprehensions - Use comprehensions for simple transforms (Python)
• •idiom-go-error-handling - Handle errors immediately (Go)
• •idiom-prefer-language-builtins - 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 - Category structure and impact levels
• •Rule template - Template for adding new rules

Reference Files