typescript-best-practices | 用型別表達有效狀態
本頁以 pstack-claude 0.9.126 為基準。typescript-best-practices 把型別系統紀律落到 TypeScript 語法與實際邊界，原文的適用路徑是 .ts 與 .tsx。
定位與適用情境
例如匯入工作 API 回傳任意 JSON，目前程式用一袋可選欄位表示排隊、執行、成功與失敗。結果可能同時有成功檔案與失敗訊息，也可能成功卻沒有檔案。這個技能要讓模型先表達哪些狀態合法，而不是到處補 if 或非空斷言。
輸入是 API 邊界、既有結構驗證工具、權威資料定義、狀態消費者與測試。預期輸出是明確解析邊界及可被編譯器檢查的領域模型。
準備
- 原文要求先套用 principle-type-system-discipline。它是
user-invocable: false的參考原則，通常由主流程按需讀取，不另編造 slash 指令。 - 找出專案現有的結構描述 (Schema) 函式庫與型別來源。優先沿用，不因本頁出現 schema 就安裝新依賴。
- 盤點外部 JSON 到內部函式的路徑，以及
as、any、!與可選欄位正在掩蓋的假設。 - 找到現有型別檢查與真實測試命令。單純編譯通過不等於外部輸入已驗證。
操作步驟
- 先定資料形狀。 以含
kind字面值的可辨識聯集 (Discriminated Union) 分開排隊、執行、成功與失敗。只有成功分支能有下載結果，失敗分支必須帶錯誤，避免所有欄位都可選。 - 把解析留在邊界。 外部資料先視為
unknown，以既有 schema 解析成具名領域型別，並從 schema 推導型別。不要讓Record<string, unknown>一路流入業務邏輯，也不要用as假裝解析成功。 - 區分語意值並逐步縮窄。 工作 ID 與使用者 ID 即使都是字串也不應互換，可用品牌型別 (Branded Type) 表達。品牌只能由真正驗證的型別守衛取得，不由強制轉型製造。分支優先依辨識欄位縮窄，再考慮
in、typeof、instanceof與可信守衛。 - 補齊編譯期契約。 在聯集分支的預設處以
const _exhaustive: never = x;做窮盡檢查 (Exhaustiveness Check)。常值設定優先用satisfies檢查，不用轉型掩蓋錯誤。既有資料形狀優先用Pick、Omit、ReturnType等推導。 - 驗證使用者能觀察的行為。 跑型別檢查與真實解析、狀態轉移測試。只有本機無法執行的依賴才考慮模擬。診斷資訊使用可依 ID 追蹤的結構化記錄，不在交付程式中留下
console.log。
可直接使用的提示詞
Claude Code 可用 /pstack:typescript-best-practices，Codex 插件可選 $pstack:typescript-best-practices。以下是自然語言任務。
用 pstack:typescript-best-practices 檢查匯入工作 API 到 UI 的 TypeScript 資料流。
先套用 principle-type-system-discipline，讀取現有 schema、型別與所有狀態消費者。
把排隊、執行、成功、失敗改成有 kind 的聯集，不能以可選欄位拼出矛盾狀態。
外部 JSON 先是 unknown，用專案既有工具驗證後再進入業務層。
區分工作 ID 與使用者 ID，不以 as 製造品牌或繞過錯誤。
先提出資料形狀與影響範圍，確認後才修改指定檔案。
跑既有型別檢查與真實測試，不安裝依賴、不用模擬結果冒稱 API 已驗證。預期結果與驗收
| 檢查點 | 應能辨認的結果 |
|---|---|
| 狀態模型 | 成功卻沒有結果、成功又帶失敗資料等組合不能成立 |
| 邊界解析 | 不合法 JSON 在邊界被拒絕，內部接收具名型別 |
| 語意識別碼 | 工作 ID 與使用者 ID 不能因同為字串而互換 |
| 新增狀態 | 漏處理的聯集分支能被編譯器指出 |
| 測試與診斷 | 測試呼叫真實解析路徑，錯誤能用結構化上下文追查 |
型別加強要有實際用途。所有操作都能安全處理空陣列時，維持 T[] 即可。只有鬆散型別迫使程式使用 !、轉型或「不該發生」拋錯時，才考慮 [T, ...T[]] 等非空模型。
限制與權限
型別守衛必須真的驗證它聲稱的條件。謊稱安全的守衛比明顯轉型更難發現問題。satisfies 也不會驗證執行期的外部 JSON。
原文對多參數介面偏好物件參數，但每幀渲染、詞法分析或剖析等熱路徑有例外。不要為遵循形式改壞效能，也不要把每個陣列都升級成複雜型別。
原文另指向 references/patterns.md，本次來源快取未含該附件。本頁依主技能與型別紀律原則說明，不聲稱重現附件範例。paths 是來源的適用範圍資訊，各平台是否自動啟用需另外確認。
技能不授權新增套件、廣泛重構或變更 API 契約。範例要求先確認形狀；型別檢查通過也不構成整個產品正確的保證。