interface:
  display_name: "Project Docs"
  short_description: "Audit and maintain linked project documentation"
  default_prompt: "Use $project-docs to inspect this project and update its technical documentation from code and evidence."

# 文件適用性目錄

回 [project-docs](../SKILL.md)。在決定要補哪些資訊時讀本頁；每列是讀者問題，不是必須新增的檔名。組織／契約要求優先，同一頁可以回答多列。

| 資訊類型 | 何時適用 | 最少回答／查證來源 |
|---|---|---|
| 概觀、術語、文件索引 | 所有需交接專案 | 系統做什麼、不做什麼、誰讀哪頁、版本與入口；README／現行設計 |
| 需求與驗收追溯 | 有使用者／交付行為 | 已批准需求、實作、測試如何對應；沒有批准原件時只列觀察行為與待確認 |
| 架構、外部與信任邊界 | 多元件或有外部依賴 | 元件責任、呼叫／資料方向、執行與部署拓樸；modules／entrypoints／deploy config |
| 流程、時序、狀態圖 | 非同步、跨程序、多步驟工作 | 觸發、完成、超時、重試、取消、並行；handlers／transactions／故障測試 |
| 資料字典、ER、演進 | DB 或持久化檔案 | schema、key／index／FK、JSON／file formats、migration／回填、保留與刪除；沒有關聯 DB 可只寫檔案模型 |
| 介面契約 | API、CLI、SDK、事件、hook、檔案交換 | 輸入輸出、預設、錯誤、副作用、身份、冪等與版本；parser／routes／schema／adapter |
| 環境、設定、相容性 | 需安裝或執行 | 支援平台／runtime、依賴版本、設定來源及優先序、憑證取得與輪替入口；lockfile／launcher |
| 品質屬性與容量 | 有品質目標或操作限制 | 已訂目標、量測方式、限制；實測延遲不是 SLA、沒有指標就列待決 |
| 快速開始、日常任務 | 有操作使用者 | 最小成功路徑、預期結果、常見錯誤；以實際入口驗證，不執行正式副作用 |
| 操作手冊（使用者／管理者） | 非工程讀者要自己完成任務 | **動手前要先具備什麼**（權限、前置資料、誰先做過什麼）、逐步操作與畫面、卡住時怎麼判斷與求助、哪些動作不可逆；前提必須查證，不能從程式行為倒推成「本來就該這樣」 |
| 開發、建置、測試 | 有維護者 | 依賴、命令、fixtures、CI、擴充點；檢查可執行檔／測試路徑存在 |
| 驗證／交接證據 | 所有補文件任務 | 版本、環境、命令、結果、測試層級、未驗項目；記錄不能冒充簽核 |
| 維運、監控、故障恢復 | 服務、排程或重要持久資料 | health／告警、值班入口、備份還原、停啟、解除安裝；未演練的恢復標待驗 |
| 安全與隱私設計 | 憑證、外部輸入或個人／機敏資料 | 身份／授權、資料去向、工具界線、留存、撤回與剩餘風險；不把技術檢查冒充全面合規 |
| 升級、遷移與退版 | 已有使用者與資料 | breaking change、版本前置條件、步驟、前後核對、不能回退的資料；migration／相容測試 |
| 發布說明與交付清單 | 某版本將交付 | 來源 revision、產物／雜湊、範圍、已知問題、安裝升級與驗收狀態；文件化不等於批准發布 |
| 依賴、授權、來源 | 使用第三方元件 | lockfile／授權／來源版本；需要時附正式 SBOM／provenance，不能把 lockfile 改名當完整 SBOM |
| 維護／支援／安全回報 | 團隊交接或 OSS | 維護責任、回報入口、支援版本／淘汰流程；從組織現有紀錄查，不能自己承諾 SLA 或杜撰聯絡人 |
| 技術債／未知事項 | 發現不一致或能力缺口 | 影響、來源、是否阻擋文件／交付、可執行下一步；分開追程式修復 |
| 領域特殊文件 | 由專案／契約觸發 | 前端可及性、SDK 版本矩陣、資料 lineage、ML 評估／資料授權、硬體接線、法規文件；確認適用性，別只因有類似字眼就整套套用 |

## 某次 release 要凍結什麼

選擇與該交付物相關的資訊：來源 revision／產物識別、變更與限制、相容性、安裝／升級／退回、實際測試與未驗項目、第三方來源／授權、已有批准紀錄、維護入口。這些可在一份 release handoff 中連回持續維護的技術文件，不複製整套手冊。

沒有 release 時，不製造空白 release notes、簽章、認證或虛構批准者。若只有 source 交付就如實說明；有正式 artifact 才記實際 artifact 雜湊。

## 方法來源

此目錄綜合下列第一手框架作裁剪參考，不宣稱等同標準符合性清單，亦不複製完整模板或付費標準全文：

- [ISO/IEC/IEEE 15289:2019 公開摘要](https://www.iso.org/standard/74909.html)：生命週期文件資訊可組合／裁剪，這裡只引用公開摘要。
- [arc42 overview](https://arc42.org/overview/)：架構、限制、執行、部署與風險的檢視面向。
- [Diátaxis](https://diataxis.fr/start-here/)：使用任務、教學、參考與原理解說的讀者需求。
- [Google SRE launch checklist](https://sre.google/sre-book/launch-checklist/)：上線／維運與恢復問題，按專案規模裁剪。
- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final)：安全準則、證據、元件來源與安全設定資訊；不推定適用法規或認證。
- [SLSA v1.2 provenance](https://slsa.dev/spec/v1.2/provenance)：產物與來源／建置的追溯。
- [GitHub community profiles](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories)：OSS 使用者／貢獻者入口。

使用特定標準版本或政策作合規聲明前，重新核對官方現行要求與適用範圍；上述方法來源本身不構成合規證明。

# 操作手冊寫法

> **English summary:** Write end-user and administrator manuals so they double as acceptance criteria: every consequential step states what the reader should see. Copy on-screen names verbatim, order prerequisites by walking them, and verify the finished manual with a context-free walkthrough.

回 [project-docs](../SKILL.md)。**只有在寫給終端使用者與管理者的操作手冊時讀本頁**；技術文件不適用。

## 骨架：每一頁回答四個問題

| # | 問題 | 寫在哪 |
|---|---|---|
| 1 | 這是幹嘛的 | 章節開頭第一段 |
| 2 | 用之前要先有什麼 | 「用之前要先有」小節。**最容易漏，而全新環境必定沒有** |
| 3 | 按了會怎樣 | 操作步驟的「應該看到什麼」欄 |
| 4 | 失敗了怎麼辦 | 章末「不順利的時候」 |

第 3 問用兩欄表寫，一欄「你做什麼」、一欄「應該看到什麼」：

| 你做什麼 | 應該看到什麼 |
|---|---|
| 只填標籤就送出 | 擋下並說明分組的代碼與顯示名要填 |
| 填了標籤與分組、但不選來源 | 擋下並說明來源必填 |

三條寫法紀律：

- **寫到可以判斷真假**。「會有提示」不算，「擋下並說明來源必填」才算。
- **被擋下的情況也要寫**，那是使用者最需要、也最少被記載的部分。
- **「什麼都沒發生」也要寫**。按了沒反應是最難自救的狀況，手冊要寫出該去哪裡確認。

## 名稱一律抄畫面上的字

使用者在畫面看到一個名字，去手冊找另一個名字，就找不到。導覽寫「使用者管理」而手冊叫「帳號管理」，那一章等於不存在。

- 章名、欄位名、按鈕名照抄，**不要替它取更好的名字**。
- **畫面自己前後不一致時，兩個名字都寫進同一句**。例：同一個狀態，清單的徽章寫「啟用」、篩選下拉寫「使用中」——寫成「狀態欄是綠色的『啟用』徽章（狀態篩選那個下拉把它叫『使用中』，是同一件事）」，兩種找法都成立。
- 手冊開頭放一張**導覽名稱 ↔ 章節對照表**，順便當覆蓋率檢查：導覽上有、表裡沒有的，就是漏寫的一章。

## 前置條件章節：有序，而且要走過

**全新安裝那一章通常是整份手冊最有價值的一章**，因為缺東西多半不會報錯，只是某些功能靜靜地做不下去，而使用者不會知道要去補什麼。

- 寫成**有序清單**，每一步附「不做的後果」，不要寫成無序的「需求清單」。
- 走完附一組**驗收題**（開哪一頁、應該看到什麼），讓人能自己判斷「可以開始用了」。
- 🔴 **順序必須實際走一遍，不能用推的。** 真實案例：把「建知識庫」排在「建群組」前面，但建庫時一定要勾授權群組——照那個順序做，第一步就卡住。這種相依性用讀程式碼看不出來。

## 兩個會寫出假敘述的來源

兩者都會產生「永遠不會發生」的敘述，而且寫的當下都覺得有根據。

**（a）把走不到的分支當成行為。** 前端有一段「這個庫還沒接上檢索系統」的提示，於是寫進手冊說選到未連上的庫會看到它。實際上那個下拉在送進元件之前已先過濾掉未連上的庫，**提示永遠不會出現**。

> 判準：**程式裡有一段 UI 文案，不等於使用者看得到它。** 要確認的是「什麼資料會流到這個元件」，不是「這個元件寫了什麼」。

**（b）沿用舊版文件未查證的句子。** 舊手冊寫「零授權的庫，清單會標『沒有任何群組可讀這個庫』」——那句話確實存在，但在另一個視窗裡，清單那欄只顯示「—」。

> 既有專案一定有舊文件，而**舊文件是假敘述密度最高的地方，偏偏看起來最可信**。改版時把每一句當成待查證，不要因為它已經在那裡就留著。事前點名的錯誤只是已經有人發現的那幾處；沒人發現的要靠走查挖。

## 抓實機截圖

動手前先取得使用者同意，要講哪三件事見 [skill 的分流與邊界](../SKILL.md#分流與邊界)。同意之後：

- **先鋪代表性資料再拍。** 空清單、零筆紀錄的截圖沒有價值，讀者看不出這一頁正常長什麼樣。
- **拍之前清掉測試殘骸**，否則整頁都是「測試項目 001」，交出去很難看。
- **對話框用元素截圖，不要整頁截**，否則底部的錯誤訊息會被切掉——而錯誤訊息常是那張圖唯一要證明的東西。
- **視窗高度調到貼近內容**，不然截圖一半是空白。
- **圖檔名加前綴**（例 `am2-`）避免多份文件共用圖片目錄時撞檔；路徑寫**最終位置**，不是暫存位置。
- 🔴 **截圖可能跟內文打架。** 依「現況有缺陷時寫該有的」寫了理想行為，而畫面是壞的，那張圖就不能放在那句話旁邊；改放在描述版面規則的段落，圖說只講版面，不講那個行為。

## 交付前的一致性走查

與 [驗證方法](verification.md#接手者測試) 的「接手者測試」**不是同一件事**：那個驗的是技術文件**找不找得到答案**，這個驗的是照著做**做不做得到**。

**環境**：清回全新安裝。🔴 **不要相信單一個 reset 指令，逐項驗。** 真實案例：重置腳本清了入料產物與照片，卻不清標籤字典，而「字典是空的」正是要驗的前提——差一步整輪白跑。

**給走查的人**：網址、帳號、手冊。**不給**：缺陷清單、寫手冊時的規格、程式碼。設一個操作次數上限，快到上限就停下來寫報告。

**差異必須分三類**，否則會把自己寫錯的當成產品缺陷去報：

| 類別 | 意義 | 處置 |
|---|---|---|
| A 既有缺陷確認還在 | 有價值：證明沒有任何提示也會被撞到 | 併工程待辦 |
| B 新缺陷 | 有基準才找得到的 | 開新單 |
| **C 手冊自己寫錯** | 把「該有的」寫得比實際設計更理想，或上一節那兩種假敘述 | **改手冊，不是改程式** |

⚠️ **C 佔一半是正常的**（實測一輪 14 條差異裡 7 條是 C）。C 佔比低反而要懷疑走查的人是不是看過不該看的東西。

**涵蓋率要誠實記**：哪幾步走完、哪幾步卡住、哪些頁面沒走到與為什麼。前置條件那條路徑本身就會吃掉大部分操作次數，沒走到的頁面通常要另外再跑一輪，不要假裝一輪就掃完了。

# 文件驗證與交接

> **English summary:** Verify documentation language, navigation, rendered diagrams, and evidence against the actual implementation. Scale validation to the change and distinguish offline checks from live acceptance.

回 [project-docs](../SKILL.md)。文件初稿完成後用本頁挑驗證方式；按實際風險，不用把每個專案變成全量測試工程。

## 導覽與格式

- 依 [skill 的語系規則](../SKILL.md#4-寫成單一現況來源) 逐頁核對本次正文與 GitHub 文件的英文摘要；雙語 README 核對內容一致。中文標題搭配全英文正文不算完成。翻譯不得改變指令、API／schema 識別字或授權原文。

- 檢查新增／修改的相對連結、章節 anchors、圖片來源、reference-style links。標題改名／檔案搬動要追入站引用；用 repo 真正的 Markdown/wiki 解析方式。git ls-files 有非 ASCII 路徑時用 `-z`，不能把 Git 顯示用的引號／八進位 escape 當檔名。
- 從 README／AGENTS／既有索引走到現行頁；有歷史頁也要能找到現行替代文件。連結圖可達只證明可找到，不代表分類或敘述易懂。
- worktree 裡的 sibling-repo 相對連結要分辨部署慣例與暫存路徑。若用主 checkout 映射檢查，記清楚映射及限制，不偷偷略過失敗。
- Mermaid 不只檢查 code fence：用可用的 Mermaid renderer／CLI 實際渲染，檢查文字截斷、重疊、箭頭、實體與狀態標示。保留原 `.md`，暫存渲染物不自動進版控。無渲染工具就記「語法／視覺未驗」，不要填通過；安裝額外工具依既有授權處理。
- 圖中狀態／欄位若為教學用概念而非程式 literal，要明示。資料模型標實際 FK 與邏輯關係，欄位 NULL／UNIQUE 不憑印象補。

## 行為與證據

| 驗證層 | 能說明 | 不能代替 |
|---|---|---|
| 靜態 parser/schema 對照 | 指令、欄位、預設與程式符合 | 正式環境正常 |
| 合成／離線測試 | 被測的故障、邊界、狀態轉移 | 外部服務／真實使用驗收 |
| 原生／整合 canary | 指定版本與環境的有限互動 | 長期可靠性或語意無誤 |
| 部署查核 | 實際版本、健康／READY、保留狀態 | 使用者滿意或所有功能正確 |
| 真人驗收 | 指定使用情境的實際結果 | 未測平台、負載或全面安全 |

執行命令前辨認副作用；`--help`／`status` 也可能有啟動或資料寫入。優先在 fixture／暫存 DB 核對 schema 和失敗，不對正式資料跑 install／init／reset。只記取得的證據：exit 0 但有 errors／skip／部分失敗時如實區分。

臨時探針需要日後重現時，把來源與輸出保存在 repo／組織允許的證據位置；只留暫存的驗證要標明一次性及保存限制，並留下必要重現步驟。不要把 `/tmp` 檔案寫成乾淨 checkout 已內附的測試。

有既存紅色 CI，先辨認是否本次導致。只補文件的任務列出問題和真實檢查結果；不順便修 CI、跳過必要檢查或宣稱全綠。

## 接手者測試

有條件且已授權時，讓獨立 reviewer 從入口開始，僅提供專案、讀者角色和典型任務：如何安裝／跑測試、在哪改設定、資料如何保存、失敗怎麼恢復、哪些能力未完成。要求回答來源檔案／章節，再對照程式。不要先餵正確答案或預期缺口。

沒使用獨立 agent 時可自行走一遍，報告應寫自查而非獨立審查。根據實際發現修正，再驗相關部分；不要用固定必須零風險／無限輪次拖住交付。

## 驗證 skill 本身

通用流程改動可用隔離的合成專案 forward-test：只有 CLI 無 DB、API＋DB＋migration、有既存公司模板的多模組 repo。加入可查的舊指令／失效 CI 與未確認需求，檢查輸出能否保留未知、尊重模板與範圍、區分內部／公開、建立可走的連結和可渲染的圖。這是能力測試建議，不是每次跑 project-docs 都要重建三個專案。

對照測試前後的檔案 hashes／diff，確認產品程式沒被文件任務改掉；再跑一次檢查是否增量更新而非重複建立文件。不要只斷言出現某個標題或固定用詞。