claude-code/claude-zh/commands/update-docs.md

更新文件 (Update Documentation)

將文件與程式碼庫保持同步，並從「單一事實來源」(source-of-truth) 檔案中自動生成。

步驟 1：識別事實來源 (Sources of Truth)

來源	生成內容
package.json 中的腳本	可用指令參考
.env.example	環境變數文件
openapi.yaml / 路由檔案	API 端點參考
原始碼匯出 (Exports)	公共 API 文件
Dockerfile / docker-compose.yml	基礎設施設定文件

步驟 2：生成腳本參考 (Script Reference)

1. 讀取 package.json (或 Makefile, Cargo.toml, pyproject.toml)
2. 擷取所有腳本/指令及其描述
3. 生成參考表格：

| 指令 | 描述 |
|---------|-------------|
| `npm run dev` | 啟動具備熱重載功能的開發伺服器 |
| `npm run build` | 進行帶有型別檢查的生產環境建置 |
| `npm test` | 執行帶有覆蓋率報告的測試套件 |

步驟 3：生成環境變數文件

1. 讀取 .env.example (或 .env.template, .env.sample)
2. 擷取所有變數及其用途
3. 分類為「必填」與「選填」
4. 記錄預期格式與有效值

| 變數 | 是否必填 | 描述 | 範例 |
|----------|----------|-------------|---------|
| `DATABASE_URL` | 是 | PostgreSQL 連接字串 | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | 否 | 日誌詳細程度 (預設：info) | `debug`, `info`, `warn`, `error` |

步驟 4：更新貢獻指南 (Contributing Guide)

生成或更新 docs/CONTRIBUTING.md，包含：

• 開發環境設定 (先決條件、安裝步驟)
• 可用腳本及其用途
• 測試程序 (如何執行、如何撰寫新測試)
• 程式碼風格強制執行 (Linter, Formatter, Pre-commit hooks)
• PR 提交清單

步驟 5：更新維運手冊 (Runbook)

生成或更新 docs/RUNBOOK.md，包含：

• 佈署程序 (逐步指引)
• 健康檢查端點與監控
• 常見問題及其解決方案
• 回滾程序 (Rollback)
• 告警與呈報路徑

步驟 6：陳舊度檢查 (Staleness Check)

1. 找出超過 90 天未修改的文件檔案
2. 與最近的原始碼變更進行交叉比對
3. 將可能過期的文件標記為需要手動審查

步驟 7：顯示摘要

文件更新摘要
──────────────────────────────
已更新：  docs/CONTRIBUTING.md (腳本表格)
已更新：  docs/ENV.md (新增 3 個變數)
標記：    docs/DEPLOY.md (已陳舊 142 天)
跳過：    docs/API.md (未偵測到變更)
──────────────────────────────

規則

• 單一事實來源：始終從程式碼生成，切勿手動編輯生成的區塊。
• 保留手動區塊：僅更新生成的區塊；保留手寫的說明文字。
• 標註生成內容：在生成的區塊前後使用 <!-- AUTO-GENERATED --> 標記。
• 不要擅自建立新文件：除非指令明確要求，否則不要建立新的文件檔案。