CLAUDE.md 產生器
讀取程式碼庫。撰寫一份恰如其分、只告訴 Claude 所需資訊的 CLAUDE.md。
關鍵規則： 好的 CLAUDE.md 應少於 100 行。只包含 Claude 無法從閱讀程式碼本身推斷出的資訊。請勿自動寫入檔案：務必先顯示草稿，等待使用者核准。
程式碼片段規則： 絕對不要在 CLAUDE.md 中包含行內程式碼範例。請改用 file.ts:42 的引用方式。CLAUDE.md 中的程式碼會浪費 token 且容易過期。
步驟 1：偵測模式
判斷要執行哪一種模式：
create：無 CLAUDE.md 存在。從頭撰寫一份。 update：CLAUDE.md 已存在。在不丟棄自訂內容的前提下改進它。 audit：為專案中所有 CLAUDE.md 檔案評分（A-F）並產出品質報告。如果使用者說「稽核」、「檢查」、「審查」或「評分」我的 CLAUDE.md，則執行稽核模式。
# 找出所有 CLAUDE.md 的位置
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "找到全域 CLAUDE.md"
ls .claude.local.md 2>/dev/null && echo "找到 .claude.local.md"
如果找到多個 CLAUDE.md：列出它們。詢問：「在 [位置] 找到 CLAUDE.md。我應該全部更新，還是只更新 [根目錄]？」
步驟 2：稽核模式（若為建立/更新則跳至步驟 3）
針對每個找到的 CLAUDE.md，使用下列評分標準評分（A-F）：
| 標準 | 檢查項目 |
|---|---|
| 指令 | 建置/測試/lint 指令是否存在且可執行？ |
| 架構 | 是否說明了非顯而易見的結構？ |
| 非顯而易見的模式 | 是否記錄了注意事項、自動產生檔案、環境變數順序？ |
| 簡潔性 | 少於 100 行？沒有明顯的填充內容？ |
| 時效性 | 指令是否仍與目前的 package.json/Makefile 相符？ |
| 可操作性 | 新貢獻者是否能在不發問的情況下依此操作？ |
分數：90-100 = A，70-89 = B，50-69 = C，30-49 = D，0-29 = F
以表格呈現：
## CLAUDE.md 稽核報告
| 檔案 | 分數 | 等級 | 主要問題 |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | 缺少注意事項區段，測試指令過時 |
| ./packages/api/CLAUDE.md | 45 | D | 無指令，340 行（太長），過時的架構筆記 |
**總體：B (72/100)**
發現的問題：
- ./packages/api/CLAUDE.md：340 行：遠超過 100 行目標
- ./packages/api/CLAUDE.md：測試指令參考 `jest`，但 package.json 使用 `vitest`
- ./CLAUDE.md：缺少注意事項區段：最有價值的區段遺失了
報告結束後，詢問：「要我修復其中任何一個嗎？（全部 / 僅根目錄 / 指定）」
如果使用者說「是」，針對他們想要修復的每個檔案，繼續執行步驟 3。
步驟 3：掃描專案結構
# 專案類型和套件管理器
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# 頂層目錄結構
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
步驟 4：提取建置和測試指令
# npm/yarn/pnpm/bun 腳本
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Python、Go、Rust Makefile
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
識別出下列項目的確切指令：建置、測試（全部）、測試（單一檔案/名稱）、開發伺服器、lint/型別檢查。注意執行它們所需的任何環境變數。
步驟 5：尋找程式碼風格與注意事項
# 匯入別名（最常被忽略）
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('匯入別名:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# 所需的環境變數
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# 自動產生的檔案（禁止編輯）
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
| xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5
# 測試設定需求
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# 資料庫/遷移設定
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
構成注意事項的項目（包含這些，跳過其他所有項目）：
- 自動產生的檔案（禁止編輯）
- 測試執行前所需的環境變數
- 非預設的匯入別名對應
- 需要執行中服務的測試指令
- 已知的刻意怪癖（因應措施，非錯誤）
步驟 6：使用 Gemini 產生 CLAUDE.md 草稿
彙整所有發現，產生草稿：
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "為一個軟體專案撰寫 CLAUDE.md 檔案。規則：(1) 總行數少於 100。 (2) 只包含 Claude 無法從閱讀程式碼推斷的內容。 (3) 無行內程式碼範例：改用 file.ts:42 的引用方式。 (4) 區段：指令、程式碼風格（僅非預設項目）、測試（僅需設定時）、注意事項（必要：最易出錯之處）。若某區段沒有任何非顯而易見的內容可寫，則跳過。 (5) 所有指令放在程式碼區塊中。 (6) 建議順序：簡短專案概述（1-2 句，僅在非顯而易見時）、指令、架構（僅非顯而易見的結構）、程式碼風格、測試、注意事項。 (7) 不要使用 em dash。 (8) 只輸出 CLAUDE.md 內容，無註解。"
}]
},
"contents": [{
"parts": [{
"text": "PROJECT_ANALYSIS_HERE"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
將 PROJECT_ANALYSIS_HERE 替換為步驟 3-5 的發現。
對於大型專案（50 個以上檔案）： 在 CLAUDE.md 底部加入 @path 指標，而非行內細節：
## 延伸參考
詳見 @docs/ai-context/architecture.md 取得完整的模組對應。
詳見 @docs/ai-context/testing.md 取得整合測試設定細節。
將無法容納於 100 行內的詳細資訊，寫入 docs/ai-context/ 的參考檔案中。
步驟 7：自我品質確認
在呈現草稿前，檢查：
- 少於 100 行（計數：
echo "$CONTENT" | wc -l） - 無行內程式碼範例（僅有
file.ts:42引用或 shell 指令） - 所有指令放在程式碼區塊中，且可直接執行
- 注意事項區段存在，且至少包含一個真實條目
- 沒有僅包含從檔案中即可明顯看出之內容的區段
- 沒有 em dash
- 沒有行銷用語或填充詞句（「此專案使用 React 來...」）
- 若存在匯入別名，則已記錄
- 若存在自動產生的檔案，則已標示「禁止編輯」
如有任何檢查未通過，請先修正再呈現。
步驟 8：呈現草稿並等待核准
未經使用者核准，絕不寫入檔案。
將草稿呈現在程式碼區塊中：
## CLAUDE.md 草稿（[N] 行）
[完整草稿內容於此]
---
是否寫入 CLAUDE.md？（yes / edit first / cancel）
如果使用者說 yes：寫入檔案，然後確認：「CLAUDE.md 已寫入（[N] 行）。區段：[列出所有 ## 標頭]。」
如果使用者說 edit first：套用他們的編輯，重新顯示草稿。
如果使用者說 cancel：停止。
不要包含的內容
- 語言/框架版本（「這是一個 TypeScript 專案」）
- 框架如何運作（Claude 已經知道 React、FastAPI 等）
- 所有依賴項的清單
- lint 工具已強制執行的風格規則（縮排大小、引號風格）
- 與 README.md 重複的內容
- 行內程式碼範例或多行程式碼片段
- 任何使用相同技術棧的專案都會相同的內容