methodology-writing

name	methodology-writing
description	方法論撰寫指南。Use for: (1) 撰寫新方法論, (2) 改寫冗長的舊方法論, (3) 檢查方法論品質

方法論撰寫指南

核心原則

原則一：讀者是專家

讀者已經知道方法論內容，只是忘記細節。

你的任務：幫讀者找回記憶，不是教導或說服。

禁止：

• 「這不是 XXX」反向定義
• 無關的術語和譬喻
• 說服性論述

原則二：30 秒電梯理論

一個方法論必須在 30 秒內可讀完。

超出部分 → reference 到其他方法論或 SKILL

專注於：檢查和複習，不是完整說明

原則三：SKILL vs 方法論區分

類型	定位	內容
SKILL	完整實作指南	設計邏輯、實作細節、範例、錯誤處理
方法論	30 秒快速複習	核心概念、檢查清單、reference 連結

---

方法論標準結構

# [方法論名稱]

## 核心概念
[1-2 句話定義]

## 執行步驟
1. [步驟]
2. [步驟]
3. [步驟]

## 檢查清單
- [ ] [檢查項]
- [ ] [檢查項]

## Reference
- [相關方法論]

層級限制：最多 H1 → H2 → H3，禁止 H4 以下

---

精簡技巧

刪除什麼

刪除對象	理由
「XXX 不是什麼」	讀者知道，不需要提醒
重複的範例	保留 1 個代表性範例
反模式章節	已在正向規則中說明
冗長的背景說明	讀者是專家
空洞的結論	沒有新資訊

保留什麼

保留對象	理由
核心定義（1-2 句）	快速回憶
執行步驟（3-5 步）	可操作
檢查清單	驗證完成度
Reference 連結	深入查閱

何時 Reference 出去

• 範例程式碼超過 10 行 → reference 到 SKILL
• 理論背景 → reference 到外部文獻
• 相關流程 → reference 到其他方法論

---

禁止模式

模式一：反向定義

[FAIL] 禁止
### 註解不是什麼
- 不是程式碼解釋器
- 不是 API 文件
- 不是 TODO 列表

[OK] 直接說
### 核心概念
註解是需求保護器，記錄業務決策和修改約束。

模式二：重複對比

[FAIL] 禁止（同概念講 4 次）
2.3: 選擇1 vs 選擇2
2.4: 對比表
3.3: 詳細對比
3.5: 對比總結

[OK] 直接說
## Sociable vs Solitary
| 面向 | Sociable | Solitary |
|-----|----------|----------|
| Unit | Module | Class |
| Mock | 外部依賴 | 所有協作者 |

模式三：過度範例

[FAIL] 禁止（每個規則都有完整範例）
規則一範例：20 行程式碼
規則二範例：25 行程式碼
規則三範例：15 行程式碼

[OK] 直接說
## 執行步驟
1. 判斷錯誤類型
2. 程式錯誤 → 改程式
3. 架構變更 → 先更新文件

詳細範例見 [SKILL 名稱](./path/to/skill.md)

---

改寫檢查清單

結構檢查

• 標題層級 ≤ 3 層（H1-H3）
• 有「核心概念」章節
• 有「執行步驟」章節
• 有「檢查清單」章節
• 有「Reference」章節

內容檢查

• 無「XXX 不是什麼」反向定義
• 無重複的對比表格
• 無超過 10 行的程式碼範例
• 無空洞的結論章節
• 無冗長的背景說明

可讀性檢查

• 30 秒內可讀完
• 專業術語無需解釋
• 檢查清單可直接使用

---

改寫指南

改寫舊方法論時，除了精簡內容，還需處理「引用完整性」。

Step 1: 分析被引用情況

# 搜尋所有引用該方法論的文件
grep -r "方法論檔名" .claude/

建立「引用→章節」對照表：

引用者	引用次數	實際引用內容
file-a.md	3 次	第二章五層定義
file-b.md	1 次	第六章檢查機制

Step 2: 拆分決策

拆分標準：

條件	決策
章節可完全獨立	拆分為衛星文件
章節有高複用性	拆分為獨立方法論
章節是核心定義	保留在主文件
章節是範例/FAQ	拆分或刪除

是否需要 SKILL：

• 有完整操作流程 → 建立 SKILL
• 有程式碼範例 → 移到 SKILL
• 只有概念說明 → 不需要 SKILL

Step 3: 建立引用遷移計劃

對每個引用者判斷：

| 引用者 | 原引用 | 新引用 | 動作 |
|-------|-------|-------|-----|
| file-a.md | 主文件 | 主文件 | 不變 |
| file-b.md | 主文件 | 衛星文件 | 更新 |
| file-c.md | 主文件 | 主文件 + 衛星 | 更新 |

Step 4: 執行拆分

1. 建立衛星文件：從主文件提取章節
2. 精簡主文件：刪除已拆分章節，加入導航連結
3. 更新引用者：按遷移計劃更新所有連結
4. 驗證：確認所有引用有效

改寫驗證檢查清單

• 已搜尋所有引用者
• 引用遷移計劃已建立
• 衛星文件已建立（如需要）
• SKILL 已建立（如需要）
• 主文件已精簡
• 所有引用者已更新
• 所有引用有效（無斷連）

---

改寫後整合評估

觸發條件：完成 2 個以上方法論改寫後（批量改寫必須執行）

重疊檢測

檢查項目：

檢查項目	問題	判斷標準
主題重疊	多個方法論講同一件事？	核心概念相似度 > 70%
職責模糊	讀者會困惑該看哪個？	使用場景無法區分
內容重複	相同檢查清單或步驟？	步驟重複 > 50%

處理決策

情況	處理	範例
完全重疊	刪除其一，更新引用	A 和 B 講同一件事 → 刪除 B
部分重疊	合併為一，各自精簡	A 有 80% 和 B 重疊 → 合併
互補關係	保留，加入交叉引用	A 講概念，B 講實作 → 互相 reference
無重疊	維持現狀	各自獨立

整合執行步驟

1. 列出所有改寫後的方法論
2. 兩兩比較核心概念：相似 → 標記
3. 檢查使用場景：相同場景 → 合併候選
4. 決策：刪除 / 合併 / 交叉引用 / 維持
5. 執行整合：更新所有引用
6. 驗證無斷連

整合檢查清單

• 已列出所有改寫後的方法論
• 已完成兩兩重疊比較
• 重疊方法論已處理（刪除/合併/交叉引用）
• 所有引用已更新
• 無斷連驗證通過

---

Reference

改寫範例

• 完整改寫範例 - error-fix-refactor-methodology.md 改寫前後對比

相關方法論

• 方法論改寫方法論 - 改寫流程（30 秒版）
• 框架元層管理方法論 - SKILL vs 方法論分工、撰寫/改寫檢查清單
• Atomic Ticket 方法論 - 精簡範本參考

---

Last Updated: 2026-03-02 Version: 1.0.0