README 撰寫工具 是做什麼的?
一份 README 只有一個任務:讓訪客在 60 秒內從「這是什麼?」順利執行第一條指令,然後展示如何更進一步以及如何貢獻。
使用時機
- 為新專案撰寫 README,或改寫內容貧乏或雜亂的現有 README
- 在專案發佈或 1.0 版本前審查 README
- 使用者表示專案有流量但沒有星星、安裝數或貢獻者
不應使用的情況
- API 參考文件(應從程式碼產生,並在 README 中提供連結)
- 長篇教學或架構文件:應放在
docs/目錄,並在 README 中提供連結
工作流程
-
撰寫前先收集事實。 讀取專案清單檔(
pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI--help或主要進入點、現有文件以及授權條款。找出實際的安裝指令和一個真實範例。絕不憑空捏造旗標、輸出結果、基準測試或功能。 -
只詢問程式碼無法告訴你的事: 專案的目標對象、解決的單一問題,以及為何比明顯的替代方案更優秀。如果無法取得這些資訊,則根據程式碼撰寫中性的介紹,並標註為待審查。
-
對現有 README 進行 lint 檢查(如果有的話)。
scripts/路徑相對於此技能:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
根據 structure.md 中的結構進行撰寫,從範本開始。順序很重要:標題和徽章、介紹、(示範圖片)、快速入門、功能、使用方式/範例、設定、常見問題、路線圖、貢獻指南、授權條款。
-
套用撰寫規則:
- 介紹:一句話,不超過 200 個字元,不使用誇大詞彙。模式:「
<名稱>是一個<類別>,為<目標對象>提供<功能>,<關鍵差異化優勢>。」 - 第一個程式碼區塊應在 60 行以內。每個指令都必須是可複製貼上且真實可用的。
- 在指令後顯示輸出結果(使用
# => ...或獨立區塊)。 - 使用表格呈現選項和比較,使用列表呈現功能(先寫優點)。
- 提供連結,不直接貼上:長篇文件、變更日誌和 API 參考資料應放在其他地方。
- 每張圖片都需有替代文字;建議使用 SVG 或展示主要流程的短 GIF。
- 介紹:一句話,不超過 200 個字元,不使用誇大詞彙。模式:「
-
徽章。 只使用真實且持續維護的徽章,順序如下:CI 狀態、最新版本(PyPI/npm/Packagist/release)、下載量(可選)、授權條款。範例請見 structure.md。
-
重新進行 lint 檢查,直到沒有任何錯誤。處理警告,或向使用者說明不處理的原因。
-
檢查 lint 工具無法檢查的連結: 絕對 URL 和錨點。實際點擊測試,或說明哪些連結未經驗證。
產出
- 新的或更新的 README.md(對於改寫,顯示差異摘要)。
- 最終 lint 結果。
- 無法驗證的事實清單,以及使用者必須自行填寫的佔位符(示範 GIF、螢幕截圖、基準測試數據)。
Lint 規則
| 規則 | 層級 | 說明 |
|---|---|---|
| title | error/warning | 必須剛好有一個 H1 |
| pitch | error/warning | 標題下方需有一段簡短的介紹 |
| badges | warning | 未找到徽章 |
| install | error/warning | 需有安裝(或快速入門)章節,且包含程式碼區塊 |
| quickstart | error/warning | 需有使用方式、快速入門或範例章節,且包含程式碼區塊 |
| code | error | 完全沒有任何程式碼區塊 |
| scroll | warning | 第一個程式碼區塊出現在 --max-scroll 行之後(預設 60 行) |
| contributing, license | warning | 缺少對應章節 |
| faq, toc | info | 建議新增 |
| alt-text | warning | 圖片沒有替代文字 |
| broken-link | error | 相對連結指向不存在的檔案,或連結為空 |
| broken-anchor | error | #anchor 連結(目錄)未對應到任何標題或 HTML id/name,使用 GitHub 的 slug 規則 |
| placeholder | warning | 文件中仍有 TODO、TBD 或 lorem ipsum |
若有錯誤則退出並回傳 1(使用 --strict 時,警告也會導致退出)。