SKILL.md
唯讀
名稱
agent-md-refactor
描述
重構過於龐大的 AGENTS.md、CLAUDE.md 或類似代理指令檔案，遵循漸進式揭露原則。將單一大型檔案拆分為有組織、相互連結的文件。
Agent MD Refactor
重構過於龐大的代理指令檔案（AGENTS.md、CLAUDE.md、COPILOT.md 等），遵循漸進式揭露原則——將核心內容保留在根目錄，其餘部分組織成有分類且相互連結的檔案。
觸發時機
在以下情況使用此技能：
- 「重構我的 AGENTS.md」/「重構我的 CLAUDE.md」
- 「拆分我的代理指令」
- 「整理我的 CLAUDE.md 檔案」
- 「我的 AGENTS.md 太長了」
- 「為我的指令採用漸進式揭露」
- 「清理我的代理設定」
快速參考
| 階段 | 動作 | 產出 |
|---|---|---|
| 1. 分析 | 找出矛盾 | 待解決衝突清單 |
| 2. 萃取 | 識別核心內容 | 根檔案的核心指令 |
| 3. 分類 | 將其餘指令分組 | 邏輯分類 |
| 4. 結構化 | 建立檔案層級 | 根檔案 + 連結檔案 |
| 5. 刪除標記 | 標記應刪除的內容 | 冗餘/模糊指令 |
流程
階段 1：找出矛盾
識別任何互相衝突的指令。
尋找：
- 矛盾的風格指南（例如「使用分號」vs「不使用分號」）
- 衝突的工作流程指令
- 不相容的工具偏好
- 互斥的模式
針對每個找到的矛盾：
## 發現矛盾
**指令 A：** [引用]
**指令 B：** [引用]
**問題：** 哪一個應優先，或者兩者都應視情況而定？
要求使用者在繼續前先解決。
階段 2：識別核心內容
只萃取屬於根代理檔案的內容。根檔案應保持精簡——適用於每一個任務的資訊。
核心內容（保留在根目錄）：
| 類別 | 範例 |
|---|---|
| 專案描述 | 一句話：「一個用於分析的 React 儀表板」 |
| 套件管理器 | 僅當非 npm 時（例如「使用 pnpm」） |
| 非標準指令 | 自訂建置/測試/型別檢查指令 |
| 關鍵覆寫 | 必須覆寫預設值的項目 |
| 通用規則 | 適用於 100% 的任務 |
非核心（移至連結檔案）：
- 語言特定慣例
- 測試指南
- 程式碼風格細節
- 框架模式
- 文件標準
- Git 工作流程細節
階段 3：將其餘內容分組
將剩餘指令組織成邏輯分類。
常見分類：
| 分類 | 內容 |
|---|---|
typescript.md |
TS 慣例、型別模式、嚴格模式規則 |
testing.md |
測試框架、覆蓋率、模擬模式 |
code-style.md |
格式化、命名、註解、結構 |
git-workflow.md |
提交、分支、PR、審查 |
architecture.md |
模式、資料夾結構、相依性 |
api-design.md |
REST/GraphQL 慣例、錯誤處理 |
security.md |
驗證模式、輸入驗證、機密 |
performance.md |
最佳化規則、快取、懶加載 |
分組規則：
- 每個檔案應針對其主題自成一個完整單元
- 目標為 3-8 個檔案（不過細也不過粗）
- 檔案命名清晰：
{topic}.md - 只包含可操作的指令
階段 4：建立檔案結構
輸出結構：
project-root/
├── CLAUDE.md (或 AGENTS.md) # 精簡的根檔案，包含連結
└── .claude/ # 或 docs/agent-instructions/
├── typescript.md
├── testing.md
├── code-style.md
├── git-workflow.md
└── architecture.md
根檔案範本：
# 專案名稱
專案的一句描述。
## 快速參考
- **套件管理器：** pnpm
- **建置：** `pnpm build`
- **測試：** `pnpm test`
- **型別檢查：** `pnpm typecheck`
## 詳細指令
如需特定指南，請參閱：
- [TypeScript 慣例](.claude/typescript.md)
- [測試指南](.claude/testing.md)
- [程式碼風格](.claude/code-style.md)
- [Git 工作流程](.claude/git-workflow.md)
- [架構模式](.claude/architecture.md)
每個連結檔案的範本：
# {主題} 指南
## 概述
簡要說明這些指南適用的情境。
## 規則
### 規則類別 1
- 具體、可操作的指令
- 另一個具體指令
### 規則類別 2
- 具體、可操作的指令
## 範例
### 良好
\`\`\`typescript
// 正確模式的範例
\`\`\`
### 避免
\`\`\`typescript
// 不應這樣做的範例
\`\`\`
階段 5：標記刪除
識別應完全移除的指令。
刪除條件：
| 條件 | 範例 | 為何刪除 |
|---|---|---|
| 冗餘 | 「使用 TypeScript」（在 .ts 專案中） | 代理已知道 |
| 過於模糊 | 「寫出乾淨的程式碼」 | 無法操作 |
| 過於明顯 | 「不要引入錯誤」 | 浪費上下文 |
| 預設行為 | 「使用描述性變數名稱」 | 標準做法 |
| 過時 | 引用已棄用的 API | 不再適用 |
輸出格式：
## 標記為刪除
| 指令 | 原因 |
|-------------|--------|
| 「寫出乾淨、可維護的程式碼」 | 過於模糊，無法操作 |
| 「使用 TypeScript」 | 冗餘——專案已是 TS |
| 「不要提交機密」 | 代理已知道 |
| 「遵循最佳實踐」 | 沒有具體內容則無意義 |
執行檢查清單
[ ] 階段 1：所有矛盾已識別並解決
[ ] 階段 2：根檔案只包含核心內容
[ ] 階段 3：所有剩餘指令已分類
[ ] 階段 4：已建立檔案結構並包含正確連結
[ ] 階段 5：已移除冗餘/模糊指令
[ ] 驗證：每個連結檔案自成一個完整單元
[ ] 驗證：根檔案少於 50 行
[ ] 驗證：所有連結正確運作
反模式
| 避免 | 原因 | 替代方案 |
|---|---|---|
| 把所有內容留在根目錄 | 龐大、難以維護 | 拆分為連結檔案 |
| 分類過多 | 碎片化 | 合併相關主題 |
| 模糊指令 | 浪費 token，無價值 | 具體說明或刪除 |
| 重複預設值 | 代理已知道 | 只在需要時覆寫 |
| 層級過深 | 難以導航 | 扁平結構搭配連結 |
範例
重構前（龐大的根檔案）
# CLAUDE.md
這是一個 React 專案。
## 程式碼風格
- 使用 2 個空格
- 使用分號
- 優先使用 const 而非 let
- 使用箭頭函式
...（再 200 行）
## 測試
- 使用 Jest
- 覆蓋率 > 80%
...（再 100 行）
## TypeScript
- 啟用嚴格模式
...（再 150 行）
重構後（漸進式揭露）
# CLAUDE.md
即時分析視覺化的 React 儀表板。
## 指令
- `pnpm dev` - 啟動開發伺服器
- `pnpm test` - 執行測試並包含覆蓋率
- `pnpm build` - 生產環境建置
## 指南
- [程式碼風格](.claude/code-style.md)
- [測試](.claude/testing.md)
- [TypeScript](.claude/typescript.md)
驗證
重構後，請驗證：
- 根檔案精簡 - 少於 50 行，只包含通用資訊
- 連結有效 - 所有引用的檔案都存在
- 無矛盾 - 指令一致
- 內容可操作 - 每個指令都具體明確
- 完整覆蓋 - 沒有遺失任何指令（除非標記為刪除）
- 檔案自足 - 每個連結檔案可獨立存在
