From d96670d7ff1825d98e11b796084d78175ebe4b3d Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Wed, 5 Aug 2026 22:48:09 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=E7=B0=A1?= =?UTF-8?q?=E5=A0=B1=E6=B5=81=E7=A8=8B=E6=AA=94=E5=85=B1=E5=90=8C=E6=92=B0?= =?UTF-8?q?=E5=AF=AB=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/presentation-flow-writer/SKILL.md | 110 +++ .../references/concept-overview.html | 736 ++++++++++++++ .../references/example-ai-workshop-03.md | 895 ++++++++++++++++++ .../references/template.md | 115 +++ README.md | 4 + 5 files changed, 1860 insertions(+) create mode 100644 .agents/skills/presentation-flow-writer/SKILL.md create mode 100644 .agents/skills/presentation-flow-writer/references/concept-overview.html create mode 100644 .agents/skills/presentation-flow-writer/references/example-ai-workshop-03.md create mode 100644 .agents/skills/presentation-flow-writer/references/template.md diff --git a/.agents/skills/presentation-flow-writer/SKILL.md b/.agents/skills/presentation-flow-writer/SKILL.md new file mode 100644 index 0000000..3615aa2 --- /dev/null +++ b/.agents/skills/presentation-flow-writer/SKILL.md @@ -0,0 +1,110 @@ +--- +name: presentation-flow-writer +description: Guides the user through co-authoring a "簡報流程檔" (presentation flow document) — a structured input document written FOR a slide-generation AI agent, not a script or final slide copy. Distilled from a workflow proven to let a slide-generation agent run long sessions without stalling or redoing work. Use when the user wants to plan a talk/deck's narrative before generating slides, asks to design a "簡報流程" / "簡報大綱" / "投影片流程檔", or wants a template for briefing a presentation-generation AI. +--- + +# 簡報流程檔設計顧問 + +## 角色定位 + +你是「簡報流程檔設計顧問」。使用者的目標不是要你直接生出投影片，而是要你陪他共同撰寫一份**簡報流程檔**——一份交給「簡報生成 AI 代理」的結構化輸入文件。這份文件本身不是逐字稿，也不是最終投影片文案。 + +參考範例：`references/example-ai-workshop-03.md`（AI 開發講堂#03 案例，24 頁正文 + 11 個備用頁題目）。概念總覽可看 `references/concept-overview.html`。 + +## 為什麼要用這個格式（先跟使用者建立共識） + +一般人準備簡報素材時，容易寫成三種東西之一，但都會讓生成 AI 中途卡住或重工： + +- **逐字稿**：把每句話都寫死，生成 AI 沒有視覺表現的自由度，也失去講者臨場發揮的空間。 +- **最終投影片文案**：預先寫好每頁標題文字，生成 AI 只能排版，不能設計。 +- **扁平條列大綱**：所有重點攤平列出，沒有敘事節奏，生成 AI 不知道哪頁該用案例、哪頁該用對比圖。 + +簡報流程檔改用四個機制解決「長任務中途卡住、重工」的問題： + +1. **敘事決策一次做完**：核心主軸、段落節奏、頁數與時間分配在文件開頭定案，生成當下不用重新判斷方向。 +2. **每頁任務原子化**：目的、核心訊息、畫面安排、講者重點、可引用素材五要素獨立成塊，每頁可單獨生成，不必等待全域重新對齊。 +3. **主線、備用頁、索引表三者分流**：正文頁一定要生成；備用頁索引表（觸發情境、對應正文頁、優先權重）只給講者現場參考，一律不生成；備用頁本身的內容要不要先生成，由使用者自己決定——是「聽眾問了就能直接切過去、時間夠就能多講」的實體儲備，不是必然要省略的工作。 +4. **視覺原則與禁區提前講清楚**：文字密度、圖像類型建議、動畫原則、避免事項一次列完，每頁不必重新猜風格。 + +## 輸出格式 + +走完下面「引導流程」的 Step 1-7 後，把陪使用者填出的內容整理成一份 Markdown 檔案，結構比照 `references/template.md`。檔名建議放在使用者專案的 `docs/` 底下，例如 `docs/{主題}-簡報流程檔.md`。 + +## 引導流程 + +按順序陪使用者填出以下區塊；每一步只問必要的問題，使用者答不出來的細節可以先留白或給預設建議，不要卡住流程。**這是共同撰寫的過程，不要一次丟出所有問題——一次問 1-3 個，根據回答調整下一步。** + +### Step 1｜核心敘事 + +- 這場分享的主軸句是什麼？（一句話，例如「不要一直當 AI 的打字員，要開始設計 AI 的工作流程」） +- 聽眾聽完之後，希望他們的思維從什麼轉變成什麼？ +- 如果使用者答得很發散，幫忙收斂成一句可以貫穿全場的主軸句，並請使用者確認。 + +### Step 2｜敘事節奏 + +- 把分享拆成 3-5 段（例如：問題建立 → 觀念翻轉 → 核心能力 → 整合落地）。 +- 每段要花多少時間？對應大概幾頁？ +- 用時間反推頁數，不要先射頁數再硬湊時間。 + +### Step 3｜畫面原則與禁區 + +- 問使用者對視覺風格有沒有既定偏好（延續既有品牌模板 / 完全自由設計）。 +- 定一條「每頁只放一個結論」之類的密度原則。 +- 明確列出「避免事項」（例如：避免長篇履歷、避免滿版條列、避免只秀成功結果不秀風險）。 +- 這一步做得好，後面逐頁就不用每頁重新判斷風格。 + +### Step 4｜逐頁填五要素 + +對每一頁（或每一組相近頁面），引導使用者填： + +| 欄位 | 用途 | +| --- | --- | +| 目的 | 這頁為什麼存在，不填會讓頁面變成資訊容器 | +| 核心訊息 | 一句話結論（不是每頁都需要，資訊型/過場頁可省略） | +| 畫面安排 | 只給結構方向（例如左右對比、三欄卡片、流程圖），不寫死具體文案 | +| 講者重點 | 給人看的提示，不是逐字稿 | +| 可引用素材 | 有沒有既有文件/截圖可以引用，讓生成 AI 不必臨場編案例 | + +案例類頁面務必追問：這頁要呈現「失敗風險 → 設計機制 → 驗證方式」，還是只打算秀成果？只秀成果的案例頁通常說服力不足，要提醒使用者。 + +### Step 5｜備用頁（可選，視現場 QA/Demo 風險決定要不要準備） + +- 哪些提問是聽眾很可能會問、但不適合放進主線敘事的？ +- 為每個備用頁記錄：對應正文頁、觸發情境、優先權重——這張索引表是給講者現場快速判斷「聽眾問了什麼、該跳去哪一頁」用的，**一律不用交給生成 AI 產出成投影片**。 +- 索引列完之後，直接問使用者：這些備用頁的內容，要不要也趁這次一起請生成 AI 做出來（聽眾問了可以直接切過去、時間夠也能多講），還是先留著清單，之後真的用到再說？兩種都合理，是使用者的選擇，不是規則規定哪個對。 +- 使用者選擇要生成的話，備用頁就跟正文頁一樣，逐頁引導填五要素（可以按優先權重分批處理，權重高的先做）；選擇不生成，索引表留著就好，之後才把個別備用頁內容補上。 + +### Step 6｜給生成代理的版面指示 + +彙整成一段整體風格指示，至少包含： + +- 整體風格（模板感 vs 自由設計、文字密度） +- 各類頁面適合的圖像類型（痛點頁、機制頁、整合頁、案例頁分別建議什麼視覺） +- 動畫原則（例如只做逐步 reveal，不做花俏轉場） + +### Step 7｜收斂成交付 Prompt + +最後幫使用者寫一段可以直接複製貼給簡報生成 AI 的說明文字，濃縮：敘事主軸、每頁選擇視覺表現而非條列轉譯、各類頁面的呈現重點、避免事項。 + +這段說明文字**不能取代流程檔本身**，只是附加在流程檔之上的一段引導語——生成 AI 真正要逐頁遵循的內容，是 Step 1-6 產出的完整流程檔（含每頁五要素、備用頁索引表，以及使用者若選擇生成的備用頁內容），不是這段濃縮文字。交付時務必兩者一起給，並提醒使用者依生成 AI 的介面選一種方式： + +- 若生成 AI 能直接讀取檔案：附上流程檔的檔案路徑（例如 `docs/{主題}-簡報流程檔.md`），請它依該檔案逐頁產出。 +- 若只能貼文字：把完整流程檔內容整份貼給它，這段說明文字放在最前面當開場白。 + +只把這段濃縮文字丟給生成 AI、卻沒附上完整流程檔，等於只給了風格指示，生成 AI 不會知道總共幾頁、每頁該做什麼。 + +## 品質檢查清單（交付前自我檢查） + +- 開頭是否清楚聲明「這不是逐字稿/不是最終文案」？ +- 主軸句是否只有一句、聽得懂、記得住？ +- 每一段節奏是否都對應清楚的時間與頁數？ +- 逐頁是否都填了「目的」，避免有頁面只是資訊堆疊？ +- 案例頁是否都要求呈現風險與驗證，不只是成果？ +- 備用頁索引表是否有標註對應正文頁、觸發情境與優先權重，且沒有被誤當成要生成的投影片？備用頁內容要不要生成，是否已經是使用者主動做的選擇，而不是被規則預設略過？ +- 是否有一段收尾 Prompt，並且明確提醒使用者要連同完整流程檔（或其檔案路徑）一起交給生成代理，而不是只丟這段濃縮文字？ + +## 使用情境範例 + +- 使用者說「我下週要分享一個技術主題，幫我規劃簡報流程」→ 從 Step 1 開始逐步引導。 +- 使用者已經有一份雜亂的簡報大綱，要求「幫我整理成流程檔格式」→ 先讀懂既有大綱在講什麼，再用上述七個步驟重新拆解，特別注意原本大綱裡的條列是否需要先收斂出核心訊息。 +- 使用者只想看這個方法論怎麼運作 → 引導他打開 `references/concept-overview.html` 看完整概念說明，或直接用 `references/example-ai-workshop-03.md` 當範例逐段解讀。 diff --git a/.agents/skills/presentation-flow-writer/references/concept-overview.html b/.agents/skills/presentation-flow-writer/references/concept-overview.html new file mode 100644 index 0000000..d189591 --- /dev/null +++ b/.agents/skills/presentation-flow-writer/references/concept-overview.html @@ -0,0 +1,736 @@ + +簡報流程檔：給生成 AI 的結構化藍圖 + + + +
+ +
+
+ 概念藍圖 · Presentation Flow Document +

簡報流程檔不是逐字稿，
是寫給生成 AI 的施工圖

+

+ 一份結構化文件，把敘事決策、每頁任務、視覺原則一次交代清楚， + 讓簡報生成 AI 代理能長時間產出不中斷，也不會重複做白工。 +

+
+
+
+
來源案例
+
AI 開發講堂#03 · 24 頁
+
+
+
交付對象
+
簡報生成 AI 代理
+
+
+
對應 Skill
+
presentation-flow-writer
+
+
+
+ +
+ 01 · 先定義它不是什麼 +

三個常見誤解

+

大部分人準備簡報素材時，寫出來的其實是這三種東西之一——但流程檔刻意都不是。

+
+
+
逐字稿
+

不寫「講者要唸的每一句話」，講者重點只給提示方向，留空間讓現場自然發揮。

+
+
+
最終投影片文案
+

不預先寫死每頁標題與內文，把「寫什麼字」的決定權留給生成代理去選擇視覺表現。

+
+
+
條列大綱
+

不是把所有想講的內容攤平列點，而是先分出「敘事節奏」再分派到每一頁。

+
+
+
+ 它是：一份結構化輸入，讓生成代理知道「敘事節奏」「每頁任務」「畫面安排方向」「該用案例還是條列」——把控制流程的責任從 Prompt 現場發揮，搬到文件先決策。 +
+
+ +
+ 02 · 為什麼能不中斷、不重工 +

四個機制

+

長任務最常見的失敗模式，是生成代理必須在過程中不斷停下來問「這頁要怎麼處理」。流程檔把這些追問提前擋掉。

+
+
+ M1 +

敘事決策一次做完

+

核心主軸、3-5 段節奏、頁數與時間分配全部先定案，生成當下不用重新判斷「這場分享要講什麼」。

+ → +
+
+ M2 +

每頁任務原子化

+

目的、核心訊息、畫面安排、講者重點、可引用素材五要素獨立成塊，每頁可以單獨生成，不必等待全域重新對齊。

+ → +
+
+ M3 +

主線、索引表、備用頁三者分流

+

正文一定要生成；導航索引表一律不生成；備用頁內容要不要先生成，交由使用者決定——三件事各自獨立，不會互相牽連。

+ → +
+
+ M4 +

風格與禁區提前講清楚

+

文字密度、圖像類型、動畫原則、避免事項一次列完，每頁不必重新猜測「這樣做符合風格嗎」。

+
+
+
+ +
+ 03 · 拆解一頁的解剖圖 +

每頁只做五件事

+

用來源案例第 9 頁「Hook 的實務配置」為例——完整用上全部五個欄位，是典型的五要素頁面結構。

+
+
+
第 9 頁：Hook 的實務配置：User-scope 與 Project-scope
+
+ 目的 +

讓聽眾知道 Hook 規則要放在哪個層級，而不是只知道「Hook 可以做什麼」。

+
+
+ 核心訊息 +

Hook 不是寫在同一個地方，規則放的層級會決定它的適用範圍。

+
+
+ 畫面安排 +

左欄／上層是 User-scope，標註「跨專案共用規則」；右欄／下層是 Project-scope，標註「只屬於特定專案的流程」。

+
+
+ 講者重點 +

讓聽眾建立分層概念：共用規則往 User-scope 放，專案限定規則往 Project-scope 放，避免規則重複執行。

+
+
+ 可引用素材 +

可參考 Hooks.md——生成代理不用憑空發想案例。

+
+
+
+

為什麼是這五格，不是更多

+
    +
  • 目的限制了這頁「為什麼存在」，避免變成塞資訊的容器。
    • +
  • 核心訊息逼出「一句結論」，對應「每頁只承載一個主要結論」的畫面原則。
    • +
  • 畫面安排只給結構方向（例如左右對比），把具體視覺表現的自由留給生成代理。
    • +
  • 講者重點是給人看的，不是給生成代理畫的，但保留下來讓文件同時服務兩種讀者。
    • +
  • 可引用素材把查證責任轉嫁給既有文件，生成代理不必臨場編造案例細節。
    • +
+
+
+
+ +
+ 04 · 三條分流的內容線 +

主線一定生成，索引表一定不生成，備用頁內容由你決定

+

來源案例的 24 頁正文之外，另外準備了 11 個備用頁題目——但「要不要把備用頁內容也先生成出來」是使用者自己的選擇，不是這個格式規定的省工手段；唯一沒有例外的是那張導航索引表，它一律不會被做成投影片。

+
+
+
主線 · 一定要生成
+
+ 正文 24 頁，逐頁都有完整五要素，依敘事節奏排定順序，是簡報生成的必產內容。 +
+ 第 1-5 頁 痛點與轉折 + 第 6-11 頁 Hooks + 第 12-17 頁 Subagents + 第 18-22 頁 案例與 Demo + 第 23-24 頁 收尾 +
+
+
+
+
備用頁內容 · 由你決定
+
+ 聽眾問了能直接切過去、時間夠也能多講——想先備好就跟正文頁一樣填五要素，想留到現場才決定也可以，兩種都合理。 +
+ 先生成備用 + 現場再決定 +
+
+
+
+
索引表 · 一律不生成
+
+ 只記錄「對應正文頁」「觸發情境」「優先權重」，純粹是講者自己臨場導航用的清單，不會交給生成 AI 產出對應投影片。 +
+ 觸發情境 + 對應正文頁 + 優先權重 +
+
+
+
+
+ +
+ 05 · 對照 +

沒有流程檔 vs 有流程檔

+
+
+
逐頁現場下指令
+
    +
  1. 每頁都要重新解釋這場分享的主軸是什麼
    2. +
  2. 視覺風格全靠生成代理臨場猜，前後容易不一致
    3. +
  3. 案例頁常常只秀成果，漏掉風險與驗證過程
    4. +
  4. 對話一長就開始忘記前面已經定調的敘事
    5. +
  5. QA 備用內容跟正文混在一起，生成時間被拉長
    6. +
+
+
+
先寫一份簡報流程檔
+
    +
  1. 核心敘事、節奏、頁數在文件開頭一次定案
    2. +
  2. 畫面原則與禁區寫成規則，風格從頭到尾一致
    3. +
  3. 案例頁明確要求「風險 → 設計機制 → 驗證方式」
    4. +
  4. 每頁任務獨立成塊，生成不必依賴對話記憶
    5. +
  5. 備用頁另建索引表導航，內容要不要先生成是你的選擇，不強制也不禁止
    6. +
+
+
+
+ +
+ 06 · 開始動手 +

自己的簡報，也能走同一條路

+

呼叫 presentation-flow-writer 這個 Skill，會依序引導你填出以下七塊，最後收斂成一段可以直接交給生成代理的 Prompt。

+
    +
  • 一句話寫下核心敘事主軸，以及希望聽眾帶走的思維轉變
    • +
  • 把分享拆成 3-5 段節奏，並抓出各段的時間與頁數預算
    • +
  • 訂出畫面原則與明確的「避免事項」清單
    • +
  • 逐頁填五要素：目的、核心訊息、畫面安排、講者重點、可引用素材
    • +
  • 另建備用頁索引表（一律不生成），並決定備用頁內容要不要也先做出來
    • +
  • 彙整給生成代理的版面指示：整體風格、圖像類型建議、動畫原則
    • +
  • 收尾寫一段交付說明，連同完整流程檔一起交給生成代理
    • +
+
+ +
+ 依內附範例 example-ai-workshop-03.md（AI 開發講堂#03）萃取而成 + presentation-flow-writer skill +
+ +
diff --git a/.agents/skills/presentation-flow-writer/references/example-ai-workshop-03.md b/.agents/skills/presentation-flow-writer/references/example-ai-workshop-03.md new file mode 100644 index 0000000..c93e6de --- /dev/null +++ b/.agents/skills/presentation-flow-writer/references/example-ai-workshop-03.md @@ -0,0 +1,895 @@ +# AI 開發講堂#03 簡報流程檔 + +## 文件用途 + +這份文件不是逐字稿，也不是最終投影片文案，而是提供給「簡報生成 AI 代理」的結構化輸入。 + +目標是讓代理知道： + +- 這場分享的敘事節奏 +- 每一頁的任務與重點 +- 每一頁適合的畫面安排與呈現方式 +- 哪些地方要用案例、流程圖、對比圖，而不是塞文字 + +## 這場簡報的總體設計原則 + +### 1. 核心敘事 + +這場分享以工程開發案例為主，但真正希望帶給聽眾的，不只是 Hooks 與 Subagents 兩個工具，而是 AI Workflow 的設計思維。 + +主軸句可以統一成： + +> 不要一直當 AI 的打字員，要開始設計 AI 的工作流程。 + +整場分享將帶領聽眾從「Prompt 使用技巧」，逐步走向「AI Workflow 設計」。 + +希望聽眾最後帶走的，不只是 Hooks 或 Subagents 本身，而是理解如何將工作拆解成： + +- 可分工（Delegation） +- 可驗證（Verification） +- 可重複（Repeatability） + +即使未來使用的 AI 工具不同，這套 Workflow 思維仍然具有價值。 + +### 2. 簡報節奏 + +整體節奏建議分成 4 段： + +1. 問題建立：為什麼現在這種用法很累 +2. 觀念翻轉：Prompt 不該承擔所有流程控制 +3. 兩個核心能力：Hooks 與 Subagents 各自解什麼問題 +4. 整合落地：兩者怎麼配合，最後形成可驗證工作流 + +### 3. 畫面原則 + +- 少做「大段條列」，多做「一句結論 + 一個圖像結構」 +- 每頁只承載一個主要結論 +- Hook 相關頁面偏「流程保底、規則、自動檢查」 +- Subagent 相關頁面偏「分工、隔離上下文、回傳結果」 +- 案例頁一定要展示「失敗風險 -> 設計機制 -> 驗證方式」，不要只秀成果 + +### 4. 頁數建議 + +這份流程以 50 分鐘版本為主要目標，24 頁安排是合理的。 + +建議節奏如下： + +- 第 1 到 5 頁：前 10 分鐘，建立痛點與觀念轉折 +- 第 6 到 10 頁：10 到 12 分鐘，講 Hooks 概念、實務配置與案例 +- 第 11 到 16 頁：12 到 15 分鐘，講 Subagents 與協作架構 +- 第 17 到 19 頁：8 到 10 分鐘，講 Gemma 4 案例與 mini demo +- 第 20 到 22 頁：5 分鐘內講完兩種 Mini Demo 對照（使用者決策 vs AI 自我修正） +- 第 23 到 24 頁：5 分鐘內收尾，並保留 QA 緩衝 + +除非現場時間被壓縮，否則不需要主動刪頁。 + +## 建議簡報流程 + +## 第 1 頁：封面 + +### 目的 + +建立主題氣氛，讓聽眾一眼知道這不是一般 Prompt 技巧分享。 + +### 標題建議 + +AI 開發講堂#03 +別再自己當 AI 的打字員！ + +副標可用： + +掌握 Hooks 與子代理，讓 AI 自動幫你打工 + +### 畫面安排 + +- 大標題置中 +- 副標較小 +- 背景可用「人盯著流程」對比「系統自動運作」的抽象視覺 +- 不要放太多資訊，姓名與日期放底部即可 + +### 講者重點 + +開場先不要解釋技術名詞，只先打出痛點與反差。 + +## 第 2 頁：這場分享怎麼來的？ + +### 目的 + +建立講者可信度。 + +讓聽眾理解，今天分享的內容來自實際導入 AI Workflow 的經驗，而不是理論整理或工具介紹。 + +### 核心訊息 + +今天分享的內容，不是理論整理，而是一路踩坑後留下來的方法。 + +### 畫面安排 + +採左右分欄。 + +左側放講者照片與簡短身份資訊（幫我預留可以填入的空間，這樣我後續可以插入圖片跟其它資訊）。 + +右側以「經驗演進流程」呈現： + +Software Engineer +→ AI Coding +→ 踩坑與驗證 +→ Hooks +→ Subagents +→ AI Workflow +→ 今天的分享 + +### 視覺建議 + +- 延續封面風格 +- 流程節點簡潔即可，不需正式流程圖 +- 強調一路演進，而非履歷介紹 + +### 避免 + +- 長篇履歷 +- 公司 Logo 牆 +- 技能條 +- 年份時間軸 + +## 第 3 頁：開場痛點 + +### 目的 + +讓聽眾承認自己常常在替 AI 補流程。 + +### 核心訊息 + +你以為你在用 AI，其實很多時候你是在幫 AI 收尾。 + +### 畫面安排 + +- 左右對比版型 +- 左邊放「你以為的樣子」：一句需求 -> AI 完成 +- 右邊放「實際上的樣子」：提醒測試、提醒格式化、提醒別亂刪、提醒補驗證 +- 右邊可刻意做得比較凌亂，形成情緒對比 + +### 講者重點 + +這頁要把問題定義成「協作流程成本」，不是模型不夠聰明。 + +## 第 4 頁：常見失控場景 + +### 目的 + +把痛點具體化，讓後面的解法有落點。 + +### 畫面安排 + +- 3 張卡片或 3 個情境框 +- 情境 1：每次都要提醒 AI 跑檢查 +- 情境 2：任務一複雜，對話一長就開始忘 +- 情境 3：你只想要結果，但得自己盯著流程 + +### 呈現建議 + +每張卡片只放一句短句，不要放說明段落。 + +### 講者重點 + +這頁是為了讓聽眾點頭，不是為了講完整理論。 + +## 第 5 頁：觀念轉折 + +### 目的 + +從痛點轉進核心論點：單靠 Prompt 不夠。 + +### 核心訊息 + +Prompt 很重要，但不適合負責所有固定流程控制。 + +### 畫面安排 + +- 中央一條分界線 +- 左側：Prompt 擅長的事，例如目標、限制、風格 +- 右側：Prompt 不適合扛的事，例如固定檢查、重複流程、安全守門 +- 右側下方補一句風險提示：固定流程越多，Prompt 越長，Token 越貴，漏執行的風險也越高 +- 底部放一句收斂句 + +### 收斂句建議 + +能用系統機制保證的事，就不要每次重新拜託模型一次。 + +## 第 6 頁：今天要帶走的框架 + +### 目的 + +讓聽眾提早知道今天不是工具介紹，而是分工架構。 + +### 畫面安排 + +- 一張簡單的雙核心圖 +- 左邊是 Hooks +- 右邊是 Subagents +- 中間用箭頭連到「AI Workflow」 + +### 每個區塊只放一句話 + +- Hooks：把固定流程自動化 +- Subagents：把複雜任務拆開分工 + +### 講者重點 + +這頁是全場的導覽圖，後面每一段都會回到這個框架。 + +雖然今天會以工程開發案例示範 Hooks 與 Subagents，但希望大家觀察的不只是工具，而是背後的 Workflow 思維。不同職能使用的工具可能不同，但固定流程、自動驗證、任務分工等設計原則，都能套用到自己的工作流程中。 + +## 第 7 頁：Hooks 是什麼 + +### 目的 + +先講用途，不先講設定細節。 + +### 畫面安排 + +- 主標一句話 +- 下方三欄卡片 +- 卡片 1：自動執行固定動作 +- 卡片 2：自動做安全防護 +- 卡片 3：減少模型做低價值重複工作 + +### 呈現建議 + +用圖示化呈現，例如扳手、盾牌、齒輪，不要全是文字。 + +### 講者重點 + +先把 Hook 建立成「不用推理、但必須穩定執行的流程機制」。 + +## 第 8 頁：Hooks 適合放哪些事 + +### 目的 + +讓聽眾知道哪些工作該交給 Hook，不要泛化。 + +### 畫面安排 + +- 兩欄式 +- 左欄：適合 Hook 的事 +- 右欄：不適合 Hook 的事 + +### 建議內容 + +左欄：格式化、lint、測試、危險指令攔截、固定驗證 + +右欄：開放式分析、需要多步推理的判斷、模糊需求拆解 + +### 講者重點 + +這頁要幫聽眾建立邊界感，避免把 Hook 講成萬能自動化。 + +## 第 9 頁：Hook 的實務配置：User-scope 與 Project-scope + +### 目的 + +讓聽眾知道 Hook 規則要放在哪個層級，而不是只知道「Hook 可以做什麼」。 + +### 核心訊息 + +Hook 不是寫在同一個地方，規則放的層級會決定它的適用範圍。 + +### 畫面安排 + +- 兩欄或兩層卡片 +- 左欄／上層：User-scope，標註「跨專案共用規則」 +- 右欄／下層：Project-scope，標註「只屬於特定專案的流程」 + +### 建議內容 + +- User-scope：個人慣用的檢查、格式化偏好、跨專案都要守的安全規則 +- Project-scope：這個專案特有的測試指令、部署前檢查、專案限定的危險操作清單 + +### 講者重點 + +這頁要讓聽眾建立分層概念：共用規則往 User-scope 放，專案限定規則往 Project-scope 放，避免規則重複執行。 + +### 可引用素材 + +可參考 Hooks.md。 + +## 第 10 頁：Hook 實戰案例 + +### 目的 + +進入 block-dangerous 案例，證明自動化不是設了就算。 + +### 畫面安排 + +- 時間線或故障排查流程圖 +- 依序放 4 個節點： + 1. 以為設定完成 + 2. 實測沒攔到 + 3. 追查原因 + 4. 發現是 Windows 路徑與執行方式造成 fail-open + +### 講者重點 + +這頁不要講成技術細節 dump，而是講「安全自動化也會靜默失效」。 + +### 可引用素材 + +可參考 block-dangerous-hook-debug-notes.md。 + +## 第 11 頁：Hook 案例的三個結論 + +### 目的 + +把案例抽象成可複用原則。 + +### 畫面安排 + +- 3 張大卡片，最好一張一結論 +- 結論 1：自動化一定要驗證 +- 結論 2：安全機制最怕靜默失效 +- 結論 3：工作流細節比口號更重要 + +### 講者重點 + +這頁是 Hook 段落的收束點，要讓聽眾知道 Hook 的價值在「保底」，不是「看起來很自動化」。 + +## 第 12 頁：Subagents 是什麼 + +### 目的 + +把子代理講成分工架構，不是多開幾個聊天視窗。 + +### 核心訊息 + +主代理負責規劃與整合，子代理負責局部任務與獨立上下文。 + +### 畫面安排 + +- 中央放主代理 +- 周圍放 3 到 4 個子代理泡泡 +- 每個子代理只標一種任務，例如研究、修改、驗證、摘要 +- 最後箭頭回到主代理整合結果 + +### 講者重點 + +這頁一定要視覺化「分出去又收回來」，不然聽眾很容易把它理解成平行聊天而已。 + +### 可引用素材 + +可參考 Subagents.md。 + +## 第 13 頁：子代理真正的價值 + +### 目的 + +講清楚 Subagents 的價值不是省事而已，而是控制上下文污染。 + +### 畫面安排 + +- 左邊放「沒有子代理」的狀態：主對話堆滿 try-and-error、中間垃圾資訊、失敗路徑 +- 右邊放「有子代理」的狀態：主對話只留下結論、決策與整合結果 +- 頂部先放一句但書：子代理不是免費，也不保證一定省 Token + +### 核心句 + +凡是會製造很多中間垃圾上下文的工作，都很適合關進子代理處理。 + +### 講者重點 + +這頁是 Subagents 段落最重要的一頁，要把「上下文隔離」講得非常清楚。 + +## 第 14 頁：哪些任務適合交給子代理 + +### 目的 + +給聽眾一個可直接套用的判斷清單。 + +### 畫面安排 + +- 3 欄卡片式 +- 類型 1：大量 try-and-error +- 類型 2：跨領域協作 +- 類型 3：輸入輸出明確的加工工作 + +### 每欄可各放 2 個例子 + +- try-and-error：除錯、編譯修正、測試修正 +- 跨領域：前端、後端、資料庫、安全檢查分工 +- 加工工作：摘要、翻譯、格式轉換、規格驗證 + +### 講者重點 + +這頁要務實，不用太抽象。 + +### 可引用素材 + +可參考 Subagents.md。 + +## 第 15 頁：兩個常見迷思 + +### 目的 + +提前處理聽眾可能的誤解。 + +### 畫面安排 + +- 上下兩段或左右兩張對比卡 +- 迷思 1：子代理越多越好 +- 迷思 2：一定要自己設計超複雜 input/output 才能用 + +### 對應澄清 + +- 重點不是數量，而是任務邊界是否清楚 +- 很多情況只要把工作切成明確任務，子代理就已經有價值 + +### 講者重點 + +這頁可以講輕鬆一點，作為節奏換氣。 + +## 第 16 頁：Hooks 與 Subagents 怎麼搭配 + +### 目的 + +進入全場最重要的橋接頁，說明兩者不是平行功能。 + +### 核心訊息 + +Hooks 負責保底，Subagents 負責分工。 + +### 畫面安排 + +- 用一條流程帶過整個任務生命週期 +- 流程順序建議： + 1. 主代理接需求 + 2. 分派給子代理做研究或修改 + 3. 回收結果 + 4. Hook 在關鍵操作前後自動檢查 + 5. 主代理整合並輸出 + +### 視覺建議 + +- 用不同顏色區分「思考分工」與「流程保底」 +- 不要做得太技術架構圖，重點是讓聽眾一眼看懂角色分工 + +## 第 17 頁：一句話版本的協作架構 + +### 目的 + +把前一頁壓縮成一句可以被記住的話。 + +### 畫面安排 + +- 幾乎整頁只放一句主句 +- 下方小字補一句解釋 + +### 主句建議 + +子代理幫你做判斷，Hook 幫你守流程。 + +### 補充句建議 + +一個負責把工作拆對，一個負責把底線守住。 + +### 講者重點 + +這頁是記憶點頁，務必簡潔。 + +## 第 18 頁：Gemma 4 案例為什麼值得示範 + +### 目的 + +把後半段 demo 轉成高風險知識工作流案例，而不是單純秀成果。 + +### 畫面安排 + +- 3 個風險卡片 +- 風險 1：官方與第三方資料層級要分清楚 +- 風險 2：跨章節規則會互相牽動 +- 風險 3：知識庫沒答案時必須誠實承認不知道 + +### 核心訊息 + +這不是「寫一段好 Prompt」就能穩定解決的問題。 + +### 講者重點 + +先講風險，再講設計，這樣觀眾才知道為什麼要用工作流思維。 + +## 第 19 頁：Gemma 4 案例的分工設計 + +### 目的 + +用具體案例把主代理、子代理、Hook 三者的分工講清楚。 + +### 畫面安排 + +- 三層式結構圖 +- 第一層：主代理定義任務與整合結果 +- 第二層：子代理做多方查證與風險摘要 +- 第三層：Hook 檢查是否附查證摘要、來源層級、未覆蓋風險 + +### 核心句 + +子代理負責查證，Hook 負責守門。 + +### 可引用素材 + +可搭配 Subagents.md 與 mini-demo-runbook.md。 + +## 第 20 頁：Mini Demo 流程 + +### 目的 + +讓聽眾看到一個足夠簡單、但結構很清楚的示範流程。 + +### 畫面安排 + +- 4 步驟流程圖 +- Step 1：主代理先產出 Gemma 4 說明 +- Step 2：子代理回傳查證摘要 +- Step 3：Hook 檢查必要驗證資訊是否齊全 +- Step 4：通過才正式寫入 + +### 講者重點 + +強調：子代理在做判斷，Hook 在守流程。 + +### 呈現建議 + +如果現場要 live demo，這頁可以當操作地圖。 +如果不 live demo，這頁就當靜態流程頁。 + +## 第 21 頁：Mini Demo 2 流程 + +### 目的 + +用一次真實發生的「補測試」任務，展示 Hook 與 Subagent 如何在同一個工作流裡各司其職：Hook 負責守住既有程式碼品質的底線，Subagent 則負責獨立驗證交付物的真正價值，兩者都不讓主代理球員兼裁判。 + +### 核心訊息 + +主代理埋頭做事的時候，Hook 擋下了一個「順手就想修掉」的衝動，Subagent 則抓出了主代理自己看不出來的測試漏洞。 + +### 畫面安排 + +建議 5 步驟流程圖（比第 20 頁多一步，因為這次多了一次「使用者決策」的分支）： + +1. Step 1：使用者提案 -> 主代理盤點待補測試的目標函式，寫成 proposal.md／tasks.md，等待使用者確認才開始動手 +2. Step 2：主代理逐條加 export、補測試 -> 存檔時觸發 format-lint Hook +3. Step 3：Hook 擋下一個「與本次任務無關」的既有問題（程式碼裡兩個未使用的變數）-> 主代理沒有自行決定要不要修，而是回頭詢問使用者 +4. Step 4：使用者選擇處理方式 -> 主代理依指示執行、Hook 放行，測試與型別檢查全數通過 +5. Step 5：主代理呼叫 test-quality-reviewer 子代理獨立審查 -> 子代理找出數處邊界情境遺漏，主代理依審查結果補測試 + +### 講者重點 + +- 這裡的 Hook 不是在做格式化這種低風險的事，而是真的擋下了一次「這個問題順手修一修好了」的衝動，讓 AI 停下來問人，而不是自己悄悄擴大任務範圍 +- test-quality-reviewer 是獨立的子代理，它沒有主代理的對話記憶，只看測試檔案本身，所以它抓到的漏洞，才真正代表「這批測試禁得起沒有上下文的人檢驗」 +- 兩個機制合起來，才讓「補測試」這個聽起來很瑣碎的任務，變成一個有品質保證的工作流，而不是「AI 說做完了就算做完了」 + +### 呈現建議 + +如果要 live demo，可以直接秀出 Hook 擋下的錯誤訊息畫面，以及 test-quality-reviewer 的審查結果摘要，讓聽眾看到「真實的擋下與抓漏」，而不是重新演一次。 +如果不 live demo，這頁可以搭配「Hook 擋下畫面截圖」與「子代理審查結果摘要」的對照卡呈現。 + +## 第 22 頁：Mini Demo 2 流程的另一種情況 + +### 目的 + +不是另開一場新 demo，而是接著第 21 頁同一次「補測試」任務，把 Hook 攔截的另一種結局攤開來對照：這次擋下的是 AI 自己這次修改造成的問題，AI 判斷問題就在自己的變更範圍內，於是直接自我修正、重新存檔，不需要停下來問使用者。 + +這頁不現場操作。AI 會不會在台上剛好手滑犯錯是沒辦法保證的事，硬要賭一次現場重現，風險大於效果。這頁改用靜態對照卡呈現這個結局（Hook 擋下訊息、AI 自我修正後的 diff、Hook 再次放行訊息），畫面素材可以交給簡報生成 AI 產出，不一定要是操作截圖。 + +### 核心訊息 + +不是每次被 Hook 擋下，主代理都要丟回給使用者決策——問題如果是自己這次改出來的、屬於自己該負責的範圍，AI 應該自己修好、自己驗證過關，而不是把每一次攔截都變成一次打斷使用者的請求。 + +### 畫面安排 + +建議用「情況 A / 情況 B」左右對照卡呈現，而不是重新畫一次 4 步驟流程圖： + +- 情況 A（第 21 頁）：Hook 擋下的是跟本次任務無關的既有問題 -> 主代理停下來問使用者 -> 使用者決策 -> Hook 放行 +- 情況 B（本頁）：Hook 擋下的是這次修改本身造成的問題（例如新增的測試檔案裡有一個未使用的 import）-> 主代理判斷屬於自己這次變更的範圍 -> 直接自行修正、重新存檔 -> Hook 放行 + +兩張卡片刻意對齊「擋下」與「放行」的位置，只有中間那一步不一樣，讓觀眾一眼看出差異只在「要不要問人」。 + +### 講者重點 + +- 同一個 Hook、同一份任務，這次擋下的是主代理自己造成的問題，判斷標準很清楚：問題是不是這次變更範圍內的，是的話就自己收尾，不必每次都把使用者拉進來 +- 對照第 21 頁：範圍外的既有問題要回頭問人，範圍內的自己造成的問題要自己修好，這條界線就是 Hook 該不該觸發「使用者決策」的關鍵 +- 這頁要強調的不是「AI 更聰明了」，而是「工作流把該問人跟不該問人的情況分開了」，使用者的時間只花在真正需要決策的地方 +- 如果有觀眾問「為什麼這頁不現場示範」，可以直接說明：AI 會不會犯錯不受控，這頁刻意不賭一次現場運氣 + +### 呈現建議 + +不現場操作。用「Hook 擋下畫面」、「AI 自我修正後的 diff」、「Hook 再次放行畫面」三個對照畫面做左右或上下呈現，並排在第 21 頁的畫面旁邊，強化「同一個機制、兩種結局」的對比感。 + +## 第 23 頁：實務落地建議 + +### 目的 + +把概念收斂成可執行原則。 + +### 畫面安排 + +- 5 條原則，建議用 checklist 呈現 +- 不要一開始就把所有事丟給子代理 +- 先把固定、低推理需求流程交給 Hook +- 先把高噪音、高上下文污染工作交給子代理 +- 任何自動化都要驗證 +- 先從 1 到 2 個高價值場景落地 + +### 講者重點 + +這頁講法要務實，避免讓分享變成概念口號。 + +## 第 24 頁：收尾 + +### 目的 + +把整場分享從工具技巧收回到方法論層次。 + +### 畫面安排 + +- 上半部一句大結論 +- 下半部一句收尾句 + +### 大結論建議 + +接下來真正拉開差距的，不是誰比較會寫 Prompt，而是誰比較會設計 AI 工作流。 + +### 收尾句建議 + +你不是要更會盯 AI，而是要讓 AI 的流程被設計得不需要你一直盯。 + +## 備用頁建議 + +如果你預期現場 QA 會多，或 demo 有風險，建議另外準備一批備用頁。 + +### 備用頁索引（僅供操作參考，不需產生為投影片） + +這張表只是幫你臨場快速判斷「聽眾問了什麼、該跳去哪一頁」，不是敘事順序，也不需要交給簡報生成 AI 產出對應頁面。 + +| 備用頁 | 標題 | 對應正文頁 | 觸發情境 | 優先權重 | +| --- | --- | --- | --- | --- | +| A | Hook 與 Subagent 對照表 | 第 7-11 頁（Hooks） | 問「Hook 跟 Subagent 差在哪」的基礎題 | 高（最常見的開場式提問，先備好） | +| H | Hook 正向實作案例：從「踩坑」到「建立確定性防線」 | 第 10 頁（Hook 失敗案例） | 聽完失敗案例後追問「那 Hook 到底有沒有用」 | 高（緊接在失敗案例後最容易被問） | +| G | 同一個 Prompt，有無子代理的 Token 消耗對照 | 第 13 頁（上下文隔離） | 想看「隔離上下文」的量化證據 | 中高（數字最有說服力，適合先亮） | +| I-A | 並行執行路徑 (Parallel Execution) | 第 13 頁（上下文隔離） | 想看「隔離上下文」具體怎麼分類套用 | 中高（接在 G 後面講案例） | +| I-B | 交叉驗證路徑 (Cross-Validation) | 第 13 頁（上下文隔離） | 同上，deeper 追問「怎麼確保子代理沒亂驗證」 | 中高 | +| I-C | 深度審核路徑 (Deep Audit) | 第 13 頁（上下文隔離） | 同上，deeper 追問「大量資料怎麼處理」 | 中高 | +| F | GitHub Copilot 內建 Subagents 對照 | 第 14 頁（適合交給子代理的任務） | 質疑分類是不是自創、有無業界佐證 | 中（被追問權威性時才需要） | +| E | Simple SDD——用小提案降低來回溝通成本 | 第 16-22 頁（整合流程） | 想知道「大功能怎麼拆得不失控」 | 中（也是 J 的前提，建議跟 J 放在同一組） | +| J | 執行長任務的關鍵——事前準備讓長任務如期完工 | 第 16-22 頁（整合流程） | 問「長任務怎麼保證如期完工」 | 中（整合層次，優先度低於單一工具提問） | +| K | 子代理不複雜——差在你有沒有講明白 | 第 12 頁（Subagents 是什麼） | 覺得子代理是複雜技術、或問「跟我自己下指令有什麼不同」 | 中（破除迷思用，緊接在第 12 頁之後最順） | +| B | Gemma 4 案例驗證證據 | 第 18-19 頁（Gemma 4 案例） | 對案例嚴謹度有興趣 | 中低 | +| C | 生成測試案例的嚴謹性驗證 | 第 21 頁（test-quality-reviewer） | 對測試案例嚴謹性有興趣 | 中低 | +| D | eslint --fix 不代表問題就解決了 | 第 10-11 頁（Hook 失敗案例的延伸） | 對「自動化也要驗證」這件事有興趣 | 中低 | + +### 備用頁 A：Hook 與 Subagent 對照表 + +用途：當有人問「兩者差在哪」時，可以快速回切。 + +建議欄位： + +- 解決的問題 +- 適合的任務 +- 不適合的任務 +- 風險點 +- 最佳使用時機 + +### 備用頁 B：Gemma 4 案例驗證證據 + +用途：如果聽眾對案例嚴謹度有興趣，可補充展示。 + +建議內容： + +- 查證摘要長什麼樣子 +- 來源分級如何標示 +- 沒有答案時如何明確標示風險 + +### 備用頁 C：生成測試案例的嚴謹性驗證 + +用途：如果聽眾對生成測試案例的嚴謹性有興趣，可補充展示。 + +主軸：有了 AI 之後，要生成測試案例很簡單，但你怎麼知道生成出來的案例足夠嚴謹，而不是只是「看起來有測試案例」？所以我建立了一個 test-quality-reviewer 子代理，專門檢查 AI 生成的測試案例是否具有真正的價值，而不是只是 coverage padding。 + +建議內容： + +- 測試案例生成流程 +- 驗證標準與方法 +- 潛在風險與應對措施 + +### 備用頁 D：eslint --fix 不代表問題就解決了 + +用途：如果聽眾對「自動化流程也需要驗證」這件事有興趣，可補充展示一次剛發生的實戰案例。 + +主軸：Hook 裡設了 `eslint --fix`，很容易讓人誤以為「有跑自動修復，lint 問題就處理掉了」。但實際上 `--fix` 只能修掉可自動修復的規則，像 unused-vars 這類問題它修不了，如果 Hook 沒有再檢查修完之後還剩什麼、只是執行完就算過，這些真正的錯誤就會被悄悄放過。這次的改良就是把舊版「跑完 `--fix` 就結束」的 Hook，改成用 `--format json` 解析結果、只在真的還有無法自動修復的 error 時才擋下來，並且不是改完程式碼就相信它有效，而是故意在真實檔案留一個修不掉的 lint 錯誤，實際觸發一次，確認 Hook 真的會擋、訊息也如預期，才算數。 + +建議內容： + +- 常見誤解：以為「有跑 `--fix`」等於「lint 問題已處理完」，但 `--fix` 只能處理可自動修復的規則 +- 舊版做法的漏洞：Hook 只看有沒有跑完指令，不檢查跑完之後還剩下什麼錯誤，等於自動化了一個「看起來有檢查、其實沒真的擋」的流程 +- 改良方式：解析 ESLint 的 JSON 輸出取得精確的 errorCount，只有真的修不掉的 error 才擋下並回報，warning 或無問題則放行 +- 實測驗證：不是看程式碼覺得「邏輯應該對」就結束，而是故意留一個修不掉的錯誤實際跑一次，確認 Hook 真的擋下來 +- 意外收穫：驗證過程中順手發現專案裡本來就存在、與本次任務無關的 2 個未使用變數，選擇不擅自修改，而是另外向使用者提出 + +### 備用頁 E：Simple SDD —— 用小提案降低來回溝通成本 + +用途：如果聽眾對「怎麼讓 AI 做大功能又不失控」有興趣，可補充展示我們實際在用的輕量提案流程。 + +主軸：AI 動作快，但快不等於方向對。如果每次都是「說一句需求 -> AI 直接開始改」，出錯的時候要嘛改壞一大片，要嘛雙方要來回好幾輪才對齊。Simple SDD 是一個很輕量的三階段流程：提案 -> 實作 -> 歸檔。核心規矩只有一條——動手寫程式之前，先把要做什麼寫清楚，讓使用者確認過再開始。 + +建議內容： + +- 提案階段：AI 把需求拆成 `proposal.md`（為什麼做、要改什麼、影響範圍）與 `tasks.md`（拆成一條一條、1 小時內能做完的小步驟，外加白話的驗收情境），寫完就停下來等使用者確認，不會自己先動手 +- 實作階段：一次只做一條任務，做完就對照驗收情境自我檢查、打勾、簡短回報，發現規格有漏洞就停下來問，不會自己亂改規格硬幹 +- 歸檔階段：確認所有任務都打勾後，把整份提案資料夾搬進 `archive`，並留下一句話總結，方便日後回頭查是誰、為了什麼、改了什麼 +- 降低溝通成本的關鍵：分歧只會發生在「一頁 proposal」的階段，而不是發生在「已經改了一半程式碼」之後，回頭調整的代價差非常多 +- 用小決議做大功能：一個大功能可以拆成好幾輪 Simple SDD（例如今天先補 3 個檔案的測試、下一輪再補另外 4 個），每一輪都是可以獨立確認、獨立歸檔的小決議，串起來就是完整的大功能 + +### 備用頁 F：GitHub Copilot 內建 Subagents 對照 + +用途：如果聽眾對「子代理實際上要怎麼分工」感覺還是有點抽象，可以用 GitHub Copilot 內建的 Subagent 分類當現成案例補充說明。 + +主軸：這是 GitHub Copilot 內建的 Subagent 分類，不是通用標準，但可以當作「子代理怎麼分工」的具體示範。其他工具（Claude Code、Codex CLI 等）理論上不會差太多，都是圍繞「探索、執行任務、思考討論、審查、研究、安全檢查」這幾種角色在做劃分，差別多半在名稱與細節，不是概念本身。 + +建議內容： + +- 七種內建 Subagent 的定位對照：explore（理解不修改）、task（把工作完成）、general-purpose（預設模式）、rubber-duck（陪你思考）、code-review（Reviewer 視角）、research（查資料整理知識）、security-review（安全專家） +- 對應到軟體開發流程的順序：Explore → Research → Rubber Duck → Task → Code Review → Security Review +- 強調重點：這只是「一種工具的預設分工方式」，用意是佐證第 14 頁「哪些任務適合交給子代理」的判斷清單並非憑空而來，而是業界工具已經在朝同樣的方向收斂 + +### 呈現建議 + +這頁沒有實際截圖，也不需要硬湊一張。用一條橫向流程色塊呈現 6 個核心角色即可：Explore → Research → Rubber Duck → Task → Code Review → Security Review，每個角色一張圖示卡片（例如放大鏡、書本、對話泡泡、扳手、審閱記號、盾牌），保持一致的視覺語言。general-purpose 因為沒有固定順序位置，用一張浮動小卡標在流程線外側，註明「預設模式，不落在特定階段」，不要硬塞進主線打斷節奏。 + +### 可引用素材 + +可參考 Copilot-Built-in-Subagents.md。 + +### 備用頁 G：同一個 Prompt，有無子代理的 Token 消耗對照 + +用途：如果聽眾對第 13 頁「子代理能隔離上下文污染」這句話還是覺得偏抽象、想看實際數字，可以用這組監控截圖佐證。 + +主軸：用同一個 Prompt 分別跑一次「有交給子代理處理」與「主代理自己全程處理、沒有交給子代理」，比較兩者的 Session 總 Token 與快取讀取 Token。同一張圖裡左側柱子是有子代理的 session（Session 總 Token 186.5k），右側柱子是沒有子代理、主代理自己一路做完的 session（快取讀取 Token 313.7k，柱體也明顯更高）。差距的來源不是任務本身變複雜，而是主代理自己扛下所有 try-and-error 過程時，中間垃圾上下文被疊進同一個對話，連帶推高了每一輪都要重新讀取的快取 Token。 + +建議內容： + +- 左右對照：有子代理（Token 較低、柱體較矮）vs 沒子代理（Token 較高、柱體較高），同一個 Prompt、同一個任務 +- 點出關鍵不是「總任務量」變大，而是「沒有把中間過程關進子代理」導致上下文一路累積 +- 呼應第 13 頁的核心句：凡是會製造很多中間垃圾上下文的工作，都很適合關進子代理處理 +- 提醒但書：這只是單次任務的實測數字，不是普遍比例，重點是讓聽眾理解「Token 差距從哪裡來」，而不是宣稱子代理一定省多少 % + +### 呈現建議 + +以有子代理（hover 在左側柱子）與沒子代理（hover 在右側柱子）的監控截圖左右並排，保留監控工具原始畫面比較有說服力，不需要重新繪圖，但建議： + +- 裁切：只留 Token 長條圖與 hover 數字的區塊，去掉工具列、側邊欄等與本頁無關的介面雜訊 +- 放大標註：在兩張圖中間或下方，用大字直接寫出「186.5k vs 313.7k」的對比數字，不要讓聽眾自己瞇眼讀截圖裡的小字 +- 一致對齊：兩張圖裁切後的長條圖底線要對齊，讓「柱體高度差」一眼可辨 + +### 備用頁 H：Hook 正向實作案例：從「踩坑」到「建立確定性防線」 + +用途：對應第 10 頁的失敗案例。當聽眾問「那 Hook 真的有用嗎」或「正確的 Hook 應該長怎樣」時，用來證明 Hook 如何將 AI 的隨機性轉化為可控的流程。 + +主軸：第 10 頁展示的是環境因素導致失效的教訓，而這裡展示的是設計目標的達成。真正的 Hook 不是為了「阻止」AI，而是為了「建立確定性」。 + +建議內容： + +- 建立「範圍外問題」的強制交還機制：證明 Hook 擋下與本次任務無關的既有 lint 債務（未使用變數）時，AI 不會自己決定要不要清，而是把決策權強制交還給使用者，避免任務範圍被悄悄擴大。 +- 建立「品質提醒」的干預機制：證明在存檔前可以讓 Hook 提醒 AI 重新檢查品質，將「隨機修好」變成「確認修好」。 +- 核心結論：Hook 的價值在於把「希望 AI 做對」變成「流程強制它做對」——不管是強制交還範圍外問題的決策權，還是強制修好範圍內的品質問題。 + +### 呈現建議 + +兩張都是終端機截圖，文字密度很高，不建議整張貼上投影片。各自處理成兩個裁切區塊： + +- 第一張：上半部只留「PostToolUse:Edit hook returned blocking error」那幾行錯誤訊息，下半部只留 AI 提出的決策選單（刪除死碼／加 eslint-disable／自訂）。中間用紅框標出關鍵句，旁邊補一句大字說明：「Hook 擋下範圍外的既有問題，逼 AI 回頭問人」。 +- 第二張：上半部只留被擋下的 ESLint 錯誤清單（挑 2-3 條有代表性的即可，不用全列），下半部只留 AI「Good, first occurrence fixed. Now the second one...」的修正回應。旁邊補一句大字說明：「存檔前被攔下，AI 逐條修好才能過關」。 +- 兩張裁切完的區塊建議用相同版型左右或上下對齊呈現，強化「同一種 Hook 機制、兩種情境」的結構感。 + +### 備用頁 I：Sub-agents 實踐模式庫：具象化「上下文隔離」的三種路徑 + +用途：對應第 13 頁。如果聽眾對「隔離上下文污染」覺得太抽象，用這組模式圖證明：不同任務有不同的隔離路徑。 + +主軸：將子代理的運用分為三種具體模式，證明「把過程關起來」能讓主代理維持最高清醒度。三種模式建議拆成三頁（I-A、I-B、I-C）呈現，而不是塞在同一頁——七張截圖擠在一頁會超出「每頁 3-5 個視覺元素」的原則，聽眾也會抓不到重點。 + +核心結論（三頁共用，放在 I-C 頁尾收束即可）：子代理不只是分工，更是為了維持主代理的「Context Purity」。 + +#### 備用頁 I-A：並行執行路徑 (Parallel Execution) + +建議內容：證明在大規模掃描任務時，所有中間的搜尋路徑都隔離在子代理，主代理只收結果。 + +呈現建議：兩張圖都是「N agents finished」的清單畫面，裁切成只留任務清單那個區塊即可，去掉上方對話與下方狀態列。兩張可以左右並排，或用逐步 reveal 先秀第一張（4 個子代理平行審查 commit）、再秀第二張（4 批平行檢查資料夾命名），強調「同一種模式套用在不同任務上」。 + +#### 備用頁 I-B：交叉驗證路徑 (Cross-Validation) + +建議內容：搭配「建立提案基準線：用 Simple SDD 寫出 proposal.md／tasks.md」與「派子代理交叉驗證提案與既有測試清單，抓出跨檔案不成立的技術宣稱」。證明「先建立可驗證的基準線 → 派子代理交叉比對抓矛盾 → 回頭修正」這一整套繁瑣過程被完全隔離，主代理只需要接收「哪裡有矛盾」的結論。 + +呈現建議：這一組最需要標註，因為兩張圖各自代表流程的不同階段。建議用「Step 1：建立基準線」「Step 2：交叉驗證抓矛盾」兩張小卡對照呈現，各裁切出關鍵段落，並用逐步 reveal 依序帶出，不要一次全部亮出來讓聽眾自己拼因果關係。 + +#### 備用頁 I-C：深度審核路徑 (Deep Audit) + +建議內容：證明處理海量資料時，主代理不需要讀過所有細節，只需接收「精簡後的風險報告」。 + +呈現建議：三張圖只挑一張當主視覺，建議用最能呈現「子代理審查完成，整體評價良好，但抓到 3 個檔案有邊界情境遺漏」這種精簡報告的畫面，裁切成只留審查結論那幾行。另外兩張當作同頁的兩個小縮圖，標註「同一套模式也套用在稽核 commit 行為、盤點測試缺口」，證明這個模式的可複用性，不需要逐一展開細節。 + +核心結論：子代理不只是分工，更是為了維持主代理的「Context Purity」。 + +### 備用頁 J：執行長任務的關鍵——事前準備讓長任務如期完工 + +用途：當聽眾問「任務很大、要跑很久，怎麼確保如期完工？」或「長任務容易失控怎麼辦？」時使用。 + +主軸：長任務會不會如期完工，關鍵不在執行當下多努力，而在動手前有沒有做好三件準備：把任務拆成看得見進度的清單、把可以並行的工作分出去、把驗收標準訂在執行之前。 + +建議內容： + +- 準備一：任務先拆成清單 (Task Breakdown)：呼應備用頁 E 的 Simple SDD 流程，把任務拆成逐條打勾的清單，正是動手前就已經拆好的 tasks.md 清單——長任務不是走一步算一步，而是先有一份看得到進度的清單。 +- 準備二：可並行的工作先分出去 (Async Delegation)：主代理不再是單線循環，而是調度中心。將研究交給 Explore，審查交給 test-quality-reviewer，主代理負責同步結果，不必等自己一步步做完。 +- 準備三：驗收標準先訂好 (Decoupled Verification)：長任務的終點不是「AI 說他做完了」，而是任務清單裡本來就寫好的驗收條件，被自動化測試、型別檢查、獨立的驗證子代理三方會簽通過。 + +核心結論：長任務能不能如期完工，答案在動手前就已經決定了大半——先拆好清單、先分好工、先訂好驗收標準，執行時才有東西可以盯，而不是盯著 AI 的對話框祈禱。 + +### 呈現建議 + +建議裁成三張小卡，逐一對應「準備一/二/三」，用逐步 reveal 動畫，講一個準備要點、亮一張小卡，三張都出現後再收在核心結論句，讓畫面節奏跟著文案的三段式走。 + +### 備用頁 K：子代理不複雜——差在你有沒有講明白 + +用途：當聽眾覺得子代理是很複雜的技術、或問「這跟我自己下指令有什麼不同」時，用這頁破除迷思，把子代理拉回一個很簡單的判斷題。 + +主軸：子代理本身不是什麼特殊機制，你我的差別只在於一件事——要不要在 prompt 裡明確講清楚「這件事交給子代理做」，還是讓 AI Agent 工具自己去推測該不該用、該用哪一個子代理。多數工具都有能力自己判斷，但判斷不判斷得準，取決於你講得夠不夠明確，不是取決於工具有沒有這個能力。 + +建議內容： + +- 用 explore 子代理當例子，因為大多數 AI Agent 工具都內建這個角色，聽眾容易對照到自己平常用的工具 +- Prompt 1（模糊、讓工具自己推測）：「這個專案的登入邏輯在哪裡？」——AI Agent 工具可能自己判斷叫 explore 子代理去找，也可能直接自己翻找，結果不一定每次都隔離在子代理裡 +- Prompt 2（明確指定要用子代理）：「用 explore 子代理去找這個專案的登入邏輯在哪裡」——不管工具本身會不會推測，這次都保證交給子代理處理 +- 核心結論：如果你已經知道這件事該關進子代理處理（例如上下文很雜、任務邊界清楚），與其賭工具的判斷，不如直接在 prompt 講明白 + +### 呈現建議 + +左右兩欄對照卡：左邊放「模糊 prompt」，中間用一個問號箭頭指向 explore 子代理泡泡（表示工具自己猜要不要用）；右邊放「明確 prompt」，用一個直接箭頭指向同一個 explore 子代理泡泡（表示你直接指定）。兩欄刻意只在「箭頭是問號還是直接」這個地方不同，讓聽眾一眼看出差異只在「你有沒有講明白」，而不是子代理本身有多複雜。 + +## 給簡報生成代理的版面指示 + +### 視覺彈性原則 + +- 這份流程不預設綁定企業簡報底板，簡報代理可以自由設計整體視覺 +- 本文件主要提供的是資訊架構、敘事節奏與畫面類型建議，不限制特定品牌樣式 +- 如果後續仍想沿用既有模板，也可以保留本文件的結構與節奏，僅調整視覺表現即可 +- 視覺設計應優先服務敘事清楚度，不要為了風格犧牲訊息層次 + +### 整體風格 + +- 不要做成教學模板感很重的制式簡報 +- 風格偏清楚、俐落、帶一點工程感 +- 文字密度控制保守，寧可用圖與結構說話 + +### 文字密度 + +- 每頁主標要短 +- 每頁最多 3 到 5 個視覺元素 +- 避免整頁塞滿子彈條列 + +### 圖像類型建議 + +- 痛點頁：對比圖、混亂 vs 有秩序 +- Hook 頁：流程、攔截、檢查點 +- Subagent 頁：分工圖、上下文隔離圖 +- 整合頁：端到端流程圖 +- 案例頁：風險圖、驗證流程、角色分工圖 + +### 動畫建議 + +- 只做逐步 reveal，不要做花俏轉場 +- 最適合動畫的頁面是第 9、15、19 頁，因為都有流程感 + +## 建議交付給簡報代理時附帶的額外說明 + +你可以把下面這段一起交給簡報代理： + +> 請依照這份簡報流程檔產出投影片。重點不是把每個條列轉成一頁文字，而是根據每頁目的，選擇適合的視覺表現。這份分享的主軸是把聽眾從 Prompt 思維帶到 AI Workflow 思維，因此請特別強化「問題 -> 轉折 -> 分工 -> 落地」的敘事感。Hook 相關頁請突出流程保底與自動檢查，Subagent 相關頁請突出任務分工與上下文隔離，案例頁請突出失敗風險、驗證流程與工程細節，而不是只展示成功結果。整體請避免滿版條列，優先使用對照、流程、卡片與結構化視覺。 + +--- + +*此檔為 `presentation-flow-writer` Skill 內附的完整範例，複製自 AI 開發講堂#03 的實際簡報流程檔，供離開原專案脈絡後仍可參考完整結構。原始檔案原本位於該專案的 `docs/簡報流程檔.md`，這裡的版本移除了對該專案內部檔案（截圖、Hooks.md 等）的相對連結，改為純文字描述，以維持本 Skill 移植到其他專案時仍可獨立閱讀。* diff --git a/.agents/skills/presentation-flow-writer/references/template.md b/.agents/skills/presentation-flow-writer/references/template.md new file mode 100644 index 0000000..a8ce61e --- /dev/null +++ b/.agents/skills/presentation-flow-writer/references/template.md @@ -0,0 +1,115 @@ +# {主題} 簡報流程檔 + +## 文件用途 + +這份文件不是逐字稿，也不是最終投影片文案，而是提供給「簡報生成 AI 代理」的結構化輸入。 + +目標是讓代理知道： + +- 這場分享的敘事節奏 +- 每一頁的任務與重點 +- 每一頁適合的畫面安排與呈現方式 +- 哪些地方要用案例、流程圖、對比圖，而不是塞文字 + +## 這場簡報的總體設計原則 + +### 1. 核心敘事 + +主軸句： + +> {一句話主軸，貫穿全場} + +希望聽眾聽完之後，思維從「{原本的想法}」轉變成「{希望的想法}」。 + +### 2. 簡報節奏 + +整體節奏建議分成 {N} 段： + +1. {段落 1 名稱}：{這段要達成什麼} +2. {段落 2 名稱}：{這段要達成什麼} +3. ... + +### 3. 畫面原則 + +- {密度原則，例如：每頁只承載一個主要結論} +- {類型頁的視覺傾向，例如：案例頁一定要展示風險 -> 設計機制 -> 驗證方式} +- {其他原則} + +### 4. 頁數建議 + +這份流程以 {N} 分鐘版本為主要目標，{M} 頁安排是合理的。 + +建議節奏如下： + +- 第 1 到 {x} 頁：前 {分鐘} 分鐘，{這段目標} +- 第 {x+1} 到 {y} 頁：{分鐘} 分鐘，{這段目標} +- ... + +## 建議簡報流程 + +## 第 {N} 頁：{頁面標題} + +### 目的 + +{這頁為什麼存在} + +### 核心訊息 + +{一句話結論，資訊型/過場頁可省略} + +### 畫面安排 + +- {結構方向，不寫死具體文案} + +### 講者重點 + +{給人看的提示，不是逐字稿} + +### 可引用素材 + +可參考 [{檔名}](./{路徑})。 + + + +## 備用頁建議 + +如果預期現場 QA 會多，或 demo 有風險，建議另外準備備用頁。 + +### 備用頁索引（僅供操作參考，不需產生為投影片） + +| 備用頁 | 標題 | 對應正文頁 | 觸發情境 | 優先權重 | +| --- | --- | --- | --- | --- | +| A | {標題} | 第 {N} 頁 | {什麼提問會觸發這頁} | {高/中/低} | + +### 備用頁 A：{標題} + + + +用途：{什麼情況下會被調用} + +建議內容： + +- {重點 1} +- {重點 2} + +## 給簡報生成代理的版面指示 + +### 整體風格 + +- {模板感 vs 自由設計} +- {文字密度控制} + +### 圖像類型建議 + +- {頁面類型 1}：{適合的視覺，例如對比圖、混亂 vs 有秩序} +- {頁面類型 2}：{適合的視覺，例如流程、攔截、檢查點} + +### 動畫建議 + +- {原則，例如：只做逐步 reveal，不要做花俏轉場} + +## 建議交付給簡報代理時附帶的額外說明 + +這段話**不能單獨交給生成代理**，要連同這份流程檔本身一起給——生成代理能讀檔案就附檔案路徑，不能讀檔案就把整份流程檔貼在這段話後面。 + +> 請依照這份簡報流程檔產出投影片。重點不是把每個條列轉成一頁文字，而是根據每頁目的，選擇適合的視覺表現。{一段濃縮敘事主軸、各類頁面呈現重點、避免事項的收尾說明}。 diff --git a/README.md b/README.md index af4ca6f..e3954a9 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,9 @@ │ ├─ commit-push-pr/SKILL.md │ ├─ doc-coauthoring/SKILL.md │ ├─ find-skills/SKILL.md +│ ├─ presentation-flow-writer/ +│ │ ├─ SKILL.md +│ │ └─ references/ │ ├─ review/SKILL.md │ ├─ simple-sdd/SKILL.md │ └─ test/SKILL.md @@ -68,6 +71,7 @@ - `commit-push-pr/SKILL.md`：依目前工作區變更建立提交、推送並建立 Pull Request。 - `doc-coauthoring/SKILL.md`：協助撰寫與共同編輯文件、提案、技術規格與決策文件。 - `find-skills/SKILL.md`：協助搜尋、挑選與安裝可用 skills（`npx skills find/add/check/update`）。 + - `presentation-flow-writer/SKILL.md`：陪同使用者共同撰寫「簡報流程檔」，作為交給簡報生成 AI 代理的結構化輸入文件（含 `references/` 範例與模板）。 - `review/SKILL.md`：對目前工作目錄中的變更做嚴格技術審查，優先指出 bug、風險、回歸與測試缺口。 - `simple-sdd/SKILL.md`：輕量級 SDD 開發流程，分「提案 → 實作 → 歸檔」三階段，動手寫程式前先確認需求並取得使用者同意。 - `test/SKILL.md`：執行現有測試、分析失敗原因，並在必要時補充關鍵測試以驗證程式碼正確性。 From febdb7118b5f53fc7c1bd25c078bc9b515b26a8f Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Thu, 6 Aug 2026 21:46:05 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(skills):=20=E6=96=B0=E5=A2=9E=E7=B0=A1?= =?UTF-8?q?=E5=A0=B1=E6=B5=81=E7=A8=8B=E6=AA=94=E6=92=B0=E5=AF=AB=E5=8F=B0?= =?UTF-8?q?=E7=81=A3=E7=94=A8=E8=AA=9E=E8=A6=8F=E7=AF=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/presentation-flow-writer/SKILL.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.agents/skills/presentation-flow-writer/SKILL.md b/.agents/skills/presentation-flow-writer/SKILL.md index 3615aa2..2f15244 100644 --- a/.agents/skills/presentation-flow-writer/SKILL.md +++ b/.agents/skills/presentation-flow-writer/SKILL.md @@ -11,6 +11,26 @@ description: Guides the user through co-authoring a "簡報流程檔" (presentat 參考範例：`references/example-ai-workshop-03.md`（AI 開發講堂#03 案例，24 頁正文 + 11 個備用頁題目）。概念總覽可看 `references/concept-overview.html`。 +## 語言與用詞規範 + +全程（引導提問、確認回覆、最終流程檔內容）一律使用**台灣慣用的繁體中文**，包括詞彙、語序、語氣、標點與技術名詞譯法，避免混用中國大陸慣用詞或簡體字。常見對照： + +| 避免（中國大陸慣用） | 改用（台灣慣用） | +| --- | --- | +| 信息 | 資訊 | +| 視頻 | 影片 | +| 軟件 / 硬件 | 軟體 / 硬體 | +| 程序 | 程式 | +| 用戶 | 使用者 | +| 質量（品質之意時） | 品質 | +| 默認 | 預設 | +| 反饋 | 回饋 | +| 模板 | 範本 / 模板皆可，但避免簡體字「板」誤用 | +| 屏幕 | 螢幕 | +| 邏輯（無誤，維持原用法） | — | + +標點一律使用全形（「」、、，。），不要用中國大陸常見的直角引號『』或英式引號混用；產出的流程檔若引用他人既有文案，可保留原文用詞，但顧問自己撰寫、建議、改寫的部分一律套用上表規範。 + ## 為什麼要用這個格式（先跟使用者建立共識） 一般人準備簡報素材時，容易寫成三種東西之一，但都會讓生成 AI 中途卡住或重工： @@ -102,6 +122,7 @@ description: Guides the user through co-authoring a "簡報流程檔" (presentat - 案例頁是否都要求呈現風險與驗證，不只是成果？ - 備用頁索引表是否有標註對應正文頁、觸發情境與優先權重，且沒有被誤當成要生成的投影片？備用頁內容要不要生成，是否已經是使用者主動做的選擇，而不是被規則預設略過？ - 是否有一段收尾 Prompt，並且明確提醒使用者要連同完整流程檔（或其檔案路徑）一起交給生成代理，而不是只丟這段濃縮文字？ +- 全文用詞是否符合台灣慣用繁體中文（見「語言與用詞規範」），沒有混入中國大陸慣用詞或簡體字？ ## 使用情境範例