產品 docs 規範說明
1. 目的與適用範圍
本規範定義開發團隊在產品程式庫中使用 docs/ 目錄的方式。docs/ 是產品開發的共享事實源，用於保存正式規格、模組說明、開發計畫、操作手冊，以及按需要保留的設計資料。
docs/ 不是臨時筆記區，也不是程式碼的複製品。文件應讓開發者與 QA 能快速定位目前有效的規格、實作計畫及驗證依據。
2. 建議目錄結構
docs/
├── README.md # 文件入口、索引與推薦閱讀順序
├── specs/ # PRD、SAD、系統級或跨模組設計文件
│ ├── prd-*.md
│ ├── sad-*.md
│ └── <system-or-cross-module-design>.md
├── plans/ # 有序的迭代計畫、執行狀態與驗證證據
│ └── 001-<feature-slug>.md
├── modules/ # 單一模組的詳細規格與穩定契約
│ └── <module-slug>.md
├── guides/ # 整合、操作、聯調及故障排查手冊
└── designs/ # UI 設計過程、架構圖等（按需要建立）
除上述核心目錄外，可依產品發展需要增加其他目錄，但必須先定義用途與維護責任，並避免與現有目錄重複。
2.1 README.md：文件入口與索引
docs/README.md 是開發團隊進入產品文件的第一入口，應保持簡潔並至少包含：
- 產品與文件範圍。
specs/、plans/、modules/、guides/、designs/的索引。- 推薦閱讀順序。
- 目前進行中的 Plan 與最近完成的 Plan。
- 文件維護責任或聯絡方式。
新增、搬移或淘汰文件時，必須同步更新 README，避免文件存在但無法被團隊發現。
2.2 specs/：產品、系統與跨模組規格
specs/ 只存放下列文件：
- PRD。
- SAD。
- 系統級設計文件。
- 涉及兩個或以上模組的跨模組設計與契約。
單一模組的詳細邏輯不放入 specs/，應放入 modules/。短期任務拆解、執行狀態與驗證證據不放入 specs/，應放入 plans/。
2.3 plans/：開發計畫與狀態管理
每個迭代或功能使用一個有序 Plan，例如 001-user-authentication.md。Plan 是本規範中唯一需要管理執行狀態的文件類型。
Plan 應記錄：
- 背景、目標、非目標與開發邊界。
- 前置規格，且只能引用
specs/或modules/下的文件。 - 影響範圍與依賴。
- 可執行的任務拆解與目前狀態。
- 驗收標準、測試方式與執行證據。
- 風險、重要決策與實際結果。
- 完成後的規格回補清單。
建議使用 draft、approved、in_progress、blocked、completed、cancelled 作為 Plan 狀態。團隊可依既有流程調整，但同一產品內必須保持一致。
2.4 modules/：單一模組詳細規格
每份模 組文件描述一個模組的長期有效知識，包括：
- 模組職責與非職責。
- 輸入、輸出及對外契約。
- 資料、權限與租戶邊界。
- 依賴關係、錯誤處理及可觀測性。
- 主要流程、穩定限制與相容性要求。
模組文件不應複製 Plan 的任務狀態與執行日誌，只保留完成後仍然有效的最新規格。
2.5 guides/：可操作的手冊
存放整合、操作、聯調、部署前置與故障排查說明，例如對外整合手冊、AIFF 接入手冊或本機開發指南。
Guide 應標示適用版本、前置條件、操作步驟、驗證方式與常見失敗處理。範例中的密碼、Token、私鑰與內部網址必須使用安全佔位符。
2.6 designs/：按需要保留的設計資料
涉及 AI 輔助 UI 設計、重要互動、架構圖或需要保留設計過程時，可建立 designs/。設計定案後，與開發相關的穩定規則仍應回寫到 specs/ 或 modules/，避免設計過程檔案成為唯一規格來源。
3. Plan 完成後的文件回補
Plan 完成後， 必須依實際執行結果回補文件。回補的目標是讓 specs/ 與 modules/ 反映目前真實且最新的產品邏輯，而不是只記錄「工作已完成」。
回補時應遵循以下規則：
- 以實際完成的程式碼、測試結果與已確認決策為依據。
- 產品、系統級或跨模組邏輯變更，回補
specs/。 - 單一模組的職責、流程、介面或限制變更，回補
modules/。 - 若同時影響兩者，分別更新並建立相對連結，不以複製全文代替引用。
- 更新現有規格的最新邏輯，不以新增補丁文件長期堆疊差異。
- 同步檢查 README 索引及相關 Guide 是否仍然正確。
- 回補與一致性檢查必須是 Plan 完成前的最後一個任務。
4. QA 使用方式
QA 可以結合以下文件產出驗收標準、Test Case、回歸範圍與測試證據：
| 文件來源 | QA 主要用途 |
|---|---|
specs/ | 確認產品目標、系統行為、跨模組流程與正式契約 |
modules/ | 確認單一模組的輸入輸出、限制、錯誤處理及邊界案例 |
plans/ | 確認本次變更範圍、驗收標準、風險、實際結果與測試證據 |
若 QA 發現實際行為與規格不一致：
- 屬於實作缺陷時，回到原 Plan 修正並補充回歸證據。
- 屬於已確認的規格變更時，先更新對應
specs/或modules/，再更新驗收標準與 Test Case。 - 尚未確認差異是否合理時，不得直接把現況視為新規格。
5. Plan 最小模板
# 001 <功能名稱>
## 狀態
- status: draft
- owner: <負責人>
- updated_at: YYYY-MM-DD
## 背景與目標
## 非目標與邊界
## 前置規格
- [ ] `../specs/<spec>.md`
- [ ] `../modules/<module>.md`
## 影響範圍與依 賴
## 任務拆解與狀態
## 驗收標準
## 風險與決策
## 驗證命令與證據
## 文件回補（完成前最後一步）
- [ ] 依實際結果更新相關 `specs/`
- [ ] 依 實際結果更新相關 `modules/`
- [ ] 檢查 `docs/README.md` 索引與相關 `guides/`
- [ ] 檢查文件、程式碼與測試證據是否一致
Plan 不應引用 designs/、臨時分析稿或口頭結論作為唯一前置規格。若必要決策尚未進入 specs/ 或 modules/，應先完成規格整理再開始正式開發。
6. AI 協作與 Skills 的相容原則
本文件只規範 docs/ 的目錄用途與文件維護結果，不限定開發團隊必須使用哪一套 AI 協作方法、Skills、Agent、提示詞或 AI Coding 規範。
開發團隊可依產品規模、技術棧與協作習慣自行選擇，例如：
- 自行編寫符合產品流程的 Skills。
- 採用 AI Collaboration Guide、Superpowers 或其他主流 AI 開發工作流。
- 使用工具提供的 AI Coding 規範、Agent 執行約束、計畫管理或驗證流程。
- 不使用 Skills，改由團隊既有工程流程維護文件。
由於 AI 工具與最佳實務持續快速演進，團隊可自行導入、替換或組合相關方案，不需要為了符合本規範而綁定特定工具或固定實作方式。
無論採用何種方式，產出的文件仍須符合本規範：
- 文件放入職責正確的目錄，避免 specs、modules、plans 與 guides 混用。
- Plan 的前置規格只引用
specs/或modules/下的正式文件。 - Plan 完成後，依實際執行結果回補相關
specs/或modules/。 - README 索引、文件連結、測試證據與 QA 依據保持可定位且一致。
- AI 產出的內容須由開發團隊確認；若規格、程式碼與測試結果衝突，應先取得決策，不得將 AI 的選擇直接視為正式規格。
換言之，Skills 與 AI 工作流屬於可替換的執行工具；docs/ 的結構、內容邊界與回補結果才是本規範要求的共同契約。
7. 開發工作完成條件
一項開發工作只有同時滿足以下條件，才可將 Plan 標記為 completed：
- 實作結果符合相關
specs/與modules/，或差異已完成規格更新。 - 驗收標準、Test Case 與必要的回歸測試已有結果。
- Plan 已保存必要的驗證證據與重要決策。
- 最新邏輯已依影響範圍回補
specs/或modules/。 - README 索引、相關 Guide 與文件連結仍然有效。
本規範的核心不是增加文件數量，而是讓開發團隊在任何時間都能從 docs/ 找到可執行、可驗證且與目前產品一致的資訊。