simplify-parallel

并行简化代码库

通过自动将大型代码库划分为逻辑代码块，并按正确的依赖顺序并发处理，来简化代码。

快速参考

命令	说明
/simplify-parallel	分析并简化整个代码库
/simplify-parallel --dry-run	仅分析，显示计划但不执行
/simplify-parallel --focus=lib	限定到特定区域
/simplify-parallel --segments=4	设置并行 Agent 数量上限

用法

/simplify-parallel [options]

选项

选项	默认值	说明
--dry-run	false	仅分析，不修改文件
--focus=AREA	all	限定到指定区域：api、lib、components、hooks、pages
--segments=N	3	并行 Agent 数量上限
--max-files=N	20	每个代码段的文件数上限
--verbose	false	显示详细进度

---

关键：不要更改的内容

本节优先级最高。 违反这里的要求会让简化失去价值。 工作人员在进行任何更改前必须阅读本节。

切勿删除注释

工作人员绝不能删除以下任何内容：

请勿删除	示例
章节分隔符	// ===== Types =====、// ===== Helpers =====、// ===== Component =====
JSDoc/TSDoc 文档字符串	/** Computes the current project step... */
文件头注释	文件顶部用于说明用途的块注释
“原因”注释	// Only truly block when mutation is actively in flight
业务逻辑注释	// While any query is loading, trust the server-provided step
错误处理依据	// Check if error is retryable based on status code
TODO/FIXME/NOTE 注释	这些用于追踪技术债务
Biome 忽略指令	// biome-ignore lint/style/useNamingConvention: reason
重新导出注释	// Re-export types for convenience、// Production hooks use tRPC
阶段/章节标记	// Phase 14.16、// Step 1: Fetch and validate

切勿删除以下代码模式

请勿删除	原因
明确表达意图的模式	if (x) { return x; } return undefined; 表达了意图；隐式的 return x; 则不然
命名的中间变量	const isMutationPending = mutation.isPending 比内联写法更清晰
错误处理结构	不要合并处理不同错误类型的 try/catch 代码块
手动测试输出	*.integration.ts 或 manual.*.ts 文件中的 console.log 是有意保留的

规则

如果删除注释或进行简化会降低_意图_表达的清晰度，就不要这么做。

简化意味着移除_不必要的复杂性_，而不是移除_文档说明_。

---

工作原理

阶段 1：代码库分析

编排器会分析代码库结构：

1. Directory Tree Scan     -> Identify top-level modules
2. File Metrics Collection -> Count files, LOC, complexity per directory
3. Dependency Graph        -> Parse imports to build file->file dependency map
4. Cluster Formation       -> Group tightly-coupled files into processing units

阶段 2：划分代码段

根据以下因素将文件分组：

• 自然边界：src/app/api/、src/lib/、src/components/
• 依赖耦合：相互导入的文件放在同一组
• 大小限制：每个代码段以 10–25 个文件为目标

阶段 3：并行执行

Orchestrator (Main Agent)
  |-- Worker Agent (Segment A)
  |-- Worker Agent (Segment B)
  |-- Worker Agent (Segment C)

阶段 4：验证与整合

所有代码段完成后：

1. 运行类型检查（npm run typecheck）
2. 运行 lint（npm run lint）
3. 运行单元测试（npm run test:run）
4. 确认没有注释被删除（必须执行）
5. 创建整合提交

工作流步骤

步骤 1：运行分析

npx tsx scripts/analyze-codebase.ts --verbose

注意： 分析脚本会自动排除 .github/worktrees/ 目录。

步骤 2：检查并行组

分析输出会显示哪些代码段可以并发执行。

核心原则：各组按顺序处理，但组内的代码段会并行运行。

步骤 3：执行简化

对于每个并行组：

1. 使用 Task 工具启动工作 Agent
2. 每个工作 Agent 都会收到一份专属的待修改文件列表
3. 各工作 Agent 同时运行，彼此不重叠
4. 等待所有工作 Agent 完成后，再处理下一组

步骤 4：验证并提交

所有组完成后，运行完整验证套件：

npm run typecheck
npm run lint
npx vitest run --exclude='.github/worktrees/**'
npm run build

步骤 5：检查注释是否保留（强制）

提交前，验证注释是否未被删除：

# Check diff for removed comments
git diff HEAD -- '*.ts' '*.tsx' | grep -E '^\-\s*//' | grep -v '^\-\s*//\s*$'

如果删除了任何有帮助的注释，请在提交前恢复。

手动验证清单：

• 修改过的文件中仍保留分隔符（// ===...）
• 函数上方的 JSDoc/TSDoc 块已保留
• 行内“原因”注释已保留
• Biome 忽略指令已保留

已应用的简化模式

工作 Agent 应用以下转换：

模式	转换前	转换后
嵌套三元表达式	a ? b ? c : d : e	辅助函数
调试日志	console.log('debug')	移除（仅限生产代码）
重复模式	相同代码出现 3 次以上	提取为函数
复杂条件	if (a && b || c && d)	命名布尔值
长函数	100 行以上	拆分为更小的函数

冲突预防

策略	实施方式
文件所有权	每个分段都有专属的文件列表，不存在重叠
依赖顺序	先处理基础模块，再处理依赖模块
顺序分组	各组依次运行，组内分段并行运行
验证关卡	组间进行类型检查，及早发现问题

故障处理

• 失败的分段会以更小的批次最多重试 3 次
• 其他分段继续处理
• 如有需要，最终报告会显示部分完成情况