kamae-review

Kamae 代码审查

依据 kamae 原则进行对抗式审查。知识库位于 ../kamae/；此技能会链接到知识库，而非重复其内容。

步骤 0：加载适用规则

在执行任何其他步骤之前，按优先级顺序使用 glob 查找并读取规则：

1. .claude/rules/*.md（工作树根目录下的项目级覆盖规则）
2. ~/.claude/rules/*.md（用户全局偏好）
3. 相对于此 SKILL.md 的 ../../rules/defaults/*.md（插件默认规则）

对于每个文件：

• 读取 YAML frontmatter。如果 applies-to 不是 kamae-review 或 *，则跳过该规则。
• 按 name 分组。对于每个 name，只保留优先级最高的实例（1 > 2 > 3）；同一优先级内，保留文件名按字典序排序最后的实例。
• enabled: false 的 check-toggle 规则会从下方步骤 3 的检查流程中移除指定检查项。
• convention 规则会设定审查所遵循的项目特定预期（例如，Branded Types 的指定存放位置）。

如果未找到规则，则启用所有检查并继续。规则格式请参阅 ../../rules/README.md。

审查流程

1. 加载原则知识。 在阅读任何待审查代码之前，先阅读：

   • ../kamae/SKILL.md — 原则索引
   • 与项目 package.json 对应的验证库指南，位于 ../kamae/validation-libraries/（zod.md / valibot.md / arktype.md）
   • 与项目 package.json 对应的 Result 库指南，位于 ../kamae/result-libraries/（neverthrow.md / byethrow.md / fp-ts.md / option-t.md）
   • 所阅读的清单子文件所引用的 ../kamae/ 下的每个主题文件。

2. 阅读待审查文件。

3. 逐项检查清单。 按顺序阅读每个清单子文件，并将发现的问题对应到其条目。

   • checklist/domain-modeling.md — 判别联合、伴生对象、Branded Types、文件结构、领域拥有的端口、分开的单操作解析器／存储（条目 1.x）
   • checklist/state-transitions.md — 纯状态转换、穷尽性（条目 2.x）
   • checklist/error-handling.md — Result 类型、错误边界分类、DU 错误类型（条目 3.x）
   • checklist/boundary.md — 架构验证、不使用 as 断言、从架构派生类型（条目 4.1、4.2、4.4）
   • checklist/pii-protection.md — 对 PII 使用 Sensitive<T>（条目 4.3）
   • checklist/declarative-and-tests.md — 数组操作、事件、测试夹具（条目 5.x、6.x）

4. 报告发现的问题。 对于每项违规：

   1. 位置（path:line）。
   2. 问题所在 — 引用相关原则（链接至 ../kamae/...），并说明违反原则的风险。
   3. 修复方法 — 提供展示修正版本的代码示例。

5. 建议（非违规但仍有改进空间的事项）采用相同格式说明，并明确标注为建议，而非发现的问题。

严重程度分类

每个清单条目都标记为高／中／低。

• 高 — 直接导致运行时错误或合规违规（as、缺少 PII 保护、缺少架构验证、语义不同的原始类型缺少 Branded Types）。
• 中 — 无效状态表示、错误处理不一致、缺少穷尽性检查、包含所有类型的文件、将类用于领域模型、领域契约与基础设施类型耦合。
• 低 — 风格、可读性、边界情况正确性（方法表示法、领域类型使用 interface、缺少 Readonly<>、非 kind 判别字段、命令式数组循环、测试夹具未使用 as const satisfies、架构与类型重复匹配、端口位置不当但没有向外部的依赖、不必要地扩大依赖契约）。现有的架构／类型不匹配问题，应根据其错误接受、拒绝或数据暴露的影响提出。

Example Finding

### Use of method notation

`src/domain/task/task-store.ts:15`

`save(task: Task): Promise<void>` uses method notation. Per
[`../kamae/SKILL.md` §1 "Use function property notation"](../kamae/SKILL.md),
parameters become bivariant under method notation, so a narrower implementation
such as `save(task: DoingTask): Promise<void>` will pass type checking at the
injection site.

Suggested fix:
\`\`\`typescript
type TaskStore = {
  save: (task: Task) => Promise<void>;
};
\`\`\`