jiantw83andClaude Opus 5
821261ad9d
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>
57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# 交付內容型別
|
||
|
||
詢問時機與鐵則（不得自行預設、不得跳過詢問）由 `skills/implement/SKILL.md` 步驟 7 擁有。本檔只定義每個選項要產出什麼內容。
|
||
|
||
| 選項 | 內容 |
|
||
| --- | --- |
|
||
| 1. API 文件 | 端點路徑、輸入參數（**全部**）、輸出參數（**全部**）；見下節 |
|
||
| 2. 由使用者輸入 | 使用者自己講要什麼內容；照使用者說的做，不套 API 文件格式 |
|
||
|
||
## API 文件
|
||
|
||
### 必備欄位
|
||
|
||
| 區塊 | 要求 |
|
||
| --- | --- |
|
||
| 端點路徑 | 方法與完整路徑（例 `GET /v1/members/{id}`），含版本前綴 |
|
||
| 輸入參數 | **列出全部**——路徑、查詢字串、標頭、請求主體逐層列，不可只列「主要的幾個」 |
|
||
| 輸出參數 | **列出全部**——回應主體逐層列，含錯誤回應的結構與狀態碼 |
|
||
|
||
每個參數都要有：名稱、型別、必填與否、範例、資料來源、新舊狀態。
|
||
|
||
### 參數範例：真實資料優先
|
||
|
||
1. 先找真實來源：資料庫欄位與實際資料列、實際 API 回應、既有設定檔或 fixture、日誌。標成 `真實：{source}`（`{source}` 換成實際來源名稱）。
|
||
2. 找不到來源才由邏輯推理，標成 `推論：無來源`，讓接手者知道那個值還沒被驗證。
|
||
3. **不得**編一個看起來合理的值當成真實資料。
|
||
4. 範例只保留**結構與格式**。個資一律遮蔽或改寫成格式描述，不把真實個資寫進交付文件。
|
||
|
||
### 既有端點：新舊參數必須明顯區分
|
||
|
||
改的是既有端點時，接手者最需要知道「哪些是這次動到的」。用兩種標示，兩者都要：
|
||
|
||
**一、參數表加狀態欄**
|
||
|
||
| 狀態 | 標示 | 意義 |
|
||
| --- | --- | --- |
|
||
| 新增 | 🆕 **新增** | 這次新增的參數 |
|
||
| 變更 | ⚠️ **變更** | 既有參數改了型別、必填性、預設值或語意 |
|
||
| 既有 | （留空） | 這次沒動 |
|
||
| 移除 | ❌ **移除** | 這次移除，含淘汰時程 |
|
||
|
||
**二、差異區塊用 `diff` 語法標色**
|
||
|
||
Gitea 與 GitHub 的 markdown 都會替 `diff` 程式碼區塊上色，`+` 綠、`-` 紅，是最可靠的「顏色」做法（HTML 的 `style` 屬性會被 wiki 過濾掉，不要用）：
|
||
|
||
````markdown
|
||
```diff
|
||
GET /v1/members/{id}
|
||
id string 必填
|
||
+ include_tags boolean 選填 預設 false（本次新增）
|
||
- legacy_flag boolean 選填 （本次移除，2026-12-31 前相容）
|
||
! status string 必填 列舉值新增 suspended（本次變更）
|
||
```
|
||
````
|
||
|
||
新端點不需要狀態欄與差異區塊，但要註明「本次新增端點」。
|