来源: everything-claude-code by Affaan Mustafa 原始文件: agents/build-error-resolver.md + commands/build-fix.md
构建错误修复（Build Error Resolution）
概述
一套专注于以最小改动修复构建和类型错误的工作流。核心原则是"修复错误、验证构建通过、继续前进"，不做重构、不改架构、不加新功能。支持多语言项目的构建系统检测和错误修复。
---|----------|
| implicitly has 'any' type | 添加类型注解 |
| Object is possibly 'undefined' | 可选链 ?. 或空值检查 |
| Property does not exist | 添加到接口（Interface）或使用可选属性 ? |
| Cannot find module | 检查 tsconfig 路径、安装包或修复导入路径 |
| Type 'X' not assignable to 'Y' | 解析/转换类型或修复类型定义 |
| Generic constraint | 添加 extends { ... } |
| Hook called conditionally | 将 Hook 移到顶层 |
| 'await' outside async | 添加 async 关键字 |
二、构建修复命令（Command）
增量修复构建和类型错误，使用最小、安全的改动
第 1 步：检测构建系统
识别项目的构建工具并运行构建：
| 标识 | 构建命令 |
|---|---|
package.json 含 build 脚本 |
npm run build 或 pnpm build |
tsconfig.json（仅 TypeScript） |
npx tsc --noEmit |
Cargo.toml |
cargo build 2>&1 |
pom.xml |
mvn compile |
build.gradle |
./gradlew compileJava |
go.mod |
go build ./... |
pyproject.toml |
python -m py_compile 或 mypy . |
第 2 步：解析和分组错误
- 运行构建命令并捕获标准错误输出（stderr）
- 按文件路径分组错误
- 按依赖顺序排序（先修复导入/类型，再修复逻辑错误）
- 统计错误总数以跟踪进度
第 3 步：修复循环（每次修一个错误）
对每个错误：
- 读取文件 -- 使用 Read 工具查看错误上下文（错误周围 10 行）
- 诊断 -- 识别根本原因（缺失导入、错误类型、语法错误）
- 最小修复 -- 使用 Edit 工具进行能解决错误的最小改动
- 重新运行构建 -- 验证错误已消除且无新错误引入
- 继续下一个 -- 处理剩余错误
第 4 步：安全护栏
在以下情况下停止并询问用户：
- 某个修复引入了比它解决的更多的错误
- 同一个错误在 3 次尝试后仍然存在（可能是更深层的问题）
- 修复需要架构层面的改动（不仅仅是构建修复）
- 构建错误源于缺失的依赖（需要
npm install、cargo add等）
第 5 步：总结
展示结果：
- 已修复的错误（附文件路径）
- 剩余的错误（如有）
- 新引入的错误（应为零）
- 对未解决问题的建议后续步骤
三、应做与不应做
应做（DO）
- 在缺失处添加类型注解
- 在需要时添加空值检查
- 修复导入/导出
- 添加缺失的依赖
- 更新类型定义
- 修复配置文件
不应做（DON'T）
- 重构不相关的代码
- 改变架构
- 重命名变量（除非导致错误）
- 添加新功能
- 改变逻辑流程（除非修复错误）
- 优化性能或风格
四、恢复策略
| 情况 | 操作 |
|---|---|
| 缺少模块/导入 | 检查包是否已安装；建议安装命令 |
| 类型不匹配 | 读取两个类型定义；修复更窄的类型 |
| 循环依赖 | 用导入图识别循环；建议提取公共模块 |
| 版本冲突 | 检查 package.json / Cargo.toml 的版本约束 |
| 构建工具配置错误 | 读取配置文件；与正常工作的默认配置对比 |
终极恢复手段
# 终极选项：清除所有缓存
rm -rf .next node_modules/.cache && npm run build
# 重新安装依赖
rm -rf node_modules package-lock.json && npm install
# 修复 ESLint 可自动修复的问题
npx eslint . --fix
五、优先级
| 级别 | 症状 | 操作 |
|---|---|---|
| CRITICAL（严重） | 构建完全中断，无开发服务器 | 立即修复 |
| HIGH（高） | 单个文件失败，新代码类型错误 | 尽快修复 |
| MEDIUM（中） | 代码检查警告，已弃用的 API | 有空时修复 |
六、成功指标
npx tsc --noEmit以代码 0 退出npm run build成功完成- 未引入新错误
- 最小行数变更（< 受影响文件的 5%）
- 测试仍然通过
七、不适用场景
- 代码需要重构 -> 使用
refactor-cleaner - 需要架构改动 -> 使用
architect - 需要新功能 -> 使用
planner - 测试失败 -> 使用
tdd-guide - 安全问题 -> 使用
security-reviewer
记住：修复错误、验证构建通过、继续前进。速度和精准胜过完美。