project-docs — 把現有專案整理成接得下去的文件

English summary: Audit existing code and maintain linked Markdown/Mermaid documentation. Use Traditional Chinese prose by default and add an English summary for GitHub publication, while preserving explicitly agreed bilingual README editions.

從程式、設定、測試與既有決策查證現況，補齊讀者需要的資訊。文件完整度看「關鍵問題能否找到有證據的答案」，不看產出幾份檔案。

兩種讀者，兩套寫法，別混在一份裡。

讀者	要回答什麼	交付物
下一位維護者	架構、契約、資料模型、部署、如何改	技術文件，圖用 Mermaid
終端使用者與管理者	要先具備什麼、怎麼操作、按了會怎樣、卡住怎麼辦	操作手冊，圖用實機截圖

文件適用性目錄「快速開始、日常任務」那列就是後者，適用條件是「有操作使用者」。判斷適用性時不要因為預設在寫技術文件就跳過它。

🔴 第三問「按了會怎樣」是手冊唯一可被驗證的部分。 每個會造成後果的操作都附一欄「應該看到什麼」——那一欄是驗收點，不是敘述。沒有它，手冊只能被「讀起來合理嗎」檢查，沒有人能判斷它說的是不是真的。寫手冊的完整紀律見操作手冊寫法。

1. 確認範圍，承接已有授權

讀目標 repo 的規則、入口文件、現有模板與版本狀態；保留他人的 dirty 檔。先確認本次是唯讀盤點還是補寫／更新，以及內部或公開讀者。使用者已說清楚就直接做，不重新問批准問題，也不擅自把無人值守任務改成訪談。

• 只要求盤點：交付證據、缺口、建議更新位置，不直接改專案文件。
• 已授權補齊：先盤點，再依結果更新；不需要把每個例行文件選擇重新交給使用者。
• 從 repo 可查的事自己查；真正缺少的需求、支援承諾或設計理由標待決。只有答案會影響必要工作時才問，其他部分繼續。
• 內部文件保留有用的內部名稱與部署脈絡，憑證只記取得／安全保存方式。公開輸出另做去敏；掃整個專案不等於把使用者資料、秘密、原始對話或 vendor 全部抄入文件。

2. 建立全專案覆蓋與證據地圖

先用檔案清單辨認各模組和責任，再深入入口、邊界與相依關係。大型 repo 分區，清楚記已檢查／待檢查／排除及理由；不能只看 README 與一個模組就宣稱掃完。

清單要包含隱藏的 CI／設定檔，例如用 rg --files --hidden -g '!.git' 並搭配 git ls-files -z；被 ignore 的 runtime／生成物另按需要查核，不為了盤點就讀出秘密或原始使用者資料。

至少盤點：應用／服務／CLI／批次入口、跨模組介面、資料存放與 migration、設定與外部依賴、權限／敏感資料邊界、建置／部署／排程、測試與 CI、現行與歷史文件。沒有的項目記不適用及理由，未知的不要當不存在。

每個發現留下可追溯的 file/symbol／schema／test 或 command evidence，並記來源 commit／檢查日期。檔名只能指路，不能證明內容正確：比對 README 指令與 parser、CI 路徑是否存在、schema 真正約束、部署腳本和實際驗證範圍。

寫手冊時這條有兩個特有的變形，兩個都會寫出永遠不會發生的敘述：程式裡有一段 UI 文案，不等於使用者看得到它（那個分支可能走不到）；舊版文件的既有句子不能沿用（既有專案裡假敘述密度最高的地方，偏偏看起來最可信）。兩者都只能逐句查證，例子見操作手冊寫法。

若要宣稱「正在部署／現在正常」，需相應 live evidence；否則寫「依某日期部署紀錄」。使用只讀入口不一定零寫入：先看 helper 是否建表、對帳或變更狀態。文件任務不自動觸發服務、正式模型、發送訊息或資料遷移。

3. 裁剪文件並決定更新位置

讀 文件適用性目錄，依專案形態與組織模板建立精簡矩陣：

資訊／讀者問題	狀態	證據／理由	更新位置與驗收
依專案填寫	可用／過時／缺少／不適用／待確認	具體來源	優先既有現行頁

不用把每列都變成獨立檔案。CLI 沒有 DB 就不硬畫 ER；沒有 HTTP 就寫 CLI／hook／事件契約，不硬產 OpenAPI。缺 SLA 寫未訂定；觀察到的程式行為不能倒寫成當年批准需求，找不到決策理由就記未找到，不能補造 ADR。

使用既有 docs／wiki／組織模板，保留正式章節、術語及權責；不強制把產品 repo 改成另一種知識庫型態。組織模板要求的欄位即使未知也保留並說明缺口。技術文件可引用需求原件，不取代 PRD／簽核紀錄。

3.1 承接實測素材（有的話）

寫操作手冊最缺的是「使用者實際會卡在哪」，那從程式碼讀不出來。專案若剛跑過一輪實機 QA，素材可以直接接：

素材	接到手冊哪一節
系統隱含要求但沒寫出來的前提	「使用前提」
行為正確但使用者看不懂的卡關點	「常見問題」
成功路徑的逐步截圖	操作步驟
缺陷清單	不進手冊，那是工程待辦

🔴 接素材有一條紀律：QA 挖到的是「系統實際這樣做」，不等於「本來就該這樣」。

標成待判定、還沒有人拍板的項目，不可以直接寫進手冊當成正式規格。寫進去就等於替它蓋章，之後沒人會再質疑它合不合理。沒拍板的先留在待決清單，或在手冊裡明確標成「目前行為，尚待確認」。

沒有實測素材照樣寫得出手冊，只是每條使用前提都要自己回去查證，並標明證據狀態。

現況有缺陷時，手冊寫什麼

照現況寫等於教使用者繞過缺陷，並把缺陷凍結成正式流程；寫「該有的樣子」會讓手冊與現況產生落差，但那個落差可以被發現。預設選後者。

例：已知「上傳完成頁沒有挑附圖的入口」。

• ❌ 「按完成回首頁，從最近紀錄點挑附圖」——把缺陷寫成正常流程。
• ✅ 「收完帶圖的文件後，應該可以在當下決定要不要附圖」。

⚠️ 手冊裡不標任何已知問題。 標了等於把答案先洩給後面走查的人，他會去複現而不是自己發現。缺陷留在工程待辦（見上表最後一列），不進手冊。

4. 寫成單一現況來源

產出以 Markdown 為準；架構、流程、時序、狀態、ER 等圖表以 mermaid fenced code blocks 呈現，對照表用 Markdown table。 圖是可維護的原始碼；渲染圖放既有產物位置或暫存，不拿截圖取代 Mermaid 來源。若使用者明確指定其他格式，先遵循該要求並保留可追溯來源。

⚠️ 上句「不拿截圖取代 Mermaid 來源」只管架構、流程、時序、狀態、ER 這類結構圖 —— 它們的正本必須是可維護的原始碼。操作手冊的實機截圖不在此限：使用者要對著畫面找按鈕，Mermaid 畫不出那個。手冊截圖要標註它證明了什麼、取自哪個版本與環境；版本改了畫面就過期，重截並更新標註，不要留著舊圖。

技術文件預設使用正體中文（臺灣用語）；要發布到 GitHub 的文件，開頭放簡短英文摘要，正文用正體中文。 私有文件也沿用中文正文，不因去敏／OSS 匯出而改成全英文。已約定的雙語 README 保留獨立英文版與中文版，內容同步並互連；英文版不套中文正文規則。程式碼、指令、API／schema 識別字與授權原文保留原樣。使用者或組織明確指定其他語系時才依該要求；既有檔案碰巧是英文不構成例外。這是本 skill 的預設交付慣例，驗收時核對本次產出，不藉此翻譯未授權的歷史檔案。

依實作與風險深度補內容，而非套固定長度。特別注意：

• 跨程序／非同步：觸發、完成邊界、持久狀態、重試／去重、取消、競態和未知結果。區分寫入成功、外部送達、使用者驗收與備份成功。
• 資料：欄位、型別、唯一鍵、FK、索引、資料版本／migration、保留／刪除。ER 的 DB 外鍵與應用層邏輯關係分開；不要把名稱相似畫成強制約束。
• 介面：輸入／輸出、必要與選用欄位、預設值、錯誤／exit code、重試語意、相容性。多階段 CLI exit 0 是否仍有部分失敗要查證。
• 維運：前置條件、健康判讀、備份、還原、升級、退回／停用，以及操作的資料影響。沒有恢復工具或沒演練過就直說，不能編造一鍵命令。
• 證據：已實作、已離線測試、實際部署紀錄、真人驗收、提案／待決分開。歷史原件保留，用現行連結說明被哪份後續文件取代。

從主要入口連到索引或相關文件，各頁有意義地交叉引用依賴、契約、程式、測試和驗證；讀者能循連結找答案，不只列一長串檔名。預設用可在 GitHub 顯示的相對 Markdown links；已有 wiki link 慣例時尊重其解析方式。移動檔案要修入站連結和 anchors。

5. 驗證並交接

讀 驗證方法，按變更的風險執行。最少核對：正文語系與 GitHub 文件的英文摘要、連結／anchors 與入口可達性、Mermaid 真正渲染、關鍵命令／schema 對照、歷史與現況一致、缺口與證據範圍。測試結果要有命令、環境、時間、來源版本與實際結果；未執行或 skip 不填通過。

操作手冊另有一道交付前關卡：一致性走查。 把環境清回全新安裝，找一個沒有脈絡的人或 agent，只給網址、帳號與手冊，不給缺陷清單、不准看程式，請他照手冊走一遍；做不到的地方就是差異。差異必須分三類——既有缺陷確認還在／新缺陷／手冊自己寫錯——否則會把自己寫錯的當成產品缺陷去報。做法見操作手冊寫法。

🔴 走查不可以由寫手冊的這個 session 自己做。 它知道手冊想表達什麼，會自動照腦中的意思去操作，等於自己驗自己。抓圖可以自己來，走查要換人。

發現程式／CI 問題時記獨立工程待辦、影響與證據；除非使用者同時授權，文件工作不修程式或改服務。舊 CI 失敗與文件檢查成功分開回報。只改低風險文字不用重跑所有昂貴測試；新的契約問題或失敗才擴大驗證。

最後留下：更新哪些現行頁、覆蓋哪些模組、哪些沒看／沒驗、仍缺什麼、由哪個入口接續，以及何種變更需要更新文件。再次執行先比較來源版本與現行頁，增量修訂；不要重建第二套 docs 或為同一次證據再生一份「最新版」。

分流與邊界

需要新功能設計走 spec，需求不明確才走 grill；要查 bug 根因走 diagnose；明確要求公開發布整備可接 prep-repo。可用 workflow-router 選擇，但缺少其他 skill 也能完成本文的文件任務，不以安裝它們作前置條件。

本 skill 不自行 commit／push／部署／發布，也不決定敏感資料公開；依該次使用者的既有授權和 repo 流程執行。不要把只補文件變成重構、稽核認證或一整套新專案。

本 skill 不執行測試、不做實機 QA。 寫操作手冊時若發現「使用者到底會卡在哪」只有實跑才知道，先跑一輪實機 QA 再回來接素材（見 §3.1），不要憑程式碼想像使用者的體驗。

例外：寫操作手冊時可以驅動瀏覽器抓實機截圖。 但這是動真的系統，開始前一定要先跟使用者講清楚並得到同意，至少講三件事：

1. 要連哪一套環境。 同一個產品常有多套站（測試／示範／正式），連錯會動到別人正在用的那套。
2. 會不會寫入。 空環境截不出有用的圖，通常得先鋪代表性資料、清掉先前的測試殘骸——那些都是寫入。
3. 畫面上可能有真實資料。 客戶名、人名、實際文件內容會連同截圖一起留在文件裡，之後很難收回。

使用者沒有明確同意就不要開瀏覽器。抓圖以外的實機操作（跑流程驗功能、一致性走查）不在這個例外裡。