yapi777/create-doc — 建立傳遞給投影片製作技能的架構文件

create-doc — 建立傳遞給投影片製作技能的架構文件 是做什麼的？

讀取研究記錄（執行記錄 md、結果 CSV、圖、程式碼），撰寫一份 Markdown 格式的架構草案，明確描述每一張投影片要說什麼、用哪種版型展示、放什麼內容、以及口頭講稿。

接收端是 progress-report-deck 技能（位於同一個 research-slides 外掛中，此技能的相鄰資料夾 ${CLAUDE_SKILL_DIR}/../progress-report-deck/ 內）。此技能的輸出，是讓 progress-report-deck 以「## 一個標題等於一張投影片」的方式讀取，並填入範本版型。開始工作之前，請先讀取 ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md，並確認下方「與投影片製作技能的約定」沒有互相矛盾（若對方的規則有變，則以對方的規則為準）。若找不到該檔案，則依照此處的約定撰寫即可。

若存在使用者設定檔 ~/.claude/yapi-skills/profile.md（包含姓名、研究領域、主要聽眾、自訂規則），請優先讀取。自訂規則（如配色、最小字型大小）優先於下方的約定，並請在架構文件的「關於此文件」區塊中抄錄。

架構草案的範本請參考 references/template.md。撰寫格式若有疑問，請以範本為準。

與投影片製作技能的約定（源自 progress-report-deck 的規則）

架構草案必須遵守以下約定，否則在製作投影片階段可能會被刪減或需要重做。

項目	約定	原因（progress-report-deck 側的規則）
標題	## 一個＝一張投影片。包含補充投影片在內，## 只用於投影片。章節分隔使用 #	草稿的 ## 會被當作投影片來讀取
骨架	標題 → 本次進度（目錄） → 研究背景(1/2)(2/2) → 研究目的（本次小目標） → 內容 → 總結・課題 → 感謝聆聽，依此順序	固定的範本骨架
研究背景	若與上次相同，只需寫「維持不變（沿用基礎資料）」，不需撰寫內容	研究背景基本上維持不變
本次小目標	在研究目的投影片中必須寫上「本次小目標」一詞（1～2行）	對方每次都會向使用者詢問的項目。先決定好
投影片數量	以最終的張數撰寫（避免對方需要合併或分割）	對方發現 ## 過多時會建議合併
版型	內容投影片必須指定一種佈局版型（見下表）	若直接填入條列項目，會被指出「下半部留白」
配色	顏色的意義只有兩種：藍色＝提案・對應・結論・主要數值、橙色＝傳統方法・問題・指出・注意。不要為不同方法分配第三種顏色。表格中主要的那一行請寫「以淡藍色強調」	主題色只有藍色 #156082 與橙色 #E97132
文字量	主張限制在30個全形字元以內（全形18pt可容納在一行內）。條列項目每個也約30個全形字元。每個面板最多3行。若需更長，請改用圖表或拆分投影片	文字必須16pt以上，無法縮小塞入
文字大小	不要寫「小字」「註解請用小字」等指示。腳註也需以16pt可容納的長度（一行）撰寫	小於16pt禁止
數學公式	使用 $...$（LaTeX 語法）撰寫，並明確標記為「數學公式（OMML）」	數學公式將以 OMML 方式排版
圖檔	使用輸出資料夾中 images/ 目錄內的 png，以 images/<名稱>.png 指定（若只有 pdf，則轉換為 png 放入）。不要使用儲存庫內的路徑或 ../。同時注意是否可容納在 4:3 的投影片中（例如兩張橫向圖垂直並排）	pptx 只能貼上 png 格式。投影片為 4:3 比例。投影片可能在不同資料夾或裝置上製作，無法看到外部的路徑
示意圖	若無圖檔但需以圖示呈現的內容（流程圖、時間軸、傳統vs提案對比），請明確指定版型名稱與繪製方式	讓對方不需再詢問使用者圖片的處理方式
備註	口頭講稿寫在「備註」中，不要放在投影片上	—
補充	用於問答的補充投影片，放在「感謝聆聽」的後面	結尾應為本體的最後一部分

可指定的佈局版型（取自 progress-report-deck 的 assets/template.pptx 實際範例）：

版型	使用時機	template.pptx 的實際範例
晶片＋面板（問題→對應）	「傳統問題 → 本次對應」「指摘 → 對應」	p.7, p.11
號碼徽章＋面板	帶有①②③編號的項目列舉（優點、步驟）	p.8-9
Before/After 示意圖	傳統方法與提案方法的對比（左＝橘色框、右＝藍色框、中間箭頭）	p.10
時間軸示意圖	時間方向的處理流程（實線／虛線框＋連接器）	p.12
雙欄晶片＋面板＋下方帶狀區	並排比較兩種方法／設定，含數學公式	p.13
表格＋全寬帶狀區	結果表格及其下方「解讀」的帶狀區（主要那一行用深藍色塗滿）	p.14
KPI 磚塊（2×2）	放大顯示4個數值或結論	p.15
檢查清單（✓）	列舉已確認或已完成的事項	p.16
雙層框線方塊	總結／未來展望	p.17
圖＋全寬帶狀區	放大貼上既有圖片，下方以帶狀區呈現解讀	（將 p.14 的表格替換為圖片）

目錄（本次進度）不需指定版型（保留條列形式，僅將關鍵字加粗，不加顏色）。

執行方式

1. 詢問需求（使用 AskUserQuestion，一次問完）

從對話或需求描述中能得知的項目不需再問。只問不清楚的部分。

• 發表類型與長度：進度報告 / 研討會 / 學會。張數估算約為內容投影片1張≒1分鐘（15分鐘約內容投影片10張左右＋骨架的5～6張）
• 聽眾：實驗室成員 / 學會 / 非領域人士。會影響背景知識的深度
• 包含的周邊資訊（可複選）：動機・背景、比較實驗、失敗分析、方法演變、錯誤修正的影響等。候選項目從讀取記錄中發現的主題中提出
• 研究背景是否維持不變：若需與上次資料不同，請說明變更的內容

若使用者以非選項的自由文字回答，也視為需求（例如「請將動機〇〇也加入」）。

2. 收集材料（僅讀取，不重新執行實驗）

• 投影片製作技能：${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md（確認上述約定）
• 記錄：執行記錄_*.md、*結果*.md、README.md、方針文件等。從日期最新的開始讀取
• 數值：summary/*.csv、*.md 中的表格。用於發表的數值必須從此處抄錄
• 圖檔：使用 ls 搜尋既有的 png。若有含日文標籤的圖檔優先使用。記錄下要使用的圖檔原始路徑（在步驟4中複製到 images/ 並在出處中標註）
• 設定值：補充投影片中要放的超參數、常數、模型配置，應取自程式碼的實際數值（常數、argparse 的預設值、執行時儲存的設定 json），而非記錄 md。若記錄與程式碼不一致，以程式碼為準，並告知使用者

3. 決定架構

依照骨架（配合 progress-report-deck 的範本）：

1. 標題
2. 本次進度（目錄：簡短列出內容投影片的標題）
3. 研究背景 (1/2)
4. 研究背景 (2/2)
5. 研究目的（目的＋本次小目標）
6. ～ 內容投影片
7. 總結・課題
8. 感謝聆聽
9. 補充投影片（用於問答）

內容投影片大致依此順序（根據張數增減）：

1. 動機・課題（為何要做這件事）→ 晶片＋面板
2. 提案・變更內容與優點 → Before/After 示意圖 或 號碼徽章＋面板
3. 方法細節（處理流程）→ 時間軸示意圖
4. 正確性保證・驗證 → 檢查清單
5. 參數決定方式 → KPI 磚塊 或 表格＋帶狀區
6. 實驗設定（資料、比較方法、評估指標）→ 雙欄 或 表格＋帶狀區
7. 結果（每個主張一張投影片）→ 表格＋帶狀區、圖＋帶狀區
8. 成本・限制 → 表格＋帶狀區 或 KPI 磚塊

務必附上補充投影片（用於問答）。不計入發表時間。

• 詳細設定（模型、最佳化、常數表格）
• 資料・模擬設定
• 比較方法的詳細內容（數學公式請指定 OMML）
• 評估指標的嚴格定義
• 參數搜尋等完整結果表格
• 預想問題與回答範例（約8題）：此部分不製作為投影片（以 # 章節形式放在架構草案最後，供發表者參考）。優先列出針對弱點的問題，例如「差異是否太小」「一次試驗能否下結論」「為何選擇這個比較對象」「計算成本如何」「未驗證的主張根據為何」等

4. 撰寫並輸出至統一資料夾

投影片可能在 progress-report-deck 中於不同資料夾或不同裝置（例如有 PowerPoint 的電腦）上製作。因此，請將架構草案與使用的圖檔統一輸出到一個資料夾，只需攜帶該資料夾即可製作投影片。

投影片製作文件-<日期>/ | 目錄
├── 投影片製作文件-<日期>.md   ← 架構草案
└── images/
    ├── speed_sweep.png
    └── ...

• 資料夾名稱與 md 檔案名稱統一為 投影片製作文件-<日期>（例如 投影片製作文件-2026-10-15/）。日期以建立日期的 YYYY-MM-DD 格式撰寫。若同一天需製作多份不同用途的文件而名稱衝突，請在日期後加上簡短識別碼（例如 投影片製作文件-2026-10-15-研討會/）。不要覆寫既有的資料夾。資料夾建立在專案根目錄下
• 圖檔：將架構草案中使用的所有圖檔複製到 images/ 目錄（複製而非移動，不修改原始檔案）
  • 檔案名稱保持原名稱。若名稱衝突或名稱無法識別內容（如 fig1.png），請改用能描述內容的英文數字名稱（例如 velocity_field_f195.png）。不要使用空格
  • 若只有 pdf 格式的圖檔，請轉換為 png 放入（例如使用 pdftoppm -png -r 200 -singlefile in.pdf images/name，或使用 PyMuPDF 以 200 dpi 轉換）
  • 在架構草案中以 images/<名稱>.png 的方式引用
  • 在「出處」章節中以「images/xxx.png ← 原始路徑」的形式記錄原始路徑（以便日後重新製作圖檔時可追溯）
• 示意圖（無圖檔者）不製作圖片，只需在架構草案中說明繪製方式

在開頭的「關於此文件」（# 章節，不製作為投影片）中，寫明對 progress-report-deck 的指示：

• 發表類型・長度・張數・聽眾
• 每張投影片的格式（如下）
• 不要修改或重新四捨五入數值
• 請以此資料夾作為工作目錄執行 progress-report-deck。圖檔位於此資料夾的 images/ 中，並以 images/<名稱>.png 指定。不要製作新圖檔（示意圖則依指定方式繪製）
• 方法名稱的標示規則、配色分配（藍色＝提案、橙色＝傳統・比較方法）
• 研究背景是否維持不變

每張投影片的格式：

## 投影片N — <標題>

- **版型**：<佈局版型（從上表中選一種）>
- **主張**：<30個全形字元以內的一句話。此張投影片最想表達的重點>
- **本文**：<條列項目。每個項目約30個全形字元，最多3～4項>
- **表格** / **圖檔**：<表格以 Markdown 寫出，標明要強調的行／列。圖檔請寫 `相對路徑.png`（說明是何種圖檔）>
- **數學公式（OMML）**：<若有，請以 $...$ 寫出>
- **備註**：<口頭講稿。不要放在投影片上>

撰寫時的規範：

• 主張要寫結論。不要寫「結果①」「關於〇〇」「顯示〇〇」，而要寫「速度越快差異越大」。不使用ですます體
• 評價詞需有數值佐證。若寫「大幅」「有效」「優越」，則在同一張投影片中必須包含比較對象、指標、實驗次數。「同等」「保證」容易說過頭（應改為「幾乎同等」「已確認」）
• 避免使用常見的浮誇詞彙（如「非常」「劃時代」「能夠實現」「無縫」等）。可參考 ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md 中的對照與替代建議
• 本文中的條列項目每個為一句話（若有「。」連接的兩句話，請分開）
• 未驗證的事項必須標明未驗證。不要混合預期特性與實驗結果。請在該張投影片的本文或帶狀區中加一行，並在總結・課題的「未來」中提及
• 為公平比較所作的條件（例如使用收斂完成的設定等）請用一行腳註說明。若使用者要求包含較長的背景說明，再行撰寫
• 無法完整放在投影片上的詳細說明，請移至備註或補充投影片。不要讓本文過長
• 最後以 # 章節附上「出處」表格（內容 → 檔案）

5. 驗證（務必執行）

1. 數值比對：使用正規表示法擷取架構草案中所有小數，並與來源 md / CSV（CSV 為四捨五入至4位或2位數的數值）進行比對。若找不到，請逐一檢查是自行計算的差值、轉錄錯誤、還是四捨五入不一致，並修正。比對腳本請放在暫存區
2. 資料夾自足性：確認架構草案中所有圖檔引用皆為 images/ 下的 png，且該檔案確實存在。沒有殘留 ../、絕對路徑或儲存庫內路徑。反之，images/ 中不應有未被引用的多餘檔案。同時回報資料夾總大小
3. 圖檔內容：針對描述圖檔內容的文字（例如「在〇〇處較大」），實際打開圖檔確認正確性
4. 約定檢查：檢查 ## 數量是否與預期投影片張數一致、所有投影片（骨架投影片除外）都有指定「版型」、沒有第三種配色的指示。主張長度（30個全形字元以內）、主張是否為結論、是否有 AI 用語、格式不一致等問題，請使用投影片製作技能的檢查腳本：

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<架構草案.md>" > check_doc.txt
   

   以 Read 讀取輸出，修正 WARN（若為研究上正確的說法則可保留）。若最後一行不是 DONE: …，表示檢查未通過，不得視為零問題。若找不到腳本，則手動檢查此項目
5. 張數：計算本體是否落在需求的張數範圍內

6. 回報

• 第一行寫明預設的讀者（例如：「預期讀者：progress-report-deck 技能（其後為實驗室研討會的聽眾）」）
• 輸出資料夾的路徑與內容（1個 md + 圖檔數量・總大小）
• 架構（每張投影片列出摘要）與補充內容
• 驗證結果（比對的數值個數、圖檔確認、約定檢查）
• 發表前使用者應注意的事項：未驗證的主張、容易被質疑的數值及其理由、所使用的結果來自何時與哪個程式碼
• 下一步：「在此資料夾中（若在其他裝置上，請先複製整個資料夾）執行 progress-report-deck 即可製作投影片」。攜帶方式（USB、Box/OneDrive、壓縮後寄送等）交由使用者決定
• 不進行 git commit（若使用者要求則執行）