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>
This commit is contained in:
2026-08-25 14:58:54 +08:00
co-authored by Claude Opus 5
parent b78f7e8b3f
commit 821261ad9d
10 changed files with 79 additions and 87 deletions
+8 -8
View File
@@ -15,7 +15,7 @@
- 工作目錄:{關鍵檔案與結構摘要}
- 複用來源:[REPO_{HASH}]({REPO 頁絕對網址})(commit sha:`{sha}`)
- 複用決策:{複用哪些方法/端點、為什麼;不複用的原因}
- 複用決策:{複用哪些方法、端點、為什麼;不複用的原因}
## 未決項
@@ -27,15 +27,15 @@
## 工作分解結構(WBS)
`WP-01` 固定是交付/交接工作包,獨立成一包,不與實作合併;用到它規格的實作工作包相依於它。
交付型別於實作階段開工時確認(API 文件/由使用者輸入)。
資料來源欄記錄範例資料的出處:`真實:{來源}` 或 `推論:無來源`。
`WP-01` 固定是交付、交接工作包,獨立成一包,不與實作合併;用到它規格的實作工作包相依於它。
交付型別於實作階段開工時確認(API 文件、由使用者輸入)。
資料來源欄記錄範例資料的出處:`真實:{source}` 或 `推論:無來源`。
PR 欄記錄該工作包的 PR 連結與編號;PR 未合併前不得開始下一個工作包。
| 編號 | 工作包名稱 | 交付 | 交付型別 | 相依 | 工時(h) | 天數 | 資料來源 | 工作證 | PR | 狀態 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WP-01 | {交付/交接:規格與介面定義} | 是 | API 文件 | - | {h} | {d} | 真實:{來源} | | | 未完成 |
| WP-02 | {實作類名稱} | 否 | - | WP-01 | {h} | {d} | 真實:{來源} | | | 未完成 |
| WP-01 | {交付、交接:規格與介面定義} | 是 | API 文件 | - | {h} | {d} | 真實:{source} | | | 未完成 |
| WP-02 | {實作類名稱} | 否 | - | WP-01 | {h} | {d} | 真實:{source} | | | 未完成 |
| WP-03 | {實作類名稱} | 否 | - | WP-01 | {h} | {d} | 推論:無來源 | | | 未完成 |
- 關鍵路徑:{WP-01 → WP-02 → ⋯⋯},總天數 {d}
@@ -43,10 +43,10 @@ PR 欄記錄該工作包的 PR 連結與編號;PR 未合併前不得開始下
## 待辦事項(TDD)
### WP-01 {交付/交接工作包名稱}
### WP-01 {交付、交接工作包名稱}
- [ ] 盤點端點與參數:{對象}
- [ ] 產出規格與範例資料(標明真實/推論)
- [ ] 產出規格與範例資料(標明真實、推論)
- [ ] 與使用者確認交付內容並產出交付文件
### WP-02 {工作包名稱}
+1 -1
View File
@@ -1,6 +1,6 @@
# 交付目錄
<!-- 交付欄:是 = 交付/交接工作包(WP-01),接手者要據此動工;否 = 實作類工作包。 -->
<!-- 交付欄:是 = 交付、交接工作包(WP-01),接手者要據此動工;否 = 實作類工作包。 -->
| 計畫名稱 | 工作包 | 交付 | 交付型別 | 交付頁 | HASH | 存取庫 | 交付時間 |
| --- | --- | --- | --- | --- | --- | --- | --- |
+4 -4
View File
@@ -30,19 +30,19 @@
- 說明:{這個端點做什麼}
標示規則:🆕 **新增**、⚠️ **變更**、❌ **移除**(含淘汰時程)、既有參數留空。
資料來源:`真實:{來源}` 或 `推論:無來源`。範例只留格式,個資不留值。
資料來源:`真實:{source}` 或 `推論:無來源`。範例只留格式,個資不留值。
#### 輸入參數(全部)
| 參數 | 位置 | 型別 | 必填 | 範例 | 資料來源 | 狀態 |
| --- | --- | --- | --- | --- | --- | --- |
| {name} | path/query/header/body | {型別} | 是/否 | {值} | 真實:{來源} | 🆕 **新增** |
| {name} | path/query/header/body | {型別} | 是、否 | {值} | 真實:{source} | 🆕 **新增** |
#### 輸出參數(全部)
| 參數 | 型別 | 說明 | 範例 | 資料來源 | 狀態 |
| --- | --- | --- | --- | --- | --- |
| {name} | {型別} | {說明} | {值} | 真實:{來源} | |
| {name} | {型別} | {說明} | {值} | 真實:{source} | |
#### 錯誤回應
@@ -76,7 +76,7 @@
| 項目 | 指令或步驟 | 結果 |
| --- | --- | --- |
| {測試} | `{指令}` | {通過/失敗} |
| {測試} | `{指令}` | {通過、失敗} |
## 已知限制
-9
View File
@@ -1,9 +0,0 @@
# 異常目錄
> 由失敗回報流程維護。新異常附加在文末,查問題時先看最新一筆。
## 異常清單
| 時間 | 頁名 | 存取庫名稱 | 觸發流程 | 退出碼 | 摘要 |
| --- | --- | --- | --- | --- | --- |
| {yyyy-MM-dd HH:mm:ss} | [[{error title}|ERROR_{HASH}]] | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |
-33
View File
@@ -1,33 +0,0 @@
# 異常紀錄:{error title}
> 由失敗回報流程建立。這是一筆單次異常紀錄,不覆寫舊內容;同類失敗再發生時,請另開新頁。
- 頁名:`ERROR_{HASH}`
- HASH:`{HASH}`
- 發生時間:{yyyy-MM-dd HH:mm:ss}
- 存取庫名稱:{owner}/{repo}
- CLI:{cli}
- Session:{session_id}
- 觸發流程:{hook_name}
- 退出碼:{exit_code}
- 錯誤摘要:{error_summary}
## 現象
- {現象描述}
## 可能原因
- {可能原因}
## 處理結果
- {處理方式}
## 相關資訊
| 欄位 | 內容 |
| --- | --- |
| 訊息來源 | {stdin / env / command} |
| 相關輸出 | {stdout / stderr 摘要} |
| 關聯 ticket | `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}` |
+1 -1
View File
@@ -7,6 +7,6 @@
## 功能與端點
| 檔案路徑 | 方法/端點名稱 | 類型 | 邏輯摘要 |
| 檔案路徑 | 方法、端點名稱 | 類型 | 邏輯摘要 |
| --- | --- | --- | --- |
| {path} | {method 或 HTTP 動詞加路由} | 方法 \| 端點 | {做什麼、輸入輸出概要} |