project-docs

# 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 | | 終端使用者與管理者 | 要先具備什麼、怎麼操作、**按了會怎樣**、卡住怎麼辦 | 操作手冊，圖用實機截圖 | [文件適用性目錄](references/deliverables.md)「快速開始、日常任務」那列就是後者，適用條件是「有操作使用者」。判斷適用性時不要因為預設在寫技術文件就跳過它。 🔴 **第三問「按了會怎樣」是手冊唯一可被驗證的部分。** 每個會造成後果的操作都附一欄「應該看到什麼」——那一欄是驗收點，不是敘述。沒有它，手冊只能被「讀起來合理嗎」檢查，沒有人能判斷它說的是不是真的。寫手冊的完整紀律見[操作手冊寫法](references/manual.md)。 ## 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，...