與 Kiro 同行：晶圓廠工程健康度 Hook 工作坊

時長： 2 小時

目標受眾： 在半導體廠系統中負責治理 AI 輔助開發的專業開發人員、平台工程師與資深審查員

主要 AWS AI 服務： Kiro

工作坊重點： 用於預測性維護與設備健康度集中事件的 Kiro Hook、審查治理與開發人員工作流程

獨立成果： 開發人員將建立 Hook 規則與治理實驗室，用於設備健康度事件持久化（persistence）、維護事件不退化（non-regression）以及審查品質控制。

僅限教育工程研討會。這是一項軟體架構練習，而非流程發佈建議。

---

摘要

本工作坊旨在教導開發人員如何針對半導體預測性維護工作流程治理 Kiro Hook。參與者將為設備健康度集中事件定義原始碼安全、測試覆蓋率、審查品質、版本推出以及 Pull Request（PR）控制項。實驗室將示範含有缺陷與修正後的 TypeScript 處理常式（handlers）、精確的 Hook 回饋、雜訊調優、事件範例，以及保留原始值、保護既有晶圓廠行為並支援跨團隊人工審查的決策紀錄。

---

1. 工作坊目標

本工作坊提供了更多實作開發實驗室，以在晶圓廠工程儲存庫（repository）中使用 Kiro Hook。情境聚焦於預測性維護與設備健康度集中事件。開發人員將建立 Hook，在變更進入 Pull Request 審查之前，自動檢查程式碼、測試與審查輸出中是否存在不安全的模式（patterns）。

本工作坊採用設備健康度、維護視窗、稼動率（utilization）、漂移集中度、感測器因子、晶圓批次良率風險（wafer-lot yield exposure）以及自動化控制滑移（automation control slip）等實例，不使用泛用的應用程式領域範例。

製造背景知識： 設備健康度集中度會與漂移訊號、稼動率狀態及晶圓批次良率風險一同進行審查，因為維護時機可能會影響生產佇列延遲（queue delay）、重工（rework）風險以及整體的良率控制。

---

2. 學習目標

開發人員將學習如何：

● 為設備健康度事件程式碼建立 Kiro Hook。

● 在儲存檔案時自動審查有缺陷的持久化（persistence）程式碼。

● 為測試覆蓋率與審查輸出品質建立 Hook 規則。

● 調優高雜訊的 Hook 規則。

● 將 Hook 回饋轉換為 Pull Request 治理控制。

● 闡述 Hook 如何輔助而非取代人工工程審查。

---

3. 實驗室議程

---

4. 實驗室 1 — Hook 治理模型

開發人員任務

要求 Kiro 為設備健康度持久化工作流程分類 Hook 檢查項目。

提示詞範例

建立一個用於設備健康度集中度事件持久化的 Hook 治理模型。將規則分類為原始碼安全、測試覆蓋率、審查輸出品質以及版本推出治理。

預期 Kiro 結果

原始碼安全：
- 精確的事件資格比對。
- 直接儲存原始欄位。
- 不儲存完整負載（payload）。
- 不使用自動生成的 ID 或時間戳記。
- 處理所有健康度因子。

測試覆蓋率：
- 符合資格的事件須能持久化摘要與因子。
- 無關的維護與警報事件保持不變。
- 缺少 health_factors 時應能安全處理。
- 時間欄位保持獨立。

審查輸出品質：
- 顯示 通過（PASS）或 失敗（FAIL）。
- 列出確切的違反事項。
- 僅提供最小化修補（patch）。

版本推出治理：
- 建議/諮詢階段（Advisory phase）。
- 雜訊審查。
- 針對 Hook 變更進行 Pull Request 審查。

業務邏輯說明： 治理（Governance）將技術規則檢查與導入流程相分離。

程式碼邏輯說明： Kiro 可以利用這些分類來建立獨立的 Hook 檔案。

預期結果： 開發人員能理解為何使用多個 Hook 會優於單一龐大的 Hook。

系統設計決策

● 將規則分類可確保 Hook 回饋具備可執行性（actionable）。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時（save-time）、測試時（test-time）及審查時（review-time）的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式（operational failure mode）連結，避免增加不必要的平台複雜度。

● 治理規則能降低自動化產生的雜訊或不可信風險。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據（source evidence）與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性（traceability）、可重複性（reproducibility）及生產環境不退化（production non-regression）負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● Hook 應該要提升審查的一致性，而非繞過人工評判。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務（engineering practice）。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構（refactors）或隱含的假設之中。

---

5. 實驗室 2 — 設備健康度程式碼 Hook

請建立 .kiro/hooks/equipment-health-code-review.md。

# 設備健康度程式碼審查 Hook

觸發條件：
當符合以下檔名模式的檔案被儲存時執行：
- `src/*Health*.ts`
- `src/*Maintenance*.ts`
- `src/*Handler.ts`

代理工具行動：
審查 TypeScript 程式碼，確保設備健康度集中度持久化（persistence）的安全性。

規則：
1. 新的持久化邏輯必須僅在 `event_type === "EQUIPMENT_HEALTH_CONCENTRATION"` 時執行。
2. 既有的 `EQUIPMENT_ALARM`、`MAINTENANCE_EVENT` 與 `AUTOMATION_CONTROL_COMMAND` 之行為必須保持不變。
3. 每個符合資格的事件必須恰好建立一筆健康度摘要紀錄（health summary record）。
4. `health_factors` 必須被視為陣列（array）處理。
5. 每個健康度因子（health factor）必須恰好建立一筆因子紀錄（factor record）。
6. 每一筆因子紀錄必須使用 `health_event_id` 連結至對應的摘要紀錄。
7. 儲存的欄位必須直接來自來源事件（source event）或為 null。
8. 絕對不得儲存完整的 JSON 負載（payload）。
9. 在持久化映射（persistence mapping）過程中，不得轉換遙測值、集中度分數與機率。
10. 不得使用自動生成的 ID 與自動生成的時間戳記。
11. `event_time`、`maintenance_window_time` 與 `factor_time` 必須保持獨立。
12. 請勿建議進行寬泛的重構（broad refactoring）。

輸出：
- 顯示 通過（PASS）或 失敗（FAIL）。
- 列出確切的違反事項。
- 僅提供最小化修補（patch）。

業務邏輯說明： 此 Hook 用於檢查設備健康度持久化是否會干擾維護、警報或自動化控制命令等工作流程。

程式碼邏輯說明： 當符合條件的檔案被儲存時，Kiro 會執行此 Markdown 指令。

預期結果： 不安全的原始碼將會收到精確的失敗（FAIL）回饋。

系統設計決策

● 精確的事件資格比對可防止對無關事件進行寬泛的處理。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 原始欄位儲存保障了與晶圓廠遙測資料進行鑑識比對（forensic comparison）的能力。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 獨立的時間欄位可支援維護計劃與事件時序分析（incident chronology）。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

6. 實驗室 3 — 測試覆蓋率 Hook

請建立 .kiro/hooks/equipment-health-test-review.md。

# 設備健康度測試審查 Hook

觸發條件：
當符合以下檔名模式的檔案被儲存時執行：
- `test/*Health*.test.ts`
- `test/*Maintenance*.test.ts`
- `test/*Handler.test.ts`

代理工具行動：
審查測試程式碼，確保設備健康度集中度持久化具有足夠的測試覆蓋率。

必要覆蓋率範圍：
1. 符合資格的設備健康度事件必須建立一筆摘要紀錄。
2. 包含至少兩個健康度因子的合規事件，必須建立多筆因子紀錄。
3. 每個因子紀錄必須保留父層的 `health_event_id`。
4. 缺少 `health_factors` 時，必須建立一筆摘要紀錄且建立零筆因子紀錄。
5. 遺漏選填的摘要欄位時，必須以 null 形式儲存。
6. 遺漏選填的因子欄位時，必須以 null 形式儲存。
7. 設備警報（Equipment alarm）行為必須保持不變。
8. 維護事件（Maintenance event）行為必須保持不變。
9. 自動化控制命令（Automation control command）行為必須保持不變。
10. 事件時間、維護視窗時間與因子時間必須分開進行斷言（asserted）。

輸出：
- 顯示 通過（PASS）或 失敗（FAIL）。
- 列出缺少的測試。
- 建議的測試名稱。
- 僅針對缺少的測試提供最小化的程式碼片段（snippets）。

業務邏輯說明： 此 Hook 可確保測試既能驗證新的設備健康度功能，又能證明既有流程沒有發生退化（non-regression）。

程式碼邏輯說明： Kiro 會審查測試檔案並回報未涵蓋的行為。

預期結果： 涵蓋率不足的測試將會收到具體可執行的改善建議。

系統設計決策

● 測試覆蓋率應與營運風險（operational risks）相對應。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 維護事件不退化（non-regression）至關重要，因為維護排程會直接影響產能（production capacity）。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 建議的測試名稱能加快開發人員修復的速度。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

7. 實驗室 4 — 有缺陷的健康度處理常式

請將以下有缺陷的程式碼貼入 src/equipmentHealthHandler.ts。

export async function persistEquipmentHealth(message: any, db: any) {
  if (message?.event_type?.includes("HEALTH")) {
    await db.insertHealthSummary({
      health_event_id: message.health_event_id || crypto.randomUUID(),
      payload: JSON.stringify(message),
      equipment_health_concentration: Number(message.equipment_health_concentration || 0),
      created_at: new Date().toISOString()
    });

    const firstFactor = message.health_factors?.[0];
    if (firstFactor) {
      await db.insertHealthFactor({
        factor_id: firstFactor.factor_id || crypto.randomUUID(),
        health_event_id: message.health_event_id,
        sensor_name: firstFactor.sensor_name,
        sensor_value: Number(firstFactor.sensor_value || 0)
      });
    }

    return "persisted";
  }

  return "ignored";
}

業務邏輯說明： 此範例故意違反了健康度 Hook 規則：包含處理過於寬泛的事件、儲存完整負載（payload）、自動生成 ID、自動生成時間戳記、轉換原始數值，且僅儲存第一個因子。

程式碼邏輯說明： Hook 應該要標記出 includes、crypto.randomUUID、JSON.stringify、Number、new Date 以及僅處理第一個因子的邏輯。

預期結果： Hook 將會回傳失敗（FAIL）。

預期 Hook 回饋

失敗（FAIL）
確切違反事項：
- 資格檢查使用 includes("HEALTH")，而非精確比對 EQUIPMENT_HEALTH_CONCENTRATION。
- health_event_id 存在自動生成的邏輯。
- 儲存了完整的 JSON 負載（payload）。
- equipment_health_concentration 被轉換為數字類型（Number）。
- created_at 時間戳記為自動生成。
- 僅儲存了第一個健康度因子（health factor）。
- factor_id 存在自動生成的邏輯。
- sensor_value 被轉換為數字類型（Number）。

最小化修補：
- 改用精確的 event_type 檢查。
- 移除自動生成的 ID、完整負載儲存、類型轉換以及自動生成的 created_at 欄位。
- 使用迴圈遍歷 message?.health_factors || []。
- 直接儲存原始來源欄位或 null。

系統設計決策

● 包含缺陷的範例能訓練開發人員識別不安全的 AI 生成程式碼。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 精確的 Hook 回饋能讓修復提示詞（repair prompts）更加精準。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 修復應保持最小化以規避新的生產環境風險。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

8. 實驗室 5 — 修正後的設備健康度處理常式

提示詞範例

僅套用來自設備健康度程式碼審查 Hook 的最小化修補。保留直接的來源數值或 null。請勿重構無關的程式碼。

預期修正後的程式碼

export async function persistEquipmentHealth(message: any, db: any) {
  if (message?.event_type === "EQUIPMENT_HEALTH_CONCENTRATION") {
    await db.insertHealthSummary({
      health_event_id: message.health_event_id || null,
      fab_id: message.fab_id || null,
      tool_id: message.tool_id || null,
      tool_type: message.tool_type || null,
      utilization_state: message.utilization_state || null,
      equipment_health_concentration: message.equipment_health_concentration || null,
      drift_cluster_level: message.drift_cluster_level || null,
      maintenance_window_time: message.maintenance_window_time || null,
      event_time: message.event_time || null
    });

    for (const factor of message?.health_factors || []) {
      await db.insertHealthFactor({
        factor_id: factor.factor_id || null,
        health_event_id: message.health_event_id || null,
        sensor_name: factor.sensor_name || null,
        sensor_value: factor.sensor_value || null,
        control_boundary: factor.control_boundary || null,
        unit: factor.unit || null,
        factor_time: factor.factor_time || null
      });
    }

    return "equipment-health-concentration-persisted";
  }

  return "ignored";
}

業務邏輯說明： 修正後的程式碼會直接儲存原始的設備健康度欄位以及所有的健康度因子。

程式碼邏輯說明： 以精確的事件比對與陣列迴圈，取代原本不安全的寬泛比對及僅處理單一因子的邏輯。

預期結果： 原始碼審查 Hook 應該要回傳通過（PASS）。

系統設計決策

● 設備健康度集中度是一個特定的事件類型，不應比對所有名稱類似健康度的事件。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 必須完整保留所有健康度因子，以便後續進行維護調查（maintenance investigation）。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 直接儲存欄位可避免將持久化與預測性評分邏輯（predictive scoring logic）混為一談。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

9. 實驗室 6 — 審查輸出品質 Hook

請建立 .kiro/hooks/review-output-quality.md。

# 審查輸出品質 Hook

觸發條件：
當 Kiro 審查筆記（review notes）或審查 Markdown 檔案被儲存時執行。

代理工具行動：
檢查審查輸出對於設備健康度與程序風險變更（process-risk changes）是否具備可執行性（actionable）。

規則：
1. 審查輸出必須包含 通過（PASS）或 失敗（FAIL）。
2. 失敗（FAIL）的輸出中必須包含確切的違反事項。
3. 失敗（FAIL）的輸出中必須包含最小化修補指引（minimal patch guidance）。
4. 除非有明確要求，否則審查輸出不得建議進行寬泛的重構。
5. 審查輸出不得引入新的業務需求。
6. 審查輸出必須將原始碼問題與測試覆蓋率問題明確區分。

輸出：
- 顯示 通過（PASS）或 失敗（FAIL）。
- 列出缺少的審查輸出要求。
- 提供最小化的重寫建議（minimal rewrite suggestion）。

業務邏輯說明： 開發團隊需要一致且能被快速執行的審查回饋。

程式碼邏輯說明： 此 Hook 評估的是審查筆記的品質，而非生產環境程式碼。

預期結果： 模糊不清的審查內容將被重寫為具體可執行的回饋。

系統設計決策

● 審查自動化的品質與程式碼自動化的品質同等重要。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 模糊的 AI 審查會拖慢開發人員的進度。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 最小化審查指引能確保回饋與變更範圍（change scope）保持一致。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

10. 實驗室 7 — Hook 雜訊調優

提示詞範例

審查此 Hook 規則的雜訊風險：「每個設備健康度檔案必須包含至少 30 行的註解。」它應該被保留、移除還是重寫？

預期 Kiro 結果

重寫。
此規則具有高雜訊，因為註解的行數並不能證明安全性。
更好的規則：
當引入或變更設備健康度欄位映射（field mapping）時，必須包含一個來源事件範例（source event example），並在映射了 event_time、maintenance_window_time 與 factor_time 時說明這些欄位的用途。

業務邏輯說明： 高雜訊的 Hook 會降低信任度，並可能導致開發人員忽略真正重要的警告。

程式碼邏輯說明： Kiro 將武斷的樣式規則（style rule）轉換為有意義的文件規範規則。

預期結果： Hook 訊號品質得到提升。

系統設計決策

● Hook 應該要檢查在運作上具有實質意義的風險。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 武斷的樣式規則會造成警報疲勞。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 文件規範要求應與欄位語意（field semantics）綁定。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

11. 實驗室 8 — Pull Request 治理檢核表

提示詞範例

將設備健康度 Hook 轉換為 Pull Request 治理檢核表。保持簡潔，並聚焦於來源安全、測試覆蓋率、審查品質以及版本推出。

預期 Kiro 輸出

Pull Request 治理檢核表：
- 原始碼使用精確的 EQUIPMENT_HEALTH_CONCENTRATION 事件資格比對。
- 既有的警報（alarm）、維護（maintenance）與自動化控制命令行為保持不變。
- 健康度摘要紀錄（health summary records）與健康度因子紀錄（health factor records）已正確持久化。
- 無儲存完整負載（payload）、無自動生成 ID、無自動生成時間戳記，且無原始來源數值轉換。
- 測試已涵蓋合規事件、多筆健康度因子、遺漏因子、選填欄位、設備警報、維護事件以及自動化控制命令等情境。
- 審查輸出包含 通過/失敗（PASS/FAIL）、確切違反事項以及最小化修補指引。
- Hook 規則的變更比照原始碼接受審查。

業務邏輯說明： PR 檢核表可協助團隊在全面強制執行之前，逐步導入 Hook 機制。

程式碼邏輯說明： Kiro 將 Hook 規則轉換為人工審查查核項目。

預期結果： 開發人員與審查員能達成相同的預期共識。

系統設計決策

● PR 治理連結了本地 Hook 回饋與團隊審查標準。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● Hook 變更應該受到審查，因為它們會影響未來 AI 輔助開發的行為。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 人工審查仍對最終的生產環境決策負有最終責任。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

12. 完成情況檢核表

● Hook 治理模型已建立。

● 設備健康度原始碼 Hook 已建立。

● 測試覆蓋率 Hook 已建立。

● 有缺陷的處理常式已完成審查。

● 修正後的處理常式已生成。

● 審查輸出品質 Hook 已建立。

● 雜訊調優已完成。

● PR 治理檢核表已建立。

---

13. 實驗室 9 — 設備健康度事件範例實驗室

提示詞範例

建立一個完整的 EQUIPMENT_HEALTH_CONCENTRATION 事件範例以用於程式碼註解。包含 health_event_id、fab_id、tool_id、tool_type、utilization_state、equipment_health_concentration、drift_cluster_level、maintenance_window_time、event_time 以及兩個 health_factors。

預期事件範例

{
  "event_type": "EQUIPMENT_HEALTH_CONCENTRATION",
  "health_event_id": "health_evt_20260626_001",
  "fab_id": "FAB-HK-ADV-01",
  "tool_id": "DEPOSITION-PVD-04",
  "tool_type": "THIN_FILM_DEPOSITION",
  "utilization_state": "HIGH_UTILIZATION",
  "equipment_health_concentration": "0.81",
  "drift_cluster_level": "ELEVATED",
  "maintenance_window_time": "2026-06-26T18:00:00+08:00",
  "event_time": "2026-06-26T14:30:00+08:00",
  "health_factors": [
    {
      "factor_id": "health_factor_vacuum_001",
      "sensor_name": "chamber_vacuum",
      "sensor_value": "1.8e-6",
      "control_boundary": "2.0e-6",
      "unit": "torr",
      "factor_time": "2026-06-26T14:29:58+08:00"
    },
    {
      "factor_id": "health_factor_rate_002",
      "sensor_name": "deposition_rate",
      "sensor_value": "48.5",
      "control_boundary": "50.0",
      "unit": "angstrom_per_second",
      "factor_time": "2026-06-26T14:29:59+08:00"
    }
  ]
}

業務邏輯說明： 事件範例將設備健康度持久化與真實的晶圓廠訊號及維護排程相結合。

程式碼邏輯說明： 該事件包含一個父層健康度 ID 以及多個健康度因子 ID。時間欄位保持獨立。

預期結果： Kiro 可以在程式碼註解、測試與審查提示詞中使用此範例。

系統設計決策

● 事件範例能減少結構空想（schema invention）。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 多重健康度因子反映了真實的設備健康度集中度分析情境。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 時間欄位可同時支援事件分析 與維護排程。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

14. 實驗室 10 — 治理決策紀錄

提示詞範例

建立一份簡短的架構決策紀錄（ADR），說明為何設備健康度持久化直接將原始來源字串儲存，且不在處理常式中計算健康度分數。

預期 Kiro 結果

決策：設備健康度持久化直接將原始來源欄位儲存為字串。
背景脈絡：處理常式負責捕獲健康度集中度事件，以便後續調查與維護排程。
原由分析：計算邏輯屬於分析層（analytics layer）。持久化層必須保留原始來源數值以確保可追溯性。
影響與後果：處理常式保持簡潔、測試具備確定性（deterministic），且可在不更動原始來源事件紀錄的情況下新增未來的分析功能。

業務邏輯說明： 開發人員需要理解為何即使健康度指標看起來是數字，處理常式也應避免進行計算。

程式碼邏輯說明： 決策紀錄解釋了為何程式碼要直接儲存數值並保持簡單的映射關係。

預期結果： 審查員可以使用此決策紀錄來拒絕不必要的類型轉換。

系統設計決策

● 架構決策紀錄（ADR）在工作坊結束後仍能保留設計思維。這是一項系統設計抉擇，因為設備健康度 Hook 治理需要嚴格且專一的合約，以便開發人員在儲存時、測試時及審查時的回饋中進行推導。此決策使實驗室聚焦於可觀測的行為，而非流於寬泛的實作偏好，從而讓學習者能將單一規則與特定的運作失效模式連結，避免增加不必要的平台複雜度。

● 直接儲存保護了來源事件的可追溯性。針對設備健康度 Hook 治理，系統架構應在優化開發人員便利性之前，優先保留原始證據與既有的事件行為。這一點明確劃定了界線：自動生成的輔助程式可以提出變更建議，但系統仍須對可追溯性、可重複性及生產環境不退化負責。這樣一來，系統將更容易被審計，且演進時更具安全性。

● 將分析與持久化分離可支援更安全的未來演進。最後一個設計要點將實驗室的行動轉化為設備健康度 Hook 治理的長期工程實務。它說明了所選定的範疇邊界如何支援團隊審查、未來的維護以及受控的版本推出。藉由保持行動的最小化與可衡量性，開發人員可以改善工作流程，而不會將風險隱藏在龐大的重構或隱含的假設之中。

---

進階開發人員額外實作實驗室

這些額外實驗室延伸設備健康度 Hook 工作坊，並刻意避開前面已涵蓋的 Hook 建立、有缺陷處理常式修復、審查輸出品質、雜訊調優、事件範例與決策紀錄。重點轉向 Hook 封裝、儲存庫政策邊界、分階段強制執行、可稽核性，以及 Hook 規則之間的衝突處理。

15. 實驗室 11 — Hook 規則清單與擁有權中繼資料

開發人員任務

建立一份清單，將每個設備健康度 Hook 描述為受治理的工程資產。這份清單不取代 Hook 內容，而是記錄擁有權、觸發範圍、強制執行階段與審查期待。

提示詞範例

建立 .kiro/hooks/equipment-health-hook-manifest.md，用於設備健康度 Hook 集合。包含 Hook 名稱、觸發範圍、擁有者角色、強制執行模式、預期輸出合約與必要審查者角色。不要重複完整 Hook 規則。

預期 Kiro 結果

# 設備健康度 Hook 清單

## 範圍
本清單描述受治理的 Kiro Hook，用於設備健康度集中度事件持久化。

## Hook

### equipment-health-code-review.md
- 擁有者角色：晶圓廠平台工程
- 觸發範圍：`src/*Health*.ts`、`src/*Maintenance*.ts`、`src/*Handler.ts`
- 強制執行模式：首次推出期間採建議模式；完成兩個乾淨的審查週期後改為阻擋模式
- 輸出合約：PASS 或 FAIL、確切違反事項、僅提供最小化修補
- 必要審查者角色：資深晶圓廠系統開發人員

### equipment-health-test-review.md
- 擁有者角色：測試自動化工程
- 觸發範圍：`test/*Health*.test.ts`、`test/*Maintenance*.test.ts`、`test/*Handler.test.ts`
- 強制執行模式：採建議模式，直到缺少的不退化測試低於團隊門檻
- 輸出合約：PASS 或 FAIL、缺少的測試、建議的測試名稱、僅提供最小化片段
- 必要審查者角色：測試負責人或模組維護者

### review-output-quality.md
- 擁有者角色：工程賦能
- 觸發範圍：審查筆記與產生的審查 Markdown
- 強制執行模式：建議模式
- 輸出合約：PASS 或 FAIL、缺少的審查輸出要求、最小化重寫建議
- 必要審查者角色：Pull Request 審查者

## 變更控制
Hook 行為變更需要經過 Pull Request 審查，因為它們會影響未來 AI 輔助開發的行為。

業務邏輯說明： Hook 擁有權可避免多個團隊依賴設備健康度持久化行為時發生靜默的政策漂移。 程式碼邏輯說明： 清單是文件而非可執行程式碼，但能讓審查者穩定掌握 Hook 意圖與推出狀態。 預期結果： 開發人員能辨識每個 Hook 由誰負責，以及何時處於建議模式或阻擋模式。

系統設計決策

● Hook 中繼資料將政策治理與原始碼檢查分離，讓 Hook 規則保持小而可審查，同時讓擁有權與強制執行狀態清楚可見。

● 明確標示強制執行模式，讓團隊能分階段導入而不讓開發人員感到意外。

● 審查者角色有助於避免不了解維護與設備健康度事件營運影響的人核准 Hook 變更。

16. 實驗室 12 — 跨 Hook 衝突審查

開發人員任務

要求 Kiro 審查兩條可能衝突的 Hook 規則，並提出安全解法。

衝突情境

原始碼 Hook 規定：Store direct source values or null only. 文件 Hook 規定：If equipment_health_concentration is present, explain whether it is above 0.80.

提示詞範例

審查設備健康度原始碼 Hook 與文件 Hook 之間的可能衝突。原始碼 Hook 禁止在持久化映射中進行計算。文件 Hook 要求開發人員說明 equipment_health_concentration 是否高於 0.80。請在不允許原始碼加入計算的前提下解決衝突。

預期 Kiro 結果

解法：保留原始碼 Hook 不變，並改寫文件 Hook。

原因：
- 持久化映射器不得計算門檻值，也不得推導健康狀態。
- 文件可以描述來源欄位的意義，但不得要求變更程式碼或新增派生欄位。

改寫後的文件規則：
當映射 equipment_health_concentration 時，包含一個來源事件範例，並說明門檻值解讀屬於分析層或製程工程審查的責任，而非持久化處理常式的責任。

PASS 條件：
- 處理常式會直接儲存 equipment_health_concentration 或 null。
- 原始碼中沒有新增門檻值比較。
- 文件說明欄位語意，但不新增派生狀態。

業務邏輯說明： 衝突審查可避免文件規則間接將分析邏輯推入持久化處理常式。 程式碼邏輯說明： Kiro 會改寫較弱的規則，同時保留較強的持久化安全邊界。 預期結果： 開發人員能在 Hook 衝突造成不一致 PR 回饋之前先完成處理。

系統設計決策

● 當生產行為存在風險時，原始碼安全規則應優先於模糊的文件規則。

● 文件可以說明語意，但不應成為派生計算的隱性需求。

● 跨 Hook 審查能在團隊新增更多自動化時維持 Hook 集合的一致性。

17. 實驗室 13 — 分階段強制執行模擬

開發人員任務

建立一份分階段推出計劃，將設備健康度 Hook 從建議型警示推進到 Pull Request Gate。

提示詞範例

建立設備健康度 Hook 的分階段強制執行計劃。從建議型回饋開始，接著是 PR 警告，最後僅針對高信心違規進行阻擋。包含升級與回復準則。

預期 Kiro 結果

# 分階段強制執行計畫

## 第 1 階段 — 本機建議型回饋
- Hook 會在儲存時執行。
- 開發人員記錄誤判與遺漏案例。
- 不阻擋任何 Pull Request。

升級準則：
- Hook 輸出能一致使用 PASS 或 FAIL。
- 最小化修補指引在至少兩個審查週期中保持準確。
- 沒有尚未處理的高嚴重性誤判。

## 第 2 階段 — Pull Request 警告
- Hook 結果會附加到 Pull Request。
- 審查者必須確認 FAIL 輸出。
- 只要有文件化的審查者核准，仍允許合併。

升級準則：
- 重複發生的違規已被理解，且具備可執行的處理方式。
- 針對警報、維護與自動化控制命令行為，已有不退化測試。

## 第 3 階段 — 針對高信心違規進行阻擋
阻擋項目：
- 寬泛的事件資格比對，例如 includes("HEALTH")。
- 儲存完整負載。
- 在持久化映射中產生 ID 或時間戳記。
- 在持久化映射中轉換來源值。

回復準則：
- Hook 阻擋了安全的生產環境緊急修補。
- 規則反覆產生誤判。
- Hook 與已核准的架構決策紀錄衝突。

業務邏輯說明： 分階段強制執行可在提升維護敏感工作流程安全性的同時保護開發效率。 程式碼邏輯說明： 只有確定性高、信心高的違規會成為阻擋檢查。 預期結果： 團隊能導入 Hook，而不會立即把所有 AI 回饋都變成合併阻擋條件。

系統設計決策

● 先採建議模式可讓團隊在強制執行之前累積證據。

● 阻擋應限於營運風險清楚且解讀歧義低的規則。

● 回復準則是安全治理的一部分，不代表 Hook 失敗。

18. 實驗室 14 — Hook 治理變更的稽核證據包

開發人員任務

為變更設備健康度持久化程式碼的 Pull Request 產生一份精簡稽核證據包範本。

提示詞範例

為受 Kiro Hook 治理的設備健康度持久化 Pull Request 建立稽核證據包範本。包含原始碼變更摘要、Hook 結果、測試證據、不退化證據、未解風險與人工審查者簽核。

預期 Kiro 結果

# 設備健康度持久化稽核證據包

## Pull Request 摘要
- 變更目的：
- 已變更檔案：
- 受影響事件類型：EQUIPMENT_HEALTH_CONCENTRATION

## Hook 證據
- 原始碼安全 Hook：PASS/FAIL
- 測試覆蓋率 Hook：PASS/FAIL
- 審查輸出品質 Hook：PASS/FAIL
- 任何建議型警告：

## 測試證據
- 已測試符合資格事件的摘要持久化：是/否
- 已測試多個健康度因子：是/否
- 已測試缺少 health_factors：是/否
- 已測試選填欄位為 null：是/否
- 已分別測試時間欄位：是/否

## 不退化證據
- EQUIPMENT_ALARM 保持不變：是/否
- MAINTENANCE_EVENT 保持不變：是/否
- AUTOMATION_CONTROL_COMMAND 保持不變：是/否

## 人工審查
- 審查者：
- 決策：
- 後續工作：

業務邏輯說明： 可稽核證據能協助團隊證明設備健康度變更保留可追溯性，且未改變無關的晶圓廠流程。 程式碼邏輯說明： 範本將 Hook 輸出與測試結果轉成審查成品，而不新增任何執行階段行為。 預期結果： 審查者有一致的檢核表可用於核准受 Hook 治理的變更。

系統設計決策

● 稽核證據包會將本機自動化回饋轉為持久的審查證據。

● 不退化證據是一等公民，因為無關的晶圓廠事件必須保持穩定。

● 人工簽核保持明確，因為 Hook 支援審查，但不承擔生產責任。

19. 進階實驗室完成情況檢核表

● Hook 清單已建立，包含擁有權與強制執行中繼資料。

● 跨 Hook 衝突已審查並解決，且未削弱原始碼安全性。

● 分階段強制執行計劃已建立，包含升級與回復準則。

● 設備健康度 Pull Request 稽核證據包範本已建立。