使用 Kiro 建置：他加祿語 學習 App 的教育優先開發技巧工作坊

目標大眾： 建立學習產品、內部啟用工具或社群應用程式的專業開發人員

時長： 2 小時

主要 AWS AI 服務： Kiro

專案產出： 一個教育優先的他加祿語練習應用程式，包含學習分類、禮貌規則、驗證輔助工具以及 Kiro 輔助測試。

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

工作坊摘要

本工作坊協助開發人員在設計語言學習軟體時，將教學法（Pedagogy）置於功能之前。參與者將使用 Kiro 來擷取學習目標、禮貌用語規則、練習分類、內容審查預期和測試。這些練習展示了教育限制如何引導資料模型、UI 行為和自動化，從而使他加祿語練習應用程式在未來的內容更新中，依然保持實用、對初學者友善、文化謹慎且易於擴充。

工作坊目標

本工作坊教導開發人員如何建立一個教育意義大於技術性的語言學習應用程式。該應用程式專注於初學者的信心、禮貌用語、可重複練習、發音和實際活動情境。Kiro 被用來建立規格書、透過引導文件（Steering）指引實作、生成程式碼、產生測試，並定義保持教育合約完整性的 Hook。

2 小時議程

---

步驟 1 — 定義教育優先的引導

Kiro 提示詞範例

為一個教育性的他加祿語學習應用程式建立引導文件。
該應用程式必須減少學習者的恐懼、使犯錯常態化、教授禮貌用語，並提供簡短的練習鑽研。
使用 React、TypeScript、Vite、Vitest 和本地 JSON 資料。
生成的語言內容在經過母語人士審查之前均為草稿。

系統設計決策

● 教學法即架構： 產品目標不只是將英文翻譯成他加祿語。應用程式必須協助初學者安全地練習、理解語氣，並在社群活動中禮貌地發言。教育規則屬於引導文件，因為它們會影響 Schema 設計、UI 版面配置、測試和內容審查。

● 透過限制確保學習安全： 應用程式應避免過度自信的 AI 行為。審查狀態、簡短說明、語氣標籤和母語人士審查提醒，能讓系統對其局限性保持誠實。這在教授語言和文化脈絡時尤為重要。

● 開發者可重複性： 專業開發人員需要一種可重複的方法來建立學習功能。引導文件確保 Kiro 在整個工作坊中都使用相同的專案詞彙——練習分類、句子卡片、禮貌形式、發音、範例和審查狀態。

程式碼範例 — .kiro/steering/pedagogy.md

# 教育指引

本應用程式透過使用簡短、可重複、具禮貌性的練習卡片來教導初學者。
每張卡片應協助學習者理解該說什麼、何時該說，以及聽起來有多正式。

## 學習規則

- 偏好可以大聲朗讀的簡短範例。
- 在好玩的菲律賓式英語（Filipino-English）之前，先顯示自然的他加祿語。
- 將好玩的菲律賓式英語標記為非正式（informal）。
- 將 `po`、`opo`、`kayo` 和 `ninyo` 解釋為尊稱標記。
- 在片語旁提供發音。
- 使用審查狀態：`draft`（草稿）、`native-reviewed`（母語人士已審查）或 `blocked`（已封鎖）。
- 在沒有母語人士審查的情況下，切勿將生成的語言內容視為最終版本。

程式碼說明

● 商業邏輯： 此引導文件定義了每個功能都應遵循的教育標準。

● 程式碼邏輯： Kiro 讀取 Markdown 上下文，並使用它來塑造生成的規格需求、元件、測試和審查建議。

● 預期結果： 生成的實作與學習策略保持一致，而不會變成一個通用的閃卡應用程式。

---

步驟 2 — 生成教育性 Kiro 規格書

Kiro 提示詞範例

建立一個名為 educational-practice-flow 的 Kiro 規格書。
該功能透過練習分類、提示/顯示卡片、禮貌註記、發音和審查狀態來教導他加祿語。
使用可透過 Vitest 和 Testing Library 進行測試的驗收準則。

系統設計決策

● 學習流程的功能級規格書： 規格書專注於學習者如何練習，而不僅僅切留在資料如何渲染。這使得系統可以從學習者的角度進行測試：選擇一個分類、閱讀英文提示、顯示他加祿語、檢查禮貌程度並重複。

● 驗收準則驅動實作： 可測試的準則減少了模糊性。如果規格書寫著「當學習者顯示卡片時，禮貌的他加祿語應變為可見」，開發人員就可以直接實作並測試該行為。

● 微小功能切片： 一個兩小時的工作坊需要一個垂直切片。分類選擇、提示/顯示和禮貌註記已足夠演示 Kiro 的規格書驅動工作流程，而無需引入身分驗證、資料庫或外部 API。

程式碼範例 — .kiro/specs/educational-practice-flow/tasks.md

# 任務

- [ ] 定義 PracticeCategory 和 PracticeCard 型別。
- [ ] 為 greetings（問候）、directions（指路）、workshops（工作坊）、thanks（感謝）和 waiting（等待）添加種子卡片。
- [ ] 實作禮貌輔助工具，為初次接觸者返回更安全的指引。
- [ ] 建構 CategorySelector 元件。
- [ ] 建構具有顯示（reveal）行為的 PracticeCard 元件。
- [ ] 為分類篩選、顯示行為、非正式標籤和審查狀態添加測試。
- [ ] 添加在卡片資料變更後執行測試的 Hook 指引。

程式碼說明

● 商業邏輯： 任務代表了從資料到練習行為的教育工作流程。

● 程式碼邏輯： 每個任務都可以獨立實作並在 Kiro 中勾選完成。

● 預期結果： 开发人員有一條從規格需求到正常運作之應用程式的清晰路徑。

---

步驟 3 — 建立練習分類資料

Kiro 提示詞範例

生成一個用於他加祿語練習分類和卡片的 TypeScript 模型。
包含活動分類：greetings（問候）、directions（指路）、workshops（工作坊）、thanks（感謝）、waiting（等待）。
每張卡片需要英文提示、自然他加祿語、禮貌他加祿語、語氣、發音和審查狀態。

系統設計決策

● 分類組織學習意圖： 學習者是針對特定情境進行準備，而不是抽象的單字列表。像是問候、指路、工作坊、感謝和等待等分類，直接對應到 AWS 馬尼拉社群日（AWS Manila Community Day）的行動。

● 提示/顯示格式支持記憶： 首先顯示英文提示可以鼓勵主動回憶（Active recall）。隨後顯示他加祿語可建立一個簡單的練習迴圈，日後可演進為間歇重複（Spaced repetition）。

● 審查狀態與內容同行： 因為教育品質取決於正確性，每張卡片都儲存了審查狀態。這使 UI 和測試能夠防止將未經審查的內容視為最終版本呈現給使用者。

程式碼範例 — src/data/practiceCards.ts

export type PracticeCategory = "greetings" | "directions" | "workshops" | "thanks" | "waiting";
export type ReviewStatus = "draft" | "native-reviewed" | "blocked";

export interface PracticeCard {
  id: string;
  category: PracticeCategory;
  englishPrompt: string;
  naturalTagalog: string;
  politeTagalog: string;
  tone: "casual" | "polite" | "event-ready" | "informal-playful";
  pronunciation: string;
  reviewStatus: ReviewStatus;
}

export const practiceCards: PracticeCard[] = [
  {
    id: "greetings-hello-learning",
    category: "greetings",
    englishPrompt: "Hello, I am learning Tagalog.",
    naturalTagalog: "Kumusta, nag-aaral ako ng Tagalog.",
    politeTagalog: "Kumusta po, nag-aaral po ako ng Tagalog.",
    tone: "event-ready",
    pronunciation: "koo-MOOS-tah poh, nag-ah-AH-ral poh AH-koh ngah tah-GAH-log",
    reviewStatus: "draft"
  },
  {
    id: "directions-md-room",
    category: "directions",
    englishPrompt: "Where is the md room?",
    naturalTagalog: "Saan ang md room?",
    politeTagalog: "Saan po ang md room?",
    tone: "polite",
    pronunciation: "SAH-ahn poh ahng md room",
    reviewStatus: "draft"
  },
  {
    id: "waiting-on-my-way",
    category: "waiting",
    englishPrompt: "I am on my way.",
    naturalTagalog: "Papunta na ako.",
    politeTagalog: "Papunta na po ako.",
    tone: "event-ready",
    pronunciation: "pah-POON-tah nah poh AH-koh",
    reviewStatus: "draft"
  }
];

程式碼說明

● 商業邏輯： 該資料為學習者做好了實際活動行動的準備：問候、詢問方向和協調抵達。

● 程式碼邏輯： 聯集型別限制了有效的分類、語氣值和審查狀態。這可以防止意外的自由格式標籤。

● 預期結果： 開發人員可以按分類篩選卡片，並渲染一致的練習流程。

---

步驟 4 — 實作禮貌指引輔助工具

Kiro 提示詞範例

建立一個 TypeScript 輔助工具，用以說明禮貌的他加祿語是否更安全。
輸入：對象型別與情境。
返回指引訊息、推薦變體和原因。

系統設計決策

● 禮貌即產品邏輯： 尊稱用語不是附註。該應用程式的核心價值在於協助初學者在面對演講者、主辦方、志工、場地工作人員、長輩和初次接觸者時，選擇更安全的措辭。

● 規則先於 AI 生成： 決定性的輔助工具能提供可預測的指引。AI 可能會生成草稿，打執行期的教育行為應保持穩定且可測試。在工作坊中，基於規則的指引更容易進行稽核。

● 與 UI 分離： 此輔助工具不渲染 HTML。它返回一個簡單的物件，因此相同的邏輯可以支援網頁 UI、測試、文件或未來的 API 回應。

程式碼範例 — src/lib/politeness.ts

export type Audience = "peer" | "speaker" | "organizer" | "volunteer" | "venue-staff" | "elder" | "unknown";

export interface PolitenessGuidance {
  recommendedVariant: "natural" | "polite";
  message: string;
  reason: string;
}

const formalAudiences: Audience[] = ["speaker", "organizer", "volunteer", "venue-staff", "elder", "unknown"];

export function getPolitenessGuidance(audience: Audience): PolitenessGuidance {
  if (formalAudiences.includes(audience)) {
    return {
      recommendedVariant: "polite",
      message: "優先使用禮貌的他加祿語版本。",
      reason: "與初次接觸者、活動工作人員、演講者、長輩和志工溝通時，使用禮貌用語更安全。"
    };
  }

  return {
    recommendedVariant: "natural",
    message: "在氣氛輕鬆且與同儕互動的場合下，使用自然的他加祿語是可接受的。",
    reason: "建立交情後，日常休閒口吻能顯得更加親切。"
  };
}

程式碼說明

● 商業邏輯： 此輔助工具教導何時使用禮貌用語更安全。

● 程式碼邏輯： 固定的正式對象列表控制了推薦變體是 polite 還是 natural。

● 預期結果： 呼叫 getPolitenessGuidance("speaker") 會返回禮貌推薦，而呼叫 getPolitenessGuidance("peer") 則返回自然指引。

---

步驟 5 — 建構分類選擇器

Kiro 提示詞範例

建立一個 CategorySelector React 元件。
它接收 categories、selected category 和 onChange 回呼函式。
使用具備無障礙輔助的按鈕和可見的選取狀態。

系統設計決策

● 情境優先導覽： 分類反映了活動情境。開發人員應避免在學習者需要快速查找某個片語時，強迫他們滾動瀏覽無關的卡片。

● 受控元件模式： 選擇器從其父元件接收狀態。這保持了篩選邏輯的集中化，並使元件易於測試和重複使用。

● 工作坊演示中按鈕優於下拉選單： 按鈕使分類切換在現場教學期間清晰可見。在兩小時的課程中，它們更容易讓參與者進行檢查、測試和樣式設計。

程式碼範例 — src/components/CategorySelector.tsx

import type { PracticeCategory } from "../data/practiceCards";

interface Props {
  categories: PracticeCategory[];
  selected: PracticeCategory;
  onChange: (category: PracticeCategory) => void;
}

export function CategorySelector({ categories, selected, onChange }: Props) {
  return (
    <nav aria-label="Practice categories" className="category-selector">
      {categories.map((category) => (
        <button
          key={category}
          type="button"
          aria-pressed={category === selected}
          className={category === selected ? "active" : ""}
          onClick={() => onChange(category)}
        >
          {category}
        </button>
      ))}
    </nav>
  );
}

程式碼說明

● 商業邏輯： 學習者選擇他們想要練習的活動情境。

● 程式碼邏輯： 元件將分類對應到按鈕，並透過 onChange 回報變更。

● 預期結果： 點擊分類會更新父元件中選定的練習群組。

---

步驟 6 — 建構提示/顯示練習卡片

Kiro 提示詞範例

建立一個 PracticeCardView 元件。
先顯示英文提示。
在學習者點擊 Reveal 之後，顯示自然他加祿語、禮貌他加祿語、發音、語氣和審查狀態。
如果語氣是 informal-playful，顯示一個 Informal 徽章。

系統設計決策

● 主動回憶優於被動閱讀： 提示/顯示設計讓學習者在看到答案前先思考。與總是立即顯示所有翻譯相比，這提高了練習價值。

● 顯示行為保持低認知負荷： 初學者可能會被文法、語氣和發音壓得喘不過氣。先顯示英文提示，稍後再顯示詳細資訊，可以創造更溫和的體驗。

● 語氣和審查保持可見： 即使在顯示之後，學習者也需要知道內容是否為草稿以及風格是否為非正式。UI 絕不能隱藏品質或語氣的元資料。

程式碼範例 — src/components/PracticeCardView.tsx

import { useState } from "react";
import type { Audience } from "../lib/politeness";
import { getPolitenessGuidance } from "../lib/politeness";
import type { PracticeCard } from "../data/practiceCards";

interface Props {
  card: PracticeCard;
  audience: Audience;
}

export function PracticeCardView({ card, audience }: Props) {
  const [revealed, setRevealed] = useState(false);
  const guidance = getPolitenessGuidance(audience);

  return (
    <article className="practice-card">
      <p className="practice-card__category">{card.category}</p>
      <h2>{card.englishPrompt}</h2>
      <p>{guidance.message}</p>

      <button type="button" onClick={() => setRevealed((value) => !value)}>
        {revealed ? "隱藏答案" : "顯示他加祿語"}
      </button>

      {revealed && (
        <section aria-label="Practice answer">
          <p><strong>自然他加祿語:</strong> <span lang="tl">{card.naturalTagalog}</span></p>
          <p><strong>禮貌他加祿語:</strong> <span lang="tl">{card.politeTagalog}</span></p>
          <p><strong>發音:</strong> {card.pronunciation}</p>
          <p><strong>語氣:</strong> {card.tone}</p>
          {card.tone === "informal-playful" && <span className="badge">Informal</span>}
          <p><strong>審查狀態:</strong> {card.reviewStatus}</p>
          <p><strong>原因:</strong> {guidance.reason}</p>
        </section>
      )}
    </article>
  );
}

程式碼說明

● 商業邏輯： 該元件建立了一種學習互動：閱讀英文、選擇是否顯示答案，然後比較自然和禮貌的形式。

● 程式碼邏輯： React 狀態控制了顯示/隱藏行為。禮貌輔助工具根據對象返回指引。

● 預期結果： 學習者可以一次練習一個提示，並為選定的對象獲得更安全的語氣指引。

---

步驟 7 — 組合教育練習應用程式

Kiro 提示詞範例

建立 App.tsx，讓學習者可以選擇分類和對象。
按分類篩選練習卡片並渲染提示/顯示卡片。
預設分類應為 greetings，預設對象應為 unknown。

系統設計決策

● 篩選優於搜尋： 對於小型工作坊應用程式，分類篩選比全文檢索更簡單且更具解釋性。它強化了活動情境模型，並保持實作易於檢查。

● 對象感知練習： 同一個句子在休閒或禮貌的脈絡下皆可被接受。對象選擇有助於學習者理解為什麼與未知接觸者、工作人員或演講者在一起時，禮貌變體更安全。

● 可組合狀態： App 外殼擁有選定的分類和對象。子元件則保持專注且可重複使用。這對於工作坊來說是一個乾淨的 React設計，因為開發人員可以快速推導狀態流。

程式碼範例 — src/App.tsx

import { useMemo, useState } from "react";
import { practiceCards, type PracticeCategory } from "./data/practiceCards";
import type { Audience } from "./lib/politeness";
import { CategorySelector } from "./components/CategorySelector";
import { PracticeCardView } from "./components/PracticeCardView";

const categories: PracticeCategory[] = ["greetings", "directions", "workshops", "thanks", "waiting"];
const audiences: Audience[] = ["unknown", "peer", "speaker", "organizer", "volunteer", "venue-staff", "elder"];

export default function App() {
  const [selectedCategory, setSelectedCategory] = useState<PracticeCategory>("greetings");
  const [audience, setAudience] = useState<Audience>("unknown");

  const visibleCards = useMemo(
    () => practiceCards.filter((card) => card.category === selectedCategory),
    [selectedCategory]
  );

  return (
    <main>
      <h1>AWS 馬尼拉社群日的教育性他加祿語練習</h1>
      <p>選擇一個情境、選擇一個對象，然後顯示他加祿語答案。</p>

      <label>
        溝通對象
        <select value={audience} onChange={(event) => setAudience(event.target.value as Audience)}>
          {audiences.map((item) => <option key={item} value={item}>{item}</option>)}
        </select>
      </label>

      <CategorySelector categories={categories} selected={selectedCategory} onChange={setSelectedCategory} />

      {visibleCards.map((card) => (
        <PracticeCardView key={card.id} card={card} audience={audience} />
      ))}
    </main>
  );
}

程式碼說明

● 商業邏輯： 學習者根據情境和對象練習片語。

● 程式碼邏輯： useState 追蹤分類和對象。useMemo 有效率地為選定的分類篩選卡片。

● 預期結果： 選擇「directions」會顯示指路卡片；選擇「speaker」會優先推薦禮貌的他加祿語。

---

步驟 8 — 添加測試與資料品質 Hook

Kiro 提示詞範例

為教育練習流程生成測試。
驗證分類篩選、顯示行為、針對演講者對象的禮貌指引以及審查狀態的可見性。
建立一個 Kiro hook，在卡片資料變更時提醒開發人員驗證 reviewStatus。

系統設計決策

● 行為測試優於快照測試： 關鍵的學習行為是分類篩選和顯示。測試應該模擬學習者的操作，而不是僅僅比較 HTML 快照。

● 禮貌指引必須經過驗證： 應用程式的鑑別度在於教育性的語氣支援。如果對象選擇停止為演講者推薦禮貌用語，即使 UI 仍能渲染，產品也是失敗的。

● 資料變更 Hook： 語言應用程式中的內容更新非常頻繁。一個監視 src/data/ 的 Kiro Hook 可以在內容變更時，提醒開發人員檢查審查狀態、非正式標籤和發音覆蓋率。

程式碼範例 — src/tests/politeness.test.ts

import { describe, expect, it } from "vitest";
import { getPolitenessGuidance } from "../lib/politeness";

describe("getPolitenessGuidance", () => {
  it("為演講者推薦禮貌的他加祿語", () => {
    const result = getPolitenessGuidance("speaker");
    expect(result.recommendedVariant).toBe("polite");
    expect(result.message).toContain("禮貌的他加祿語");
  });

  it("允許在輕鬆的同儕情境中使用自然的他加祿語", () => {
    const result = getPolitenessGuidance("peer");
    expect(result.recommendedVariant).toBe("natural");
  });
});

程式碼說明

● 商業邏輯： 該測試確認了「對演講者而言禮貌用語更安全」的教育規則。

● 程式碼邏輯： 它直接呼叫輔助工具並斷言（Assert）返回的推薦。

● 預期結果： 如果禮貌規則不小心被削弱，測試將會失敗。

Kiro Hook 範例 — .kiro/hooks/card-data-quality.md

# Hook：卡片資料品質提醒

觸發條件：當 `src/data/` 底下的檔案被儲存時。
動作：
1. 檢查每張卡片是否都有 `reviewStatus`。
2. 檢查每張卡片是否都有發音文字。
3. 提醒開發人員，`draft` 內容在發布到正式環境之前，需要經過母語人士審查。
4. 如果引入了新分類，建議添加或更新測試。

Hook 說明

● 商業邏輯： 隨著資料集的增長，該 Hook 保持了教育內容的可審查性。

● 程式碼邏輯： 它將品質提醒附加到資料變更上，而不是依賴人工記憶。

● 預期結果： 每當資料變更時，系統都會提示開發人員維護審查和發音標準。

完成檢查清單

● [ ] 教育引導文件存在。

● [ ] Kiro 規格書任務存在。

● [ ] 練習卡片模型包含分類、語氣、發音和審查狀態。

● [ ] 禮貌輔助工具為決定性（Deterministic）且通過測試。

● [ ] 分類選擇器可正確篩選卡片。

● [ ] 提示/顯示卡片運作正常。

● [ ] 針對資料品質的 Kiro hook 指引存在。

工作坊後的選用 AWS 擴充

● 將靜態建置版本託管於 AWS Amplify Hosting。

● 將 practiceCards 作為具備版本主控權的 JSON 儲存於 Amazon S3。

● 使用 Kiro 生成已審查學習內容的發布檢查清單。

● 將 Amazon Bedrock 的草稿生成功能嚴格限制在人工審查工作流程之後。

---

附加動手操作開發者實驗室

這些實驗室是 工作坊 2 — 教育優先開發技巧 的獨特內容。它們透過教學法、學習者信心、內容審查和禮貌用語護欄，擴充了核心的提示/顯示應用程式。焦點不在於通用的 Kiro 設定，而在於將教育意圖轉化為開發人員清晰可見的產品行為。

動手操作實驗室 A — 在添加更多卡片之前建立學習者成果量規（Rubric）

開發者行動

● 要求 Kiro 建立一個量規，定義初學者在完成每個分類後應達到的能力。

● 將此量規添加到 .kiro/steering/learning-rubric.md。

● 要求 Kiro 將目前的 practiceCards 資料與該量規進行比對。

● 將任何缺失的成果轉化為微小的實作任務。

Kiro 提示詞範例

為這個他加祿語練習應用程式建立一個學習者成果量規（learner-outcome rubric）。
按 greetings、directions、workshops、thanks 和 waiting 將成果分組。
針對每個分類，定義初學者成功標準、禮貌用語預期、發音預期以及審查風險註記。
然後檢查目前的練習卡片模型，並將差距（gaps）列為實作任務。

系統設計決策

● 擴充前先立量規： 更多卡片並不等同於學習效果的提升。量規在開發人員大規模添加資料之前，就告訴了他們每個分類應該教導什麼。

● 成果驅動的資料審查： 卡片只有在支援具體的學習者行動時才有用，例如禮貌地向志工問候或詢問某個房間在哪裡。

● Kiro 作為課程審查者： Kiro 可以將實作產出與量規進行比對並產生可執行的差距列表，而母語人士仍然擁有最終的語言審查權。

程式碼範例 — .kiro/steering/learning-rubric.md

# 學習量規

每個練習分類必須支援一項初學者行動、一個尊稱標記以及一個口說信心目標。

## Greetings（問候）
- 初學者行動：自我介紹為正在學習他加祿語的人。
- 禮貌預期：在初次見面問候中展現 `po`。
- 發音預期：包含 `Kumusta` 和 `Tagalog` 的重音指引。
- 審查風險：避免宣稱某一種問候語適用於所有地區或場合。

## Directions（指路）
- 初學者行動：詢問活動活動室、報到處或出口在哪裡。
- 禮貌預期：對志工和場地工作人員使用禮貌的提問形式。
- 發音預期：包含 `Saan po` 的簡短指引。
- 審查風險：地點詞彙應檢查是否符合自然活動情境的使用習慣。

## Workshops（工作坊）
- 初學者行動：請求允許提問、重複、加入或就座。
- 禮貌預期：對演講者和主辦方使用禮貌的措辭。
- 發音預期：包含溫和提問的口說技巧。
- 審查風險：避免使用聽起來帶有命令口吻的措辭。

程式碼說明

● 商業邏輯： 量規在確保內容數量之前，先定義了教育品質。

● 程式碼邏輯： Kiro 在生成卡片、測試和審查任務時可以使用此引導文件。

● 預期結果： 未來添加卡片時會根據學習成果進行檢查，而不是僅僅因為程式碼能編譯通過就被接受。

動手操作實驗室 B — 為初學者練習添加信心程度模型

開發者行動

● 在每張練習卡片中添加一個面向學習者的信心程度（Confidence level）。

● 要求 Kiro 更新 TypeScript 模型和種子資料。

● 在提示附近渲染信心程度，以便學習者知道該卡片的難易度。

● 添加一個測試，驗證每張卡片是否都有信心程度。

Kiro 提示詞範例

在練習卡片的資料合約中添加初學者信心模型。
使用 confidenceLevel 值：starter（入門）、guided（引導）、stretch（挑戰）。
Starter 卡片應簡短且適合初次接觸時安全使用。
Guided 卡片可包含簡短的情境附註。
Stretch 卡片可包含較長的禮貌片語。
更新型別、範例資料、UI 標籤和測試。

系統設計決策

● 信心是學習設計的一部分： 初學者需要知道哪些片語可以先安全嘗試。難度標籤能防止應用程式將所有句子視為同樣容易上手。

● 微小列舉（Enum）優於自由文字： 固定的聯集型別可避免出現不一致的標籤（如 easy, beginner, simple 或 basic）。

● 可見的元資料： 信心程度應顯示在 UI 中，而非隱藏在資料中，因為學習者會利用它來選擇練習流程。

程式碼範例 — src/data/practiceCards.ts

export type ConfidenceLevel = "starter" | "guided" | "stretch";

export interface PracticeCard {
  id: string;
  category: PracticeCategory;
  englishPrompt: string;
  naturalTagalog: string;
  politeTagalog: string;
  tone: "casual" | "polite" | "event-ready" | "informal-playful";
  pronunciation: string;
  reviewStatus: ReviewStatus;
  confidenceLevel: ConfidenceLevel;
}

export const confidenceLabels: Record<ConfidenceLevel, string> = {
  starter: "從這裡開始",
  guided: "結合情境練習",
  stretch: "排練後嘗試"
};

程式碼說明

● 商業邏輯： 該模型協助學習者選擇一個可達成的練習卡片。

● 程式碼邏輯： ConfidenceLevel 限制了有效值，而 confidenceLabels 集中了顯示文字。

● 預期結果： 新卡片若漏掉預期的初學者難度，將會導致型別或驗證上的差距。

動手操作實驗室 C — 為提示/顯示練習建構提示階梯

開發者行動

● 要求 Kiro 添加在顯示完整他加祿語答案之前出現的選用提示。

● 實作一個輔助工具，為卡片返回有序的提示。

● 使用「顯示提示」和「顯示答案」操作更新練習卡片 UI。

● 添加驗證提示在答案之前出現的測試。

Kiro 提示詞範例

為提示/顯示練習建立一個提示階梯（hint ladder）。
在顯示完整答案之前，提示應依序揭露分類情境、第一個字、尊稱標記和發音提示。
保持提示的決定性，並由現有的卡片物件衍生而來。
為提示優先的學習流程添加元件測試。

系統設計決策

● 搭建鷹架（Scaffold）引導回憶，而非直接給出答案： 提示階梯在完全揭露答案前鼓勵主動記憶。

● 衍生提示減輕內容維護負擔： 第一個版本可以從現有的卡片欄位中衍生提示，而不是要求作者維護一個新的提示資料集。

● 決定性行為是可測試的： UI 可以證明提示是按順序出現的，且完整答案會保持隱藏直到使用者要求顯示。

程式碼範例 — src/lib/hints.ts

import type { PracticeCard } from "../data/practiceCards";

export interface PracticeHint {
  label: string;
  value: string;
}

export function buildHintLadder(card: PracticeCard): PracticeHint[] {
  const firstWord = card.politeTagalog.split(/\s+/)[0] ?? "";
  const hasPo = /\bpo\b/i.test(card.politeTagalog);

  return [
    { label: "情境", value: `這是用於 ${card.category}。` },
    { label: "第一個字", value: firstWord },
    {
      label: "尊稱標記",
      value: hasPo ? "在禮貌版本中注意聽 po。" : "此片語中未出現 po 標記。"
    },
    { label: "發音提示", value: card.pronunciation }
  ];
}

程式碼說明

● 商業邏輯： 提示協助學習者進行預演，而不需要立即複製答案。

● 程式碼邏輯： 輔助工具讀取 category、politeTagalog 和 pronunciation 來建立可預測的提示步驟。

● 預期結果： 學習者可以在揭露完整片語之前，逐步請求指引。

動手操作實驗室 D — 為禮貌指引添加對象安全矩陣

開發者行動

● 要求 Kiro 建立一個對象與推薦語氣行為的矩陣。

● 將單一訊息的禮貌指引替換為結構化的策略輸出。

● 為每個對象值添加單元測試。

● 要求 Kiro 識別任何可能使學習者感到困惑的 UI 標籤。

Kiro 提示詞範例

將禮貌輔助工具重構為對象安全矩陣。
針對每個對象，返回 recommendedVariant、safetyLevel、reason 和 learnerWarning。
對演講者、主辦方、志工、場地工作人員、長輩和未知接觸者使用更嚴格的指引。
為每個對象值生成 Vitest 測試案例。

系統設計決策

● 策略表優於巢狀條件式： 與散落的 if 語句相比，矩陣更容易與教育工作者和母語人士進行審查。

● 安全等級支援 UI 決策： 應用程式可以對未知接觸者或被封鎖的內容顯示更強烈的警告，而不需要修改卡片 Schema。

● 全面測試保護語氣規則： 每個對象值都應該有一個測試，以便未來的重構不會在無意中削弱禮貌用語指引。

程式碼範例 — src/lib/audiencePolicy.ts

export type Audience = "peer" | "speaker" | "organizer" | "volunteer" | "venue-staff" | "elder" | "unknown";
export type SafetyLevel = "relaxed" | "careful" | "strict";

export interface AudiencePolicy {
  recommendedVariant: "natural" | "polite";
  safetyLevel: SafetyLevel;
  reason: string;
  learnerWarning: string;
}

export const audiencePolicy: Record<Audience, AudiencePolicy> = {
  peer: {
    recommendedVariant: "natural",
    safetyLevel: "relaxed",
    reason: "建立交情後，與同儕使用自然的他加祿語會顯得親切。",
    learnerWarning: "不確定時請使用禮貌措辭。"
  },
  speaker: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "演講者正在主持會議，因此使用禮貌用語更安全。",
    learnerWarning: "請從禮貌版本開始。"
  },
  organizer: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "主辦方負責管理活動，且可能是初次接觸的人。",
    learnerWarning: "請先使用禮貌措辭。"
  },
  volunteer: {
    recommendedVariant: "polite",
    safetyLevel: "careful",
    reason: "志工正在協助與會者，因此提出禮貌的詢問是合適的。",
    learnerWarning: "尋求協助時請使用 po。"
  },
  "venue-staff": {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "場地工作人員是在公開場合中的專業接觸對象。",
    learnerWarning: "優先使用禮貌的版本。"
  },
  elder: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "面對長輩時，使用禮貌用語更為安全。",
    learnerWarning: "除非另有建議，否則請使用禮貌標記。"
  },
  unknown: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "未知的接觸對象需要最安全的預設選擇。",
    learnerWarning: "在情境明確變為休閒之前，請選擇禮貌的他加祿語。"
  }
};

程式碼說明

● 商業邏輯： 該策略教導更具對象感知能力且安全的言語選擇。

● 程式碼邏輯： Record<Audience, AudiencePolicy> 讓缺失的對象項目對 TypeScript 來說清晰可見。

● 預期結果： UI 和測試可以為所有的語氣指引使用同一個清晰的策略物件。

動手操作實驗室 E — 為母語人士回饋建立內容審查佇列

開發者行動

● 要求 Kiro 從草稿卡片中生成審查佇列（Review queue）。

● 添加一個按分類和審查狀態對卡片進行分組的函式。

● 在應用程式中渲染一個僅限開發人員檢視的審查摘要，或輸出主控台報告。

● 添加一個測試，確保被封鎖（Blocked）的卡片絕不會出現在學習者的預設練習列表中。

Kiro 提示詞範例

為他加祿語練習卡片建立一個內容審查佇列。
按 reviewStatus 和 category 將卡片分組。
草稿卡片應顯示審查者的問題。
已封鎖的卡片應從預設的學習者練習中排除。
添加一個小型可測試的輔助工具和一個面向開發人員的摘要元件。

系統設計決策

● 審查工作流程是一項功能： 由於語言內容需要母語人士審查，開發人員需要一種方法來查看哪些內容尚未被審查。

● 區分學習者檢視與審查者檢視： 學習者不應該收到被封鎖的內容作為推薦練習，但審查者仍然需要對其進行檢查。

● 按分類分組： 審查者可以在情境中評估片語，而不是掃描一個扁平的列表。

程式碼範例 — src/lib/reviewQueue.ts

import type { PracticeCard, PracticeCategory, ReviewStatus } from "../data/practiceCards";

export type ReviewQueue = Record<ReviewStatus, Partial<Record<PracticeCategory, PracticeCard[]>>>;

export function buildReviewQueue(cards: PracticeCard[]): ReviewQueue {
  return cards.reduce<ReviewQueue>((queue, card) => {
    queue[card.reviewStatus] ??= {};
    queue[card.reviewStatus][card.category] ??= [];
    queue[card.reviewStatus][card.category]!.push(card);
    return queue;
  }, { draft: {}, "native-reviewed": {}, blocked: {} });
}

export function learnerPracticeCards(cards: PracticeCard[]) {
  return cards.filter((card) => card.reviewStatus !== "blocked");
}

程式碼說明

● 商業邏輯： 輔助工具將審查管理與學習者練習區分開來。

● 程式碼邏輯： buildReviewQueue 按狀態 and 分類對卡片進行分組，而 learnerPracticeCards 則篩選掉不安全的內容。

● 預期結果： 開發人員可以清楚看到哪些需要審查，且被封鎖的內容不會被推送給學習者。

動手操作實驗室 F — 添加講師課後小檢核（Exit-ticket）與學習分析事件模型

開發者行動

● 要求 Kiro 為工作坊學習成果定義僅限本地的分析事件。

● 為選取的分類、檢視的提示、顯示的答案和選取的信心程度添加事件型別。

● 在工作坊期間將事件保存在記憶體或主控台中；不要在外部發送遙測資料。

● 根據事件名生成一個講師課後小檢核（Exit-ticket）範本。

Kiro 提示詞範例

為此工作坊應用程式定義一個僅限本地的學習事件模型。
追蹤 category_selected、hint_viewed、answer_revealed 和 confidence_marked。
請勿添加外部遙測或網路呼叫。
建立一個簡短的講師課後小檢核範本，詢問學習者練習了什麼以及他們在哪裡仍需要協助。

系統設計決策

● 無外部複雜度的學習分析： 本地事件模型可協助講師討論行為，同時保持工作坊的隱私友善性與免設定性。

● 事件對應到教學法： 這些事件對應到學習行動，而非行銷指標。

● 課後小檢核形成閉環： 開發人員可以看見產品檢測（Instrumentation）如何支援教學品質的提升。

程式碼範例 — src/lib/learningEvents.ts

export type LearningEventName =
  | "category_selected"
  | "hint_viewed"
  | "answer_revealed"
  | "confidence_marked";

export interface LearningEvent {
  name: LearningEventName;
  cardId?: string;
  category?: string;
  value?: string;
  occurredAt: string;
}

const events: LearningEvent[] = [];

export function recordLearningEvent(event: Omit<LearningEvent, "occurredAt">) {
  events.push({ ...event, occurredAt: new Date().toISOString() });
}

export function readLearningEvents() {
  return [...events];
}

程式碼說明

● 商業邏輯： 該模型擷取了可以為未來教學設計提供實證支援的學習者行動。

● 程式碼邏輯： 事件儲存在工作坊應用程式的記憶體中，可以在不添加額外服務的情況下進行檢查。

● 預期結果： 參與者可以討論教育產品如何負責任地衡量練習行為。

---

參考架構說明

● 本工作坊強調的 Kiro 功能：教學法引導、學習者成果審查、受控的 TypeScript 重構、基於規則的禮貌原則、源自教育驗收準則的測試，以及具備審查感知的開發。

● 產品範疇：針對活動準備、對初學者友善的他加祿語練習。語言內容在經過母語人士審查之前均保持為草稿。

● 執行期範疇：優先採用本地 React 應用程式。在建立審查工作流程後，可選用 AWS Amplify Hosting 或 Amazon S3 進行部署。