与 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 审计证据包范本已建立。