README that sells（會賣的 README）
一份 README 不是文檔。它是一個剛好住在 git 儲存庫裡的落地頁。
訪客大約在 15 秒內就會決定要標星、試用，還是離開。摺疊線以上的內容
必須贏得那顆星星。文檔放在摺疊線以下或 docs/ 裡。
15 秒測試
在寫任何東西之前，一行回答這些問題。如果你做不到，README 也做不到。
- 這是什麼？ 一句話，沒有形容詞。「一個用 Zig 寫的 AI 代理無頭瀏覽器。」
- 為什麼存在？ 它解決的痛苦，用使用者的話說。「Chrome 每個分頁吃掉 500 MB；代理需要 50 個分頁。」
- 證明它有效。 一個 Demo GIF、一個基準數字，或一個前後對比。不是功能列表。
- 我如何用一個指令試用？
npx ...、pip install ...、curl ... | sh、docker run ...。
結構（依此順序，沒有例外）
# 專案名稱
一句話定位。（什麼 + 給誰 + 賣點）
[Demo GIF 或截圖 — 10 秒內，展示結果，不是設定過程]
## 安裝 ← 一個指令，可複製貼上，沒有隱藏的先決條件
## 為什麼需要 ← 3–5 行：痛點、現有替代方案、為何此專案不同
## 用法 ← 最常見的單一使用案例，作為可執行的範例
## 功能 ← 可選，簡短，條列，無行銷形容詞
## 運作原理 ← 可選，一段文字或一張圖表
## 比較 ← 可選表格，比較 2–3 個替代方案，誠實說明取捨
## 貢獻指南 / 授權
規則
- 定位語： ≤ 15 字。說出類別和差異點。避免「超快」、「強大」、「簡單卻」。如果有數字，就用數字：「將 Claude Code token 用量減少 40%。」
- 先 Demo，後文字。 GIF 或截圖直接放在定位語下方。如果還沒有 Demo，在發布前先做一個（參見 demo-gif 技能）。沒有 Demo 的 README 轉換率遠低於有 Demo 的。
- 安裝是一個區塊，一個指令。 如果需要 API 金鑰或設定檔，也在同一個區塊裡顯示。隱藏的先決條件是 clone 後人們離開的首要原因。
- 「為什麼需要」是寫給已經有解決方案的人。 說出替代方案的名稱。說它們哪些做得好。然後說這個專案做了哪一件它們做不到的事。讀者信任對競爭者公平的 README。
- 標題不要用表情符號，除非專案刻意活潑。定位語上方不要放徽章（一堆徽章是訪客第一個會略過的內容）。定位語下方放兩三個徽章還行：建置狀態、版本、授權。
- 一個真實範例勝過十個功能點。展示輸入 → 輸出。讓它成為讀者真的會執行的東西。
- 說它不做什麼。 一句誠實的範圍說明（「不是 Playwright 的替代品；還沒有 JS 渲染」）能先發制 Hacker News 上第一個敵意評論。
- 連結你擁有的社會證據。 「被 X 使用」、一個基準測試、一個 Show HN 討論串。不要編造。
- 保持前 60 行沒有初次訪客不需要的東西。 架構、路線圖、常見問題、更新日誌：全部放在下面或別處。
會扼殺轉換的反模式
- 以一段背景或歷史開頭。
- 頁面第一個東西是目錄。
- 「功能」在「安裝」之前。
- 安裝說明以「首先，clone 儲存庫」開頭（針對的是要使用而非開發的工具）。
- 展示設定檔的截圖而不是結果。
- 行銷口吻（「革命性的」、「下一代」、「毫不費力」）。
- 死掉的佔位符（「TODO: 加入 demo」）。
流程
- 讀取現有 README（如果有的話）和程式碼的進入點。從 15 秒測試中提取出四個答案。
- 草擬定位語。寫三個變體；選出具體名詞最多、形容詞最少的那個。
- 先寫安裝，然後用法，最後是為什麼需要。從乾淨目錄執行安裝中的每個指令，確認它能運作。
- 在定位語下方插入 Demo。如果沒有，加入一個
TODO(demo)標記，並告訴使用者它會阻擋發布。 - 刪除摺疊線以上所有沒通過「陌生人需要這個來做決定嗎？」考驗的內容。
- 以懷疑的工程師身分閱讀前 60 行。修正第一個會讓他們關掉分頁的地方。
輸出
回傳完整的 README.md。然後用 ≤ 5 個項目符號列出你改了什麼，以及使用者仍然必須提供的東西（Demo GIF、基準數字、真實使用者評價）。