使用 Kiro 构建：他加禄语学习 App 的提示优先产品设计工作坊

受众： 熟悉 TypeScript、React、JSON 与基本测试的专业开发者 时长： 2 小时 主要 AWS AI 服务： Kiro 项目输出： 一个以 React 静态句子卡为基础的 App，将产品提示转成经审查的模式、UI、测试与发布检查清单。

仅限教育工程研讨会。这是一项软件架构练习，而非流程发布建议。

工作坊摘要

本工作坊带领开发者从原始产品提示出发，完成经测试的 他加禄语句子卡App。参与者使用 Kiro 定义产品意图、整理需求、设计类型化卡片模式、构建 React 渲染器并加入验证。完成后，开发者将理解提示优先规划如何把语言学习想法转成可审查的实施任务与可靠发布检查，提供更安全且一致的学习体验。

开发者将构建的内容

开发者将构建一个 他加禄语句子卡学习 App。此 App 存储经整理的句子卡，并呈现自然 他加禄语、礼貌 他加禄语、友善 Filipino-English、活泼 Filipino-English、语气、文化上下文、语法、例句与发音。工作坊使用 Kiro 作为 AI 工程环境：开发者会建立 steering 文件、产生规格、审查需求、将规格转成实施任务、编写代码、产生测试，并以 hook 自动化质量检查。

2 小时议程

前提条件

node --version   # 20+
npm --version

建议的本机结构：

tagalog-prompt-first-app/
  .kiro/
    steering/
    specs/tagalog-learning-app/
  src/
    data/
    components/
    lib/
    tests/
  package.json

---

步骤 1 — 建立 Kiro 工作区与 steering 文件

Kiro 提示示例

為 AWS Manila Community Day 的 他加祿語學習 App 建立基礎 steering 文件。
此 App 以教育用途為主、非商業，並且對初學者友善。
使用 TypeScript、React、Vite、Vitest 與 CSS Modules。
App 必須分開 natural 他加祿語、polite 他加祿語、friendly Filipino-English 與 playful Filipino-English。
一律將 playful style 標示為 informal。
語言內容在 正式環境使用前必須經過 母語人士審查。

系统设计决策

● 先建立持久上下文，再进行产生： 先使用 steering 文件，是因为 App 具有不应在每次 Kiro 对话中重复说明的领域规则。此领域不只是 UI 呈现，也包含文化尊重、礼貌标记、活泼语气界线与审查要求。将这些规则写入 .kiro/steering/product.md、.kiro/steering/tech.md 与 .kiro/steering/structure.md，可让 Kiro 取得持久上下文，使后续代码建议遵循相同的产品期待。

● 工作区本机治理： 将 steering 文件保存在代码库中，而不是只依赖个人记忆。专业团队需要可审查的 AI 指引，就像审查架构决策记录一样。本机 steering 让产品范围、技术选择与文件惯例能在 Pull Request、新人导入、审计与未来工作坊中清楚可见。

● 人工审查安全性： 此 App 教授语言与文化，因此产生的内容不能被视为权威。steering 层明确要求 母语人士审查、适合初学者的措辞，以及避免刻板印象。这项设计让质量保证成为系统层级的关注点，而不只是最后的人工提醒。

代码示例 — .kiro/steering/product.md

# Product Overview

此工作區會建置一個教育用途的 他加祿語學習 App，協助準備 AWS Manila Community Day。
此 App 協助初學者練習活動中的禮貌短句，涵蓋問候、方向、工作坊、志工、等待時間與道別。

## 產品規則

- 先顯示 natural 他加祿語，再顯示 playful Filipino-English。
- 與講者、主辦者、志工、場地人員、長輩或第一次見面的人說話時，顯示 polite 他加祿語。
- 適當時說明 `po`、`opo`、`kayo` 與 `ninyo` 是尊重標記。
- 將 playful Filipino-English 標示為 informal。
- 讓例句短到適合手機閱讀。
- 正式環境發布前必須經過 母語人士審查。

代码说明

● 商业逻辑： 此文件定义会影响每个产生功能的学习产品规则。它避免 App 变成一般翻译器，并让工作坊聚焦在活动场景可用的学习。

● 代码逻辑： 虽然这是 Markdown，Kiro 会把它视为持久的项目上下文。未来产生的代码、测试与文件都应遵守这些规则。

● 预期结果： 当开发者要求 Kiro 构建组件或测试时，Kiro 应保持自然、礼貌、友善与活泼输出彼此分离，并加入审查提醒。

---

步骤 2 — 将产品想法转成 Kiro 规格

Kiro 提示示例

建立名為 tagalog-learning-app 的 規格。
功能：呈現已審查的句子卡，供 AWS Manila Community Day 準備使用。
產生 requirements、design 與 實作任務。
使用 EARS 風格驗收條件。
第一版為靜態版本，而且只使用本機 JSON 資料。

系统设计决策

● 以 规格 驱动开发，而不是直接写程序： 工作坊从 规格 开始，因为产品需要在用户目标、数据字段、UI 行为与测试之间保持可追溯性。直接 code-first 可能快速做出画面，但很难验证礼貌、语气标签、语法支持与行动装置可读性是否一致处理。规格 会成为实施的单一事实来源。

● 先完成静态版本，再准备上云： 第一版使用本机 JSON，因为核心风险是内容形状，而不是基础设施。静态 App 让开发者能在两小时内验证 模式、呈现、测试与审查流程。契约通过验证后，同一份数据形状可以移到 S3、DynamoDB 或 API，而不必重新设计学习卡片。

● 将验收条件当作测试： EARS-style 陈述让产品行为可测试。例如：「当卡片包含 playful Filipino-English 时，UI 应显示 informal 标签。」这会把文化与教育需求转成实施约束，对专业开发者工作坊至关重要。

代码示例 — .kiro/specs/tagalog-learning-app/requirements.md

# Requirements

## Requirement 1：句子卡呈現

User story：身為初學者，我想看到一個英文句子，以及 natural、polite、friendly 與 playful 變體，這樣我就能在活動中選擇正確語氣。

Acceptance criteria：

1. WHEN 句子卡被呈現 THEN 系統 SHALL 顯示 English input、natural 他加祿語、polite 他加祿語、friendly Filipino-English、playful Filipino-English 與 tone。
2. WHEN playful Filipino-English 被顯示 THEN 系統 SHALL 將它標示為 informal。
3. WHEN polite 他加祿語 被顯示 THEN 系統 SHALL 加入何時使用尊重說法的文化脈絡。

## Requirement 2：Mobile-first 學習

Acceptance criteria：

1. WHEN viewport 很窄 THEN 句子卡 SHALL 保持可讀且不需要水平捲動。
2. WHEN 文法註記 被呈現 THEN 系統 SHALL 使用短清單項目。
3. WHEN 發音 被呈現 THEN 它 SHALL 顯示在 他加祿語 片語附近。

代码说明

● 商业逻辑： 需求描述学习者体验，并定义 App 必须教会的内容。

● 代码逻辑： 每个验收条件都可以对应到组件属性、DOM 断言 或无障碍检查。

● 预期结果： Kiro 可以产生任务与测试来验证产品行为，而不只是检查组件是否能编译。

---

步骤 3 — 定义句子卡数据契约

Kiro 提示示例

為 他加祿語句子卡產生 TypeScript 資料合約。
包含 English input、natural 他加祿語、polite 他加祿語、friendly Filipino-English、playful Filipino-English、tone、cultural context、grammar breakdown、例句、發音、category 與 審查狀態 欄位。
加入兩張來自 Community Day 情境的範例卡片。

系统设计决策

● 先有 模式，再扩展内容： 稳定的 TypeScript 类型能保护 App，避免 AI 产生内容不一致。一旦契约定义完成，每张句子卡都必须包含相同的必要字段。这能避免 AI 辅助开发常见问题：每张产生的卡片标签略有不同、缺少语法说明，或例句格式不一致。

● 把审查状态视为一级数据： 模式 中包含 reviewStatus，因为语言内容存在质量风险。开发者常把审查注记放在注解或试算表中，但App需要知道内容是 draft、reviewed 还是 blocked。将审查状态视为数据，可支持筛选、徽章、发布闸门与未来审核工作流程。

● 将多种语气版本拆成独立字段： Natural 他加禄语、polite 他加禄语、friendly Filipino-English 与 playful Filipino-English 是独立字段，因为它们服务不同的学习目的。把它们混在一个文字区块中，会削弱 UI 呈现、测试与学习者理解。字段分离也能支持未来搜索、标记与分析。

代码示例 — src/data/cards.ts

export type ReviewStatus = "draft" | "native-reviewed" | "blocked";

export interface GrammarItem {
  term: string;
  meaning: string;
}

export interface ExampleSentence {
  tagalog: string;
  english: string;
}

export interface PronunciationGuide {
  full: string;
  stress: string;
  speakingTip: string;
}

export interface SentenceCard {
  id: string;
  category: "greetings" | "directions" | "workshops" | "volunteers" | "waiting";
  englishInput: string;
  naturalTagalog: string;
  politeTagalog: string;
  friendlyFilipinoEnglish: string;
  playfulFilipinoEnglish: string;
  tone: string;
  culturalContext: string;
  grammar: GrammarItem[];
  例句: ExampleSentence[];
  發音: PronunciationGuide;
  reviewStatus: ReviewStatus;
}

export const cards: SentenceCard[] = [
  {
    id: "greeting-001",
    category: "greetings",
    englishInput: "Hello, I am learning Tagalog.",
    naturalTagalog: "Kumusta, nag-aaral ako ng Tagalog.",
    politeTagalog: "Kumusta po, nag-aaral po ako ng Tagalog.",
    friendlyFilipinoEnglish: "Hello po, learning Tagalog ako.",
    playfulFilipinoEnglish: "Kumusta, learning Tagalog na ako, all right.",
    tone: "friendly, beginner-friendly, event-ready",
    culturalContext:
      "Use the polite version with volunteers, speakers, organizers, venue staff, elders, or people you meet for the first time.",
    grammar: [
      { term: "Kumusta", meaning: "hello or how are you" },
      { term: "po", meaning: "politeness marker" },
      { term: "nag-aaral", meaning: "studying or learning" }
    ],
    例句: [
      { tagalog: "Kumusta po kayo?", english: "How are you?" },
      { tagalog: "Nag-aaral po ako.", english: "I am learning." },
      { tagalog: "Salamat po sa tulong.", english: "Thank you for the help." }
    ],
    發音: {
      full: "koo-MOOS-tah poh, nag-ah-AH-ral poh AH-koh ngah tah-GAH-log",
      stress: "Stress MOOS, AH, and GAH.",
      speakingTip: "Say po softly and keep the greeting warm."
    },
    reviewStatus: "draft"
  },
  {
    id: "workshop-001",
    category: "workshops",
    englishInput: "May I ask a question?",
    naturalTagalog: "Puwede ba akong magtanong?",
    politeTagalog: "Puwede po ba akong magtanong?",
    friendlyFilipinoEnglish: "Can I ask po?",
    playfulFilipinoEnglish: "Question time na ako, all right?",
    tone: "polite, practical, workshop-ready",
    culturalContext:
      "Use the polite version before asking speakers, mentors, or organizers a question during a session.",
    grammar: [
      { term: "Puwede", meaning: "may or can" },
      { term: "ba", meaning: "question marker" },
      { term: "magtanong", meaning: "to ask" }
    ],
    例句: [
      { tagalog: "Puwede po ba akong umupo dito?", english: "May I sit here?" },
      { tagalog: "Puwede po bang pakiulit?", english: "Could you please repeat?" },
      { tagalog: "Puwede po bang sumali?", english: "May I join?" }
    ],
    發音: {
      full: "PWEH-deh poh bah AH-kong mag-tah-NONG",
      stress: "Stress PWEH, AH, and NONG.",
      speakingTip: "Make the question sound gentle, not demanding."
    },
    reviewStatus: "draft"
  }
];

代码说明

● 商业逻辑： 此 模式 代表 App 对学习者的承诺：一个句子、多种语气、语法、例句、发音与审查状态。

● 代码逻辑： TypeScript 界面 会强制数据符合预期格式。 cards 数组会提供渲染器强类型数据。

● 预期结果： App 可以一致地呈现每张句子卡。如果开发者忘记必要字段，就会出现类型错误。

---

步骤 4 — 构建 React 句子卡渲染器

Kiro 提示示例

建立名為 SentenceCardView 的 React 元件。
它接收 SentenceCard，並以可存取的標題與清單呈現每個欄位。
Playful Filipino-English 必須顯示 Informal 徽章。
審查狀態必須可見。

系统设计决策

● 每个契约对应一个组件： 渲染器接收一个 SentenceCard，且不直接提取数据。这种分离让 UI 可预测、可测试且可重复使用。开发者日后可以从本机 JSON、API 或静态产生档加载卡片，而不必变更呈现逻辑。

● 明确标示语气： UI 会以 informal 徽章显示 playful Filipino-English，因为学习者可能直接复制眼前内容。语气标签不是装饰，而是安全与教育控制。组件应教导学习者：活泼语言不同于正式他加禄语。

● 可访问的内容阶层： 语言卡片可能变得信息密集。语义化区段、标题、清单与可读标签，能让 App 在行动装置上可用，并对辅助科技友善。可访问性是系统设计的一部分，因为目标环境是使用多种装置的公开社区活动。

代码示例 — src/components/SentenceCardView.tsx

import type { SentenceCard } from "../data/cards";
import "./SentenceCardView.css";

interface Props {
  card: SentenceCard;
}

export function SentenceCardView({ card }: Props) {
  return (
    <article className="sentence-card" aria-labelledby={`${card.id}-title`}>
      <header className="sentence-card__header">
        <p className="sentence-card__category">{card.category}</p>
        <h2 id={`${card.id}-title`}>{card.englishInput}</h2>
        <span className={`review review--${card.reviewStatus}`}>{card.reviewStatus}</span>
      </header>

      <section aria-label="他加祿語 variants" className="sentence-card__variants">
        <p><strong>Natural 他加祿語:</strong> <span lang="tl">{card.naturalTagalog}</span></p>
        <p><strong>Polite 他加祿語:</strong> <span lang="tl">{card.politeTagalog}</span></p>
        <p><strong>Friendly Filipino-English:</strong> {card.friendlyFilipinoEnglish}</p>
        <p>
          <strong>Playful Filipino-English:</strong> {card.playfulFilipinoEnglish}
          <span className="badge">Informal</span>
        </p>
      </section>

      <section aria-label="Learning 註記s">
        <p><strong>Tone:</strong> {card.tone}</p>
        <p><strong>Cultural context:</strong> {card.culturalContext}</p>
      </section>

      <section aria-labelledby={`${card.id}-grammar`}>
        <h3 id={`${card.id}-grammar`}>Grammar breakdown</h3>
        <ul>
          {card.grammar.map((item) => (
            <li key={item.term}><strong>{item.term}:</strong> {item.meaning}</li>
          ))}
        </ul>
      </section>

      <section aria-labelledby={`${card.id}-例句`}>
        <h3 id={`${card.id}-例句`}>Examples</h3>
        <ol>
          {card.例句.map((example) => (
            <li key={example.tagalog}>
              <span lang="tl">{example.tagalog}</span><br />
              <span>{example.english}</span>
            </li>
          ))}
        </ol>
      </section>

      <section aria-labelledby={`${card.id}-發音`}>
        <h3 id={`${card.id}-發音`}>Pronunciation</h3>
        <p>{card.發音.full}</p>
        <p>{card.發音.stress}</p>
        <p>{card.發音.speakingTip}</p>
      </section>
    </article>
  );
}

代码说明

● 商业逻辑： 此组件会将经审查的学习卡片转成面向学习者的课程。

● 代码逻辑： 它会从类型化卡片呈现结构化区段，将语法与例句映射为清单，为 他加禄语文字加入 lang="tl"，并将 informal 徽章套用到活泼输出。

● 预期结果： 开发者会看到包含所有必要学习字段的完整卡片，学习者也能辨识哪个句子是自然、礼貌、友善或 informal。

---

步骤 5 — 加入响应式样式

Kiro 提示示例

為 SentenceCardView 建立 行動優先 CSS。
使用易讀間距、高對比、可見的 informal 徽章，並確保小螢幕不需要水平捲動。

系统设计决策

● 因活动准备场景而采用 行动优先： 学习者可能在通勤、排队或坐在场次中使用 App。界面必须优先考虑小屏幕可读性，而不只是桌面呈现。

● 使用卡片而非表格： 表格版面会压缩较长的语言字段并降低可读性。卡片能让每个学习区段保有空间，尤其是语法与发音。这是产品决策，因为语言学习需要快速扫描与口说练习。

● 审查与语气的视觉状态： 徽章与审查标签能帮助用户快速理解信心水准与语气。在学习产品中，视觉阶层可降低认知负荷，并避免 informal 内容被误认为建议的正式答案。

代码示例 — src/components/SentenceCardView.css

.sentence-card {
  border: 1px solid #d0d7de;
  border-radius: 16px;
  padding: 1rem;
  margin: 1rem 0;
  background: #ffffff;
  color: #1f2328;
  line-height: 1.6;
}

.sentence-card__header {
  display: grid;
  gap: 0.5rem;
}

.sentence-card__category {
  margin: 0;
  font-size: 0.85rem;
  color: #57606a;
  text-transform: uppercase;
  letter-spacing: 0.04em;
}

.sentence-card__variants {
  border-left: 4px solid #ff9900;
  padding-left: 1rem;
}

.badge,
.review {
  display: inline-block;
  margin-left: 0.5rem;
  padding: 0.15rem 0.5rem;
  border-radius: 999px;
  font-size: 0.75rem;
  font-weight: 700;
}

.badge {
  background: #fff3cd;
  color: #7a4d00;
}

.review--draft {
  background: #eaeef2;
  color: #57606a;
}

.review--native-reviewed {
  background: #dafbe1;
  color: #116329;
}

.review--blocked {
  background: #ffebe9;
  color: #82071e;
}

@media (min-width: 760px) {
  .sentence-card {
    padding: 1.5rem;
  }

  .sentence-card__header {
    grid-template-columns: 1fr auto;
    align-items: start;
  }
}

代码说明

● 商业逻辑： 样式通过让分类、语气与审查状态容易扫描，支持学习任务。

● 代码逻辑： CSS 使用卡片容器、响应式 grid 标头、变体左侧强调线，以及 informal／审查状态的徽章样式。

● 预期结果： UI 在行动装置上保持可读，在较大屏幕上则更宽敞。

---

步骤 6 — 呈现 App shell

Kiro 提示示例

建立 App.tsx，呈現 src/data/cards.ts 中的所有句子卡。
加入簡短免責聲明，說明產生內容需要 母語人士審查。

系统设计决策

● 为工作坊可靠性采用静态 shell： 在两小时工作坊中，App 应能在没有外部 API 或网络凭证的情况下执行。这能降低设置阻力，让开发者专注于 Kiro 的 spec-to-code 工作流程。

● 在产品 UI 中放入免责声明： 语言学习原型必须向用户传达审查状态。将免责声明放在 App shell 中，可让限制在展示时可见，而不是藏在文件里。

● 导入数据而非硬编码 JSX： shell 会映射 cards，证明 UI 是数据驱动。当更多内容被产生或审查时，App 可通过新增数据扩展，而不是复制 UI 标记。

代码示例 — src/App.tsx

import { cards } from "./data/cards";
import { SentenceCardView } from "./components/SentenceCardView";

export default function App() {
  return (
    <main className="app-shell">
      <header>
        <h1>AWS Manila Community Day 他加祿語學習卡</h1>
        <p>
          教育用途原型。正式環境使用前，請與母語人士審查 他加祿語翻譯、
          文法註記 與文化指引。
        </p>
      </header>

      {cards.map((card) => (
        <SentenceCardView key={card.id} card={card} />
      ))}
    </main>
  );
}

代码说明

● 商业逻辑： shell 会将 App 呈现为教育原型，并呈现所有可用的学习卡片。

● 代码逻辑： React 会将类型化的 cards 数组映射到可重复使用的 SentenceCardView 组件。

● 预期结果： 执行 App 后会看到标题、审查免责声明，以及每笔数据项目对应的一张 UI 卡片。

---

步骤 7 — 产生测试并使用 Kiro hook 进行质量检查

Kiro 提示示例

為 SentenceCardView 產生 Vitest 測試。
驗證 natural 他加祿語、polite 他加祿語、informal 徽章、文法註記、例句、發音 與 審查狀態 都能正確呈現。
接著建立一個 Kiro hook 想法：當 來源檔案 儲存時執行測試。

系统设计决策

● 测试对应验收条件： 测试不应只检查 快照。它们应断言必要学习字段会出现，且活泼内容会标示为 informal。这能让实施与 规格 保持一致，并在加入更多卡片或样式时防止回归。

● 以 hook 辅助纪律： Kiro hooks 很有价值，因为开发者在快速 AI 辅助构建时常忘记重复性的验证步骤。file-save hook 或 pre-commit hook 可以提醒团队执行测试、更新文件或验证卡片模式。

● 产生内容的质量闸门： AI 辅助的代码与内容应通过可重复的决定性检查。测试提供稳定安全网，而人工审查处理语言细节。这种分层质量设计将机械正确性与文化正确性分开处理。

代码示例 — src/tests/SentenceCardView.test.tsx

import { render, screen } from "@testing-library/react";
import { describe, expect, it } from "vitest";
import { SentenceCardView } from "../components/SentenceCardView";
import { cards } from "../data/cards";

describe("SentenceCardView", () => {
  it("renders all required learning sections", () => {
    render(<SentenceCardView card={cards[0]} />);

    expect(screen.getByText(cards[0].englishInput)).toBeInTheDocument();
    expect(screen.getByText(cards[0].naturalTagalog)).toBeInTheDocument();
    expect(screen.getByText(cards[0].politeTagalog)).toBeInTheDocument();
    expect(screen.getByText(cards[0].friendlyFilipinoEnglish)).toBeInTheDocument();
    expect(screen.getByText(cards[0].playfulFilipinoEnglish)).toBeInTheDocument();
    expect(screen.getByText("Informal")).toBeInTheDocument();
    expect(screen.getByText("Grammar breakdown")).toBeInTheDocument();
    expect(screen.getByText("Examples")).toBeInTheDocument();
    expect(screen.getByText("Pronunciation")).toBeInTheDocument();
    expect(screen.getByText(cards[0].reviewStatus)).toBeInTheDocument();
  });
});

代码说明

● 商业逻辑： 测试会确认每张句子卡都教授必要的学习面向。

● 代码逻辑： Testing Library 会呈现组件，并搜索第一张卡片中的预期文字。

● 预期结果： 当 UI 呈现所有必要卡片字段时测试会通过；如果字段消失，测试会失败。

Kiro hook 示例 — .kiro/hooks/run-tests-on-save.md

# Hook：儲存 source 時執行測試

Trigger：當 `src/` 底下的檔案被儲存。
Action：
1. 執行 `npm test -- --run`。
2. 如果測試失敗，摘要失敗測試並建議最小修正。
3. 如果卡片資料有變更，提醒開發者確認 reviewStatus 與 母語人士審查 註記s。

Hook 说明

● 商业逻辑： hook 会在快速迭代期间保护教育契约。

● 代码逻辑： 它会将来源文件变更连结到测试执行与审查提醒。

● 预期结果： 当 UI 或数据变更破坏学习需求时，开发者会立即收到反馈。

---

步骤 8 — 最终 Kiro 审查与扩展任务

Kiro 提示示例

依照 規格 審查實作。
找出缺少的 requirements、薄弱測試、不清楚標籤與 mobile-readability 風險。
建議接下來五個任務，用來加入 directions、volunteer thanks、waiting time 與 goodbye 分類。

系统设计决策

● 先审查，再扩大： 在前两张卡片正确之前，App 不应产生数十个分类。专业工作流程会在扩展内容前，先验证契约、组件、测试与审查流程。

● 让 Kiro 担任审查者，而不只是产生器： Kiro 可以说明 规格 与代码之间的落差、提出下一步任务并产生文件。这能帮助开发者把 AI 当成工程协作者，而不是 code-completion 捷径。

● 逐步扩展分类： 新分类应重用相同的 模式 与组件。这能保持架构简单并避免功能偏移。产品通过数据与测试扩展，而不是通过新的 一次性 页面扩展。

完成检查清单

● .kiro/steering/product.md 记录产品规则。

● .kiro/specs/tagalog-learning-app/requirements.md 已存在。

● TypeScript SentenceCard 契约已存在。

● 至少两张卡片可正确呈现。

● Playful Filipino-English 显示 informal 徽章。

● 审查状态出现在 UI 中。

● 组件测试通过。

● 已有用于测试自动化的 Kiro hook 指引。

工作坊后的选用 AWS 扩展

● 将静态构建托管在 AWS Amplify Hosting 或 Amazon S3。

● 加入 Amazon CloudFront 进行全球交付。

● 将经审查的卡片存储在 Amazon S3 JSON。

● 日后使用 Amazon Bedrock 进行受控的 draft-card 产生，并在发布前进行人工审查。

---

额外动手开发实验

以下实验会以更具体的开发者操作加深工作坊内容。它们是为想练习把 Kiro 当作工程工作流程工具，而不只是 chat assistant 的专业开发者所设计。这些实验刻意使用 Kiro steering、规格、agentic chat、hooks、任务执行、测试产生、文件产生、审查支持与 MCP-ready 整合模式。

动手实验 A — 使用 Kiro agentic chat 初始化代码库

开发者操作

● 在 Kiro 中开启项目文件夹。

● 要求 Kiro 检查空白工作区并提出最小结构。

● 要求 Kiro 产生初始文件，然后在接受变更前审查 diff。

● Kiro 建立文件后，手动执行本机 App 或产生器命令。

Kiro 提示示例

檢查此工作區並建立最小實作計畫。
如果既有 steering 與 規格 檔案存在，請使用它們。
不要產生不必要的基礎設施。
只建立第一個 vertical slice 所需的檔案。
提出變更後，說明每個檔案以及它存在的原因。

系统设计决策

● 从工作区检查开始： Kiro 应先理解既有内容，再产生文件。这能避免重复文件夹、相冲突的依赖软件包与意外重新设计。在专业工作坊中，这就像开发者加入既有代码库的流程：检查、理解，然后变更。工作区检查也让 Kiro 能在实施前连结 steering 文件、规格 与源代码。

● 产生 vertical slice： 第一个实施应证明从数据到可见结果的最小完整路径。vertical slice 比构建许多彼此断开的工具更好，因为它会同时验证产品契约、渲染器、测试设置与开发者工作流程。这能提供参与者快速反馈并避免过度工程化。

● 接受前审查 diff： Kiro 可以快速产生有用代码，但专业开发者仍拥有代码库责任。审查 diff 能强化责任感、抓出不想要的假设，并教导参与者把 Kiro 当作工程助理协作，而不是盲目委派。

代码示例 — React 工作坊变体的 package.json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest --environment jsdom",
    "test:run": "vitest --environment jsdom --run",
    "lint:data": "node scripts/validate-cards.mjs"
  },
  "dependencies": {
    "@vitejs/plugin-react": "latest",
    "vite": "latest",
    "typescript": "latest",
    "react": "latest",
    "react-dom": "latest"
  },
  "devDependencies": {
    "vitest": "latest",
    "@testing-library/react": "latest",
    "@testing-library/jest-dom": "latest",
    "jsdom": "latest"
  }
}

代码说明

● 商业逻辑： 这些 scripts 定义开发者反馈循环：执行 App、构建 生产环境输出、执行测试，并验证学习卡片数据。

● 代码逻辑： dev 会启动 Vite，build 会编译 TypeScript 并打包 App，test 会执行组件测试，lint:data 会执行自定义卡片验证器。

● 预期结果： 开发者可以在整个工作坊中使用相同的命令词汇，Kiro 也能在产生 hooks 与任务计划时引用这些 scripts。

---

动手实验 B — 产生并精炼 Kiro steering 文件

开发者操作

● 在 Kiro 中产生基础 steering 文件。

● 手动编辑 product、tech 与 structure steering 文件。

● 要求 Kiro 摘要 steering 文件将如何影响未来实施。

● 为语言内容审查建立一个额外 steering 文件。

Kiro 提示示例

為此工作區產生基礎 steering 文件。
接著加入 language-review steering 檔案。
此 App 教授活動準備用的 他加祿語，因此實作必須讓 審查狀態 可見、標示 informal 內容，並避免將產生的語言內容呈現為 最終版本。
說明每個 steering 檔案將如何引導未來程式碼產生。

系统设计决策

● 分离产品、技术与内容规则： 产品规则说明学习者成果，技术规则限制实施选择，内容规则保护教育质量。拆分这些关注点可让 steering 更容易审查与更新。这也能帮助 Kiro 在产生组件、测试、hook 或文件页面时提取正确上下文。

● 让审查政策持久化： 母语人士审查 要求必须超越单一 chat 消息。如果它只写在暂时对话中，未来产生的卡片可能会省略审查状态或夸大正确性。持久 steering 文件会让政策成为工作区运作模型的一部分。

● 使用 steering 对齐团队： 在开发者工作坊中，参与者可能产生项目变体。steering 文件让这些变体收敛到相同标准。当多位开发者并行要求 Kiro 产生代码且仍需要一致输出时，这特别有用。

代码示例 — .kiro/steering/language-review.md

# 語言審查標準

所有 他加祿語學習內容在母語人士審查前，都是教育用途 草稿內容。
UI 必須在學習者看得到的位置顯示 審查狀態。
不要只把 審查狀態 藏在 註解、日誌 或 文件 中。

## 必要欄位

- `reviewStatus`: draft, native-reviewed, or blocked
- `reviewNotes`: 給 審查者 的簡短 註記
- `lastReviewedAt`: ISO date string or null
- `reviewedBy`: 審查者 name 或 null

## 產生規則

- Natural 他加祿語 顯示在 playful Filipino-English 之前。
- Playful Filipino-English 必須標示為 informal。
- Polite 他加祿語 必須說明何時使用尊重說法較安全。
- 未經審查前，不得宣稱具備最終語言權威。

代码说明

● 商业逻辑： 此文件定义语言质量与学习者透明度的治理方式。

● 代码逻辑： Kiro 可在产生类型、UI 标签、验证 scripts 与测试时，将此 Markdown 作为持久工作区上下文。

● 预期结果： 未来产生的功能会包含可见的审查元数据，且不会将 draft 内容视为 最终版本。

---

动手实验 C — 使用 Kiro 规格 建立需求、设计与任务追踪

开发者操作

● 要求 Kiro 为下一个功能建立 规格。

● 在接受设计前审查 requirements。

● 要求 Kiro 将已接受的设计转换为实施任务。

● 一次执行一个任务，并在每个任务后审查 diff。

Kiro 提示示例

為具備審查意識的句子卡功能建立 規格。
Requirements 必須包含可見 審查狀態、playful Filipino-English 的 informal label、發音 display、文法註記 與 行動裝置可讀性。
完成 requirements 後，建立 design 與排序過的 實作任務。
在 tasks 被審查前不要實作。

系统设计决策

● 先有 requirements，再实施： Specs 会迫使团队在代码存在前先同意行为。这很有价值，因为 AI 辅助实施可能产生看似合理但未审查的行为。Requirements 定义产品必须做什么，以及后续测试应验证什么。

● 先有设计，再有任务： 设计区段会说明组件边界、数据流、验证点与可访问性期待。没有设计时，任务可能变成文件清单，而不是架构。当 Kiro 拥有设计意图，而不只是功能请求时，效果会更好。

● 逐项执行任务： 一次实施一个任务能保持 diff 小，并教导开发者审查 AI 输出。这也让失败更容易隔离。如果组件测试在某个任务后失败，原因会比一大批产生变更后更清楚。

代码示例 — .kiro/specs/review-aware-card/requirements.md

# Requirements

## Requirement 1：可見的審查狀態

Acceptance criteria：

1. WHEN 句子卡被呈現 THEN 系統 SHALL 顯示 `reviewStatus`。
2. WHEN `reviewStatus` 是 `draft` THEN 系統 SHALL 顯示面向學習者的草稿提示。
3. WHEN `reviewStatus` 是 `blocked` THEN 系統 SHALL 不建議使用該卡片練習。

## Requirement 2：語氣安全

Acceptance criteria：

1. WHEN playful Filipino-English 被呈現 THEN 系統 SHALL 顯示 Informal 徽章。
2. WHEN polite 他加祿語 被呈現 THEN 系統 SHALL 顯示何時使用禮貌說法較安全。

代码说明

● 商业逻辑： requirements 会保护学习者，避免将 draft 或 informal 语言误认为 最终版本 建议说法。

● 代码逻辑： 每个验收条件都可成为组件 assertion、数据验证器规则或发布检查。

● 预期结果： Kiro 可以产生直接对应审查与语气需求的实施任务与测试。

---

动手实验 D — 为产生或整理过的卡片数据加入 模式 验证

开发者操作

● 为句子卡数据建立 validator script。

● 手动执行它。

● 要求 Kiro 加入缺少的验证规则。

● 将 validator 串接到 test 或 build 指令。

Kiro 提示示例

為句子卡建立資料驗證 script。
驗證必要欄位、reviewStatus 值、非空 發音、至少三個 grammar items，以及 playful Filipino-English 的 informal label 覆蓋情況。
此 script 應以清楚訊息失敗，並可在 npm scripts 中使用。

系统设计决策

● 将数据验证与 UI 分开： UI 测试能证明呈现结果，但不能保证整份数据集完整。专用 validator 可在 App 呈现前，先找出所有卡片中缺少的字段。当 Kiro 或开发者快速新增大量卡片时，这特别重要。

● 以可行动消息失败： validator 应清楚告诉开发者是哪张卡片、哪个字段失败。清楚的失败消息能降低工作坊阻力，并培养良好发布习惯。模糊失败会迫使开发者手动检查数据，拖慢学习。

● 让验证可被 script 执行： validator 必须能通过 指令、hook 或 CI job 执行。可 script 化会把质量规则变成可重复的工程实务，也让 Kiro 在建立 hooks 或 release tasks 时能引用相同 指令。

代码示例 — scripts/validate-cards.mjs

import { readFileSync } from "node:fs";

const raw = readFileSync("src/data/cards.json", "utf8");
const cards = JSON.parse(raw);

const allowedReviewStatus = new Set(["draft", "native-reviewed", "blocked"]);
const failures = [];

for (const card of cards) {
  const prefix = `Card ${card.id ?? "<missing id>"}`;

  for (const field of ["id", "englishInput", "naturalTagalog", "politeTagalog", "playfulFilipinoEnglish", "發音", "reviewStatus"]) {
    if (!card[field]) failures.push(`${prefix}: missing ${field}`);
  }

  if (!allowedReviewStatus.has(card.reviewStatus)) {
    failures.push(`${prefix}: invalid reviewStatus ${card.reviewStatus}`);
  }

  if (!Array.isArray(card.grammar) || card.grammar.length < 3) {
    failures.push(`${prefix}: expected at least three grammar items`);
  }

  if (card.playfulFilipinoEnglish && card.playfulLabel !== "Informal") {
    failures.push(`${prefix}: playful Filipino-English must use playfulLabel = Informal`);
  }
}

if (failures.length > 0) {
  console.error(failures.join("\n"));
  process.exit(1);
}

console.log(`Validated ${cards.length} cards successfully.`);

代码说明

● 商业逻辑： validator 会在发布前对每张卡片强制执行教育契约。

● 代码逻辑： 它会加载 JSON、检查必要字段、验证允许的 审查状态s、确认 grammar 覆盖率，并在错误时让流程失败。

● 预期结果： 执行 npm run lint:data 时，有效数据会印出成功消息；无效数据会印出清楚的卡片层级错误。

---

动手实验 E — 使用 Kiro hooks 提供自动化质量反馈

开发者操作

● 在 .kiro/hooks/ 中建立 hook 指引。

● 要求 Kiro 精炼 hook triggers 与 actions。

● 存储数据或组件文件，观察建议的验证工作流程。

● 调整 hook，让它只执行相关检查。

Kiro 提示示例

為此工作區建立 Kiro hook 指引。
當 來源資料 變更時，驗證 cards。
當 React 元件 變更時，執行 元件測試。
當 建置腳本 變更時，執行 正式環境 build。
每個 hook 都應摘要失敗內容，並建議最小且安全的修正。

系统设计决策

● 依上下文执行检查： 每次文件变更都执行所有检查会浪费时间。Hook 应将文件类型对应到相关验证：数据变更触发 数据验证、组件变更触发 tests、构建脚本 变更触发 发布检查。这能提供快速反馈，而不会让开发者负担过重。

● 自动化教练： 在工作坊中，hooks 不只是自动化，也会教导工作流程纪律。当 hook 说明失败卡片或缺少标签时，开发者会学到此项目中质量代表什么。Kiro 会成为 审查者 与 coach。

● 小而安全的修正： AI 产生的修正建议应该最小化。当一张卡片缺少 发音 时，hook 不应重写整个 App。小修正能保留开发者控制权，并让 diffs 可审查。

代码示例 — .kiro/hooks/workspace-quality.md

# Hook：工作區品質檢查

## 資料變更
Trigger：`src/data/` 底下的檔案
Action：
1. 執行 `npm run lint:data`。
2. 如果驗證失敗，列出 card IDs 與缺少欄位。
3. 建議最小 JSON 修正。

## 元件變更
Trigger：`src/components/` 底下的檔案
Action：
1. 執行 `npm run test:run`。
2. 摘要失敗的 assertions。
3. 建議最小元件或測試更新。

## 建置變更
Trigger：`package.json`、`vite.config.ts` 或 `scripts/` 底下的檔案
Action：
1. 執行 `npm run build`。
2. 摘要 TypeScript 或 bundling errors。
3. 建議最小安全修正。

代码说明

● 商业逻辑： 此 hook 会在开发者快速迭代时维持学习产品可靠。

● 代码逻辑： 此 Markdown 定义 Kiro 可在工作区内作为自动化指引使用的 trigger/action 行为。

● 预期结果： 开发者编辑数据、组件或构建设置时，会收到针对性的验证反馈。

---

动手实验 F — 加入 Kiro 辅助测试产生与审查

开发者操作

● 要求 Kiro 根据 规格 acceptance criteria 产生测试。

● 审查 tests 是否具有有意义的 assertions。

● 执行测试并要求 Kiro 说明失败原因。

● 为 blocked 内容 加入一个 negative test。

Kiro 提示示例

根據已接受的 requirements 產生測試。
不要建立只有 快照 的測試。
測試可見 審查狀態、blocked 卡片 behavior、informal badge、grammar section、發音 section 與 polite 指引。
寫完測試後，說明每個測試涵蓋哪一項 requirement。

系统设计决策

● 从 requirements 产生测试： 测试应证明 requirements 已被实施，而不只是目前 HTML 符合 快照。Kiro 可以将 acceptance criteria 对应到 assertions，协助开发者让测试与产品行为保持一致。

● Negative tests 很重要： blocked 卡片 不应被建议用于练习。只测 正常路径 会漏掉安全行为。在 draft 或 blocked 内容 不得被推广的教育 App 中，负向测试 特别重要。

● 说明覆盖范围： 要求 Kiro 说明每个测试涵盖哪项 requirement，会让 测试软件包 更容易审查，也会教参与者如何评估 AI 产生的测试，而不是自动认为它们足够。

代码示例 — src/tests/card-policy.test.ts

import { describe, expect, it } from "vitest";

type Card = {
  id: string;
  reviewStatus: "draft" | "native-reviewed" | "blocked";
};

function isPracticeRecommended(card: Card) {
  return card.reviewStatus !== "blocked";
}

describe("card review policy", () => {
  it("does not recommend blocked 卡片 for practice", () => {
    const card = { id: "blocked-001", reviewStatus: "blocked" } satisfies Card;
    expect(isPracticeRecommended(card)).toBe(false);
  });

  it("allows draft cards to appear with visible draft status", () => {
    const card = { id: "draft-001", reviewStatus: "draft" } satisfies Card;
    expect(isPracticeRecommended(card)).toBe(true);
  });
});

代码说明

● 商业逻辑： Blocked content 不得被推荐；草稿内容 只有在 UI 其他地方清楚显示其状态时才可出现。

● 代码逻辑： helper 只会对 blocked 返回 false。测试会验证 blocked 与 draft 行为。

● 预期结果： 如果未来变更推荐了 blocked 卡片，测试软件包 会抓出政策回归。

---

动手实验 G — 使用 MCP-ready 上下文规划且不增加 运行时 复杂度

开发者操作

● 要求 Kiro 提出 MCP 服务器 使用案例，但不要实施。

● 决定未来版本中哪些外部上下文会有帮助。

● 编写 整合 注记，保持目前工作坊 local-first。

● 为未来 MCP 整合 加入 backlog item。

Kiro 提示示例

為此 App 的未來版本建議 MCP-ready 整合 選項。
考慮 design 檔案、content review sheets、issue trackers 與 deployment 中繼資料。
現在不要實作 整合。
建立 backlog 註記，說明此工作坊的 local-first 範圍與未來 MCP 機會。

系统设计决策

● 规划 整合，但不偏离工作坊： MCP 可以连接外部工具与上下文，但两小时构建应保持 local-first。规划未来 整合 可展示能力，同时不增加设置复杂度。

● 将 运行时 App 与工程上下文分开： 面向学习者的 App 不需要直接访问设计工具或 issue trackers。这些 整合 对开发工作流程、审查与规划有用。保持分离可保护 App 的简洁度。

● 把 backlog 当作架构记忆： 编写未来 整合 注记s 可避免想法遗失，同时让目前实施保持聚焦。这也展示 Kiro 如何协助团队记录工程策略。

代码示例 — docs/mcp-backlog.md

# MCP-ready 待辦清單

此工作坊保持 local-first。兩小時建置不需要 MCP 伺服器。

未來 MCP 機會：

1. 連接 design context，讓 Kiro 能將元件對齊已核准的 UI patterns。
2. 連接 content review sheets，讓 Kiro 能讀取 母語人士審查狀態。
3. 連接 issue tracker context，讓 Kiro 能將 bugs 對應到 規格s 與 tasks。
4. 連接 deployment 中繼資料，讓 Kiro 能摘要 發布就緒度。

決策：讓 執行階段 App 與 engineering 整合 保持獨立。

代码说明

● 商业逻辑： 此 注记 捕捉未来工作流程改善，同时保留工作坊的实务范围。

● 代码逻辑： 此 Markdown 文件是 Kiro 与开发者日后可参考的架构文件。

● 预期结果： 参与者可理解 MCP-ready 规划，而工作坊期间不需要外部服务。

---

动手实验 H — 要求 Kiro 进行最终架构审查

开发者操作

● 要求 Kiro 将实施与 steering、规格s 匹配。

● 要求找出风险、缺少的测试与不清楚的内容审查状态。

● 要求 Kiro 产生最终开发者交接 注记。

● 将审查结果转成 backlog tasks。

Kiro 提示示例

對此工作區執行最終架構審查。
將實作與 steering 檔案、規格s 進行比對。
找出 審查狀態 visibility、informal 標示、行動裝置可讀性、tests、資料驗證 與 發布自動化 的落差。
以 嚴重程度、證據 與 建議修正 格式回傳 發現事項。
接著建立開發者交接 註記。

系统设计决策

● 让 Kiro 担任 审查者： 最终审查会使用 Kiro 的 代码库上下文 检查意图与实施是否一致。这不同于要求 Kiro 产生更多代码；它会教开发者用 AI 进行架构审查、测试审查与发布信心检查。

● 以 证据 为基础的 发现事项： Findings 应包含 证据，而不是模糊建议。Evidence 可能是缺少测试档、组件没有徽章，或 validator 忽略 review 注记s。Evidence 让审查更可行且公平。

● 用交接 注记 维持延续性： 工作坊常以可运作代码结束，但文件薄弱。交接 注记 会说明构建了什么、如何执行、已知未完成项目，以及下一步应做什么。这能让成果在课程后仍然有用。

代码示例 — docs/developer-交接.md

# 開發者交接

## 本工作坊完成項目

- 產品、技術、結構與語言審查用的 Kiro steering 檔案。
- 句子卡或產生器工作流程的 Kiro 規格。
- 型別化卡片模型或 Python 內容合約。
- UI 呈現器 或 靜態 HTML 呈現器。
- 驗證與測試 指令。
- 品質檢查用的 hook 指引。

## 執行 指令

npm run dev
npm run test:run
npm run lint:data
npm run build

已知限制

● 语言内容在 母语人士审查前皆为 草稿。

● 运行时 generation 有意排除在第一个工作坊构建范围外。

● MCP 整合 只记录为未来 backlog，尚未实施。

下一步任务

● 加入更多已审查卡片。

● 加入 blocked-card UI 行为。

● 加入部署到 AWS Amplify Hosting 或 Amazon S3。

● 使用相同本机 指令 加入 CI 验证。

代码说明

● 商业逻辑： 交接文件保留工作坊的学习与工程成果。

● 代码逻辑： Markdown 以 Kiro 与开发者可重用的格式记录已构建成果、指令、限制与下一步任务。

● 预期结果： 另一位开发者可以开启代码库、理解目前状态，并安全接续工作。

---

参考架构备注

● 本工作坊使用的 Kiro 能力：agentic chat、spec-driven development、steering 文件、hooks、MCP-ready 外部上下文、具隐私意识的工作区指引、实施任务、documentation generation 与 test generation。

● 产品范围：用于 AWS Manila Community Day 准备的教育原型。语言内容在 生产环境使用前，必须由 他加禄语母语人士审查。

● 运行时范围：以本机开发者工作站优先。工作坊后的选用 AWS 部署可使用 Amazon S3 static website hosting 或 AWS Amplify Hosting。