Menu
[UDS] 引導文件結構、內容需求和專案文件最佳實踐
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/AsiaOstrich/universal-dev-standards --skill documentation-guideThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
[UDS] 以 Claude 原生 Agent tool 编排多任务执行计划（DAG-based，无外部引擎）。 Use when: executing a plan.json file with parallel/sequential task dependencies. Keywords: orchestrate, plan, execute, DAG, task plan, 编排, 执行计划, 并行.
[UDS] 从 Spec 文档、OpenSpec 变更或自由文本需求生成 plan.json。 Use when: converting specifications into executable task plans for /orchestrate. Keywords: plan, spec, task plan, 计划, 规格, 任务, plan.json, DAG.
[UDS] AI 辅助 git push 安全层：质量门禁 + 协作护栏。 Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches. Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保护分支, 质量门禁.
Showing SKILL.md
Based on SOC occupation classification
| 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 提供專案文件的全面指導，包括：
# === 專案類型 → 文件需求 ===
document_matrix:
# README ARCH API DB DEPLOY MIGRATE ADR CHANGE CONTRIB
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]
# REQ=必要, REC=建議, if_app=如適用, NO=不需要
# === 文件金字塔 ===
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 │ ← 變更歷史
└───────────────────────────────┘
# === README.md ===
readme:
minimum:
- "# 專案名稱"
- "簡短的單行描述"
- "## 安裝"
- "## 使用"
- "## 授權"
recommended:
- "# 專案名稱 + 徽章"
- "## 功能（項目符號列表）"
- "## 安裝"
- "## 快速入門 / 使用"
- "## 文件（連結至 docs/）"
- "## 貢獻（連結至 CONTRIBUTING.md）"
- "## 授權"
# === ARCHITECTURE.md ===
architecture:
required:
- system_overview: "目的、範圍、主要功能"
- architecture_diagram: "Mermaid 或 ASCII Art"
- module_description: "職責、相依性"
- technology_stack: "框架、語言、版本"
- data_flow: "主要業務流程"
recommended:
- deployment_architecture: "生產環境拓撲"
- design_decisions: "關鍵決策（或連結至 ADR）"
# === API.md ===
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
└── ...
# 專案名稱
簡短的單行描述。
## 安裝
```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 中的「文件語言」區段如果缺少文件：
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 授權發布。
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
| 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 |
This skill is released under CC BY 4.0.
Source: universal-dev-standards