code-quality

代码质量

通过评审、重构和调试，并设置验证关卡，系统性地改进代码。

模块选择

需求	模块	参考资料
接收反馈	评审	references/code-review-reception.md
请求评审	评审	references/requesting-code-review.md
声明前先验证	评审	references/verification-before-completion.md
降低复杂度	重构	references/oop-refactoring-catalog.md
函数式模式	重构	references/functional-refactoring-patterns.md
查找代码异味	重构	references/code-smells-reference.md
测试策略	重构	references/testing-strategies.md
调查 Bug	调试	references/systematic-debugging.md
追踪根本原因	调试	references/root-cause-tracing.md
添加验证	调试	references/defense-in-depth.md
验证修复	调试	references/verification.md

---

核心原则

YAGNI、KISS、DRY——始终遵循这些原则。

保持诚实、直言不讳、开门见山、简明扼要。

技术正确性高于社交舒适度。 实施前先验证。先询问，不要臆测。先有证据，再下结论。

---

代码评审

接收反馈

模式： 阅读 → 理解 → 验证 → 评估 → 回复 → 实施

规则：

• ❌ 不要敷衍附和（“你说得对！”、“好建议！”）
• ❌ 未经验证，不要实施
• ✅ 重述需求、提出问题，并给出理由进行反驳
• ✅ 检查 YAGNI：实施建议前先用 grep 查找用法

来源：

• 人类协作者 → 理解后再实施
• 外部评审者 → 技术验证后再实施

请求评审

时机： 重大功能完成后、合并前、复杂修复后

流程：

1. 获取 SHA：BASE_SHA=$(git rev-parse HEAD~1)、HEAD_SHA=$(git rev-parse HEAD)
2. 运行 /code-review，并传入：WHAT、PLAN、SHA、DESCRIPTION
3. 立即修复 Critical，继续之前修复 Important，并记录 Minor

验证关卡

只有在本次会话中运行了能够证明结果的命令并阅读其输出后，才能声明结果；没有证据的声明只是猜测。

关卡： 确认 → 运行 → 阅读 → 验证 → 然后声明

评审发现（你自己或子 Agent 的发现）在报告前还需通过以下四项检查：

1. 防护： 指明你在同一条执行路径上搜索过的防护，并说明它为何无法阻止该 Bug。
2. 意图： 在 .okf/ 和其他项目文档中搜索相关行为。若文档表明这是预期行为，则这是一个策略问题，而不是 Bug。
3. 起因： 归咎于某次提交前，运行 git log -S 或 git show <sha>^:<file>。不要根据提交说明推断过去的行为。
4. 行号： 引用你从文件中读到的行号，而不是 Agent 摘要中的行号。

---

重构

思路

持续简化。严格保留行为。衡量一切。

每次重构都应小而安全，立即测试，并能衡量其改进效果。

流程

1. 评估——建立基线指标，识别代码异味，分类技术债务
2. 安全网——确认测试覆盖率，添加特征化测试
3. 红—绿—重构——编写失败的测试，实现最小通过方案，改进设计
4. 应用模式——SOLID、设计模式、函数式转换
5. 验证——衡量改进，确认行为保持不变

代码异味（5 类）

1. 臃肿类： 过长方法、过大类、参数列表过长
2. 面向对象滥用： Switch 语句、临时字段
3. 修改阻碍因素： 发散式修改、霰弹式修改
4. 可有可无项： 重复代码、死代码、懒惰类
5. 耦合项： 特性依恋、不恰当亲密关系

常用模式

面向对象： 提取方法、内联、用查询替换临时变量、守卫子句
函数式： Map/Filter/Reduce、纯函数、组合、不可变性

---

调试

核心原则

未经根因调查，绝不修复

随意修复会浪费时间，还会引入新 Bug。

四种技巧

1. 系统化调试（references/systematic-debugging.md）

• 阶段 1：根因调查
• 阶段 2：模式分析
• 阶段 3：假设测试
• 阶段 4：实施

2. 根因追踪（references/root-cause-tracing.md） 沿调用栈向上追踪，找出最初的触发原因。

3. 深度防御（references/defense-in-depth.md） 在每一层进行验证：入口 → 业务逻辑 → 环境 → 调试

4. 验证（references/verification.md） 运行命令。阅读输出。然后再声称结果。

快速参考

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md
  Found root cause? → defense-in-depth.md
  About to claim success? → verification.md

警示信号

如果你在想以下这些话，请停下来：

• “先快速修复，之后再调查”
• “先改改 X 试试看”
• “大概是 X，我来修一下”
• “现在应该可以了” / “看起来修好了”

---

参考资料

代码审查

• references/code-review-reception.md - 响应流程
• references/requesting-code-review.md - 请求流程
• references/verification-before-completion.md - 验证关卡

重构

• references/oop-refactoring-catalog.md - Martin Fowler 的模式
• references/functional-refactoring-patterns.md - FP 转换
• references/code-smells-reference.md - 23 种代码异味，分为 5 类
• references/testing-strategies.md - 特征测试、TDD

调试

• references/systematic-debugging.md - 四阶段框架
• references/root-cause-tracing.md - 调用栈分析
• references/defense-in-depth.md - 多层验证
• references/verification.md - 验证流程

---

核心要点

1. 审查： 技术严谨性优先于社交表现
2. 重构： 小步、安全、经过测试、可衡量
3. 调试： 先找根因，一次修复到位
4. 始终： 先有证据，再做断言

先验证，再质疑，然后实施。先有证据，再做断言。