ai-code-cleanup

AI 代码清理

此技能可识别并移除降低代码质量的 AI 生成痕迹，包括防御性冗余、不必要的注释、类型转换和风格不一致。

何时使用此技能

• AI 辅助编程后
• 代码审查或合并分支前
• 清理感觉“过度设计”的代码时
• 移除不必要的防御性代码时
• 统一 AI 生成代码的风格时
• 为生产环境准备代码时

此技能的功能

1. 识别 AI 痕迹：检测 AI 生成代码的典型模式
2. 移除冗余：消除不必要的防御性代码和注释
3. 修复类型问题：移除不必要的类型转换和变通方案
4. 统一风格：确保代码符合项目规范
5. 保留功能：在提升质量的同时保持代码行为不变
6. 验证更改：确保代码仍可编译且测试通过

使用方法

清理分支

Remove AI slop from this branch

Clean up the code in this pull request

针对性清理

Remove unnecessary comments and defensive code from src/

要移除的冗余模式

1. 不必要的注释

模式：

• 解释显而易见代码的注释
• 与文件文档风格不一致的注释
• 重复陈述代码内容的冗余注释
• 对简单操作过度添加文档说明

示例：

// ❌ AI-generated: Obvious comment
// Set the user's name
user.name = name;

// ✅ Clean: Self-documenting code
user.name = name;

2. 防御性冗余

模式：

• 代码库中不常见的额外 try/catch 代码块
• 在可信路径上进行防御性 null/undefined 检查
• 调用方已完成验证时的重复输入验证
• 永远不会触发的错误处理

示例：

// ❌ AI-generated: Unnecessary defensive code
function processUser(user) {
  try {
    if (user && user.name && typeof user.name === 'string') {
      return user.name.toUpperCase();
    }
    return null;
  } catch (error) {
    console.error(error);
    return null;
  }
}

// ✅ Clean: Trust the input, handle real errors
function processUser(user) {
  return user.name.toUpperCase();
}

3. 类型变通方案

模式：

• 为绕过类型问题而转换为 any
• 不必要的类型断言（as X）
• 没有正当理由的 @ts-ignore 或 @ts-expect-error
• 过于复杂的泛型约束

示例：

// ❌ AI-generated: Type workaround
const data = response.data as any;
const result = processData(data as ProcessedData);

// ✅ Clean: Proper typing
const data = response.data;
const result = processData(data);

4. 风格不一致

模式：

• 与文件其余部分不同的命名规范
• 与周围代码风格不符的格式
• 与文件惯例不一致的导入组织方式
• 与文件风格不一致的变量声明

示例：

// ❌ AI-generated: Inconsistent style
const UserData = fetchUser();
var processedData = process(UserData);
let FinalResult = format(processedData);

// ✅ Clean: Consistent style
const userData = fetchUser();
const processedData = process(userData);
const finalResult = format(processedData);

5. AI 痕迹

模式：

• 在代码或注释中不必要地使用表情符号
• 过于冗长的变量名
• 冗余的中间变量
• 没有实际使用场景的“以防万一”代码

清理流程

1. 获取差异

git diff $(git merge-base HEAD main)..HEAD --name-only

2. 分析每个文件

对于每个已更改的文件：

• 阅读整个文件，了解现有风格
• 识别冗余类别中的模式
• 通过精简修改移除冗余
• 保留原有功能

3. 验证

• 确保代码仍可编译/运行
• 更改应减少代码，而不是增加代码
• 运行测试以验证行为
• 检查是否存在回归问题

示例

示例 1：清理注释

输入：从 src/auth.js 中移除不必要的注释

输出：

## AI Code Cleanup: src/auth.js

### Removed
- 12 redundant comments explaining obvious code
- 3 comments inconsistent with file style
- 5 over-documented simple operations

### Changes
```javascript
// Before
// Function to validate user email
// Takes email string as input
// Returns boolean indicating validity
function validateEmail(email) {
  // Check if email is not empty
  if (!email) {
    return false; // Return false if empty
  }
  // Return regex test result
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

// After
function validateEmail(email) {
  if (!email) return false;
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

结果

• 行数减少：12 → 4
• 保留原有功能
• 测试通过

### Example 2: Defensive Bloat Removal

**Input**: Remove defensive bloat from `src/api/users.js`

**Output**:
```markdown
## AI Code Cleanup: src/api/users.js

### Removed
- 3 unnecessary try/catch blocks
- 8 redundant null checks on validated inputs
- 2 error handlers that can never trigger

### Changes
```javascript
// Before
async function getUser(userId) {
  try {
    if (!userId || typeof userId !== 'string') {
      throw new Error('Invalid userId');
    }
    const user = await db.users.findById(userId);
    if (user && user.id) {
      return user;
    }
    return null;
  } catch (error) {
    console.error(error);
    throw error;
  }
}

// After
async function getUser(userId) {
  const user = await db.users.findById(userId);
  return user || null;
}

结果

• 代码减少：15 行 → 3 行
• 保留原有功能
• 错误处理适合当前场景

## Reference Files

- **`references/REFACTORING_PLAN.template.md`** - Refactoring plan template with code smells, before/after metrics, and rollback strategy

## Best Practices

### Cleanup Guidelines

1. **Preserve Functionality**: Only remove code that doesn't affect behavior
2. **Maintain Style**: Follow existing project conventions
3. **Keep Real Errors**: Don't remove legitimate error handling
4. **Test After Changes**: Always verify code still works
5. **Incremental**: Make changes incrementally, test as you go

### What to Keep

- Legitimate error handling
- Necessary type assertions
- Helpful comments that add context
- Defensive code for untrusted inputs
- Style that matches the codebase

### What to Remove

- Obvious comments
- Unnecessary defensive code
- Type workarounds
- Style inconsistencies
- AI-generated artifacts

## Related Use Cases

- Post-AI coding cleanup
- Code review preparation
- Code quality improvement
- Style standardization
- Removing technical debt