---
doc_id: product-docs-guidelines
title: 產品 docs 規範說明
description: 定義開發團隊使用產品 docs 目錄時的文件存放、Plan 管理、規格回補與 QA 取用規則。
slug: /practices/product-docs-guidelines
category: engineering-governance
audience:
  - developer
  - qa
  - architect
visibility: public
status: published
version: 1.2.1
owner: aile-platform
updated_at: 2026-07-15
tags:
  - 文件規範
  - 開發流程
  - docs
  - AI 協作
rendered_html: /rendered/practices/product-docs-guidelines/
download: true
sidebar_position: 1
---

# 產品 docs 規範說明

## 1. 目的與適用範圍

本規範定義開發團隊在產品程式庫中使用 `docs/` 目錄的方式。`docs/` 是產品開發的共享事實源，用於保存正式規格、模組說明、開發計畫、操作手冊，以及按需要保留的設計資料。

`docs/` 不是臨時筆記區，也不是程式碼的複製品。文件應讓開發者與 QA 能快速定位目前有效的規格、實作計畫及驗證依據。

## 2. 建議目錄結構

```text
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
flowchart LR
    P["Plan 執行結果<br/>程式碼 · 決策 · 測試證據"] --> R{"規格影響範圍"}
    R -->|產品、系統或跨模組| S["更新 specs/"]
    R -->|單一模組詳細邏輯| M["更新 modules/"]
    S --> Q["QA 驗收依據"]
    M --> Q
    P --> Q
    Q --> T["驗收標準 · Test Case · 回歸證據"]
```

回補時應遵循以下規則：

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 最小模板

```markdown
# 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/` 找到可執行、可驗證且與目前產品一致的資訊。