產品 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/ 反映目前真實且最新的產品邏輯，而不是只記錄「工作已完成」。

Mermaid diagram

回補時應遵循以下規則：

1. 以實際完成的程式碼、測試結果與已確認決策為依據。
2. 產品、系統級或跨模組邏輯變更，回補 specs/。
3. 單一模組的職責、流程、介面或限制變更，回補 modules/。
4. 若同時影響兩者，分別更新並建立相對連結，不以複製全文代替引用。
5. 更新現有規格的最新邏輯，不以新增補丁文件長期堆疊差異。
6. 同步檢查 README 索引及相關 Guide 是否仍然正確。
7. 回補與一致性檢查必須是 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 工具與最佳實務持續快速演進，團隊可自行導入、替換或組合相關方案，不需要為了符合本規範而綁定特定工具或固定實作方式。

無論採用何種方式，產出的文件仍須符合本規範：

1. 文件放入職責正確的目錄，避免 specs、modules、plans 與 guides 混用。
2. Plan 的前置規格只引用 specs/ 或 modules/ 下的正式文件。
3. Plan 完成後，依實際執行結果回補相關 specs/ 或 modules/。
4. README 索引、文件連結、測試證據與 QA 依據保持可定位且一致。
5. AI 產出的內容須由開發團隊確認；若規格、程式碼與測試結果衝突，應先取得決策，不得將 AI 的選擇直接視為正式規格。

換言之，Skills 與 AI 工作流屬於可替換的執行工具；docs/ 的結構、內容邊界與回補結果才是本規範要求的共同契約。

7. 開發工作完成條件

一項開發工作只有同時滿足以下條件，才可將 Plan 標記為 completed：

• 實作結果符合相關 specs/ 與 modules/，或差異已完成規格更新。
• 驗收標準、Test Case 與必要的回歸測試已有結果。
• Plan 已保存必要的驗證證據與重要決策。
• 最新邏輯已依影響範圍回補 specs/ 或 modules/。
• README 索引、相關 Guide 與文件連結仍然有效。

本規範的核心不是增加文件數量，而是讓開發團隊在任何時間都能從 docs/ 找到可執行、可驗證且與目前產品一致的資訊。