Agent Skills 工程化实践 11：让代码更好改，也让 diff 与冲突更容易审

质量不是最后一轮 lint

Agent 可以快速增加代码，也会快速增加 interface、configuration 与跨文件 knowledge。真正的质量控制必须贯穿三个位置：设计 module shape、定期发现 architecture friction、用稳定 fixed point 审阅 diff。冲突发生时，还要能从双方 primary source 恢复 intent。

这四个 Skills 分别守住这些位置，并且不会互相替代。

codebase-design：给模块形状一套精确语言

触发方式：Model-invoked。 当你在设计 interface、寻找 seam、提升 testability 或讨论 architecture：

请用 codebase-design 评估支付计算模块：interface 是否过宽，variation 应该放在哪个 seam，测试能否只通过 public interface 完成。

它要求一致使用 module、interface、implementation、depth、seam、adapter、leverage 与 locality。重点不是发明更多 abstraction，而是形成 deep module：调用者只需理解小 interface，却能获得大量 behavior。

两个实用检查：deletion test 看移除 module 后 complexity 是消失还是只是散回 callers；interface is the test surface 看真实 behavior 能否通过 interface 被验证。如果为了测试必须穿透 private details，通常说明 seam 位置不对。

上游 Skill：codebase-design

improve-codebase-architecture：先 survey，再由人选 candidate

触发方式：User-invoked。 适合周期性 architecture health check：

/improve-codebase-architecture

它读取 domain model 与代码，寻找 deepening opportunities，生成 visual HTML report，再让人选择一个 candidate 进入 grilling。报告应该展示 Before/After、interface friction、预期 leverage 与风险，但在用户选择前不应该开始重构。

它是 survey，不是 legacy rescue。老系统里发现十个问题，不代表一次 session 应该修十个；候选项的价值是让团队选择下一项最有 leverage 的改善。频繁运行也不等于频繁改架构，很多时候正确结论是“当前没有值得支付迁移成本的 candidate”。

上游 Skill：improve-codebase-architecture

code-review：固定一个点，分开两个轴

触发方式：Model-invoked。 用户要求 review branch、PR、WIP 或“review since X”时使用：

请用 code-review 审查从 main 到 HEAD 的变化，spec 是 #128。

输入必须包含 fixed point：commit、branch、tag 或 merge-base。Skill 分别运行两个 parallel reviews：

• Standards：是否符合 repo documented standards，并以常见 Fowler smells 为 baseline；
• Spec：是否忠实实现 originating issue/spec，有没有遗漏或 scope creep。

两个轴必须分开，因为“写得漂亮但做错需求”和“功能正确但结构失控”是不同失败。发现问题后，修复并 commit，再针对同一个 fixed point 重跑；不要把 HEAD^ 当成长期 fixed point，否则每次新增 commit 都会缩小审阅范围。

完成标准： finding 指向具体证据和影响；无法确认的 spec 不是由 reviewer 猜测；最终没有 actionable findings，且完整 diff 从固定点到当前 HEAD 都被覆盖。

上游 Skill：code-review

resolving-merge-conflicts：按 intent 解决，不按“选左选右”解决

触发方式：Model-invoked。 只在 merge 或 rebase 已经处于 conflict state 时使用：

请用 resolving-merge-conflicts 继续当前 rebase，逐个 hunk 追溯双方 intent，并完成 rebase。

它先读取 git state 与 history，再为每个 conflict 找 primary sources：commit message、PR、issue、spec 和相关 tests。能同时保留双方 intent 时合并；确实不兼容时，选择符合当前 merge goal 的一方，并记录 trade-off。不要为了让标记消失而发明第三种 behavior。

解决后要运行项目真实 checks，stage，并把 merge/rebase 完成到底。Skill 明确要求 never --abort，但这不是授权它忽略风险；如果 primary sources 不足，应停下来向人确认 intent，而不是把 syntax resolution 当成 semantic resolution。

上游 Skill：resolving-merge-conflicts

把四个动作放回正确时间

设计或改变 module      → codebase-design
周期性寻找高价值改善    → /improve-codebase-architecture
实现形成稳定 diff 后     → code-review <fixed-point>
已经进入 merge conflict → resolving-merge-conflicts

质量不是统一的“再检查一下”。设计 vocabulary、architecture survey、diff review 与 conflict resolution 各自需要不同证据。把它们混成一次泛化 review，最后得到的往往只是很多意见，没有可靠门禁。

来源与版本

• 上游参考：README Reference
• 参考分支：main · 核验 commit：8b78b53 · 核验日期：2026-08-14