.github/copilot-instructions.md

GitHub Copilot 指南（專案層級）

⚠️ 抽象化指南 — 本檔案及 .github 資料夾中的所有 prompt 相關文件應保持完全抽象化，移除所有原專案特定的技術細節與領域知識。

撰寫或修改本文件時：

• ✅ 使用通用術語（如「資料欄位」、「輸入項目」、「資料點」）
• ✅ 用「資料來源查詢失敗」、「外部服務超時」而非具體服務名稱
• ✅ 用「輸入格式」、「資料格式」而非具體檔案或編碼格式
• ❌ 不要提及任何特定領域（如地震、金融、醫療等）的詞彙
• ❌ 不要參考原專案的具體資料檔案名、業務邏輯或專業術語

目標：使本指南可直接應用於其他資料處理專案，無需修改具體內容。

本文件為單人專案的 Copilot 開發指南。撰寫或修改程式碼時，務必遵循 spec/spec.md 的規格與不變條件。

關鍵文件

Spec 檔案結構（模塊化）

為了保持可讀性與管理 token 預算，規格已拆分為多個專業化文件：

• spec/00-overview.md — 專案概覽、核心目標、模組清單、不變條件速查表（對話時優先傳讀此文件）
• spec/01-data-contract.md — 資料結構、模型 I/O Shape、檔案格式、冷啟動流程（資料契約相關時查閱）
• spec/02-processing-rules.md — 批次策略、輸入項目上限、資料處理參數、資源限制（實作邏輯時查閱）
• spec/03-error-handling.md — 錯誤處理策略、日誌原則、常見場景、UI 訊息設計（除錯或新增錯誤處理時查閱）
• spec/04-extensions.md — 擴充空間、新資料來源、向後相容策略（功能擴展時查閱）

其他重要檔案：

• **spec/plan.md**（短期）：本次迭代的範圍、目標、驗收標準。臨時討論檔，每個 sprint 更新後可拋棄。
• **changelog.md**：記錄完成的變更摘要（高層描述，非逐行對應）。用於交付追蹤。

核心守則（3 點）

1. 規格優先 — 合約 + 不變條件

• 新增或變更功能時，先檢查相應的規格文件（通常 00-overview.md 或 01-data-contract.md）中的不變條件與限制。
• 若需變更 CSV 結構、模型契約、或 API 形狀，必須先更新 spec（01-data-contract.md 或 04-extensions.md），並說明相容性影響。
• 當 Copilot 指南與 spec 有衝突時，以 spec 為準。

2. 失敗不中斷 — 降級 + 日誌

• 單點錯誤（缺失欄位、資料來源查詢失敗、檔案遺失等）不應中止全流程。
• 改用預設值、跳過該點、或降級處理，並記錄 WARNING/ERROR log（使用 loguru）。
• 參考 spec/03-error-handling.md 的具體策略與常見場景。

3. 資料清晰 — I/O 契約

• 模型輸入/輸出形狀、CSV 必備欄位、檔案格式必須與 spec 保持一致。
• 若要改動資料結構（如新增 CSV 欄位），先同步更新 01-data-contract.md，並在 04-extensions.md 記錄相容性計畫。

程式碼實踐

• 在涉及 spec 約定的邏輯處加入註解，簡述與 spec 的對齊（如 "spec #2：輸入項目上限" 或 "參考 02-processing-rules.md"），無需編號標籤。
• 優先保持向後相容；新增資料來源或輸入項時參考 spec/04-extensions.md。
• 避免將關鍵邏輯（如批次策略、資源查詢）分散於多處；若需重構，提供明確的入口函式或工廠（參考 04-extensions.md 工廠模式）。

LLM 執行防護（預防常見陷阱）

避免無限驗證迴圈

• 問題：執行完檔案操作後，開始重複執行 ls, wc -l, find, file 等驗證命令
• 預防：
  • 每個主要任務完成後立即停止，不進行驗證
  • 若需驗證，由用戶在後續對話中明確要求
  • 單個工具呼叫的驗證可以（如 get_errors 檢查編譯），但連環的驗證命令應停止

避免生成不必要的報告

• 問題：執行 /project.init 等明確指定「不產生報告」的命令後，卻自動生成總結 markdown
• 預防：
  • 明確檢查指令的「限制」與「不做」清單
  • 若指令說「完成後直接返回」，就真的直接返回
  • 報告只有在用戶明確要求時才生成

避免過度消耗 token

• 問題：為了「確保完美」而執行多個驗證步驟，造成 token 浪費
• 預防：
  • 優先相信檔案操作工具成功（除非有明確錯誤訊息）
  • 避免為了「心安」而重複讀取剛建立的檔案
  • 單輪對話內集中驗證，而非分散於多個工具呼叫

提交前檢查

commit 前確認以下兩點：

1. 是否符合 spec 的輸入/輸出 shape 與不變條件（查閱 01-data-contract.md 或 02-processing-rules.md）？
2. 若變更了 CSV 結構或模型契約，spec 已同步更新（01-data-contract.md + 04-extensions.md）？

迭代與任務追蹤

• 每次開始新迭代時，在 spec/plan.md 討論本次目標、範圍、驗收標準。
• 根據 plan.md 的內容，可在 spec/task.md 維護任務拆解（子任務應小而可驗收）。
• 迭代完成後，更新 changelog.md 記錄變更摘要。
• 完成後標記 plan.md 和 task.md 為 [ARCHIVED]（保留作為歷史參考），下次迭代時重新生成新版本。
• 長期的規格變更和決策應同步回對應的 spec 模塊文件（00-overview.md / 01-data-contract.md / 02-processing-rules.md / 03-error-handling.md / 04-extensions.md），形成累積的設計參考。

對話時的 Spec 查詢策略

遇到不同類型的問題時，優先查閱對應的 spec 檔案：

問題類型	查閱檔案
「這個欄位是必須的嗎？」「模型輸入是什麼形狀？」	01-data-contract.md
「怎麼處理缺失的資料？」「最多幾個輸入項？」	02-processing-rules.md
「資料來源查詢失敗怎麼辦？」「應該記哪種日誌？」	03-error-handling.md
「怎麼新增新資料來源？」「能不能擴展資料欄位？」	04-extensions.md
「核心不變條件有哪些？」	00-overview.md

每次對話前，LLM 應根據用戶需求讀取相應的 spec 模塊（而非整個 spec.md），節省 token 預算。

Copilot Slash Commands（審核檢查點）

本專案提供以下指令協助「規格審核」與「迭代開發」的清晰分工：

/project.init（一次性初始化 — 僅用於既有專案無規格文件時）

• 目的：為既有專案（Brownfield）從無規格的狀態，快速生成模塊化規格檔案（spec/00-overview.md 至 spec/04-extensions.md）與迭代計畫模板（spec/plan.md）。
• 限制：此命令為一次性初始化，應該只產生必要的規格與計畫文件，不產生總結報告或分析文檔。初始化完成後無需進一步的報告文件。
• 執行檢查清單（防止重複驗證與報告生成）：
  • ❌ 不做：生成總結報告、比較表、驗證文檔
  • ❌ 不做：執行 ls, wc -l, file, find 等驗證命令
  • ❌ 不做：使用 show_content / open_file 顯示生成結果
  • ❌ 不做：重複讀取已建立的檔案確認內容
  • ✅ 只做：
    1. 掃描現有程式碼結構
    2. 建立 5 份規格 + 2 份計畫檔案
    3. 更新 changelog.md
    4. 直接結束，不進行任何驗證
• 流程：
  1. LLM 掃描現有程式碼結構，分析核心模組與資料流。
  2. 根據代碼分析，逐一填充 5 份模塊化規格文件（spec/00-* 至 spec/04-*）與計畫模板。
  3. 完成後直接返回（無總結、無驗證、無報告）；如需驗證規格內容，用戶可在後續對話中執行 /project.spec 或 /project.plan。

/project.spec（需求改變時用）

• 目的：調整 spec 的大方向、契約或不變條件。與現有程式碼做比較，列出後續工作清單。
• 流程：
  1. 討論新增或調整的規格項（需求、契約、不變條件）。
  2. 根據需求類型，讀取相應的 spec 模塊（01-* / 02-* / 03-* / 04-*）。
  3. LLM 掃描現有程式碼，列出符合、缺漏、或違反的地方。
  4. 產出「需要做的工作清單」。
  5. 直接更新 spec/spec.md → 等待使用者確認 → 確認後同步至 README.md 和 spec/plan.md。

/project.plan（迭代規劃時用）

• 目的：生成本次 sprint 的計畫，讓使用者在 MD 上討論和調整。
• 流程：
  1. 產生 spec/plan.md（包含迭代目標、高層任務列表、風險評估等）
  2. 暫停等待使用者確認（用戶可直接在 MD 上編輯）
  3. 確認後，提示執行 /project.task 進行詳細任務拆解

/project.task（任務拆解時用）

• 目的：根據確認的 spec/plan.md，拆解為具體的任務步驟與程式碼變更點。
• 流程：
  1. 根據 spec/plan.md 的高層任務列表，生成詳細任務拆解（T-001、T-002 等）
  2. 展示每個任務的具體變更點（檔案、行號、修改內容）
  3. 暫停等待使用者確認（用戶可調整任務順序或內容）
  4. 確認後，提示執行 /project.apply 應用程式碼變更

/project.apply（程式碼應用時用）

• 目的：直接應用經過確認的程式碼變更。
• 流程：
  1. 根據 spec/task.md 的確認任務清單，直接應用所有程式碼修改
  2. 執行語法/編譯檢查
  3. 更新 spec/task.md 標記已完成的任務（[x]）
  4. 暫停並提示使用者：「程式碼已應用，請進行手動測試」

/project.report（交付與清理時用）

• 目的：記錄變更並歸檔臨時計畫檔案。
• 流程：
  1. 根據使用者已完成的測試結果，自動更新 changelog.md
  2. 標記 spec/plan.md 和 spec/task.md 為已歸檔（在檔案開頭加入 [ARCHIVED] 標記）
  3. 生成交付報告（品質狀態、需求對齐等）
  4. 提示用戶本次迭代已完成，可開始新迭代

標準工作流

當需求改變時：

1. 執行 /project.spec 討論規格調整
2. 直接在 spec/spec.md 上編輯 → 確認後同步至 README.md 和 spec/plan.md

執行迭代時： 3. 執行 /project.plan 生成計畫 → 在 spec/plan.md 上編輯 → 確認後執行 /project.task 4. 執行 /project.task 拆解任務 → 在 spec/task.md 上編輯 → 確認後執行 /project.apply 5. 執行 /project.apply 直接應用程式碼 → 手動測試 → 測試完成後執行 /project.report 6. 執行 /project.report 記錄變更 + 標記 plan 和 task 為 [ARCHIVED] → 迭代完成

下次需求改變時： 回到步驟 1。 下次迭代開始時： 執行步驟 3（會在同位置重新生成新的 plan.md 和 task.md）。