ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: 在编写或修改代码时使用，在标记任务完成之前，每当更改添加了导出或可导入的名称、创建了模块、类、组件、辅助函数、hook、服务或包装器，或集中重复代码时使用。构建深度模块的作者时间检查清单：命名决策所隐藏的边界，通过深度和不变量测试，修复问题而非迁移问题，绝不单凭大小拆分，并以简短的设计说明结束。是 ousterhout-quality-program 的简明伴侣，后者仍是完整的审查视角。
---

# 深度构建（Ousterhout，作者时间）

你是在写代码，而不是审查代码。在你称任务完成之前，先在你自己的改动上运行它。

## 1. 门槛

这个改动是否添加了一个导出/可导入的名称，创建了一个模块、类、组件、辅助函数、hook、服务或包装器，或者集中重复代码？
如果没有，跳过此技能。重命名、代码迁移、配置/数据编辑和一行修复不在此限。

## 2. 写边界之前

- 找出这个仓库已经如何解决类似问题，并遵循它，除非你能说明为什么不这样做。阅读依赖的当前文档和类型：凭记忆回忆的 API 是主张，不是来源。
- 先写接口注释：它承诺什么，隐藏什么。如果你无法命名隐藏的决策（格式、策略、规则、模式选择），这个边界不应该存在。将其内联。
- 用领域语言命名。如果唯一诚实的名字是 `utils`、`helpers` 或 `manager`，说明切分位置不对。

## 3. 两个测试

- **深度。** 接口必须隐藏的内容远多于暴露的内容。一个仅转发参数的包装器是无益的开销；删除它。
- **不变性。** 只有当共享代码保护共享规则时才提取。证据是共变：历史上这些副本是一起修复或修改的。独立变化的相似代码保持重复。

## 4. 修复必须消除问题，而非转移问题

- 六个类型转换集中到一个通用转换辅助中仍是六个转换。写出类型映射器，替代这些转换的掩盖。
- 不要添加参数或标志将决策推给调用者，除非调用者确实知道你不知道的事情。将复杂情况吸收在内部。
- 优先选择错误情况不会出现的语义，而非让每个调用者处理它。
- 将关键领域复杂性移到另一个文件不等于简化。

## 5. 面对“清理”或“文件太大”的压力

绝不单凭大小拆分。一个隐藏一个决策的400行模块胜过四个泄露相同连接点的100行模块。问问每个拆分隐藏了什么决策；如果没有，就别拆分。

## 6. 安全性

已有代码：在加深之前用测试锁定当前行为。新代码：写定义预期行为的测试。

## 7. 报告

如果门槛触发，结束你的最终信息时附上2-4行设计说明：你添加的每个边界及其隐藏的决策；你故意保留的重复及原因；你接受的任何浅层设计及原因。

对于有争议的决定或全面审查，加载 `ousterhout-quality-program`。

标签