Code Simplifier Consultant

An expert code simplification agent that enhances code clarity, consistency, and maintainability by applying project-specific best practices while preserving exact functionality — favoring readable, explicit code over compact solutions.

When to Use This Agent

Choose Code Simplifier Consultant when:

• Complex functions need to be broken down into readable, maintainable pieces
• Code has accumulated unnecessary abstractions or indirection layers
• Refactoring legacy code to follow modern patterns without changing behavior
• Reducing cyclomatic complexity in functions with deep nesting or many branches
• Eliminating dead code, unused imports, and redundant logic

Consider alternatives when:

• Adding new functionality (simplification is about removing, not adding)
• Optimizing for performance (use a performance agent — simplicity and speed can conflict)
• Fixing bugs that require understanding the domain logic first (use a debugging agent)

Quick Start

Copy
# .claude/agents/code-simplifier-consultant.yml
name: Code Simplifier Consultant
description: Simplify code while preserving exact behavior
model: claude-sonnet
tools:
  - Read
  - Edit
  - Glob
  - Grep

Example invocation:

claude "Simplify the processOrder function in src/services/orderService.ts — reduce complexity, improve readability, and remove any dead code paths"

Core Concepts

Simplification Techniques

Technique	Before	After	When to Apply
Early return	Nested if/else chains	Guard clauses at top	Deep nesting (3+ levels)
Extract function	Long function body	Named helper functions	Functions >30 lines
Replace flag with polymorphism	if (type === 'a') chains	Strategy pattern	3+ type-based branches
Inline trivial abstraction	One-line wrapper function	Direct call	Wrapper adds no clarity
Replace loop with pipeline	for loop with mutations	map/filter/reduce	Transform + filter operations

Simplification Example

Copy
// BEFORE: Complex nested logic
function processOrder(order: Order, user: User): Result {
  let result: Result;
  if (order) {
    if (order.items && order.items.length > 0) {
      if (user && user.isActive) {
        let total = 0;
        for (let i = 0; i < order.items.length; i++) {
          const item = order.items[i];
          if (item.quantity > 0 && item.price > 0) {
            let itemTotal = item.quantity * item.price;
            if (user.discount > 0) {
              itemTotal = itemTotal * (1 - user.discount);
            }
            total += itemTotal;
          }
        }
        result = { success: true, total };
      } else {
        result = { success: false, error: 'User inactive' };
      }
    } else {
      result = { success: false, error: 'No items' };
    }
  } else {
    result = { success: false, error: 'No order' };
  }
  return result;
}

// AFTER: Simplified with guard clauses and pipeline
function processOrder(order: Order, user: User): Result {
  if (!order) return { success: false, error: 'No order' };
  if (!order.items?.length) return { success: false, error: 'No items' };
  if (!user?.isActive) return { success: false, error: 'User inactive' };

  const total = order.items
    .filter(item => item.quantity > 0 && item.price > 0)
    .reduce((sum, item) => {
      const itemTotal = item.quantity * item.price;
      return sum + (user.discount > 0 ? itemTotal * (1 - user.discount) : itemTotal);
    }, 0);

  return { success: true, total };
}

Complexity Metrics

Copy
// Target thresholds for simplified code
interface ComplexityTargets {
  cyclomaticComplexity: number;  // Max 10 per function
  nestingDepth: number;          // Max 3 levels
  functionLength: number;        // Max 30 lines
  parameterCount: number;        // Max 4 parameters
  returnPoints: number;          // Max 5 per function (with guard clauses)
  cognitiveComplexity: number;   // Max 15 (Sonar metric)
}

Configuration

Parameter	Description	Default
max_complexity	Maximum cyclomatic complexity per function	10
max_nesting	Maximum nesting depth	3
max_function_length	Maximum lines per function	30
preserve_comments	Keep existing comments during simplification	true
style_guide	Project style conventions to follow	Auto-detect
verify_behavior	Run tests after each simplification	true

Best Practices

1. Simplify one function at a time and verify tests pass between each change. Large-scale simplification across multiple files increases the risk of introducing subtle behavior changes. Focus on one function, simplify it, run the tests, confirm green. Then move to the next function. This incremental approach makes it easy to identify which simplification introduced any regression.

2. Prefer guard clauses over deeply nested conditionals. Invert negative conditions and return early. This flattens the function body, reduces indentation, and makes the "happy path" immediately visible as the main flow. Guard clauses read like preconditions: "if this is wrong, bail out" — followed by the core logic with minimal nesting.

3. Remove abstractions that do not earn their indirection cost. A utility function that wraps a single standard library call, a class with one method, or a config option used in only one place adds cognitive overhead without providing reuse or clarity. Inline these abstractions to reduce the number of places a reader must look to understand the code. Add abstractions when a pattern appears three or more times.

4. Replace boolean parameters with explicit function variants. A function like fetchUsers(includeInactive: boolean) forces the reader to look up what true means at every call site. Two functions fetchActiveUsers() and fetchAllUsers() are self-documenting. Boolean parameters create ambiguity, especially when functions take multiple booleans — process(true, false, true) is unreadable.

5. Use descriptive intermediate variables instead of long chained expressions. A single expression spanning three or more chained methods or nested function calls is hard to debug and hard to read. Break it into named intermediate variables that describe what each step produces. The variable names serve as inline documentation, and breakpoints can be placed at each step during debugging.

Common Issues

Simplification accidentally changes behavior in subtle edge cases. Moving from a loop to a functional pipeline can change behavior with NaN, undefined, or sparse arrays. Replacing == null with === null changes how undefined is handled. Always run the existing test suite after each simplification. If test coverage is thin, write characterization tests that capture the current behavior before simplifying.

Team disagrees on what constitutes "simpler" code. One developer's clarity is another's over-simplification. Establish team-level complexity thresholds (max cyclomatic complexity, max nesting depth) and use automated linting (eslint-plugin-sonarjs, eslint-plugin-complexity) to enforce them. Objective metrics reduce subjective debates. Discuss edge cases during code reviews to calibrate the team's shared understanding.

Removing "unnecessary" code breaks features that are not covered by tests. Dead code analysis tools and manual inspection can identify code that appears unused but is actually called via dynamic dispatch, reflection, or external triggers (webhooks, cron jobs). Before deleting seemingly dead code, search for string references to the function/class name, check for dynamic invocations, and verify that no external system calls it. Mark code as deprecated before removing it.