Kiro：提示词库与深度代码说明附录

仅供教育工程用途。本内容是软件架构演练，不属于工艺放行建议。

如何使用本附录

在工作坊期间，请在 Kiro 中使用这些提示。这些提示刻意写得具体，因为专业团队应该提供情境、限制与验收条件，而不是模糊地提出需求。

---

提示组 1 — 项目启动

提示 1.1 — 建立项目骨架

You are helping me build a professional TypeScript workshop project from scratch. Create the minimal Vite project files for a static browser application. Use no frontend framework. Include scripts for dev, build, test, test:watch, and lint. Do not add business logic yet.

这个提示为何有效

• 它定义角色、技术与范围。
• 它阻止过早实作领域逻辑。
• 它建立日后 hooks 可以呼叫的标准 scripts。

系统设计决策

• 提示缩小了第一个 Kiro 任务。 新项目很容易扩张出不必要的档。只要求骨架的请求提供受控基准，也避免将设定与产品行为混在一起。
• 不使用框架是一项架构限制。 工作坊重点是 Kiro 的 AI 工程工作流程，而不是组件函数库的使用。纯 TypeScript 让产生的决策更可见。
• 标准 scripts 建立稳定合约。 未来的提示、hooks 与文件可以一致参照 npm test、npm run lint 与 npm run build。

---

提示组 2 — Steering

提示 2.1 — 产生基础 Steering

Generate workspace steering files for this project. Create product.md, tech.md, structure.md, domain.md, and testing.md. The project is a local advisory-only Fab SPC portal. It must model CD-SEM risk but must never command equipment. Use deterministic TypeScript functions and Vitest tests.

提示 2.2 — 改善 Domain Steering

Review .kiro/steering/domain.md. Add missing terms for SPC blind window, TMG, Mandel Slope, Fleet deviation, Residual 3σ, FDC health-link, APC guard, and yield-loss triage. Keep the language concise and enforce advisory-only behavior.

系统设计决策

• Steering 提示应明确说明禁止的行为。 对敏感领域的工程工具而言，只描述要建置什么并不够。开发人员也必须定义不得产生什么。
• 领域词汇属于 workspace 记忆。 Kiro 理解这些术语后，后续的 spec、代码与测试产生会更一致。这能减少重复解释，并避免术语漂移。
• 测试期望应放在 steering 中。 如果及早说明需要决定性函数与 Vitest 覆盖率，Kiro 更可能产生可测试的结构，而不是高度耦合的 UI 代码。

---

提示组 3 — 建立 Spec

提示 3.1 — 建立 Spec

Create a Kiro spec named fab-spc-portal. The feature is a local browser portal for detecting when routine SPC monitoring frequency is out of sync with actual mass production. Include requirements, system design, data model, risk scoring, UI behavior, accessibility, tests, and implementation tasks.

提示 3.2 — 强化验收条件

Refine the requirements. Add acceptance criteria for: TMG above UCL, Mandel Slope outside 0.98–1.02, Fleet deviation above 2σ and 3σ, Residual 3σ above 0.18 nm, blind window above six hours, empty search results, and advisory-only safety language.

系统设计决策

• 第一个提示建立端到端计划。 Kiro 应将功能理解成一个系统，而不是一堆随机档。需求、设计与任务形成可追溯的交付路径。
• 第二个提示强化边界案例。 初始 AI spec 可能遗漏边界条件。要求特定阈值与空状态，让最终代码更容易验证。
• Spec 成为可审查的证据。 开发人员可以将产生的实作与 spec 比较，并拒绝偏离的代码。对采用 AI 辅助交付的专业团队而言，这尤其重要。

---

提示组 4 — 领域逻辑

提示 4.1 — 实作纯风险函数

Implement the risk engine as pure TypeScript functions. Inputs are CdSemTool objects. Outputs are RiskAssessment objects with score, level, action, and reasons. Do not read the DOM, localStorage, network, clock, or random values. Keep thresholds centralized.

提示 4.2 — 要求审查风险优先顺序

Review the risk engine priority order. Fleet deviation >3σ and Mandel Slope outside 0.98–1.02 should result in HoldReview. TMG above UCL should result in ApcGuard unless a higher-priority hold condition exists. Residual 3σ above limit should result in RunGoldenWafer unless a higher-priority condition exists.

系统设计决策

• 纯函数降低非决定性。 当计算不依赖外部状态时，Kiro 产生的代码更容易信任。开发人员可以有信心地测试、审查与重构领域层。
• 集中阈值改善可维护性。 散落在 UI 与测试中的阈值会造成未来漂移。单一常数区段让审查与依图层扩充更直接。
• 优先顺序审查防止误导性建议。 一般分数可能掩藏严重条件。明确的优先规则确保安全相关发现优先于较低层级的观察状态。

---

提示组 5 — UI 实作

提示 5.1 — Render 仪表板

Implement the UI rendering layer. Show summary metrics, tool rows, risk score, blind-window age, TMG, slope, Fleet σ, residual 3σ, action button, and reason details. Add search and sort. Keep rendering separate from risk calculations.

提示 5.2 — 无障碍审查

Review the UI for accessibility. Add semantic headings, button labels, sufficient contrast, keyboard-accessible interactions, useful empty states, and readable status text. Do not change domain logic.

系统设计决策

• UI 使用评估结果，而不是自行计算。 这让视觉程序代码专注在 render、互动与无障碍功能。业务规则留在领域层。
• 搜索与排序会揭示模型品质。 良好的产生 UI 不应只显示卡片，也应支持操作工作流程。依风险、TMG、斜率与 Fleet 偏差排序，能让入口网站真正有用。
• 将无障碍视为实作品质。 开发人员应要求 Kiro 审查语义与互动状态，再手动检查结果。无障碍不能成为事后补救。

---

提示组 6 — 测试

提示 6.1 — 产生测试

Generate Vitest tests for the risk engine. Cover healthy release, TMG ApcGuard, Mandel Slope HoldReview, Fleet deviation HoldReview, residual RunGoldenWafer, blind-window Watch, reason strings, and priority ordering when multiple thresholds are breached.

提示 6.2 — 询问遗漏案例

Analyze the current risk tests and list missing edge cases. Focus on threshold equality, just-over thresholds, negative inputs, NaN handling, empty series, and action priority conflicts. Do not modify files yet.

系统设计决策

• 阈值边界测试是必要的。 Production bug 常在刚好等于限制值时出现。Kiro 应测试相等与刚超过的案例，让规则解读明确。
• 无效数据处理必须刻意决定。 Demo 可以很简单，但专业开发人员应决定如何处理负值、NaN 或遗漏阵列，而不是让产生的代码意外决定行为。
• 先分析再修改能改善控制。 先要求 Kiro 列出遗漏测试，为开发人员提供一个在接受产生变更前的审查检查点。

---

提示组 7 — Hooks

提示 7.1 — 建立 Command Hook

Create a Kiro workspace hook that runs npm test after saving files under src/domain or tests. Use PostFileSave, a narrow matcher, command action, 60-second timeout, and enabled true.

提示 7.2 — 建立文件 Hook

Create a Kiro agent hook that updates docs/decision-log.md after a spec task is completed. The hook should summarize changed files, decisions made, and follow-up risks. Keep it workspace-local and do not modify source code.

系统设计决策

• Command hooks 用于决定性检查。 测试与 linting 有明确的成功或失败行为，因此自动化安全且可量测。
• Agent hooks 用于叙事工作。 Decision log 需要摘要与情境。Kiro 的语言能力在这里很有用，但 hook 应限制在文件范围。
• Matcher 保护开发人员生产力。 Hooks 只应在相关档变更时触发。范围过大的自动化会产生杂讯、拖慢开发并降低信任。

---

完整代码参考 — 领域层

src/domain/types.ts

export type AdvisoryAction =
  | "Release"
  | "Watch"
  | "RunGoldenWafer"
  | "RouteLimit"
  | "ApcGuard"
  | "HoldReview";

export type RiskLevel = "low" | "medium" | "high" | "critical";

export interface CdSemTool {
  id: string;
  layer: string;
  symptom: string;
  blindWindowHours: number;
  tmgNm: number;
  mandelSlope: number;
  fleetDeviationSigma: number;
  residualThreeSigmaNm: number;
  deltaMeanSeries: number[];
}

export interface RiskAssessment {
  toolId: string;
  score: number;
  level: RiskLevel;
  action: AdvisoryAction;
  reasons: string[];
}

说明

商业逻辑： 类型定义入口网站各處使用的领域合约，让风险输入与输出清楚。

代码逻辑： AdvisoryAction 与 RiskLevel 是 union type，因此 TypeScript 会拒绝无效字符串。介面定义必要字段。

预期结果： Kiro 产生的模块共享相同数据合约，若字段漂移，会在类型检查期间快速失败。

---

完整代码参考 — 风险引擎

src/domain/risk.ts

import type { AdvisoryAction, CdSemTool, RiskAssessment, RiskLevel } from "./types";

const LIMITS = {
  tmgUclNm: 0.2,
  slopeLow: 0.98,
  slopeHigh: 1.02,
  fleetWatchSigma: 2,
  fleetHoldSigma: 3,
  residualUclNm: 0.18,
  blindWindowWatchHours: 6
};

export function assessTool(tool: CdSemTool): RiskAssessment {
  let score = 0;
  const reasons: string[] = [];

  if (tool.tmgNm > LIMITS.tmgUclNm) {
    score += 30;
    reasons.push("TMG exceeds demo UCL");
  }

  if (tool.mandelSlope < LIMITS.slopeLow || tool.mandelSlope > LIMITS.slopeHigh) {
    score += 25;
    reasons.push("Mandel Slope outside safe range");
  }

  if (tool.fleetDeviationSigma > LIMITS.fleetHoldSigma) {
    score += 35;
    reasons.push("Fleet deviation exceeds hold threshold");
  } else if (tool.fleetDeviationSigma > LIMITS.fleetWatchSigma) {
    score += 20;
    reasons.push("Fleet deviation exceeds watch threshold");
  }

  if (tool.residualThreeSigmaNm > LIMITS.residualUclNm) {
    score += 20;
    reasons.push("Residual 3σ exceeds noise threshold");
  }

  if (tool.blindWindowHours > LIMITS.blindWindowWatchHours) {
    score += 15;
    reasons.push("SPC blind window is stale");
  }

  const normalizedScore = Math.min(score, 100);

  return {
    toolId: tool.id,
    score: normalizedScore,
    level: classifyRisk(normalizedScore),
    action: chooseAction(tool, normalizedScore),
    reasons: reasons.length > 0 ? reasons : ["No threshold breach detected"]
  };
}

export function classifyRisk(score: number): RiskLevel {
  if (score >= 85) return "critical";
  if (score >= 65) return "high";
  if (score >= 35) return "medium";
  return "low";
}

export function chooseAction(tool: CdSemTool, score: number): AdvisoryAction {
  if (tool.fleetDeviationSigma > LIMITS.fleetHoldSigma) return "HoldReview";
  if (tool.mandelSlope < LIMITS.slopeLow || tool.mandelSlope > LIMITS.slopeHigh) return "HoldReview";
  if (tool.tmgNm > LIMITS.tmgUclNm) return "ApcGuard";
  if (tool.residualThreeSigmaNm > LIMITS.residualUclNm) return "RunGoldenWafer";
  if (score >= 65) return "RouteLimit";
  if (score >= 35) return "Watch";
  return "Release";
}

说明

商业逻辑： 此函数将 fab 测量指标转换为风险严重程度与建议动作，并凸显哪些指标造成判定。

代码逻辑： 每个阈值都会增加分数与原因。分数上限为 100。动作选择使用优先规则，避免严重条件被降级。

预期结果： 开发人员可以信任入口网站一致分类已知条件，并解释机台为何具有风险。

---

完整代码参考 — Hook