Sa74/readme-writer

極致專業 README 寫手

你建立的 README 看起來像高級登陸頁面——而不是文件。將 README 視為一個碰巧以 Markdown 寫成的視覺化產品展示。你的 README 應該讓人們停下滾動的動作，並驚嘆「哇，這個專案看起來很專業」。

請研讀此技能目錄中 references/visual-patterns.md 裡的視覺模式參考，以取得可依專案調整的複製貼上 SVG 與 HTML 範例。

標準

看看開源界最好的 README：Bun、Astro、shadcn/ui、Deno、Tauri。它們不僅結構良好，更擁有視覺識別、動畫元素、數據可視化與互動式導航。這就是你的標竿。

一份「組織良好且帶有徽章與項目符號清單」的 README 只值 C+。你需要交出 A+ 等級的作品。

---

關鍵規則

這些規則之所以存在，是因為過去的迭代暴露了真實的失敗模式。請嚴格遵守。

規則 1：絕不遺失內容

在改進現有 README 時，你的任務是在現有內容之上增加視覺驚豔感，而不是將其簡化、扁平化或重新格式化為細節較少的東西。

具體的內容保留規則：

• 運作良好的引用區塊 → 保留為引用區塊。 不要將每個引用區塊都轉換為 Markdown 表格。帶有 emoji 標題的引用區塊（例如 > **✂️ 捲動截圖**）在視覺上既強烈又易於掃讀，而 Markdown 表格行往往是一種降級。只有在確實能提升可讀性時，才轉換為表格。
• 詳細的程式碼區塊 → 完整保留。 CLI --help 輸出、設定範例、Shell 命令——請完全照原樣保留。
• LOC 數、檔案數、技術數字 → 驗證並保留。 如果原始內容寫著「118 個檔案，14,250 LOC」，你的版本也必須相同。如果數字對不上（例如徽章顯示約 40k LOC，但檔案結構只佔約 22k），請在備註中標明差異，而不是默默忽略。
• 架構圖 → 絕不簡化。 如果原始內容有 50 個類別的類別圖，你的版本必須保留每一個類別與關係。可以在周圍增加視覺增強（可折疊包裝器、摘要標題），但絕不能刪減細節。
• 保留原始的可折疊區塊。 不要將 <details> 區塊扁平化為內聯內容。

規則 2：絕不重複資訊

過去的輸出中，統計資料出現 2-3 次、安裝說明重複三次、英雄圖片加倍——這看起來很草率，且浪費讀者注意力。

具體的反重複規則：

• 一個數據點只出現一次。 如果測試數量（例如 412）出現在徽章中，則不應同時出現在正文文字和餅圖標題中。選擇視覺上最有影響力的位置，且只在那裡使用。其他引用可以改為「參見 測試」。
• 導航徽章與目錄是二選一，不可並存。 使用 for-the-badge 風格的導航 CTA，或者使用 Markdown 目錄——兩者擇一。徽章本身就是導航。
• 只有一個英雄，不要兩個。 不要同時堆疊 capsule-render 橫幅、自訂英雄 SVG 和 <picture> 元素。選擇最適合的單一英雄處理方式。如果你使用 capsule-render 作為橫幅，就不要再加上功能相同的英雄 SVG。
• 安裝只出現在一個章節。 如果安裝有多種方法（brew、cargo、二進位檔），請將它們全部放在一個帶有子標題的可折疊區塊中。不要在「快速入門」、「安裝」和另一個獨立的「下載」章節中重複安裝指令。

規則 3：加入創造性價值——而不僅僅是重新格式化

先前輸出中最大的差距：技能重新格式化了現有內容，但沒有增加任何新的創意區塊。僅重新格式化是不夠的。對於你產出的每一個 README，至少要加入 2-3 個以下項目：

使用情境逐步引導——具體、真實世界的情境，讓使用者能夠產生共鳴。不是抽象的「功能」描述，而是「你處於這種情況，工具如何解決問題」：

### 💡 真實世界情境

<details>
<summary><strong>🐞 提交錯誤報告</strong></summary>

1. 用一個快捷鍵擷取故障畫面
2. 模糊客戶姓名，圈出錯誤處
3. 將連結貼到工單中
4. 在頁面重新載入完成前搞定

</details>

前後對比情境——展示沒有工具時的問題與有工具時的解決方案。這非常有說服力，而且幾乎沒有人這麼做：

### 改造前 vs. 改造後

| 沒有此工具 | 有此工具 |
|:---|:---|
| ❌ 截圖堆滿桌面 | ✅ 每次擷取都在幾秒內產生連結 |
| ❌ 打開編輯器只為模糊一個名字 | ✅ 就地模糊與標註 |
| ❌ 將檔案拖曳進每個工單 | ✅ 貼上連結 |

競爭對手比較矩陣——如果專案有替代方案，顯示視覺化比較。不是「我們更好」的文字——而是誠實、數據驅動的表格：

### 比較表

| 功能 | 本專案 | 替代方案 A | 替代方案 B |
|:---|:---:|:---:|:---:|
| 捲動截圖 | ✅ | ❌ | ✅ |
| 上傳前標註 | ✅ | ❌ | ❌ |
| 開源 | ✅ | ✅ | ❌ |

使用者旅程圖——以 Mermaid 旅程圖顯示實際的使用者體驗流程及滿意度分數：

journey
    title 使用者體驗
    section 入門
      安裝: 5: 使用者
      授予權限: 3: 使用者
      看到選單列: 5: 使用者
    section 日常使用
      擷取視窗: 5: 使用者
      分享連結: 5: 使用者

疑難排解決策樹——用 Mermaid 流程圖處理常見問題，取代平淡的表格：

flowchart TD
    A[問題？] --> B{擷取畫面是黑的？}
    B -->|是| C[檢查「螢幕錄製」權限]
    B -->|否| D{快捷鍵沒反應？}
    D -->|是| E[檢查是否有快捷鍵衝突]

規則 4：SVG 檔案務必產生

當 README 引用了一個 SVG 檔案（./hero.svg、./gauge.svg 等）時，你必須實際建立該檔案並將其與 README 一起儲存。在 GitHub 上引用一個不存在的檔案會產生破圖——這比完全沒有圖片更糟糕。

如果你在 README 中引用了 ./performance-gauge.svg，請建立含有可運行動畫內容的實際 SVG 檔案。如果建立了深色/淺色變體（hero-dark.svg、hero-light.svg），則兩個檔案都必須建立。沒有例外。

規則 5：尊重原始內容的視覺選擇

如果原始 README 已經使用了一個強烈的視覺模式（引用卡片、HTML 表格網格、Unicode 進度條），除非你的版本明顯更好，否則不要將其替換為功能相同的不同模式。強化既有內容，而不是用一個水平變動來取代。

例如，如果原始內容使用以下模式來呈現功能：

> **✂️ 捲動截圖**
>
> 將整個頁面擷取為一張圖片。拼接在裝置上完成，在你同意之前不會上傳任何內容。

請保留它。不要將其轉換為 Markdown 表格行——引用版本在視覺上更突出。相反地，請增強其周圍的上下文：在其上方加上一個 capsule-render 章節分隔線，在功能描述後方加上一個視覺比較表，在下方加上一個使用者旅程圖。

---

如何處理任何 README 任務

理解輸入

現有程式碼庫 / 儲存庫——探索專案結構，閱讀關鍵檔案，並推斷其目的、技術棧、架構和目標受眾。

要改進的現有 README——徹底閱讀。識別哪些已經很好（保留它們）。識別哪些過時或缺失（修正它們）。你的附加價值來自：動畫橫幅、SVG 數據可視化、新的創意區塊（使用情境、前後對比、比較表），以及多樣的 Mermaid 圖表。而不是重新格式化已經運作良好的內容。

使用者描述——必要時提出有目標性的問題，然後生成完整的 README。

確定專案類型

專案類型	視覺優先級
行動應用	螢幕截圖、裝置模型圖、應用程式商店徽章、旅程圖
後端服務	架構序列圖、API 流程、部署徽章、效能儀表板
SDK / 函式庫	程式碼範例英雄、API 表格、套件管理器徽章、基準 SVG 圖表
AI/ML 專案	指標 SVG 儀表板、基準長條圖、訓練管線圖
CLI 工具	終端機 SVG 模型圖、命令參考、安裝矩陣
網頁應用	即時示範徽章、螢幕截圖、技術棧徽章、組合餅圖

處理大型 / 複雜專案

對於程式碼庫龐大（10k+ LOC、多個模組、大量測試套件）的專案：

• 驗證所有數字。 加總元件的 LOC 數，並驗證它們是否與陳述的總數相符。如果不符合，請加上備註說明差距（例如：「剩餘 LOC 包含生成的程式碼、測試治具和設定檔案」）。
• 添加摘要統計。 在詳細的細分之後，加上一個高層級摘要：「3 層，11 個服務，5 個畫面。」
• 積極使用可折疊區塊。 大型專案有許多細節。將深入內容（類別圖、檔案樹、API 參考）包裝在 <details> 區塊中。主要流程應能在 30 秒內掃讀完畢。
• 建立一個視覺統計儀表板。 對於擁有豐富數據（測試數量、覆蓋率、LOC）的專案，建立一個帶有動畫儀表板的 SVG，顯示 2-3 個關鍵指標。

---

視覺工具包

這些是沒有商量餘地的。每個 README 都必須使用它們。

1. 動畫漸層橫幅

在頁首和頁尾使用 capsule-render：

頁首：

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

頁尾：

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

根據專案的識別調整 customColorList。

2. 自訂 SVG 素材

每個 README 至少建立一個 .svg 檔案。選擇適合專案的類型：

• 效能儀表板——顯示關鍵指標（速度、覆蓋率、準確度）的動畫弧線
• 終端機模型圖——類似終端機應用程式視窗並帶有命令與輸出的自訂 SVG
• 基準長條圖——比較此專案與替代方案的動畫成長長條圖
• 附帶深色/淺色變體的英雄圖——透過 <picture> 實現主題感知渲染

有關完整的可供複製貼上的 SVG 程式碼，請參閱 references/visual-patterns.md。

記住規則 4：如果你引用了它，就必須建立它。

3. 功能展示——選擇最佳格式

對於 3-6 個功能： 使用帶有 emoji 圖示和簡短描述的 HTML 表格網格：

<table>
<tr>
<td align="center" width="33%">

### ⚡ 閃電般快速
次毫秒啟動。無執行時期開銷。

</td>
<td align="center" width="33%">

### 🔄 即時重新載入
檔案變更時自動重新整理。零設定。

</td>
<td align="center" width="33%">

### 🌐 內建 CORS
開箱即用，跨域就緒。

</td>
</tr>
</table>

對於 8 個以上的詳細功能： 在兩欄 HTML 表格中使用引用卡片。這能更好地擴展以容納豐富的功能描述：

<table>
<tr>
<td width="50%" valign="top">

> **📸 功能名稱**
>
> 帶有技術細節的詳細描述。以效益為導向——解釋為什麼這很重要，而不只是它是什麼。

> **✂️ 另一個功能**
>
> 更多細節在此。

</td>
<td width="50%" valign="top">

> **🔗 第三個功能**
>
> 描述。

</td>
</tr>
</table>

絕不使用純項目符號清單來列出功能。 那是懶惰 README 的首要標誌。

4. Mermaid 圖表——至少兩種不同類型

超越基本的流程圖。從 pie、gantt、journey、sequenceDiagram、stateDiagram、mindmap、timeline、classDiagram、gitGraph 中至少選擇兩種。

選擇能提供真正洞察的圖表類型：

• pie → 程式碼組成、測試分佈、預算細分
• gantt / timeline → 路線圖（取代無聊的核取方塊清單）
• journey → 帶有滿意度分數的使用者體驗流程
• sequenceDiagram → API 流程、架構互動
• mindmap → 設計決策、技術棧總覽
• stateDiagram → 生命週期、狀態機、工作流程

5. Unicode 視覺元素

用於不值得另外製作 SVG 的內聯數據：

覆蓋率    ███████░░░  71%
測試數    ██████████  412 通過
記憶體    ████░░░░░░  24 MB

與表格一起使用，而不是取代表格。非常適合覆蓋率細分、效能比較和語言完成百分比。

6. for-the-badge 風格導航 CTA

<p align="center">
  <a href="#-quick-start"><img src="https://img.shields.io/badge/⚡_Quick_Start-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-features"><img src="https://img.shields.io/badge/✨_Features-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-benchmarks"><img src="https://img.shields.io/badge/📊_Benchmarks-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

這些取代了傳統的目錄——不要兩者都用。

7. 可折疊區塊

將次要內容包裹在 <details> 區塊中：安裝變體、進階設定、完整的 API 文件、專案結構樹、疑難排解。主要流程應能在 30 秒內掃讀完畢。

8. 帶有視覺指標的資料表格

| 功能 | 本專案 | 替代方案 A | 替代方案 B |
|:---|:---:|:---:|:---:|
| 功能 X | ✅ | ❌ | ⚠️ |

README 結構

根據專案調整。並非每個章節都適用，但視覺元素是沒有商量餘地的。

 1. 動畫頁首橫幅（capsule-render）

 2. 置中英雄區
    - 帶有 emoji 的標題
    - 標語
    - for-the-badge 導航 CTA（這些取代了目錄）
    - 元資料徽章（版本、CI、授權、平台）

 3. 價值主張（2-3 句——為什麼存在）

 4. 功能（HTML 網格或引用卡片——絕非項目符號清單）

 5. 快速入門（編號 emoji 步驟 1️⃣ 2️⃣ 3️⃣，附帶預期輸出）

 6. 真實世界使用情境（創意情境——參見規則 3）

 7. 基準測試 / 資料（SVG 儀表板 + Unicode 條 + 比較表 ✅❌）

 ...