SKILL.md
readonlyread-only
name
claude-md-improver
description
稽核並改善儲存庫中的 CLAUDE.md 檔案。當使用者要求檢查、稽核、更新、改善或修復 CLAUDE.md 檔案時使用。掃描所有 CLAUDE.md 檔案，根據範本評估品質，輸出品質報告，然後進行有針對性的更新。當使用者提到「CLAUDE.md 維護」或「專案記憶體最佳化」時也適用。
CLAUDE.md 改善工具
稽核、評估並改善程式碼庫中的 CLAUDE.md 檔案，確保 Claude Code 擁有最佳的專案背景資訊。
此技能可以寫入 CLAUDE.md 檔案。 在呈現品質報告並獲得使用者核准後，它會以有針對性的改善來更新 CLAUDE.md 檔案。
工作流程
階段 1：探索
找出儲存庫中所有的 CLAUDE.md 檔案：
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
檔案類型與位置：
| 類型 | 位置 | 用途 |
|---|---|---|
| 專案根目錄 | ./CLAUDE.md |
主要專案背景資訊（簽入 git，與團隊共享） |
| 本機覆蓋 | ./.claude.local.md |
個人/本機設定（已加入 gitignore，不共享） |
| 全域預設 | ~/.claude/CLAUDE.md |
跨所有專案的使用者全域預設 |
| 套件特定 | ./packages/*/CLAUDE.md |
單一儲存庫中的模組層級背景資訊 |
| 子目錄 | 任何巢狀位置 | 功能/領域特定背景資訊 |
注意： Claude 會自動探索父目錄中的 CLAUDE.md 檔案，讓單一儲存庫設定自動生效。
階段 2：品質評估
針對每個 CLAUDE.md 檔案，根據品質標準進行評估。詳細評分標準請參閱 references/quality-criteria.md。
快速評估檢查清單：
| 標準 | 權重 | 檢查項目 |
|---|---|---|
| 命令/工作流程已記錄 | 高 | 是否包含建置、測試、部署命令？ |
| 架構清晰度 | 高 | Claude 能否理解程式碼庫結構？ |
| 非顯而易見的模式 | 中 | 是否記錄了陷阱與特殊之處？ |
| 簡潔性 | 中 | 沒有冗長的解釋或顯而易見的資訊？ |
| 時效性 | 高 | 是否反映當前程式碼庫狀態？ |
| 可操作性 | 高 | 指示是否可執行，而非模糊？ |
品質分數：
- A (90-100)：全面、即時、可操作
- B (70-89)：涵蓋良好，有少量缺口
- C (50-69)：基本資訊，缺少關鍵章節
- D (30-49)：稀疏或過時
- F (0-29)：缺失或嚴重過時
階段 3：輸出品質報告
在進行任何更新之前，務必先輸出品質報告。
格式：
## CLAUDE.md 品質報告
### 摘要
- 找到的檔案數：X
- 平均分數：X/100
- 需要更新的檔案數：X
### 逐檔案評估
#### 1. ./CLAUDE.md（專案根目錄）
**分數：XX/100（等級：X）**
| 標準 | 分數 | 備註 |
|-----------|-------|-------|
| 命令/工作流程 | X/20 | ... |
| 架構清晰度 | X/20 | ... |
| 非顯而易見的模式 | X/15 | ... |
| 簡潔性 | X/15 | ... |
| 時效性 | X/15 | ... |
| 可操作性 | X/15 | ... |
**問題：**
- [列出具體問題]
**建議新增：**
- [列出應新增的內容]
#### 2. ./packages/api/CLAUDE.md（套件特定）
...
階段 4：有針對性的更新
在輸出品質報告後，請在使用者確認後再進行更新。
更新指南（關鍵）：
-
僅提議有針對性的新增 - 專注於真正有用的資訊：
- 分析過程中發現的命令或工作流程
- 在程式碼中發現的陷阱或非顯而易見的模式
- 不明確的套件關係
- 有效的測試方法
- 設定上的特殊之處
-
保持最小化 - 避免：
- 重述程式碼中顯而易見的內容
- 已涵蓋的通用最佳實務
- 不太可能重現的一次性修正
- 冗長的解釋（一行就夠時）
-
顯示差異 - 針對每個變更，顯示：
- 要更新的 CLAUDE.md 檔案
- 具體的新增內容（以 diff 或引用區塊呈現）
- 簡短說明為何這有助於未來的工作階段
Diff 格式：
### 更新：./CLAUDE.md
**原因：** 缺少建置命令，導致不清楚如何執行專案。
```diff
+ ## 快速開始
+
+ ```bash
+ npm install
+ npm run dev # 在連接埠 3000 啟動開發伺服器
+ ```
#### 階段 5：套用更新
在使用者核准後，使用 Edit 工具套用變更。保留現有內容結構。
### 範本
各專案類型的 CLAUDE.md 範本請參閱 [references/templates.md](references/templates.md)。
### 常見需標記的問題
1. **過時的命令**：不再運作的建置命令
2. **缺少相依性**：未提及的必要工具
3. **過時的架構**：已變更的檔案結構
4. **缺少環境設定**：必要的環境變數或設定
5. **損壞的測試命令**：已變更的測試腳本
6. **未記錄的陷阱**：未捕捉的非顯而易見模式
### 要分享的使用者提示
在提出建議時，提醒使用者：
- **`#` 鍵快捷鍵**：在 Claude 工作階段中，按下 `#` 讓 Claude 自動將學習內容納入 CLAUDE.md
- **保持簡潔**：CLAUDE.md 應易於閱讀；精簡勝於冗長
- **可操作的命令**：所有記錄的命令應可直接複製貼上
- **使用 `.claude.local.md`**：用於不與團隊共享的個人偏好（加入 `.gitignore`）
- **全域預設**：將使用者全域偏好放在 `~/.claude/CLAUDE.md`
### 優秀 CLAUDE.md 的要素
**關鍵原則：**
- 簡潔且易於閱讀
- 可複製貼上的可操作命令
- 專案特定模式，而非通用建議
- 非顯而易見的陷阱與警告
**建議章節**（僅使用相關部分）：
- 命令（建置、測試、開發、lint）
- 架構（目錄結構）
- 關鍵檔案（進入點、設定）
- 程式碼風格（專案慣例）
- 環境（必要變數、設定）
- 測試（命令、模式）
- 陷阱（特殊之處、常見錯誤）
- 工作流程（何時做什麼）
