Go 代码大规模安全重构：在保持行为不变的前提下重命名…

当 Go 函数或类型过大、代码异味阻碍新功能、需要大规模重命名/提取函数或接口/跨包移动代码，或规划多步重构时，用工具驱动的小步重构安全地改变结构而不改变行为。

适用场景

解决思路

1. 遵循核心循环：理解 → 安全网 → 小的工具驱动步骤 → 验证 → 原子化单一类别提交，然后重复。
2. 理解阶段：在动任何代码前，用 gopls 映射改动的爆炸半径（引用、调用层级、包 API）。
3. 安全网阶段：在覆盖率不足的代码上动手前先补测试；以爆炸半径的测试覆盖率（而非全局覆盖率）决定策略；把写测试当作自己验证改动的手段，而不是留给评审的形式；参考 safety-net.md 的 HIGH/MEDIUM/LOW 阈值与未测试代码的特征化测试配方。
4. 小步工具驱动：优先使用机械化的工具变换而非手工编辑；参考 go-tooling.md 与 catalog.md。
5. 验证阶段：运行 `go build ./... && go vet ./... && go test ./...`；并发改动加 `-race`；热路径用 `benchstat` 支撑的 `-bench`。
6. 原子化单一类别提交：提交要么纯结构性、要么纯行为性，绝不混合。
7. 绝不把结构改动和行为改动混在同一个 commit 或 PR 中——审查重命名正确性和审查功能副作用需要不同姿态。
8. 把代码移动和代码优化拆成两个顺序 PR，即使两者都是结构性的：移动靠 gopls 加构建/测试证明安全，优化需要基准测试和更严格的正确性审查；它们改同一片代码，所以顺序执行而非并行 worktree；每个 PR 目标 100–500 行。
9. 优先用 gopls Rename/Inline 而非 LLM 手工编辑：两者按构造保持行为不变（Rename 在遮蔽、接口满足破坏或代码畸形时拒绝执行；Inline 把带副作用的参数替换为 `# 临时变量而非重复求值）；手工编辑没有这种保证且会漏改。
10. 当改动在许多位置重复出现时，生成重写工具而非逐处手工编辑：按能力递增依次升级 `gofmt -r` → `eg` → `gopatch` → `go/analysis` fixer；生成的工具可审查、可重跑、可用 golden 文件测试。
11. 跨包移动类型时使用类型别名（`type A = B`）：这是官方认可的渐进式代码修复机制，新旧名字可互换，调用方可增量迁移，无需某个 commit 一次改完所有调用点。
12. 打破导入循环时优先使用消费方接口，再考虑拆包或共享叶子包：Go 隐式解析接口，生产方包无需导入消费方的接口，是最便宜、最精准的修复。
13. 在以下情况前暂停并取得人工签字确认：任何跨包移动或拆包、任何导出 API 变更或弃用、任何删除、引入新主版本、或即将改动的代码没有测试。
14. 任何重命名后 grep 结构体标签和反射引用：gopls Rename 只防编译破坏，看不到 struct tag、`text/template` 字段引用或 `reflect` 驱动的分发；重命名字段会静默地使其与 `json`/`db` 标签失同步。
15. 当某一步改变代码逻辑（而非仅形状）时，加载 `samber/cc-skills-golang@golang-security`（内部正确性风险再加 `golang-safety`）：机械的、工具验证的变换不会引入漏洞，但行为改动会；把“改变代码行为”当作安全与安全审查的触发条件。
16. 每一步都从干净、已提交的基线开始；变红时回退而不是向前调试：若某机械步骤导致 `go test` 变红，回退到上一个绿色 commit 重试比在不再完全信任的状态里向前打补丁更快更安全；步骤一变绿就立即提交，再开始下一步。
17. 按风险分层决定安全要求：低风险（gopls Rename、Extract Variable/Constant、Inline Variable、`gofmt -s`、整理 import、本地 `refactor.rewrite.*`）步骤后构建/vet/测试即可；中风险（Extract Function/Method、跨包 Inline Call、单参数增删、引入泛型）先补或确认爆炸半径内的针对性测试；高风险（跨多调用方改签名、跨包移动类型/函数、拆包/合包、打破导入循环、导出 API 或主版本变更）需完整安全网加落地前人工检查点。
18. 诊断规则：gopls 拒绝 Rename 或 Inline 是真实的语义危险而非工具 bug，先调查遮蔽/接口冲突再考虑手工强改；`go vet ./...` / `golangci-lint run` 报出新问题先修复再提交，不要中途累积 lint 债；`go test -race ./...` 报任何竞态就停下，并发行为已变；`benchstat old.txt new.txt` 在热路径上不是 `~` 就停下并回退或优化，性能回退的“重构”就是行为改变；用 `-coverpkg=./...` 对改动包跑 `go tool cover -func`，作为决定能多激进推进的策略门。
19. 多步重构按 Plan → Stage → Land 执行：先进入 Plan 模式（强制门），用 gopls 映射结构与爆炸半径、建立重构清单、决定顺序，并在动代码前取得用户明确签字；参考 workflow.md。
20. Execute 模式（人在环中）：每个原子改动一个子代理、一个 worktree、一个分支、一个 PR，落在重构分支上；文件不相交时并行，重叠时顺序执行；把每个改动派发给子代理并只保留其结果，以保护编排会话的上下文。
21. Simple-sweep 模式：单一机械、保持行为的变换全树应用，可用 `ultracode`。
22. Review 模式：审查重构 PR 时，在批准前验证结构/行为分离与行为保持。
23. 所有签字门（Plan 模式初始批准及重构中每个检查点）都通过环境的提问工具询问，绝不用纯文本散文，以免被略过。
24. 多步重构前阅读 workflow.md 掌握完整编排：规划门与重构清单、三种相互作用的排序（结构先于行为、冲突避免、依赖顺序）、`refactor/<topic>` 分支与每改动 worktree/PR 的 git 模型、何时并行何时顺序、`// REFACTOR(step N): ...` 标记约定，以及为何 Workflows/`ultracode` 不适合此任务。
25. 仅在简单的单遍机械清扫（一个 `gofmt -r`/`eg`/`modernize` fixer 全树应用、验证绿色、无步骤相互依赖）时使用 `ultracode`/Workflows；多步重构需要每次合并之间渐进式人工审查，不要用 Workflows。

适用边界 · 注意事项

• 代码能正常工作且没有计划中的改动会再触及它——稳定、少读的包为自身而重构没有收益。
• 没有测试的关键生产代码——不要直接重构；先建立特征化测试基线并取得明确签字，关键路径上此门不可协商。
• 截止日期紧张时——分阶段、人工审查的重构需要每个 PR 之间的审查带宽，时间压力下要么停滞要么跳过审查纪律；先做最小安全改动，把大重构留到有余地时。
• 没有明确目的时——“重构这个”背后没有即将到来的功能、要关闭的 bug 类别或评审实际指出的异味，就是为重构而重构；在规划门签字时确认目的。