Files

T

jiantw83andClaude Opus 5 821261ad9d docs(sdlc): 同步文件與參考資料

What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。

Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。

How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-25 14:58:54 +08:00

2.5 KiB

Raw Blame History

交付內容型別

詢問時機與鐵則（不得自行預設、不得跳過詢問）由 skills/implement/SKILL.md 步驟 7 擁有。本檔只定義每個選項要產出什麼內容。

選項	內容
1. API 文件	端點路徑、輸入參數（全部）、輸出參數（全部）；見下節
2. 由使用者輸入	使用者自己講要什麼內容；照使用者說的做，不套 API 文件格式

API 文件

必備欄位

區塊	要求
端點路徑	方法與完整路徑（例 `GET /v1/members/{id}`），含版本前綴
輸入參數	列出全部——路徑、查詢字串、標頭、請求主體逐層列，不可只列「主要的幾個」
輸出參數	列出全部——回應主體逐層列，含錯誤回應的結構與狀態碼

每個參數都要有：名稱、型別、必填與否、範例、資料來源、新舊狀態。

參數範例：真實資料優先

先找真實來源：資料庫欄位與實際資料列、實際 API 回應、既有設定檔或 fixture、日誌。標成 真實：{source}（{source} 換成實際來源名稱）。
找不到來源才由邏輯推理，標成 推論：無來源，讓接手者知道那個值還沒被驗證。
不得編一個看起來合理的值當成真實資料。
範例只保留結構與格式。個資一律遮蔽或改寫成格式描述，不把真實個資寫進交付文件。

既有端點：新舊參數必須明顯區分

改的是既有端點時，接手者最需要知道「哪些是這次動到的」。用兩種標示，兩者都要：

一、參數表加狀態欄

狀態	標示	意義
新增	🆕 新增	這次新增的參數
變更	⚠️ 變更	既有參數改了型別、必填性、預設值或語意
既有	（留空）	這次沒動
移除	❌ 移除	這次移除，含淘汰時程

二、差異區塊用 diff 語法標色

Gitea 與 GitHub 的 markdown 都會替 diff 程式碼區塊上色，+ 綠、- 紅，是最可靠的「顏色」做法（HTML 的 style 屬性會被 wiki 過濾掉，不要用）：

```diff
  GET /v1/members/{id}
    id            string   必填
+   include_tags  boolean  選填  預設 false（本次新增）
-   legacy_flag   boolean  選填  （本次移除，2026-12-31 前相容）
!   status        string   必填  列舉值新增 suspended（本次變更）
```

新端點不需要狀態欄與差異區塊，但要註明「本次新增端點」。

2.5 KiB Raw Blame History Unescape Escape