專案 README
README 既不是參數手冊，也不是廣告。它是幫助新讀者信任專案並獲得初步結果的最短路徑。
不要為了填寫章節而填寫章節。讀者應該能夠回答三個問題：這是什麼？適合我嗎？我能獲得初步結果並了解風險邊界嗎？
核心原則
- 每個主張都需要證據。省略無法在儲存庫中驗證或經用戶確認的主張；不要將猜測軟化為模糊的敘述。
- 快速入門是強制的：提供從安裝到獲得有用結果的最短真實路徑。如果其指令無法驗證，請提問，而不是留空或憑空杜撰。
- 當 README 已存在時，請詢問是要取代它、保留選定材料，還是原地擴充它。不要猜測或覆寫用戶編寫的內容。
- 在摺疊線上方建立身份和進入點。對於公開專案，使用專案名稱/標誌、一行描述、真實徽章和導航，然後立即放入快速入門。僅在 GIF/螢幕截圖能傳達比文字更多資訊時才使用。
- 展示而非宣稱：終端機輸出、螢幕截圖、程式碼和經過驗證的數字比形容詞更有說服力。
- 按任務組織，而非按參數。解釋「我想做什麼 → 哪個指令能做到」；將完整的選項清單留給
--help。 - 刪除任何無法幫助讀者決定、信任或行動的內容。
- 如果專案涉及本地檔案、資料庫、憑證、網路或模型呼叫，請解釋它讀取、寫入以及在裝置外發送了哪些內容，以及其預設的唯讀/確認/備份/故障關閉姿態。沒有程式碼證據，就不要做出安全承諾。
- 將 README 保持為前門；將深入細節連結到
docs/或CONTRIBUTING.md，而不是將 README 變成手冊。 - 配合專案；不要將同一模板強加於 CLI、MCP、函式庫、應用程式和研究儲存庫。
- 避免未經證實的誇耀，例如「業界領先」、「生產就緒」或「極致效能」。請參閱
content-writing中的護欄。
選擇讀者群
對 README 的讀者進行分類以設定詳細程度：
- 個人（個人專案、內部工具或個人腳本）：讀者主要是你，包括未來的你。必備：一行描述、快速入門和已知限制。徽章、貢獻指南、社群頻道、星號歷史和路線圖為可選。基本要求是三個月後你仍然能執行它。
- 公開（開源、散佈式軟體或團隊共享）：讀者是陌生人。包括描述、價值、快速入門、用法、配置、文件索引、貢獻和授權。僅在徽章和社群資訊確實存在時才添加。
若儲存庫是公開的、已發佈到套件管理器或有外部用戶，則預設為公開；對於私人個人專案和一次性工作，則預設為個人。對於混合情況，使用公開的詳細程度。
選擇模式
| 模式 | 何時使用 | 第一步 |
|---|---|---|
| 建立 | 沒有 README，或用戶明確要求重寫 | 檢查儲存庫並收集事實。 |
| 改善 | 有 README 但需要改進 | 閱讀它，詢問如何處理現有內容，然後繼續。 |
| 稽核 | 用戶僅要求診斷 | 驗證 README 的每個主張是否與儲存庫相符，並報告發現。 |
關卡： 如果 README 存在，暫停讓用戶選擇：(1) 完全取代，(2) 保留指定材料並重寫，或 (3) 原地擴充。「幫我寫一個 README」並不表示選項 1。
摺疊線上方與開發者工具風格（公開專案）
讀者會在一屏之內決定是否繼續。第一屏應顯示專案的功能。
對於 CLI、MCP 和本地開發者工具，偏好內斂、可驗證的開發者文件：
<div align="center">
可選標誌
# 專案名稱
**一行描述**
僅真實徽章
語言切換器（僅當另一個 README 存在時）
錨點導航（當文件超過 100 行時）
</div>
---
功能概述：實際的指令/工具、輸入、輸出和預設安全姿態
三個規則：
- 一行描述： 保持令人難記且約為一行：它是什麼、為誰而做、以及最重要的事實區別。將原則和背景留到後面。
- 功能概述： 列出實際的指令/工具、輸入、輸出、讀/寫物件和預設安全姿態。避免像「快速、安全且智慧」這類的一般性宣稱。
- 接下來是快速入門： 偏好 1-3 個最簡短的步驟。最後一步必須驗證安裝或服務發現。將複雜配置放在後面。
視覺素材為可選。僅在它們能增加資訊時，才選擇 GIF/asciinema、螢幕截圖和真實的終端機輸出。如果沒有示範素材，不要憑空創造；請提供真實的指令、預期輸出和驗證步驟。
個人專案可以省略標誌、徽章和導航，但一行描述和可見的輸出一樣有用。
證據階梯
在撰寫每個主張之前，對其證據進行分類：
| 等級 | 來源 | 使用方式 |
|---|---|---|
| 1 | 在儲存庫中： 原始碼、測試、範例、配置、CI、標籤、螢幕截圖 | 直接撰寫。 |
| 2 | 經用戶確認： 定位、差異化、指標、螢幕截圖、案例 | 直接撰寫。 |
| 3 | 可外部驗證： 套件頁面、發行版本、公開基準測試 | 附上連結後撰寫。 |
| 4 | 無來源 | 省略。如果重要則提問；否則刪除。 |
切勿憑空杜撰安裝指令、CLI 參數、API 簽章、配置鍵、環境變數、路徑、效能數據、相容性主張、授權條款或社群連結。
請參閱 references/evidence.md 以了解儲存庫掃描和證據規則。
工作流程
- 分類讀者群與模式： 個人/公開 以及 建立/改善/稽核。如果 README 存在，請在變更前詢問如何處理。
- 收集儲存庫證據： 檢查套件元資料、進入點、結構、配置、文件、Git/CI、資產、讀/寫路徑、憑證、網路、模型呼叫和錯誤碼。此階段收集事實，而非結論；請參閱
references/evidence.md。 - 分類專案與讀者： CLI、MCP、函式庫、應用程式、研究專案、Agent Skill 或 monorepo。根據此選擇章節；請參閱
references/structure.md。 - 驗證快速入門： 找到並驗證安裝後能產出有用結果的第一個指令。如果無法驗證，請提問且不要越過此關卡。
- 規劃章節： 為專案類型選擇章節，並為每個章節找出證據。省略無法支援的章節。同時決定摺疊線上方佈局、快速入門驗證，以及是否需要安全性/資料流、錯誤碼或疑難排解。
- 草稿： 身份與功能 → 快速入門 → 功能 → 安裝/配置 → 基於任務的用法 → 原理/背景 → 安全性/隱私邊界 → 錯誤/疑難排解 → 已知限制 → 開發/深入文件。在讀者有了可運作的路徑之後，才解釋原理，而不是在此之前。
- 執行品質關卡： 檢查
references/checklist.md中的每個項目，特別是事實準確性和可執行的步驟。 - 交付： 預設在對話中提供草稿；僅在明確要求時才寫入磁碟。在寫入前重新執行檢查清單。
輸出
簡潔說明：(1) 讀者群與模式；(2) 專案類型與目標讀者；(3) 章節計劃與每個章節的證據來源；(4) README 草稿；(5) 因缺少證據而需用戶確認的主張；(6) 已知遺漏。切勿將猜測標記為已驗證。明確列出無法支援的主張，而不是用模糊的語言來掩飾。
紅旗
- 快速入門缺失或空白，或憑空杜撰無儲存庫進入點的指令。
- 在未詢問如何處理的情況下覆寫現有 README。
- 未經證實的效能、相容性、用戶數量或星號數量主張。
- 指向不存在的 CI、套件或授權的徽章。
- 用空標題或「TODO / 即將推出」來填充模板章節。
- 嵌入完整的 API 手冊，而不是連結到它。
- 複製長篇的
--help表格，而不是展示基於任務的指令。 - 開場畫面只有標語或原則，沒有真實的進入點或可驗證的結果。
- 對於觸及本地資料、憑證、網路或模型呼叫的工具，遺漏安全性/資料流資訊。
- 未經程式碼/測試證據就承諾唯讀操作、無資料洩漏、故障關閉行為或零配置。
- 疑難排解只寫「重新啟動」，而沒有症狀、錯誤碼、原因和補救措施。
- 一行描述寫成段落，或在第一個可執行的路徑之前就出現原理說明。
- 使用「強大」、「優雅」、「極致」或「開箱即用」等形容詞來取代證據。
- 對於不存在的個人專案，強制加入貢獻指南、行為準則或社群連結。
- 架構圖包含不存在的元件或呼叫關係。
- 未經用戶授權就寫入檔案。
參考資料
僅讀取需要的內容：
references/structure.md：閱讀流程、按專案類型選擇章節，以及章節撰寫指導。references/evidence.md：儲存庫掃描、證據等級以及不得憑空杜撰的主張。references/checklist.md：針對事實、可用性、呈現方式與語言的事前撰寫品質關卡。