explain-code

解释代码

工作流

1. 先用类比开场 — 将代码比作日常生活中的事物
2. 选择合适的 C4 层级 — 根据问题确定图表的详细程度；默认使用第 2 级（容器）
3. 绘制图表 — 直接在回复中以 ASCII 方框图呈现（不使用外部工具）。按照第 2 步选择 C4 层级，然后用普通字符（+ - | v ^ <- ->）绘制方框和箭头，将每行控制在约 80 列以内，方便在终端或聊天窗口中阅读。每个方框标注组件名称（如果放得下，再加上一行职责说明），箭头标注沿其流动的操作或事件。
4. 逐步讲解代码 — 以叙述形式追踪输入到输出的过程：什么内容进入、依次经过哪些函数或模块、状态在哪里变化、什么内容输出。指出具体数据，而不只是描述步骤。
5. 指出一个易错点 — 常见的错误或误解是什么？

讲解时保持对话式风格。对于复杂概念，可以使用多个类比。

示例输出形式

单个函数

类比： debounce 就像贪睡按钮——只有等你不再按它时，才会延迟执行操作。

逐步讲解： 调用开始计时器（setTimeout）。如果计时器触发前再次调用，就会清除计时器并重新启动（clearTimeout）。计时器触发 → 回调执行一次。

易错点： 返回的函数通过闭包捕获了 timer——每个调用位置都需要自己的 debounce(fn, ms) 实例，否则它们会共用同一个计时器。

多类系统

类比： 这个身份验证服务就像俱乐部的门卫——先检查你的身份证件（令牌），再让你进入任何房间（端点）。

+--------+   token    +----------------+   validate   +-------------+
| 客户端 | ---------> | AuthMiddleware | -----------> | TokenCache  |
+--------+            +----------------+              +-------------+
                               |  claims
                               v
                       +---------------+
                       |  UserService  |
                       +---------------+
                               |  user record / UnauthorizedError
                               v
                       +---------------+
                       |   Endpoint    |
                       +---------------+

逐步讲解： 请求到达 HTTP 适配器 → AuthMiddleware 验证 JWT → 解码后的声明传递给 UserService.resolve() → 返回用户记录或抛出 UnauthorizedError。

易错点： AuthMiddleware 本身无状态，但依赖 TokenCache——如果缓存未命中，每个请求都会访问数据库。

多服务架构

类比： 这条结账流水线就像一场接力赛——每项服务都要先将接力棒（订单事件）传给下一棒，才能继续执行。

+---------------+  order.created   +------------------+  stock.reserved   +-----------------+
| OrderService  | ---------------> | InventoryService | -----------------> | PaymentService  |
+---------------+                  +------------------+                    +-----------------+
       ^                                    |                                      |
       | compensating event (on failure)    |                                      | payment.captured
       +------------------------------------+                                      v
                                                                         +----------------------+
                                                                         | NotificationService  |
                                                                         +----------------------+

演练流程： OrderService 向消息总线发出 order.created → InventoryService 预留库存并发出 stock.reserved → PaymentService 扣款并发出 payment.captured → NotificationService 发送确认邮件。任何步骤失败时，都会发出补偿事件以回滚上游操作。

注意事项： 每项服务都可独立部署，但 Saga 没有中央协调器——要调试失败的订单，需要跨 4 项服务的日志追踪关联 ID。

---

基准测试

场景：.benchmarks/scenarios/explain-code-001-worker-walkthrough.md · 运行：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/explain-code-001-worker-walkthrough.json

Model	不使用	使用	变化
claude-opus-4-8	50%	100%	+50%
claude-sonnet-4-6	50%	100%	+50%
claude-haiku-4-5	50%	100%	+50%

通过（运行于 2026-08-31）。一致提升 +50——这是本轮中最低值提升幅度最大的一次。门槛见 .agents/skills/skill-optimizer/rules/release-gates.md。