build-fix

/build-fix

内容

工具包的自主迭代循环技能。它通过循环执行、解析失败、按根因分类、应用针对性修复并重新运行，让构建失败的 dotnet build （或测试失败的 dotnet test）通过。循环会持续进行，直到构建通过或触发保护机制——就像经验丰富的开发者处理一片错误时那样，但设有严格限制，避免反复折腾。

这不是一次性修复。它能处理级联错误，即修复一个问题后又暴露出下一个问题的情况。

适用场景

• 构建失败，且存在多个编译器错误
• 代码更改或构建修复后，测试失败
• 大规模重构涉及类型名称、命名空间或签名之后
• 更新 NuGet 包之后（尤其是主版本升级）
• 合并分支并解决冲突，但尚未编译之后
• 搭建框架或生成代码后，仍需手动调整
• 用户说：“修复构建”“让它编译通过”“让测试通过”“继续尝试，直到成功”“继续修复”

工作方式

循环纪律（适用于每次循环）

1. 始终限制迭代次数——默认最多 5 次，硬上限为 10 次 （用户要求“继续尝试”时可增加 3 次，但绝不超过 10 次）。如果 5 次迭代仍无法解决，问题需要人工判断，而不是再做第 6 次相同的尝试。
2. 有进展，否则退出——每次迭代都必须减少错误或失败的数量。 修复后错误仍相同 = 卡住：停止、报告，并重新规划，采用不同方法。绝不重试已经失败的相同修复。
3. 先分类，再修复——按根因对错误分组，优先修复影响最大的错误（一个缺失的 using 就可能消除十几个后续错误）。
4. 逐次迭代保持透明——报告更改内容和原因： Iteration 3/5: fixed CS0246 by adding using System.Text.Json, 2 remain。 绝不默默修改文件。
5. 原子性——每次迭代结束时，代码库的状态不得比迭代开始时更差。 如果第 3 次迭代失败，代码应保持在第 2 次迭代后的状态。

主要流程：构建修复循环（最多 5 次迭代）

1. 构建——运行 dotnet build，捕获完整错误输出

2. 解析——提取每个 error CS####，包括文件、行号和消息

3. 分类——按根因分组：

   类别	错误代码	修复策略
   缺少 using 或引用	CS0246、CS0234	添加 using、包或项目引用
   类型不匹配	CS0029、CS1503	检查预期类型，进行强制转换或转换
   API 变更	CS0117、CS7036	检查新签名，更新调用位置
   可空性	CS8600–CS8604	添加空值检查、?. 或 ??
   歧义或重复	CS0104、CS0121、CS0111	限定命名空间，移除重复项
   缺少成员	CS1061	检查拼写，确认成员存在
   缺少实现	CS0535	实现接口或抽象成员
   过时的 API	CS0618	替换为推荐的替代方案

4. 修复——应用针对性修复，优先处理根因明确或影响最大的错误

5. 重新构建——再次运行 dotnet build，比较错误数量

6. 评估——错误为零：运行 dotnet test 进行完整性检查，并报告成功。错误减少：继续。错误相同：卡住——退出并重新规划。错误增多：回滚本次迭代，并报告回归。

变体：测试修复循环（最多 5 次；如果紧接构建修复循环，则最多 3 次）

采用相同的循环和保护机制，运行命令改为 dotnet test --no-build，并增加一个关键步骤——先诊断，再修复：

1. 阅读测试——理解断言和测试设置
2. 阅读生产代码——理解实际行为
3. 判断错误所在：预期错误 → 修复测试；生产代码有缺陷 → 修复代码；测试设置不完整 → 修复设置；契约已变更 → 更新测试以匹配
4. 绝不通过弱化断言来让测试通过。 错误做法：Assert.Equal(expected, actual) → Assert.NotNull(actual)。 正确做法：修复生产代码，让原始断言通过。

安全保护措施（立即退出）

• 卡住 — 修复后仍出现相同错误／失败，或计数反复波动 （3 → 2 → 3）：报告无法修复的问题，以及需要人工检查的内容
• 回归 — 某次迭代引入的错误多于修复的错误：还原 该迭代的更改并报告
• 级联失败 — 连续两次修复一个错误时都会引发 3 个或更多新错误：方法有误，停止
• 严重错误 — SDK 错误、缺少项目文件、解决方案损坏， 或测试运行器本身发生故障：需要人工介入，停止
• 用户中断 — 完成当前迭代，报告进度，并询问如何继续

其他循环

同样的准则——限制迭代次数、检测进度、设置安全保护措施——也适用于重构流程（/de-sloppify：针对每个目标验证构建和测试，失败时还原）和脚手架搭建（/scaffold：生成后，运行嵌套的构建修复循环和测试修复循环）。嵌套循环使用较小的预算（父级 5 → 嵌套 3），最大嵌套深度为 2，总预算为 15。

调用项

类型	名称	用途
技能	instinct-system	在 MEMORY.md 中记录修复模式
Agent	dotnet-architect	用于咨询架构错误模式

使用的 MCP 工具

• get_diagnostics — 获取限定到文件或项目的编译器错误／警告
• find_symbol — 定位已移动或重命名的类型
• find_references — 评估已损坏 API 更改的影响范围
• get_project_graph — 确定修复引用错误的依赖顺序

示例

User: /build-fix

Claude: Running dotnet build...
  Found 12 errors across 4 files.

  Iteration 1/5:
  - 6 errors: Missing namespace (CS0246) — adding using directives
  - 3 errors: Type mismatch (CS1503) — updating method signatures
  - 3 errors: Interface not implemented (CS0738) — package API changed

  Rebuilding... 3 errors remaining.

  Iteration 2/5:
  - 3 errors: CS0738 after xunit.v3 upgrade
    - IAsyncLifetime.InitializeAsync now returns ValueTask (was Task in v2),
      and DisposeAsync comes from IAsyncDisposable
    - Updating 3 test fixtures to the ValueTask signatures

  Rebuilding... 0 errors. Build is green.

  Running dotnet test... All 47 tests passed.
  Added to Memory > Packages: "xunit.v3 IAsyncLifetime uses ValueTask signatures"

相关内容

• /verify — 完整验证流程（构建 + 测试 + 格式检查 + 诊断）
• /tdd — 以测试优先的方式构建新功能时，执行红－绿－重构
• /de-sloppify — 构建通过后，清理代码质量问题