README 生成器 是做什麼的?
通過分析實際程式碼庫並提出有針對性的澄清問題,為內部/公司的程式碼儲存庫創建精心打磨、全面的 README.md 檔案。
為何有此技能
一份良好的 README 是程式碼庫的門面。對於內部專案尤其如此,缺失或內容單薄的 README 意味著每個新團隊成員都要花費數小時來弄清楚專案的用途、如何運行以及從何處入手。此技能自動化處理了這項繁重的工作——它會讀取程式碼,推斷出它能理解的資訊,針對無法確定的內容進行提問,然後產出能讓開發者快速上手的 README。
工作流程
步驟 1:分析程式碼庫
在向使用者提問之前,先執行一個結構化的四階段分析,以盡可能多地收集上下文資訊。這能減輕使用者的負擔——他們只需要填補空白,而不是描述你已經能看到的內容。
為每個事實標記置信度級別:[confirmed](從原始碼中讀取)、[inferred-high](強證據)、[inferred-low](部分證據)或 [unknown]。低置信度和未知的發現將成為步驟 2 中的澄清問題。
請參閱 references/analysis-phases.md 以了解詳細的工具操作、grep 模式、提取檢查清單和記錄範本。
階段 1 — 專案中繼資料掃描: 使用 glob 查找套件管理器檔案(pyproject.toml、package.json 等)、環境變數範本、Dockerfile、CI/CD 配置以及工具鏈檔案。讀取每個檔案並提取:專案名稱/版本、語言、依賴項(按用途分類)、腳本/命令、環境變數(必需的與可選的)、CI 階段、授權條款。
階段 2 — 架構掃描: 使用 glob 查找所有原始碼檔案以繪製目錄結構。使用 grep 查找入口點標記(if __name__、main() 等)並讀取每個入口點。通過在所有原始碼檔案中使用 grep 查找導入語句來構建導入圖——將模組分類為核心(高入度)、葉節點或協調器。使用指標檢查清單識別架構模式(pipeline、MVC、layered、microservices、event-driven、CLI、monolith)。使用 grep 查找配置加載模式以找到運行時配置檔案。
階段 3 — 深度模組分析: 讀取每個重要的原始碼檔案(優先級:核心 → 入口點 → 最大 → 其餘)。對於每個檔案,提取:目的(一句話)、帶有簽名的主要匯出、設計說明(不明顯的決策、邊緣情況、慣例)以及內部依賴項。通過導入圖追踪主要工作流程的端到端流程,標記在模組之間流動的數據類型。對於包含 8 個或更多原始碼檔案的程式碼庫,按依賴叢集分派平行子代理。
階段 4 — 支援基礎設施掃描: 使用 glob 查找測試檔案和測試固定資料。讀取每個測試檔案的前 30-50 行,以建立測試到模組的映射。使用 grep 查找自訂異常類別和 raise 語句,以建立錯誤層級結構。掃描範本、資源檔案和現有文件。為疑難排解表格提取常見錯誤場景。
步驟 2:提出澄清問題
分析完成後,針對你無法自信推斷出的資訊向使用者提問。保持問題的針對性——不要問你已經知道的事情。常見的空白包括:
- 專案目的:解決什麼問題?誰在使用它?(如果從程式碼中無法明顯看出)
- 設定陷阱:是否存在不明顯的先決條件、VPN 需求、內部套件註冊表或資料庫設定步驟?
- 關鍵工作流程:開發者對此專案最常做的 2-3 件事是什麼?
- 部署:是如何/在哪裡部署的?(如果從 CI/CD 配置中不清楚)
- 團隊慣例:是否有任何命名慣例、分支策略或需要說明的模式?
- 聯絡資訊:誰擁有/維護此專案?(聯絡人部分的姓名 + 電子郵件)
簡潔地呈現你的問題。如果程式碼庫很直接且你對分析有信心,你可能只需要 1-2 個問題——甚或不需要。請自行判斷。
步驟 3:生成 README.md
使用下面的結構和指南來撰寫 README。
README 結構
以此作為你的範本。包含所有部分,但根據項目的複雜度調整深度。在每個主要部分之間使用 --- 水平線,以營造視覺上的呼吸空間。
# 專案名稱
  
簡短、清晰的描述。使用 **粗體** 強調關鍵技術或產品類型。
---
## 目錄
生成一個詳盡的、嵌套的目錄,其中包含所有 ## 和 ### 標題。將子部分在其父部分下縮排,以便讀者能一目了然地看到完整結構。這對於較長的 README 尤其重要——目錄既是導航工具,也是整份文件的概要。
預期深度的示例:
- [概述](#overview)
- [架構](#architecture)
- [高層次架構](#high-level-architecture)
- [資料夾結構](#folder-structure)
- [模組依賴圖](#module-dependency-graph)
- [入門指南](#getting-started)
- [先決條件](#prerequisites)
- [安裝](#installation)
- [執行測試](#running-tests)
- [環境變數](#environment-variables)
- [使用方式](#usage)
- [示例:主要使用案例](#example-primary-use-case)
- [示例:次要使用案例](#example-secondary-use-case)
- [API 參考](#api-reference)
- [資源 A](#resource-a)
- [資源 B](#resource-b)
- [疑難排解](#troubleshooting)
- [聯絡資訊](#contact)
- [授權條款](#license)
文件中的每個 ### 標題都應作為在其父 ## 標題下的縮排條目出現。不要跳過子部分——詳盡目錄的重點在於讀者可以直接跳轉到文件的任何部分。
---
## 概述
擴展描述。使用**粗體**標記關鍵術語。對多步驟流程使用編號列表。
---
## 架構
### 高層次架構
```mermaid
graph TD
...
```
資料夾結構
project-root/
├── src/ # 簡短註解
├── tests/ # 簡短註解
└── ...
[數據流 / 管道 / 模組依賴 — 額外圖表]
...
入門指南
先決條件
安裝
執行測試
環境變數
| 變數 | 必需 | 描述 |
|---|---|---|
DB_URL | 是 | PostgreSQL 連線字串 |
使用方式
針對 2-3 個最常見操作的實際程式碼範例。
API 參考
疑難排解
| 症狀 | 可能原因 | 修復方式 |
|---|---|---|
錯誤訊息 | 問題何在 | 如何修復 |
聯絡資訊
如有疑問或支援需求,請聯絡:
- 姓名 — [email protected]
授權條款
僅限內部使用 – 公司名稱 專有軟體。© [年份] [公司]。版權所有。
## Shields.io 徽章
總是在 `# 標題` 標題之後直接包含 shields.io 徽章(3-6 個徽章,涵蓋語言、框架、關鍵函式庫、套件管理器、資料庫、基礎設施)。請參閱 [references/badge-reference.md](references/badge-reference.md) 以了解各類別的格式、示例和顏色建議。
## Mermaid 圖表指南
大方地使用 mermaid 圖表——它們能讓架構、數據流和流程立即變得易於理解。一個典型的 README 應該有 **3-6 個圖表**;複雜的專案(數據管線、多服務系統)可能會有 **6-10 個以上**。請參閱 [references/mermaid-guidelines.md](references/mermaid-guidelines.md) 以了解何時使用每種圖表類型、最佳實踐以及專案類型特定的建議。
## 寫作指南
- **具體優於籠統。**「執行 `npm run dev`」勝過「啟動開發伺服器。」請包含實際的命令、檔案路徑和變數名稱。
- **為新團隊成員而寫。** 假設他們具備一般工程技能,但對專案上下文一無所知。
- **在首次提及和概述中,使用粗體標記關鍵術語和產品名稱。** 這有助於讀者掃讀。
- **對順序流程使用編號列表。**「1. **提取**來自 X 的數據。2. **轉換**它。3. **載入**到 Y。」——對動詞使用粗體。
- **程式碼範例應可執行。** 儘可能從實際程式碼庫中複製。
- **環境變數表格是必不可少的。** 列出每一個。
- **表格格式的疑難排解**(症狀 | 可能原因 | 修復方式)——易於掃讀且一致。
- **資料夾結構註解應簡潔。** 每個目錄一個短語。
- **務必包含聯絡資訊部分。** 詢問使用者誰維護此專案。格式:`**姓名** — [email protected]`。
- **在所有主要部分之間使用 `---` 水平線**,以營造視覺結構。
## 輸出
將 README 儲存為儲存庫根目錄下的 `README.md`(如果無法識別儲存庫根目錄,則儲存為當前工作目錄下的 `README.md`)。如果 `README.md` 已存在,請在使用者確認後再進行覆寫——他們可能希望保留部分內容。