ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: 在撰寫或修改程式碼時使用，在標記任務完成之前，當變更新增了可匯出或可匯入的名稱、建立模組、類別、元件、輔助函式、hook、服務或包裝器，或將重複程式碼集中時使用。建構深度模組的作者時檢查清單：命名決策所隱藏的邊界，通過深度和不變性測試，修正問題而非重新定位，絕不僅以大小拆分，並以簡短的設計說明結尾。是 ousterhout-quality-program 的精簡伴侶，後者仍是完整的審查視角。
---

# Build it deep (Ousterhout, author-time)

你是在寫程式碼，而不是在審查它。在你宣告任務完成之前，先在自己的變更上執行這些步驟。

## 1. 門檻

這次變更是否新增了可匯出/匯入的名稱、建立了模組、類別、元件、輔助函式、hook、服務或包裝器，或是集中重複的程式碼？
如果沒有，跳過此技能。重新命名、程式碼轉換、設定/資料編輯和一行修正不在此限。

## 2. 在你寫邊界之前

- 找出此倉庫已如何解決此類問題並遵循它，除非你能說明為何不行。閱讀依賴的現有文件和型別：憑記憶回想 API 是主張，不是來源。
- 先寫介面註解：它承諾什麼，隱藏什麼。如果你無法命名被隱藏的決策（格式、政策、規則、結構選擇），此邊界不應存在。將其內聯。
- 用領域語言命名。如果唯一誠實的名稱是 `utils`、`helpers` 或 `manager`，表示切割位置錯誤。

## 3. 兩個測試

- **深度。** 介面必須隱藏的遠多於它暴露的。只轉發參數的包裝器是無益的成本；刪除它。
- **不變性。** 只有在保護共享規則時才抽取共用程式碼。證據是共變：歷史上這些複本是一起修正或變更的。獨立變更的相似程式碼保持複製狀態。

## 4. 修正必須移除問題，而非重新定位

- 六個轉型集中到一個泛型轉型輔助函式仍是六個轉型。寫出這些轉型掩蓋的型別映射器。
- 除非呼叫者真的知道你不知道的事，否則不要新增參數或旗標將決策推給呼叫者。將困難情況包裹在內。
- 優先選擇錯誤情況不可能發生的語意，而非讓每個呼叫者都要處理它。
- 將重要的領域複雜度移到另一個檔案不算簡化。

## 5. 在「整理這裡」或「這個檔案太大」的壓力下

絕不要單純因大小而拆分。一個 400 行模組隱藏一個決策，勝過四個 100 行模組洩漏相同的連結。問問每個拆分隱藏了什麼決策；如果沒有，就不要拆分。

## 6. 安全性

既有程式碼：在深化之前用測試鎖定目前行為。新程式碼：寫出定義預期行為的測試。

## 7. 報告

如果門檻觸發，請在最終訊息結尾附上 2-4 行設計說明：你新增的每個邊界及其隱藏的決策；你故意留下的重複及原因；你接受的任何淺層設計及原因。

對於有爭議的決定或完整審查，載入 `ousterhout-quality-program`。

標籤