ReddRadar
Agent skill
methodology-writing
方法論撰寫指南。Use for: (1) 撰寫新方法論, (2) 改寫冗長的舊方法論, (3) 檢查方法論品質
Install this agent skill to your Project
npx add-skill https://github.com/tarrragon/claude/tree/main/skills/methodology-writing
SKILL.md
方法論撰寫指南
核心原則
原則一：讀者是專家
讀者已經知道方法論內容，只是忘記細節。
你的任務：幫讀者找回記憶，不是教導或說服。
禁止：
- 「這不是 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 到其他方法論
禁止模式
模式一：反向定義
❌ 禁止
### 註解不是什麼
- 不是程式碼解釋器
- 不是 API 文件
- 不是 TODO 列表
✅ 直接說
### 核心概念
註解是需求保護器，記錄業務決策和修改約束。
模式二：重複對比
❌ 禁止（同概念講 4 次）
2.3: 選擇1 vs 選擇2
2.4: 對比表
3.3: 詳細對比
3.5: 對比總結
✅ 直接說
## Sociable vs Solitary
| 面向 | Sociable | Solitary |
|-----|----------|----------|
| Unit | Module | Class |
| Mock | 外部依賴 | 所有協作者 |
模式三：過度範例
❌ 禁止（每個規則都有完整範例）
規則一範例：20 行程式碼
規則二範例：25 行程式碼
規則三範例：15 行程式碼
✅ 直接說
## 執行步驟
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: 執行拆分
- 建立衛星文件：從主文件提取章節
- 精簡主文件：刪除已拆分章節，加入導航連結
- 更新引用者：按遷移計劃更新所有連結
- 驗證：確認所有引用有效
改寫驗證檢查清單
- 已搜尋所有引用者
- 引用遷移計劃已建立
- 衛星文件已建立（如需要）
- SKILL 已建立（如需要）
- 主文件已精簡
- 所有引用者已更新
- 所有引用有效（無斷連）
改寫後整合評估
觸發條件：完成 2 個以上方法論改寫後（批量改寫必須執行）
重疊檢測
檢查項目：
| 檢查項目 | 問題 | 判斷標準 |
|---|---|---|
| 主題重疊 | 多個方法論講同一件事？ | 核心概念相似度 > 70% |
| 職責模糊 | 讀者會困惑該看哪個？ | 使用場景無法區分 |
| 內容重複 | 相同檢查清單或步驟？ | 步驟重複 > 50% |
處理決策
| 情況 | 處理 | 範例 |
|---|---|---|
| 完全重疊 | 刪除其一，更新引用 | A 和 B 講同一件事 → 刪除 B |
| 部分重疊 | 合併為一，各自精簡 | A 有 80% 和 B 重疊 → 合併 |
| 互補關係 | 保留，加入交叉引用 | A 講概念，B 講實作 → 互相 reference |
| 無重疊 | 維持現狀 | 各自獨立 |
整合執行步驟
- 列出所有改寫後的方法論
- 兩兩比較核心概念：相似 → 標記
- 檢查使用場景：相同場景 → 合併候選
- 決策：刪除 / 合併 / 交叉引用 / 維持
- 執行整合：更新所有引用
- 驗證無斷連
整合檢查清單
- 已列出所有改寫後的方法論
- 已完成兩兩重疊比較
- 重疊方法論已處理（刪除/合併/交叉引用）
- 所有引用已更新
- 無斷連驗證通過
Reference
改寫範例
- 完整改寫範例 - error-fix-refactor-methodology.md 改寫前後對比
相關方法論
- 方法論改寫方法論 - 改寫流程（30 秒版）
- 方法論撰寫方法論 - 撰寫新方法論
- Atomic Ticket 方法論 - 精簡範本參考
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
tarrragon/claude
skill-design-guide
Use this skill when creating a new skill, updating an existing skill's YAML frontmatter, or reviewing skill quality. Provides the official Anthropic skill specification, frontmatter rules, description writing best practices, progressive disclosure architecture, and common pitfalls to avoid. Triggers include: creating skills, skill review, frontmatter validation, SKILL.md writing.
tarrragon/claude
test-async-guardian
Flutter/Dart 測試異步資源管理守護者。用於：(1) 診斷測試卡住問題，(2) 審查測試程式碼中的異步資源清理，(3) 提供 tearDown 最佳實踐，(4) 掃描潛在的資源洩漏風險。觸發場景：測試卡住、撰寫新測試、Code Review 測試程式碼、執行 flutter test 前自動掃描。
tarrragon/claude
agent-team
Agent Teams 協作派發指南。Use when: (1) Agent A 的發現會改變 Agent B 正在進行的工作, (2) 用戶要求使用 team/swarm, (3) 多代理人需即時協商共用介面或 API 契約。涵蓋 team 建立、Ticket-Task 橋接、teammate 入職、生命週期管理。
tarrragon/claude
tdd
TDD 全流程指導工具。Use for: (1) 開始新功能的 TDD 流程（Phase 0-4）, (2) 推進到下一個 TDD 階段, (3) Phase 1 SOLID 原則驅動功能拆分分析, (4) 查看當前 TDD 進度和階段狀態, (5) 評估是否需要 Phase 4 重構以及 3b 拆分評估。Use when: 開始新功能開發、進入任何 TDD Phase、需要 SOLID 拆分指導、需要確認當前所在 TDD 階段、需要做 Phase 4 豁免判斷時。
tarrragon/claude
branch-worktree-guardian
Branch Worktree Guardian - Git 分支和 Worktree 管理工具。Use for: (1) 新開發需求時建立隔離分支, (2) 使用 worktree 機制避免分支衝突, (3) 驗證當前工作分支正確性, (4) 預防在錯誤分支上開發
tarrragon/claude
design-decision-framework
多方案評估決策框架。用於面臨 3+ 技術方案時的結構化評估、架構決策時的系統化分析，防止衝動決策和技術債務累積。Use for: 技術方案選擇、重大架構決策、高風險技術選型
Didn't find tool you were looking for?