| name | documentation-guide |
| source | ../../../../skills/documentation-guide/SKILL.md |
| source_version | 2.1.0 |
| translation_version | 2.1.0 |
| last_synced | "2026-03-17T00:00:00.000Z" |
| status | current |
| description | [UDS] 引導文件結構、內容需求和專案文件最佳實踐 |
文件指南
語言: English | 繁體中文
版本: 2.1.0
最後更新: 2026-03-17
適用範圍: Claude Code Skills
目的
本 Skill 提供專案文件的全面指導，包括：
- 文件結構和檔案組織
- 依專案類型的內容需求
- 技術文件的撰寫標準
- 常見文件類型的範本
快速參考（YAML 壓縮格式）
document_matrix:
new: [REQ, REQ, if_app, if_app, REQ, NO, REC, REQ, REC]
refactor: [REQ, REQ, REQ, REQ, REQ, REQ, REQ, REQ, REC]
migration: [REQ, REQ, REQ, REQ, REQ, REQ, REQ, REQ, REC]
maintenance:[REQ, REC, REC, REC, REC, NO, if_app, REQ, if_app]
pyramid:
level_1: "README.md → 入口點，快速概覽"
level_2: "ARCHITECTURE.md → 系統概述"
level_3: "API.md, DATABASE.md, DEPLOYMENT.md → 技術細節"
level_4: "ADR/, MIGRATION.md, CHANGELOG.md → 變更歷史"
{ , }
{ , }
{ , }
{ , }
專案類型文件需求
文件需求矩陣
| 文件 | 新專案 | 重構 | 遷移 | 維護 |
|---|
| README.md | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 |
| ARCHITECTURE.md | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 |
| API.md | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 |
| DATABASE.md | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 |
| DEPLOYMENT.md | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 |
| MIGRATION.md | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 |
| ADR/ | ⚪ 建議 | ✅ 必要 | ✅ 必要 | ⚪ 如適用 |
| CHANGELOG.md | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 |
專案類型快速參考
🆕 新專案 → README + ARCHITECTURE + DEPLOYMENT + CHANGELOG
🔄 重構 → 所有文件 + MIGRATION + ADR（記錄「為何重構」）
🚚 遷移 → 所有文件 + MIGRATION（核心文件）+ 資料驗證
🔧 維護 → README + CHANGELOG（依變更範圍更新）
文件金字塔
┌─────────────┐
│ README │ ← 入口點，快速概覽
├─────────────┤
┌──┴─────────────┴──┐
│ ARCHITECTURE │ ← 系統概述
├───────────────────┤
┌──┴───────────────────┴──┐
│ API / DATABASE / DEPLOY │ ← 技術細節
├─────────────────────────┤
┌──┴─────────────────────────┴──┐
│ ADR / MIGRATION / CHANGELOG │ ← 變更歷史
└───────────────────────────────┘
文件範本（YAML 壓縮格式）
readme:
minimum:
- "# 專案名稱"
- "簡短的單行描述"
- "## 安裝"
- "## 使用"
- "## 授權"
recommended:
- "# 專案名稱 + 徽章"
- "## 功能（項目符號列表）"
- "## 安裝"
- "## 快速入門 / 使用"
- "## 文件（連結至 docs/）"
- "## 貢獻（連結至 CONTRIBUTING.md）"
- "## 授權"
architecture:
required:
- system_overview: "目的、範圍、主要功能"
- architecture_diagram: "Mermaid 或 ASCII Art"
- module_description: "職責、相依性"
- technology_stack: "框架、語言、版本"
- data_flow: "主要業務流程"
recommended:
- deployment_architecture: "生產環境拓撲"
- design_decisions: "關鍵決策（或連結至 ADR）"
檔案位置標準
project-root/
├── README.md # 專案入口文件
├── CONTRIBUTING.md # 貢獻指南
├── CHANGELOG.md # 變更日誌
├── LICENSE # 授權檔案
└── docs/ # 文件目錄
├── INDEX.md # 文件索引
├── ARCHITECTURE.md # 架構文件
├── API.md # API 文件
├── DATABASE.md # 資料庫文件
├── DEPLOYMENT.md # 部署文件
├── MIGRATION.md # 遷移文件（如需要）
└── ADR/ # 架構決策記錄
├── 001-xxx.md
└── ...
README.md 必要章節
最小可行 README
# 專案名稱
簡短的單行描述。
## 安裝
```bash
npm install your-package
使用
const lib = require('your-package');
lib.doSomething();
授權
MIT
### 建議的 README 章節
1. **專案名稱與描述**
2. **徽章**（CI 狀態、覆蓋率、npm 版本）
3. **功能**（項目符號列表）
4. **安裝**
5. **快速入門 / 使用**
6. **文件**（連結至 docs/）
7. **貢獻**（連結至 CONTRIBUTING.md）
8. **授權**
---
## ADR 範本
```markdown
# ADR-001: [決策標題]
## 狀態
已接受
## 背景
[為何需要此決策...]
## 決策
[具體決策內容...]
## 影響
### 正面
- 好處 1
- 好處 2
### 負面
- 缺點 1
- 缺點 2
## 考慮過的替代方案
1. 方案 A - 因為...而被拒絕
2. 方案 B - 因為...而被拒絕
文件稽核檢查清單
審查專案文件時：
□ README.md 存在且包含必要章節
□ 安裝說明清楚且經過測試
□ 使用範例已提供且可運作
□ 已指定授權
□ ARCHITECTURE.md 存在（非簡單專案）
□ API.md 存在（如有暴露 API）
□ DATABASE.md 存在（如使用資料庫）
□ DEPLOYMENT.md 存在（已部署的專案）
□ ADR/ 存在於重大決策
□ CHANGELOG.md 遵循 Keep a Changelog 格式
□ 所有內部連結正常運作
□ 圖表是最新的
□ 無過時資訊
配置偵測
偵測順序
- 檢查
CONTRIBUTING.md 中的「停用 Skills」區段
- 檢查
CONTRIBUTING.md 中的「文件語言」區段
- 檢查現有文件結構
- 若未找到，預設為英文
首次設定
如果缺少文件：
- 詢問：「此專案沒有完整的文件。應該使用哪種語言？(English / 中文)」
- 判斷專案類型（新專案/重構/遷移/維護）
- 依矩陣建立必要文件
- 建議在
CONTRIBUTING.md 中記錄：
## 文件標準
### 語言
此專案使用 **英文** 作為文件語言。
### 必要文件
根據專案類型，我們維護：
- README.md
- ARCHITECTURE.md
- DEPLOYMENT.md
- CHANGELOG.md
詳細指南
完整標準請參閱：
相關標準
版本歷史
| 版本 | 日期 | 變更 |
|---|
| 2.1.0 | 2026-03-17 | 新增：Diátaxis 分類、LLM 發現、品質指標、增強版 ADR 範本、翻譯友善寫作 |
| 2.0.0 | 2026-01-12 | 新增：專案類型矩陣、文件範本、文件金字塔 |
| 1.0.0 | 2025-12-24 | 初始版本 |
授權
本 Skill 以 CC BY 4.0 授權發布。
來源: universal-dev-standards
Next Steps Guidance | 下一步引導
After /docs-guide completes, the AI assistant should suggest:
文件結構與需求已釐清。建議下一步 / Documentation structure and requirements clarified. Suggested next steps:
- 執行
/docs 根據指南直接產生專案文件 ⭐ Recommended / 推薦 — 立即將文件指南化為行動 / Turn documentation guidelines into action immediately
- 執行
/changelog 建立或更新 CHANGELOG.md — 確保變更歷史完整 / Ensure change history is complete
- 執行
/sdd 將文件需求納入規格驅動開發 — 確保文件與功能同步 / Ensure docs stay in sync with features
Related Standards
Version History
| Version | Date | Changes |
|---|
| 2.1.0 | 2026-03-17 | Added: Diátaxis classification, LLM discovery, quality metrics, enhanced ADR template, translation-friendly writing |
| 2.0.0 | 2026-01-12 | Added: Project type matrix, document templates, documentation pyramid |
| 1.0.0 | 2025-12-24 | Initial release |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards
