專案背景產生器
建立或更新 .claude/docs/project.md — 這是每次對話中 Claude 都會載入的精簡專案參考文件。與為人類撰寫的 README 不同,project.md 是為 Claude 撰寫的:內容密集、事實性強、無行銷用語。
為何需要此技能
.claude/docs/project.md 會透過 CLAUDE.md 自動載入每一次 Claude 對話中。當檔案遺失或過時時,Claude 會浪費多次對話來重新發現技術棧、測試指令和架構。此技能自動化此發現過程,並產生一個緊湊且準確的參考檔案。
工作流程
步驟 1:分析程式碼庫
執行結構化的三階段分析以收集專案事實。每個事實都標記一個信心等級:[confirmed](從原始碼讀取)、[inferred-high](強力證據)、[inferred-low](部分證據)或 [unknown]。
有關詳細的工具動作、glob/grep 模式和記錄範本,請參閱 references/analysis-methodology.md。
第一階段 — 專案元數據: 使用 glob 搜尋套件管理器檔案、環境變數範本、CI 配置和工具鏈檔案。提取:專案名稱、語言、Python 版本、相依套件(附用途)、指令碼/命令、環境變數、CI 階段、測試標記。
第二階段 — 架構掃描: 使用 glob 搜尋所有原始碼檔案。識別入口點、建立匯入圖、分類模組(核心/葉子/協調器),並識別架構模式。讀取原始碼引用的配置檔案。
第三階段 — 資料來源與基礎設施: 識別外部資料來源(資料庫、API、檔案)、輸出目標(檔案、上傳、API)、測試結構和自訂例外層級。
步驟 2:提出澄清問題
分析後,針對 [inferred-low] 和 [unknown] 的項目向使用者提問。保持專注 — 不要問你已經知道的事情。常見缺口:
- 專案目的:這個專案解決什麼問題?(如果程式碼無法清楚表達)
- 資料來源:哪些系統提供資料?哪些系統接收輸出?
- 部署:這個專案如何在何處執行?(本機、排程、雲端)
如果程式碼庫很簡單,你可能只需要問 1-2 個問題 — 或甚至不需要。
步驟 3:產生 project.md
使用以下結構撰寫檔案。如果 .claude/docs/project.md 已存在,覆寫前需先取得使用者確認。
輸出結構
產生的 project.md 必須遵循此結構。根據專案規模調整深度 — 小型專案可以略過部分章節,複雜的專案可以新增小節。
# {專案名稱} — 專案背景
{一句話描述:它是什麼、做什麼、關鍵技術。}
## 技術棧
- **{語言/執行環境}** — {已知的版本限制}
- **{框架}** — {用途}
- **{關鍵套件}** — {用途}
- ...項目符號列表,工具名稱加粗,註明用途
## 專案佈局
```text
{帶說明的目錄樹 — 每個條目一句短語}
```
資料流程
{顯示來源 → 轉換 → 輸出管線的 ASCII 圖表}
資料來源
{來源名稱}— {提供的內容}- ...針對資料庫、API、本機檔案等
測試標記
{測試指令}— {執行的內容}{標記名稱}— {控制的內容}
關鍵架構模式
- {模式名稱}(
{檔案}):{一句話解釋} - ...僅列出值得說明的非顯而易見的模式
撰寫指南
- 密集勝於冗長。 每行都應有存在的價值。Claude 不需要動機或背景設定 — 只需要事實。
- 具體勝於籠統。 「執行
uv run pytest -m 'not snowflake'」優於「執行排除外部相依的測試」。 - 每個模式一句話。 架構模式應一行說明 — 名稱、檔案、解釋。
- 真實指令。 從
pyproject.toml或 CI 配置複製測試指令,而非改寫版本。 - 標註相依套件。 不要只列出
polars— 要寫polars — 高效能 DataFrame。 - 資料來源至關重要。 Claude 需要知道有哪些外部系統。列出每個資料庫、API 和檔案來源。
- 保持在 100 行以內。 如果 project.md 內容超過約 100 行,表示太詳細了 — 將具體細節移至專用文件並提供連結。
輸出
將檔案儲存為 .claude/docs/project.md(必要時建立目錄)。如果檔案已存在,覆寫前向使用者顯示差異摘要。
產生 project.md 後,檢查 CLAUDE.md 是否有引用它。如果沒有,建議加入類似以下的行:
有關專案特定詳細資訊(技術棧、架構、測試標記),請參閱 [.claude/docs/project.md](.claude/docs/project.md)。