Claude Code code-simplifier：专治 AI 代码"防御过头"和"波动拳"

一句话定位

code-simplifier 是 Anthropic Claude Code 团队内部自用的代码简化 Agent，2025 年底开源。它用 Claude Opus 作为推理引擎，专门处理一个特定问题：AI 生成的代码在多次迭代后会堆积"结构性噪音"——冗余逻辑、不一致命名、过度嵌套、失效注释——而它只改写法、不改功能，像一把精准的手术刀，把 AI 的"防御过头"和"波动拳"削回人类审美。

一、问题诊断：为什么 AI 代码越写越丑

1.1 "防御过头"——过度工程化的典型症状

AI 生成代码时倾向于"安全优先"，表现为：

// AI 的"防御过头"写法
function processUser(user: User | null | undefined): Result {
  if (!user) {
    return { success: false, error: 'User is null' };
  }
  if (typeof user !== 'object') {
    return { success: false, error: 'User is not an object' };
  }
  if (!user.id) {
    return { success: false, error: 'User has no ID' };
  }
  if (typeof user.id !== 'string') {
    return { success: false, error: 'User ID is not a string' };
  }
  // ... 终于进入正题
}

人类程序员会写：

function processUser(user: User): Result {
  if (!user?.id) throw new ValidationError('Invalid user');
  // 直接开始正题
}

1.2 "波动拳"——层层嵌套的累积效应

Claude Code 在长会话中会逐渐失去架构视角，变成"你点啥我做啥"：

// 第 1 轮：简单的条件判断
const status = user.active ? 'active' : 'inactive';

// 第 3 轮：加个验证状态
const status = user.active 
  ? user.verified ? 'active-verified' : 'active-unverified'
  : 'inactive';

// 第 5 轮：再加个暂停状态
const status = user.active
  ? user.verified
    ? user.suspended ? 'suspended-verified' : 'active-verified'
    : user.suspended ? 'suspended-unverified' : 'active-unverified'
  : user.suspended ? 'suspended' : 'inactive';

这就是"波动拳"——每一轮都在前一轮的基础上叠 buff，最后变成一坨无法阅读的嵌套地狱。

1.3 结构性噪音的三大来源

二、code-simplifier 是什么

2.1 基本信息

2.2 它改什么、不改什么

明确会改：

• 冗余代码（重复逻辑、未使用变量、死代码路径）
• 不一致命名（同一文件/函数内混用命名风格）
• 不必要的复杂度（可扁平化的嵌套条件）
• 失效注释（与代码不再匹配的注释）
• 低效模式（有更便宜等价方案时）

明确不改：

• 代码逻辑（函数的输入输出、边界情况、副作用）
• 返回值和输出
• 功能行为
• 有价值的文档注释和复杂逻辑说明

三、工作机制：Agent 式迭代重构

3.1 技术实现

用户调用 /simplify 或 "请用 code-simplifier 清理代码"
    ↓
Claude Code 启动 code-simplifier Agent（Claude Opus）
    ↓
Agent 读取项目 CLAUDE.md（团队编码标准）
    ↓
Agent 分析最近修改的代码（默认范围）
    ↓
Agent 识别改进机会（ elegance + consistency ）
    ↓
逐文件迭代重构（每次专注一个问题）
    ↓
验证：功能保持不变
    ↓
输出：简化后的代码 + 变更摘要

3.2 核心 Prompt

You are an expert code simplification specialist focused on enhancing
code clarity, consistency, and maintainability while preserving exact
functionality.

Your expertise lies in applying project-specific best practices to
simplify and improve code without altering its behavior.

You prioritize readable, explicit code over overly compact solutions.

关键指令："优先可读、显式的代码，而非过度紧凑的解法"——这直接针对 AI 的"嵌套三元表达式"恶习。

3.3 与项目标准集成

code-simplifier 会自动读取项目根目录的 CLAUDE.md，遵循团队编码规范：

# 编码标准

## 导入约定
- 使用带显式扩展名的 ES 模块（.js, .ts）
- 导入顺序：先外部包，再本地模块

## 函数模式
- 顶层函数优先使用 `function` 关键字
- 回调和内联函数使用箭头函数

## 类型注解
- 所有导出函数必须有返回类型注解
- 避免使用 `any`

这意味着：code-simplifier 不是一套固定规则，而是根据每个项目的约定进行自适应清理。

四、实战案例：从"波动拳"到人类审美

4.1 案例一：嵌套三元表达式 → 清晰 switch/if

Before（AI 的波动拳）：

const status = user.active
  ? user.verified
    ? user.suspended ? 'suspended-verified' : 'active-verified'
    : user.suspended ? 'suspended-unverified' : 'active-unverified'
  : user.suspended ? 'suspended' : 'inactive';

After（code-simplifier）：

function getUserStatus(user: User): UserStatus {
  if (user.suspended) return 'suspended';
  if (!user.active) return 'inactive';
  return user.verified ? 'active-verified' : 'active-unverified';
}
const status = getUserStatus(user);

改动分析：

• 消除 4 层嵌套三元 → 扁平化 if 返回
• 提取命名函数，语义自解释
• 保留所有功能路径（suspended/active-verified/active-unverified/inactive）

4.2 案例二：过度防御 → 早期返回

Before（防御过头）：

function validateOrder(order: Order | null): ValidationResult {
  const result: ValidationResult = { valid: false, errors: [] };
  
  if (order === null) {
    result.errors.push('Order is null');
    return result;
  }
  if (typeof order !== 'object') {
    result.errors.push('Order is not an object');
    return result;
  }
  if (!order.id) {
    result.errors.push('Order missing ID');
    return result;
  }
  if (typeof order.id !== 'string') {
    result.errors.push('Order ID must be string');
    return result;
  }
  if (!order.items || !Array.isArray(order.items)) {
    result.errors.push('Order items must be array');
    return result;
  }
  // ... 真正的业务逻辑
}

After（code-simplifier）：

function validateOrder(order: unknown): ValidationResult {
  const errors: string[] = [];
  
  if (!isValidOrder(order)) {
    return { valid: false, errors: ['Invalid order structure'] };
  }
  
  // ... 真正的业务逻辑（从第 3 行开始，而不是第 30 行）
}

改动分析：

• 提取类型守卫 isValidOrder，消除重复结构
• 早期返回模式，减少嵌套层级
• 从 30+ 行的防御壳 → 3 行类型守卫

4.3 案例三：不一致命名 → 统一规范

Before：

// 同一文件里混用三种风格
function fetch_user_data(userId: string) { /* ... */ }
const getUserProfile = (id: string) => { /* ... */ };
function loadUserOrders(user_id: string) { /* ... */ }

After：

// 统一为：动词 + 名词，camelCase
function fetchUserData(userId: string) { /* ... */ }
function fetchUserProfile(userId: string) { /* ... */ }
function fetchUserOrders(userId: string) { /* ... */ }

五、自动化集成：Pre-Commit Hook

手动运行 code-simplifier 的问题是——你会忘记。最有效的集成方式是 pre-commit hook。

5.1 基础 Hook 配置

# .git/hooks/pre-commit（或 husky/pre-commit）
#!/bin/bash
# 获取 staged 文件列表
STAGED_FILES=\((git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py|go|rs)\)')

if [ -z "\(STAGED_FILES" ]; then
  exit 0
fi

# 运行 code-simplifier
echo "Running code-simplifier on staged files..."
claude agent code-simplifier:code-simplifier --files "\)STAGED_FILES"

# 如果 simplifier 做了修改，重新 stage
MODIFIED=\((git diff --name-only)
if [ -n "\)MODIFIED" ]; then
  echo "Code simplified. Re-staging changes..."
  git add \(MODIFIED
fi
```

### 5.2 与 CI/CD 集成

```yaml
# .github/workflows/simplify.yml
name: Code Simplification Check
on: [pull_request]

jobs:
  simplify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run code-simplifier
        run: |
          claude plugin install code-simplifier
          claude agent code-simplifier:code-simplifier --diff-only
      - name: Check for uncommitted simplifications
        run: |
          if [ -n "\)(git diff)" ]; then
            echo "::error::Code needs simplification. Run 'claude agent code-simplifier' locally."
            exit 1
          fi

六、已知问题与生态现状

6.1 Bug：Plugin Name 冲突

截至 2026-03，code-simplifier 有一个已知 bug（GitHub issue #36002）：

Plugin name 和 Agent name 都是 code-simplifier，导致完全限定名为 code-simplifier:code-simplifier。当 /simplify 调用时，框架尝试用短名 code-simplifier 解析，但匹配失败。

Workaround：手动用完全限定名调用：

claude agent code-simplifier:code-simplifier

另一个相关 bug（issue #19889）：code-simplifier 被错误列在 Skill tool 的可用技能中，但用 Skill tool 调用返回 "Unknown skill"。它实际应该通过 Task tool 调用。

6.2 社区适配版本

安装 Laravel 版：

/plugin marketplace add laravel/claude-code
/plugin install laravel-simplifier@laravel

七、与其他工具的对比

code-simplifier 的独特位置：它是唯一一个专注于"清理 AI 生成的结构性噪音"的工具。ESLint 检查语法和基础风格，但不懂"这个嵌套三元该不该拆"。Prettier 只管格式，不管逻辑。只有 code-simplifier 用 AI 对抗 AI——用更强的推理模型（Opus）审查普通 AI 生成代码的审美。

八、使用建议：什么时候用、什么时候不用

8.1 推荐使用场景

• 长会话后 cleanup：编码 2 小时后运行一次，清理累积的噪音
• PR 提交前：确保代码符合团队审美标准
• 接手 AI 生成的代码：先 simplify，再阅读理解
• 代码审查前：减少审查者的认知负担

8.2 不建议使用场景

• 紧急 hotfix：可能引入不必要的改动，增加风险
• 高度优化的算法代码：Opus 可能"简化"掉你故意写的 hack
• 缺乏测试覆盖的代码：没有测试验证功能不变性
• 一次性脚本：不值得投入

8.3 最佳实践

# 1. 安装
claude plugin install code-simplifier

# 2. 项目配置（必须！）
cat > CLAUDE.md << 'EOF'
# 编码标准
## 函数模式
- 顶层函数使用 `function` 关键字
- 避免嵌套三元表达式，使用 if/else 或 switch
- 优先 early return 而非深层嵌套

## 命名
- camelCase 函数名，PascalCase 组件名
- 动作 + 名词（fetchUserData, not get_data）
EOF

# 3. 长会话后清理
claude agent code-simplifier:code-simplifier

# 4. 或针对特定文件
claude agent code-simplifier:code-simplifier --files src/components/*.tsx

# 5. 提交前确认
# 先提交一次（backup），再 simplify，再 diff 对比
git add . && git commit -m "WIP: before simplification"
claude agent code-simplifier:code-simplifier
git diff  # 审查改动

九、一句话总结

AI 写代码像新手厨师做菜——每样食材都洗三遍、每步操作都确认两遍、最后摆盘时把所有的装饰都堆上去。code-simplifier 就是那个站在你身后的老厨师，把多余的步骤删掉、把摆盘理顺、把味道保留——它不是让菜变简单，而是让菜的复杂恰到好处。

核心等式：

code-simplifier = 用更强的 AI（Opus）审查普通 AI 的审美，只削噪音、不动功能。

参考

• code-simplifier GitHub Issue #36002（命名冲突）
• code-simplifier GitHub Issue #19889（Skill/Agent 混淆）
• Boris Cherny Twitter 发布（开源宣布）
• Claude Code 插件文档: https://code.claude.com/docs/en/plugins
• Anthropic 官方插件仓库: anthropics/claude-plugins-official
• aiproductivity.ai Pre-Commit Hook 指南
• claudecn.com 中文社区文档

#code-simplifier #ClaudeCode #AI编程 #代码重构 #代码质量 #Agent #Anthropic #小凯

#code-simplifier #ClaudeCode #AI编程 #代码重构 #代码质量 #Agent #Anthropic #小凯