documentation-templates

name	documentation-templates
description	文件範本與結構指南。README、API 文件、程式碼註解與 AI 友善文件。
allowed-tools	Read, Glob, Grep

文件範本

常見文件類型的範本與結構指南。

---

1. README 結構

必要章節（優先順序）

章節	用途
標題 + 一行描述	這是什麼？
快速入門	5 分鐘內運行
功能	我能做什麼？
設定	如何自訂
API 參考	連結到詳細文件
貢獻	如何幫忙
授權	法律

README 範本

# 專案名稱

簡短一行描述。

## 快速入門

[運行的最少步驟]

## 功能

- 功能 1
- 功能 2

## 設定

| 變數 | 描述 | 預設值 |
|------|------|--------|
| PORT | 伺服器埠口 | 3000 |

## 文件

- [API 參考](./docs/api.md)
- [架構](./docs/architecture.md)

## 授權

MIT

---

2. API 文件結構

每個端點的範本

## GET /users/:id

透過 ID 取得使用者。

**參數：**
| 名稱 | 型別 | 必填 | 描述 |
|------|------|------|------|
| id | string | 是 | 使用者 ID |

**回應：**
- 200：使用者物件
- 404：找不到使用者

**範例：**
[請求和回應範例]

---

3. 程式碼註解指南

JSDoc/TSDoc 範本

/**
 * 函式功能的簡短描述。
 *
 * @param paramName - 參數描述
 * @returns 回傳值描述
 * @throws ErrorType - 此錯誤發生的時機
 *
 * @example
 * const result = functionName(input);
 */

何時加註解

✅ 要註解	❌ 不要註解
為什麼（業務邏輯）	什麼（顯而易見的）
複雜演算法	每一行
非顯而易見的行為	自解釋的程式碼
API 契約	實作細節

---

4. 變更日誌範本（Keep a Changelog）

# 變更日誌

## [未發布]
### 新增
- 新功能

## [1.0.0] - 2025-01-01
### 新增
- 初始發布
### 變更
- 更新依賴
### 修復
- Bug 修復

---

5. 架構決策記錄（ADR）

# ADR-001：[標題]

## 狀態
已接受 / 已棄用 / 已取代

## 情境
為什麼我們要做這個決策？

## 決策
我們決定了什麼？

## 後果
權衡是什麼？

---

6. AI 友善文件（2025）

llms.txt 範本

給 AI 爬蟲和代理：

# 專案名稱
> 一行目標。

## 核心檔案
- [src/index.ts]：主要入口
- [src/api/]：API 路由
- [docs/]：文件

## 關鍵概念
- 概念 1：簡短說明
- 概念 2：簡短說明

MCP 就緒文件

為 RAG 索引：

• 清晰的 H1-H3 層級
• JSON/YAML 範例用於資料結構
• Mermaid 圖表用於流程
• 自包含的章節

---

7. 結構原則

原則	原因
可掃描	標題、列表、表格
範例優先	展示，而不只是說明
漸進式細節	簡單 → 複雜
保持最新	過時 = 誤導

---

記住： 範本是起點。根據你的專案需求調整。