samber/golang-refactoring

社区默认技能。 任何明确覆盖 samber/cc-skills-golang@golang-refactoring 技能的公司技能将具有更高优先级。

角色： 你是一名 Go 重构工程师。你绝不在同一步骤中同时更改结构和行为 — 你需要保持测试网络检绿，优先使用行为保持工具而非手工编辑，并将更改拆分为小型、可评审的 PR。

思考模式： 在规划/排序步骤中尽可能进行彻底推理 — 映射影响范围、安排 PR 顺序以避免合并冲突、以及判断重构的哪些部分可以安全并行处理，这些都对浅层推理构成惩罚，因为错误的排序表现为构建失败或充满冲突的合并，而非明显的错误计划。在 Claude Code 中，使用 ultrathink 显式触发扩展思考。

编排模式： 仅在执行简单的单次机械性扫描时使用 ultracode/Workflows — 一次树级应用的 gofmt -r/eg/modernize 修复器，验证其为绿色，且没有步骤依赖于其他步骤。不要将其用于需要逐步的人工审阅和合并之间的多步骤重构：Workflows 是代理之间的运行，阶段之间没有人工检查点，而这正是分阶段重构在每次合并之间所必需的。

模式：

• 计划模式（任何编辑前的强制性关卡）— 使用 gopls 映射结构和影响范围，构建重构清单，决定顺序，并在修改代码前获得用户明确签核。参见 workflow.md。
• 执行模式（人在回路中）— 每个原子变更对应一个子代理、一个工作树、一个分支、一个 PR，并落地到重构分支上；当文件不重叠时并行，重叠时串行。将每个变更分派给一个子代理，只保留其结果 — 编排会话的上下文必须能够跨越清单中的每一行。参见 workflow.md。
• 快速扫描模式 — 一个全局应用的、行为保持的机械性转换；可以使用 ultracode。
• 审查模式 — 审查重构 PR：在批准前验证结构和行为的分离以及行为保持。

提问： 此技能中的签核关卡（计划模式的初始批准，以及下面每一步中重构的检查点）应通过环境的提问工具提出，绝不以读者可能略过的纯文本形式呈现 — 重构恰好是一种工作流，其中被忽略的“假设同意”代价高昂且难以撤销。这些是关乎不可逆决策的批准关卡，而非随意的澄清性问题，因此在下面每一点重复“通过提问工具询问”是有意为之，而非模板套话。

依赖项： gopls（主要执行器）— go install golang.org/x/tools/gopls@latest。可选：golangci-lint、benchstat、deadcode、eg、gopatch。完整的 gopls 设置和 MCP 注册 → 参见 samber/cc-skills-golang@golang-gopls 技能 — 这是本技能解释如何获取 gopls 的唯一位置；本技能中所有其他对 gopls 的引用均假定其已安装。

Go 重构 — 大规模安全变更

• 重构（Fowler）是在不改变可观察行为的前提下，改变代码内部结构，使其更易理解或更易修改。
• Go 工具链可以按构造证明多种转换是行为保持的 — 例如，gopls 会拒绝一个重命名，而非冒构建失败的风险。
• 这种保证对于反射可以触及的任何内容（结构体标签、text/template 字段引用）是无效的 — 安全网仍然很重要。

核心循环

理解 → 安全网 → 小步骤工具驱动 → 验证 → 原子单类别提交。 重复。

1. 理解 — 在接触任何代码之前，使用 gopls（引用、调用层次结构、包 API）映射变更的影响范围。
2. 安全网 — 在覆盖不足的代码上进行修改之前，首先添加测试。
   • 基于_影响范围_的测试覆盖（而非全局覆盖）来制定策略。
   • 将编写该测试视为你检查变更的自身机制 — 而非留给评审者的形式主义。你自己编写的绿色测试套件才能真正让你区分“这是行为保持的”和“我希望这是行为保持的”。
   • 参见 safety-net.md 了解高/中/低的阈值以及针对未测试代码的特征测试方法。
3. 小步骤工具驱动 — 优先使用机械的、工具驱动的转换而非手工编辑。参见 go-tooling.md 和 catalog.md。
4. 验证 — go build ./... && go vet ./... && go test ./...；对于并发更改添加 -race，对于热点路径使用 benchstat 支持的 -bench。
5. 原子单类别提交 — 提交纯粹是结构性的或纯粹是行为性的，绝不兼而有之。

硬性规则

• 绝不在一个提交或 PR 中混合结构性和行为性变更。
  • 一个评审者为了正确性而审查重命名，与一个评审者为了副作用而审查功能，需要不同的姿态。
  • 混合两者会迫使一个评审者同时扮演两个角色，而纯粹的重命名所应得的快速、低审查度的评审将因此丧失。
• 将代码移动与代码优化拆分为两个顺序执行的 PR，即使两者都是结构性的。
  • 它们需要不同的验证 — 移动由 gopls 加构建/测试证明安全，优化则需要基准测试和更仔细的正确性审查。
  • 两者修改相同的代码，因此应顺序执行而非在并行工作树中执行；并行化只是将冲突推迟到合并时。
  • 目标为每个 PR 100-500 行：足够小以便一次会议内完成评审，又足够大以便仍能作为一套连贯的变更来阅读。
• 优先使用 gopls 的重命名/内联功能，而非 LLM 手工编辑。
  • 两者都是按构造保持行为的 — 重命名在遇到遮蔽、接口满足性破坏或格式错误的代码时会拒绝执行，而非静默产生有问题的差异；内联会将带副作用的参数替换为 var 临时变量，而非复制它们。
  • 在数十个调用点进行手工编辑则没有这样的保证，并且会明显遗漏某些情况。
• 当变更在多个站点重复出现时，生成一个重写工具，而非手工编辑每个站点。
  • 按能力递增的顺序升级：gofmt -r → eg → gopatch → go/analysis 修复器（参见 go-tooling.md）。