Evolve

Skill Creator

完整工作流：引導式訪談 → 分析生成 → 驗證 → Token 優化 → 發布到 GitHub

使用方式

/evolve --new-skill "skill 名稱"

五階段流程

Stage 1: 引導式訪談

向使用者提問，收集需求：

1. 問題定義：這個 skill 要解決什麼問題？ 2. 目標使用者：新手 / 進階 / 專家？ 3. 前置需求：需要什麼 MCP servers 或 CLI tools？ 4. 參考來源：有沒有類似的 skill 可以參考？

輸出：內部需求文件

Stage 2: 分析 + 生成

搜尋順序：

1. 優先搜尋官方 Skill Repos：

• claude-domain-skills — 領域知識 skills
• claude-software-skills — 軟體開發 skills

2. 如無適合，搜尋 GitHub 上其他 skills 3. 如都無適合參考，使用 4C 方法自行研究：

• 載入 methodology/knowledge-acquisition-4c skill（from claude-domain-skills）
• Collect：WebSearch / WebFetch 收集官方文檔、最佳實踐
• Curate：篩選高品質來源，去除噪音
• Contextualize：分析領域核心概念和常見流程
• Codify：整理成 skill 可用的知識結構

生成流程：

4. 選擇適合的範本（basic / advanced） 5. 生成 SKILL.md 初稿 6. 建立目錄結構（如需要 scripts/templates）

輸出：完整的 skill 目錄

Stage 3: 驗證

檢查清單：

• [ ] SKILL.md frontmatter 格式正確
• [ ] 必要欄位存在（name, description, version）
• [ ] 模擬使用情境，確認指令清楚
• [ ] 如有 scripts，確認可執行

輸出：驗證報告

Stage 3.5: Token 優化

使用 skill-optimizer 優化新建立的 skill：

1. 分析 token 效率：

• 檢查總行數（目標 < 300 行）
• 計算核心內容佔比（目標 > 70%）
• 識別可外連的內容（大型範例、ASCII 圖表、模板）

2. 執行優化：

• 大型 ASCII 圖表 → 簡化為單行描述
• 完整範例（> 20 行）→ 外連至 extended/examples.md
• 模板（> 10 行）→ 外連至 extended/templates.md
• 配置範例 → 外連至擴展檔案

3. 建立分層結構（如需要）：

   skill-name/
   ├── SKILL.md           # 核心層 (< 300 行)
   └── extended/          # 擴展層 (按需載入)
       ├── examples.md
       └── templates.md

4. 驗證優化結果：

• 優化前後行數比較
• 確認功能完整性未受影響

輸出：優化報告（節省 X% tokens）

💡 參考：claude-domain-skills/methodology/skill-optimizer

Stage 4: 發布到 GitHub

1. 詢問：建立新 repo 或加入現有 repo？ 2. 生成 README.md 3. git init + commit + push 4. 輸出安裝指令

輸出：

✅ Skill 已發布！

GitHub: https://github.com/<user>/<repo>
安裝: /plugin install <user>/<repo>

範本選擇指南

驗證腳本

./scripts/validate-skill.sh <skill-directory>

發布腳本

./scripts/publish-skill.sh <skill-directory> [--new-repo]

Plugin 格式轉換

將 Skills 倉庫轉換為 Claude Code Plugin Marketplace 格式：

./scripts/convert-to-plugin.sh <skills-repo-path> [--marketplace|--category]

模式：

• --marketplace：建立 marketplace.json，頂層目錄成為 plugin（推薦）
• --category：為每個頂層分類建立獨立的 plugin.json

範例：

# 轉換整個 Skills 倉庫為 marketplace
./scripts/convert-to-plugin.sh ~/Workspace/my-skills --marketplace

# 輸出：
# ✅ marketplace.json 已建立
# ✅ 各分類 plugin.json 已建立
#
# 安裝指令:
#   /plugin marketplace add <user>/my-skills
#   /plugin install <plugin-name>@my-skills

初始化指南

首次使用 Self-Evolving Agent 的設定步驟

最小需求

記憶系統初始化

首次使用時，建立以下目錄結構：

# 檢查是否已存在
ls .claude/memory/ 2>/dev/null || echo "需要初始化"

若不存在，建立：

.claude/memory/
├── index.md              # 快速索引（必須維護）
├── learnings/            # 學習記錄
│   └── .gitkeep
├── decisions/            # 決策記錄 (ADR)
│   └── .gitkeep
├── failures/             # 失敗經驗
│   └── .gitkeep
├── patterns/             # 推理模式
│   └── .gitkeep
├── strategies/           # 策略記錄
│   └── .gitkeep
├── discoveries/          # 涌現發現
│   └── .gitkeep
└── skill-metrics/        # 技能效果追蹤
    └── .gitkeep

index.md 模板

# 專案記憶索引

> Last curated: YYYY-MM-DD
> Total entries: 0
> Next review: YYYY-MM-DD (7 days)

## 統計
- Learnings: 0 筆
- Failures: 0 筆
- Decisions: 0 筆
- Patterns: 0 筆

## 最近學習
<!-- LEARNINGS_START -->
<!-- LEARNINGS_END -->

## 重要決策
<!-- DECISIONS_START -->
<!-- DECISIONS_END -->

## 失敗經驗
<!-- FAILURES_START -->
<!-- FAILURES_END -->

## 推理模式
<!-- PATTERNS_START -->
<!-- PATTERNS_END -->

## 標籤索引
<!-- TAGS_START -->
<!-- TAGS_END -->

快速檢查指令

# 一鍵檢查環境
git status && \
ls CLAUDE.md 2>/dev/null || echo "⚠️ 建議建立 CLAUDE.md" && \
ls .claude/memory/ 2>/dev/null || echo "⚠️ 需要初始化記憶系統"

下一步

環境就緒後，使用 /evolve [目標] 開始執行任務。

PSB 環境準備

Plan → Setup → Build：在寫第一行程式碼前，先確保環境就緒

PSB 檢查清單

Plan（規劃）

• [ ] 1. 目標明確性：成功標準、範圍限定、驗收條件可量化

Setup（環境）

• [ ] 2. Git Repo 已建立：git init / git clone + .gitignore
• [ ] 3. CLAUDE.md 已配置：專案規範、技術棧、約定
• [ ] 4. 記憶系統已初始化：.claude/memory/ + index.md
• [ ] 5. 自動化文件（可選）：架構文件、變更日誌
• [ ] 6. MCP 連接（可選）：context7、PAL
• [ ] 7. Slash Commands（可選）：/evolve 等觸發詞
• [ ] 8. 權限配置（推薦）：/permissions 精細管理

Build（執行）

✓ 環境就緒，開始執行任務

快速檢查指令

# 檢查 Git
git status

# 檢查 CLAUDE.md
ls CLAUDE.md 2>/dev/null || echo "⚠️ 建議建立 CLAUDE.md"

# 檢查記憶系統
ls .claude/memory/ 2>/dev/null || echo "⚠️ 需要初始化記憶系統"

最小可行環境

若要快速開始，至少確保：

權限配置指南（Boris Tip #6）

精細權限管理，預先允許安全常用命令，避免 --dangerously-skip-permissions

為什麼重要

推薦使用 `/permissions`：在安全和體驗之間取得平衡。

配置方式

方式 1：使用 `/permissions` 命令

# 在 Claude Code 中執行
/permissions

# 會顯示互動式介面，可以：
# - 允許特定命令模式
# - 拒絕危險操作
# - 檢視當前設定

方式 2：編輯設定檔

// .claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(make *)",
      "Read(*)",
      "Glob(*)",
      "Grep(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(sudo *)"
    ]
  }
}

推薦的安全允許清單

建議禁止的操作

何時用什麼

Boris Tip: 「精細權限管理 > --dangerously-skip-permissions」

版本檢查與自動更新

強制檢查點 - 每次 /evolve 啟動時執行

>

💡 核心價值：確保使用最新版本，自動化更新流程

規則

┌─────────────────────────────────────────────────────────────────┐
│  🔄 版本檢查（/evolve 啟動時）                                   │
│                                                                 │
│  每次執行 /evolve 時，在 CP0 之前先檢查版本：                    │
│                                                                 │
│  1. 取得本地版本                                                │
│     → 讀取本地 SKILL.md 的 version 欄位                         │
│                                                                 │
│  2. 取得遠端版本                                                │
│     → 從 GitHub repo 取得最新 version                          │
│                                                                 │
│  3. 比較版本                                                    │
│     → 若遠端較新，詢問使用者是否更新                            │
│                                                                 │
│  4. 執行更新（若使用者同意）                                    │
│     → git pull 或重新安裝 plugin                               │
│                                                                 │
│  ✅ 完成後：繼續執行原本的 /evolve 任務                         │
│  ❌ 跳過：使用者選擇不更新時                                    │
└─────────────────────────────────────────────────────────────────┘

執行流程

┌─────────────────────────────────────────────────────────────────┐
│                    版本檢查流程                                  │
│                                                                 │
│                  /evolve 被呼叫                                  │
│                       ↓                                         │
│               取得本地版本                                       │
│                       ↓                                         │
│               取得遠端版本                                       │
│                       │                                         │
│         ┌─────────────┴─────────────┐                           │
│         ↓                           ↓                           │
│    版本相同                    遠端較新                          │
│         ↓                           ↓                           │
│   繼續 CP0               AskUserQuestion                        │
│                          「發現新版本，是否更新？」               │
│                                │                                │
│                    ┌───────────┴───────────┐                    │
│                    ↓                       ↓                    │
│                 是/更新                  否/跳過                 │
│                    ↓                       ↓                    │
│              執行更新流程             繼續 CP0                   │
│                    ↓                                            │
│              驗證更新成功                                        │
│                    ↓                                            │
│               繼續 CP0                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step 1: 取得本地版本

方式 A：從已載入的 Skill 讀取

# Skill 已載入時，version 在 frontmatter 中
# 例：version: 5.1.0

方式 B：從本地檔案讀取

# 若知道 skill 安裝位置
grep "^version:" /path/to/skills/SKILL.md | head -1
# 輸出：version: 5.1.0

方式 C：從 Plugin 安裝路徑讀取

# 檢查 Claude Code Plugin 安裝路徑
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["evolve@evolve-plugin"]'
# 輸出會包含 version 欄位

Step 2: 取得遠端版本

來源優先順序

1. GitHub API（推薦）

   # 取得 raw SKILL.md
   curl -s https://raw.githubusercontent.com/miles990/self-evolving-agent/main/skills/SKILL.md | grep "^version:"

2. GitHub Release

   # 取得最新 release tag
   curl -s https://api.github.com/repos/miles990/self-evolving-agent/releases/latest | jq -r '.tag_name'

3. marketplace.json

   # 取得 plugin 版本
   curl -s https://raw.githubusercontent.com/miles990/self-evolving-agent/main/evolve-plugin/.claude-plugin/marketplace.json | jq -r '.plugins[0].version'

Step 3: 版本比較

版本格式

MAJOR.MINOR.PATCH
例：5.1.0

MAJOR = 重大變更（不相容）
MINOR = 新功能（相容）
PATCH = Bug 修復

比較邏輯

本地: 5.0.0
遠端: 5.1.0
結果: 遠端較新 → 觸發更新詢問

本地: 5.1.0
遠端: 5.1.0
結果: 版本相同 → 跳過更新

本地: 5.2.0
遠端: 5.1.0
結果: 本地較新 → 跳過（開發版本）

Step 4: 詢問使用者

AskUserQuestion 範例

┌─────────────────────────────────────────────────────────────────┐
│  🔄 發現新版本                                                  │
│                                                                 │
│  Self-Evolving Agent 有新版本可用：                             │
│                                                                 │
│  本地版本：v5.0.0                                               │
│  最新版本：v5.1.0                                               │
│                                                                 │
│  更新內容：                                                     │
│  • 新增 Git Worktree 隔離環境工作流程                          │
│  • 新增 CP0.5/CP6.5 檢查點                                     │
│                                                                 │
│  你想要：                                                       │
│  A) 立即更新（推薦）                                            │
│  B) 稍後更新（繼續使用當前版本）                                │
│  C) 不再提醒此版本                                              │
└─────────────────────────────────────────────────────────────────┘

Step 5: 執行更新

⚠️ 重要：不要在背景執行更新

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️ 警告：/plugin 命令需要互動式終端                            │
│                                                                 │
│  /plugin install 和 /plugin update 命令：                       │
│  • 可能需要用戶確認                                             │
│  • 無法在背景進程中執行                                         │
│  • 在背景執行會導致進程卡住                                     │
│                                                                 │
│  ✅ 正確做法：提示用戶手動執行命令                              │
│  ❌ 錯誤做法：使用 Bash 工具在背景執行 /plugin 命令             │
└─────────────────────────────────────────────────────────────────┘

更新方式判斷

┌─────────────────────────────────────────────────────────────────┐
│  更新方式判斷                                                   │
│                                                                 │
│  安裝方式？                                                     │
│       │                                                         │
│  ┌────┼────────────────┐                                        │
│  ↓    ↓                ↓                                        │
│ Git  Plugin        手動複製                                     │
│  ↓    ↓                ↓                                        │
│ pull 提示手動執行  提示手動更新                                  │
│      /plugin                                                    │
└─────────────────────────────────────────────────────────────────┘

方式 A：Git 更新（可自動執行）

# 若是 git clone 安裝，可以自動執行
cd /path/to/self-evolving-agent
git fetch origin
git pull origin main

方式 B：Claude Code Plugin 更新（僅提示）

┌─────────────────────────────────────────────────────────────────┐
│  📋 請手動執行以下命令更新 plugin：                              │
│                                                                 │
│  /plugin update evolve@evolve-plugin                            │
│                                                                 │
│  或重新安裝：                                                   │
│  /plugin install evolve@evolve-plugin                           │
│                                                                 │
│  ⚠️ 這些命令必須由用戶在終端機中手動輸入執行                    │
└─────────────────────────────────────────────────────────────────┘

絕對禁止：

# ❌ 不要這樣做 - 會導致進程卡住
claude /plugin update evolve@evolve-plugin  # 禁止！

更新後驗證

# 確認版本已更新
grep "^version:" /path/to/skills/SKILL.md

# 預期輸出
version: 5.1.0

完成信號

更新成功

┌─────────────────────────────────────────────────────────────────┐
│  ✅ 更新完成                                                    │
│                                                                 │
│  Self-Evolving Agent 已更新至 v5.1.0                            │
│                                                                 │
│  新功能：                                                       │
│  • Git Worktree 隔離環境                                        │
│  • CP0.5/CP6.5 檢查點                                          │
│                                                                 │
│  → 繼續執行原本的任務...                                        │
└─────────────────────────────────────────────────────────────────┘

跳過更新

┌─────────────────────────────────────────────────────────────────┐
│  ⏭️ 跳過更新                                                    │
│                                                                 │
│  繼續使用 v5.0.0                                                │
│  （下次 /evolve 會再次提醒）                                    │
│                                                                 │
│  → 繼續執行原本的任務...                                        │
└─────────────────────────────────────────────────────────────────┘

錯誤處理

網路錯誤

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️ 無法檢查更新                                                │
│                                                                 │
│  原因：無法連接到 GitHub                                        │
│                                                                 │
│  → 跳過版本檢查，繼續執行任務                                   │
└─────────────────────────────────────────────────────────────────┘

更新失敗

┌─────────────────────────────────────────────────────────────────┐
│  ❌ 更新失敗                                                    │
│                                                                 │
│  原因：{錯誤訊息}                                               │
│                                                                 │
│  建議：                                                         │
│  • 手動執行：git pull origin main                              │
│  • 或重新安裝：/plugin install evolve@evolve-plugin            │
│                                                                 │
│  → 繼續使用當前版本執行任務                                     │
└─────────────────────────────────────────────────────────────────┘

配置選項

停用版本檢查

在 CLAUDE.md 或 .claude/settings.local.json 中：

# CLAUDE.md
evolve:
  version_check: false  # 停用版本檢查

// .claude/settings.local.json
{
  "evolve": {
    "versionCheck": false
  }
}

自動更新（僅限 Git 安裝）

# CLAUDE.md
evolve:
  auto_update: true  # 自動執行 git pull（僅限 Git 安裝）

⚠️ 注意：自動更新僅對 Git 安裝方式有效。

Plugin 安裝方式無法自動更新，會改為提示用戶手動執行。

與其他檢查點的關係

版本檢查 ← 你在這裡（/evolve 啟動時第一步）
     ↓
CP0 (北極星錨定)
     ↓
CP0.5 (Worktree 準備)
     ↓
CP1 ~ CP6 ...

相關資源

• PSB 環境準備
• GitHub: self-evolving-agent
• GitHub: evolve-plugin

00-getting-started

入門與環境設定

本模組包含

快速開始

# 1. 檢查環境
git status && ls CLAUDE.md 2>/dev/null || echo "建議建立 CLAUDE.md"

# 2. 初始化記憶系統
ls .claude/memory/ 2>/dev/null || echo "需要初始化記憶系統"

# 3. 開始使用
/evolve [你的目標]

社群貢獻

能力評估 (Capability Assessment)

在執行任務前，先評估自己是否具備所需能力

評估流程

任務分析 → 能力清單 → 差距識別 → 習得/降級決策

能力維度

評估模板

task: [任務描述]
required_capabilities:
  domain_knowledge:
    - [領域 1]
    - [領域 2]
  technical_skills:
    - [技術 1]
    - [技術 2]
  environment:
    - [環境需求 1]

self_assessment:
  have:
    - [具備的能力]
  gap:
    - [缺少的能力]

decision: acquire | delegate | simplify | abort

決策選項

搜尋記憶

在評估前，先搜尋是否有相關經驗：

# 搜尋過去類似任務的經驗
Grep(
    pattern="[任務關鍵字]",
    path=".claude/memory/",
    output_mode="files_with_matches"
)

習得 Skill

若有能力差距，先檢查已安裝狀態和版本再習得：

# Step 1: 檢查已安裝 plugins
installed = Read("~/.claude/plugins/installed_plugins.json")
# 結構: { "plugins": { "name@marketplace": [{ "version": "x.y.z" }] } }

# Step 2: 檢查已添加 marketplaces
marketplaces = Read("~/.claude/plugins/known_marketplaces.json")
# 常用: claude-software-skills, claude-domain-skills

# Step 3: 版本檢查（若已安裝）
if skill_installed:
    installed_ver = installed["plugins"]["name@marketplace"][0]["version"]
    marketplace_path = marketplaces["marketplace"]["installLocation"]
    latest = Read(f"{marketplace_path}/{plugin}/.claude-plugin/plugin.json")
    if installed_ver != latest["version"]:
        # /plugin update {plugin}  # 更新到最新版
    Skill({ skill: "skill-name" })

# Step 4: 智能決策
elif marketplace_exists:
    # /plugin install {skill}@{marketplace}
else:
    # /plugin marketplace add miles990/{marketplace}
    # /plugin install {skill}@{marketplace}

快速參考

目標分析 (Phase 1)

執行任務前的目標解析與明確性檢查

>

💡 核心洞察：寫 spec 最大的問題是「你不知道自己漏了什麼」

— 來源：@BensonTWN

目標明確性檢查（優先執行）

┌─────────────────────────────────────────────────────────┐
│  檢查項目：                                             │
│  □ 有具體的成功標準嗎？                                │
│  □ 有可量化的驗收條件嗎？                              │
│  □ 範圍是否明確？                                      │
│  □ 有技術/資源約束嗎？                                 │
│  □ 有時間/品質偏好嗎？                                 │
│  □ 需要架構設計嗎？（見下方判斷標準）                  │
└─────────────────────────────────────────────────────────┘

若有 ≥2 項不明確 → 使用 AskUserQuestion 確認
若只有 1 項不明確 → 用【假設】補齊，列出假設內容
若全部明確 → 進入深度訪談或直接目標解析（依任務複雜度）

架構考量觸發判斷

根據任務性質，判斷是否需要在 PDCA Plan 階段進行架構設計：

┌─────────────────────────────────────────────────────────────────┐
│  架構設計需求等級                                               │
│                                                                 │
│  Level 0: 不需要架構設計                                        │
│  ├─ Bug fix（修復現有功能）                                     │
│  ├─ 小幅修改（調整參數、文案、樣式）                           │
│  ├─ 單一函數/方法的變更                                        │
│  └─ 文檔更新                                                   │
│                                                                 │
│  Level 1: 輕量架構思考（PDCA Plan 時快速考慮）                  │
│  ├─ 新增單一功能（在現有模組內）                               │
│  ├─ 重構現有程式碼（不改變介面）                               │
│  └─ 效能優化                                                   │
│                                                                 │
│  Level 2: 完整架構設計（PDCA Plan 時深度考慮）                  │
│  ├─ 新增模組/服務                                              │
│  ├─ 跨多個模組的功能                                          │
│  ├─ 新增外部整合（API、資料庫、第三方服務）                   │
│  ├─ 變更核心架構/資料模型                                     │
│  └─ 建立新專案                                                │
└─────────────────────────────────────────────────────────────────┘

快速判斷表

標記方式

在目標分析完成後，標記架構等級：

goal_analysis:
  goal: "建立用戶通知系統"
  architecture_level: 2  # 0, 1, or 2
  architecture_reason: "新增完整模組，涉及多種通知管道"

此標記會影響 PDCA Plan 階段的深度。

深度訪談模式（Deep Interview）

🎯 目的：主動發現用戶沒想到的問題，挖掘隱藏假設

觸發條件

訪談執行流程

┌─────────────────────────────────────────────────────────────────┐
│  深度訪談模式                                                   │
│                                                                 │
│  角色：資深技術顧問                                             │
│  工具：AskUserQuestion（多輪對話）                              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  每個問題前的 Ultrathink 分析（內部思考）               │   │
│  │                                                         │   │
│  │  1. 這個規格可能隱藏的假設是什麼？                     │   │
│  │  2. 哪些邊界情況沒有被考慮到？                         │   │
│  │  3. 技術債務可能在哪裡累積？                           │   │
│  │  4. 這個設計決策的二階、三階效應是什麼？               │   │
│  └─────────────────────────────────────────────────────────┘   │
│                            ↓                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  提出深入問題（使用 AskUserQuestion）                   │   │
│  │                                                         │   │
│  │  涵蓋面向：                                             │   │
│  │  • 技術實作細節                                         │   │
│  │  • UI/UX 考量                                           │   │
│  │  • 潛在疑慮與風險                                       │   │
│  │  • 設計取捨                                             │   │
│  │  • 邊界情況處理                                         │   │
│  │  • 錯誤處理策略                                         │   │
│  │  • 擴展性需求                                           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                            ↓                                    │
│           持續訪談直到所有關鍵面向都被釐清                      │
│                            ↓                                    │
│                    產出完整的目標規格                           │
└─────────────────────────────────────────────────────────────────┘

訪談問題範本

使用 AskUserQuestion 時，問題應深入且不流於表面：

┌─────────────────────────────────────────────────────────────────┐
│  深度訪談問題範本                                               │
│                                                                 │
│  【隱藏假設探索】                                               │
│  • 當 X 發生時，系統應該如何反應？                              │
│  • 如果用戶在 Y 步驟中途離開，資料如何處理？                    │
│  • 這個功能是否假設用戶已經完成 Z？                             │
│                                                                 │
│  【邊界情況】                                                   │
│  • 當資料量超過 N 時，效能要求是什麼？                          │
│  • 並發操作時如何處理衝突？                                     │
│  • 網路中斷時的降級策略是什麼？                                 │
│                                                                 │
│  【技術債務預防】                                               │
│  • 這個設計未來可能需要如何擴展？                               │
│  • 哪些部分可能需要重構？                                       │
│  • 有沒有可以提前抽象化的元件？                                 │
│                                                                 │
│  【二階/三階效應】                                              │
│  • 這個功能對其他模組有什麼影響？                               │
│  • 對團隊工作流程有什麼改變？                                   │
│  • 對用戶行為可能產生什麼非預期的影響？                         │
└─────────────────────────────────────────────────────────────────┘

訪談結束條件

訪談結束於：
✅ 所有關鍵面向都已釐清（技術、UX、風險、取捨）
✅ 用戶表示「沒有其他要補充的」
✅ 連續 2 個問題用戶回答「這個不需要考慮」

訪談提前結束於：
⏸️ 用戶說「先這樣，之後再補充」
⏸️ 達到 10 個問題上限（避免疲勞）

訪談產出

訪談結束後，整理為結構化的目標規格：

goal_specification:
  original_goal: "[用戶原始輸入]"
  clarified_goal: "[經過訪談後的精確描述]"

  success_criteria:
    - "[明確的成功標準 1]"
    - "[明確的成功標準 2]"

  scope:
    included:
      - "[包含的範圍]"
    excluded:
      - "[明確排除的範圍]"

  assumptions:
    - "[訪談中確認的假設]"

  edge_cases:
    - case: "[邊界情況]"
      handling: "[處理方式]"

  risks:
    - risk: "[潛在風險]"
      mitigation: "[緩解措施]"

  interview_insights:
    - "[訪談中發現的重要洞察]"

目標解析步驟

1. 解析目標

• 最終成功標準是什麼？
• 如何驗證目標達成？
• 有哪些約束條件？

2. 分解子目標

• 將大目標拆成可執行的步驟
• 識別依賴關係
• 設定每個步驟的驗收標準

3. 評估現有能力

• 需要哪些技能/工具？
• 哪些已具備？哪些需要學習？

目標確認問卷（使用 AskUserQuestion）

當目標不明確時，一次收齊關鍵資訊：

┌─────────────────────────────────────────────────────────────────┐
│  ❓ 需要確認目標細節                                           │
│                                                                 │
│  您的目標：[用戶輸入的原始目標]                                 │
│                                                                 │
│  請幫我確認以下幾點：                                           │
│                                                                 │
│  1. 成功標準                                                    │
│     □ 能正常運作即可                                           │
│     □ 需要特定效能指標（請說明）                               │
│     □ 需要通過測試/驗收條件（請說明）                          │
│                                                                 │
│  2. 範圍限制                                                    │
│     □ 只處理核心功能                                           │
│     □ 需要完整實作（含邊界情況）                               │
│     □ 需要考慮擴展性                                           │
│                                                                 │
│  3. 品質 vs 速度                                                │
│     □ 快速完成優先（可接受後續優化）                           │
│     □ 品質優先（寧可慢也要做好）                               │
│     □ 平衡                                                     │
│                                                                 │
│  4. 其他約束                                                    │
│     □ 無特別限制                                               │
│     □ 有（請說明：技術棧/相容性/資源限制）                     │
└─────────────────────────────────────────────────────────────────┘

不明確目標範例

PDCA 執行循環

Plan → Do → Check → Act 的迭代執行

流程

Plan（規劃）

• 制定具體執行計劃、預測可能問題、準備備選方案
• 架構設計（依等級觸發，見下方）

Do（執行）

• 按計劃執行、記錄過程、收集中間結果

Check（評估）

• 結果是否符合預期？失敗則分析原因
• 評估：完全成功 / 部分成功 / 失敗

🔑 Boris Tip #13: 給 Claude 驗證工作的方式，品質提升 2-3 倍

自動化驗證策略：

• [ ] 執行測試：npm test / pytest / go test
• [ ] 執行構建：npm run build / tsc / cargo build
• [ ] Lint 檢查：eslint / prettier --check
• [ ] 型別檢查：tsc --noEmit

驗證失敗 → 不進入下一步，先修復

Act（改進）

成功時：記錄到 .claude/memory/learnings/ → 更新 index.md → 下一子目標

失敗時：反思 → 學習 → 搜索 → 更新策略 → 記錄到 .claude/memory/failures/ → 重試

Plan 階段：架構設計指引

根據 Goal Analysis 階段標記的 architecture_level，決定 Plan 階段的深度：

Level 0: 直接執行

不需要架構考量，直接制定執行計劃。

Level 1: 輕量架構思考

💡 Level 1 快速檢查（1-2 分鐘）

• [ ] 錯誤處理：這個功能可能失敗嗎？如何處理？
• [ ] 命名：函數/變數名稱是否清晰表達意圖？
• [ ] 位置：程式碼應該放在哪個檔案/目錄？
• [ ] 測試：需要寫測試嗎？測什麼？

Level 2: 完整架構設計

🏗️ Level 2 架構設計流程

Step 1: 可靠性考量

• [ ] 錯誤處理策略：可能遇到哪些錯誤？使用統一處理方式
• [ ] 重試機制：需要重試嗎？指數退避？固定間隔？
• [ ] 降級策略：核心失敗有備選方案嗎？需要 circuit breaker？

Step 2: 可擴展性考量

• [ ] 介面設計：足夠抽象？容易新增變體？
• [ ] 依賴方向：符合分層？有逆向依賴？
• [ ] 變化點識別：未來最可能變化的部分？需預留擴展點？

Step 3: 可維護性考量

• [ ] 分層與職責：模組職責單一？符合分層架構？
• [ ] 設計模式：需使用專案已採用的模式？避免過度設計（YAGNI）
• [ ] 測試策略：單元測試覆蓋哪些場景？需整合測試？

Step 4: 輸出設計決策

• 記錄關鍵決策，供 CP1.5 Phase 2 驗證

設計決策記錄模板

完成 Level 2 架構設計後，記錄關鍵決策：

architecture_decisions:
  task: "建立用戶通知系統"

  reliability:
    error_handling: "使用 NotificationError 類別，繼承 AppError"
    retry_strategy: "外部服務失敗時重試 3 次，指數退避"
    fallback: "Email 失敗時降級為 in-app 通知"

  scalability:
    interface: "NotificationChannel 抽象介面，支援多種通道"
    patterns: "Strategy Pattern 處理不同通知類型"
    extension_points: "新通道只需實作 NotificationChannel"

  maintainability:
    location: "src/notifications/ 新模組"
    layer: "Service 層，依賴 Repository 層"
    testing: "每個 Channel 獨立單元測試"

架構設計與後續流程的關係

→ 設計 → 實作 → 驗證 閉環

---

失敗模式診斷

失敗時先分類，再針對性處理：

多策略機制

不重複嘗試同一個失敗策略：

策略選擇邏輯：
1. 從 available_strategies 按 priority 排序
2. 跳過 status = "failed" 的策略
3. 選擇第一個可行的策略
4. 如果所有策略都失敗 → 詢問用戶或搜尋新策略

反思流程（Reflexion）

每次失敗後：

1. 失敗分析

• 錯誤類型是什麼？
• 根本原因是什麼？

2. 知識補充

• 需要學習什麼？
• 搜索相關資料

3. 策略調整

• 原策略哪裡有問題？
• 新策略是什麼？

4. 記憶更新

• 寫入 .claude/memory/
• 格式：[情境] → [錯誤] → [解決方案]

技能習得流程

遇到無法完成的任務時，自動搜尋並學習新技能

習得流程

┌─────────────────────────────────────────────────────────────────┐
│  技能習得流程                                                   │
│                                                                 │
│  1. 識別技能缺口                                                │
│     - 「我無法完成 X 因為我不知道如何 Y」                       │
│     - 區分：缺「知識」還是缺「工具」                            │
│                                                                 │
│  2. 搜尋已有經驗（Repo Memory）                                 │
│     Grep(pattern="Y", path=".claude/memory/")                   │
│     - 有經驗 → 直接應用                                         │
│     - 無經驗 → 繼續步驟 3                                       │
│                                                                 │
│  3. 搜尋可用 Skill（優先搜尋 priority repos）                   │
│     search_skills({ query: "Y", source: "priority" })           │
│     - 優先搜尋 miles990/claude-software-skills                  │
│     - 優先搜尋 miles990/claude-domain-skills                    │
│     - 評估推薦的 skill 是否適用                                 │
│                                                                 │
│  4. 安裝 Skill                                                  │
│     install_skill({ source: "best-skill-name" })                │
│                                                                 │
│  5. 載入並學習                                                  │
│     load_skill({ id: "best-skill-name" })                       │
│     - 仔細閱讀 instructions                                     │
│     - 理解使用方式和限制                                        │
│                                                                 │
│  6. 驗證學習                                                    │
│     - 用簡單任務測試是否學會                                    │
│     - 成功 → 應用到實際任務                                     │
│     - 失敗 → 重新學習或換 skill                                 │
│                                                                 │
│  7. 記錄學習經驗                                                │
│     Write(.claude/memory/learnings/{date}-{skill}.md)           │
│     - 記錄情境 + skill + 效果                                   │
│     - 更新 index.md                                             │
└─────────────────────────────────────────────────────────────────┘

自動領域識別

從任務描述提取關鍵詞，自動搜尋匹配的領域 skill：

用戶任務：「幫我建立一個量化交易回測系統」

Step 1: search_skills({ query: "量化交易", source: "priority" })
        → 優先搜尋 miles990/claude-software-skills
        → 優先搜尋 miles990/claude-domain-skills
        → 分析關鍵詞：量化、交易、回測

Step 2: 獲得推薦結果
        domain_skills: quant-trading (from claude-domain-skills)
        software_skills: python, database (from claude-software-skills)

Step 3: 安裝並載入
        install_skill({ source: "github:miles990/claude-domain-skills#finance/quant-trading" })
        load_skill("quant-trading")

研究模式

當整體信心度 < 50% 時，自動進入研究模式：

overall_confidence: 0.35 (< 0.5 閾值)
research_mode: true
research_suggestions:
  • 搜尋外部 skill 倉庫
  • Web 搜尋最佳實踐
  • 詢問用戶澄清具體需求

→ 不盲目執行，先補充知識再繼續

學習驗證流程

安裝新 skill 後，必須驗證真的學會才能應用：

1. 安裝 Skill
   install_skill({ source: "skill-name" })

2. 載入 Instructions
   load_skill({ id: "skill-name" })

3. 設計簡單驗證任務
   • 範圍小、可快速完成
   • 涵蓋核心能力
   • 有明確的成功標準

4. 執行驗證
   例：生成一張簡單的測試圖片

5. 評估結果
   ✅ 成功 → 加入 confident_in，繼續主任務
   ❌ 失敗 → 重新學習或嘗試其他 skill

Fallback 機制

當主要習得路徑失敗時，啟用多層降級策略：

┌─────────────────────────────────────────────────────────────────┐
│  Fallback 優先級                                                │
│                                                                 │
│  Level 1: Skill + Memory（正常路徑）                            │
│  ├─ recommend_skill() → 找到 → 安裝 → 學習                      │
│  └─ 搜尋 Memory → 找到 → 應用                                   │
│                                                                 │
│  Level 2: 外部知識源                                            │
│  ├─ context7 查詢文檔                                           │
│  │   query-docs({ libraryId: "...", query: "..." })             │
│  ├─ Web 搜尋最佳實踐                                            │
│  │   WebSearch({ query: "how to X best practices 2026" })       │
│  └─ PAL 多模型諮詢                                              │
│      chat({ prompt: "...", model: "gemini-2.5-pro" })           │
│                                                                 │
│  Level 3: 結構化降級                                            │
│  ├─ 分解任務為更小的子任務                                      │
│  ├─ 詢問用戶提供範例或參考                                      │
│  └─ 嘗試相鄰領域的 skill                                        │
│                                                                 │
│  Level 4: 誠實失敗                                              │
│  └─ 告知用戶限制，建議專業資源                                  │
└─────────────────────────────────────────────────────────────────┘

Fallback 觸發條件

範例：Fallback 執行流程

任務：「建立一個量子計算模擬器」

Step 1: recommend_skill({ query: "quantum computing" })
        → 無匹配結果

Step 2: 搜尋 Memory
        Grep(pattern="quantum", path=".claude/memory/")
        → 無相關經驗

→ 觸發 Level 2 Fallback

Step 3: context7 查詢
        resolve-library-id({ query: "quantum computing", libraryName: "qiskit" })
        → 找到 Qiskit 文檔

Step 4: Web 搜尋
        WebSearch({ query: "quantum computing python tutorial 2026" })
        → 獲得教程連結

Step 5: 評估是否足夠
        - 有基礎文檔 ✓
        - 有教程參考 ✓
        → 信心度提升到 60%，可嘗試執行

若 Step 5 信心度仍 < 50%:
→ 觸發 Level 3，詢問用戶

能力評估思考框架

task: "[分析用戶的任務後填入]"

capability_assessment:
  confident_in:
    - skill: "[技能名稱]"
      level: "熟練 / 基本 / 略知"

  uncertain_about:
    - skill: "[技能名稱]"
      reason: "[為什麼不確定]"

  definitely_need:
    - "[需要的技能或知識]"

  action_plan:
    - step: "[下一步行動]"
      tool: "[使用的工具]"

  fallback_options:
    - level: 2
      sources: ["context7", "WebSearch", "PAL"]
    - level: 3
      actions: ["分解任務", "詢問用戶", "嘗試相鄰 skill"]

01-core

核心執行流程：目標分析、能力評估、技能習得、PDCA 循環

本模組包含

核心流程

目標輸入 → 目標分析 → 能力評估 → 技能習得 → PDCA 循環
              │           │           │           │
              ▼           ▼           ▼           ▼
          分解子目標    識別差距    載入 skill   Plan-Do-Check-Act

社群貢獻

Checkpoint 0: 專案/任務開始 - 北極星錨定

🌟 強制檢查點 - 不可跳過

>

💡 核心洞察：「做到後面，好像都迷失了方向」— 這是專案失敗的常見原因

規則

┌─────────────────────────────────────────────────────────────────┐
│  🌟 專案/任務開始前（強制）                                      │
│                                                                 │
│  在執行任何複雜任務前，必須先錨定北極星：                        │
│                                                                 │
│  1. 檢查北極星文件是否存在                                      │
│     → .claude/memory/north-star/{project-name}.md               │
│                                                                 │
│  2. 若存在 → 讀取並確認                                         │
│     → 願景還是這個嗎？                                          │
│     → 完成標準有變嗎？                                          │
│                                                                 │
│  3. 若不存在 → 觸發北極星訪談                                   │
│     → 用 AskUserQuestion 收集關鍵資訊                           │
│     → 創建北極星文件                                            │
│                                                                 │
│  ❌ 禁止：大型任務沒有北極星就開始執行                          │
│  ✅ 必須：Level 1/2 任務必須有北極星錨定                        │
└─────────────────────────────────────────────────────────────────┘

觸發條件

北極星文件位置

.claude/memory/north-star/
├── {project-name}.md          # 專案級北極星
└── {feature-name}.md          # 大型功能級北極星（可選）

北極星文件模板

---
created: {date}
project: "{專案名稱}"
status: active | paused | completed | abandoned
last_checkpoint: {date}
iteration_count: 0
---

# 🌟 北極星：{專案名稱}

## 一句話願景
> [20字內：這個專案存在的理由]

## 完成標準（Done = 什麼？）
- [ ] [可驗證的標準 1]
- [ ] [可驗證的標準 2]
- [ ] [可驗證的標準 3]

## 不做清單（Scope 護欄）
- ❌ [明確排除 1]
- ❌ [明確排除 2]

## 當初為什麼開始？
[1-2句話，迷失時回來看這段]

---

## 健康檢查記錄

| 日期 | 迭代 | 方向 | 備註 |
|------|------|------|------|
| {date} | #1 | ✅ 正軌 | 初始建立 |

北極星訪談流程

當北極星文件不存在時，使用 AskUserQuestion 進行訪談：

┌─────────────────────────────────────────────────────────────────┐
│  🌟 北極星訪談                                                  │
│                                                                 │
│  問題 1：願景（必問）                                           │
│  「用一句話描述：這個專案做完後，你希望達成什麼？」             │
│                                                                 │
│  問題 2：完成標準（必問）                                       │
│  「怎樣算『做完』？請給我 2-3 個可以打勾的標準」                │
│                                                                 │
│  問題 3：排除範圍（必問）                                       │
│  「有什麼是這個專案『不要做』的？」                             │
│  （防止 scope creep）                                           │
│                                                                 │
│  問題 4：動機（必問）                                           │
│  「當初為什麼想做這個？」                                       │
│  （迷失時的提醒）                                               │
│                                                                 │
│  收集完畢 → 生成北極星文件 → 儲存到 .claude/memory/north-star/  │
└─────────────────────────────────────────────────────────────────┘

AskUserQuestion 範例

┌─────────────────────────────────────────────────────────────────┐
│  🌟 建立北極星                                                  │
│                                                                 │
│  這是一個 Level 1/2 任務，讓我先幫你錨定方向：                  │
│                                                                 │
│  1. 一句話願景                                                  │
│     這個專案做完後，你希望達成什麼？                            │
│     [________________]                                          │
│                                                                 │
│  2. 完成標準（怎樣算做完？）                                    │
│     □ [標準 1]                                                 │
│     □ [標準 2]                                                 │
│     □ [標準 3]                                                 │
│                                                                 │
│  3. 不做清單（明確排除）                                        │
│     ❌ [排除 1]                                                 │
│     ❌ [排除 2]                                                 │
│                                                                 │
│  4. 當初為什麼想做這個？                                        │
│     [________________]                                          │
└─────────────────────────────────────────────────────────────────┘

CP0 執行流程

┌─────────────────────────────────────────────────────────────────┐
│                     CP0 執行流程                                │
│                                                                 │
│                    任務開始                                     │
│                       ↓                                         │
│               判斷架構等級                                       │
│                       ↓                                         │
│         ┌─────────────────────────────┐                         │
│         │ Level 0?                    │                         │
│         └─────────────────────────────┘                         │
│                  ↓ Yes              ↓ No                        │
│              跳過 CP0           繼續 CP0                        │
│                                     ↓                           │
│                          檢查北極星文件                          │
│                                     ↓                           │
│              ┌──────────────────────────────────┐               │
│              │ 存在?                            │               │
│              └──────────────────────────────────┘               │
│                  ↓ Yes                    ↓ No                  │
│           讀取並確認                觸發北極星訪談               │
│                  ↓                        ↓                     │
│        「願景還是這個嗎？」      AskUserQuestion 收集            │
│                  ↓                        ↓                     │
│            更新 last_checkpoint      創建北極星文件             │
│                  ↓                        ↓                     │
│                  └────────────────────────┘                     │
│                              ↓                                  │
│                        進入 CP1                                 │
└─────────────────────────────────────────────────────────────────┘

為什麼重要

1. 防止迷失方向 - 有明確的錨點可以隨時回顧 2. 防止 Scope Creep - 「不做清單」是護欄 3. 知道何時結束 - 完成標準是可打勾的 checkbox 4. 迷失時有依靠 - 「當初為什麼開始」提供動力

Worktree 判斷（v5.1 新增）

CP0 完成後，評估是否需要隔離環境：

┌─────────────────────────────────────────────────────────────────┐
│  🔒 Worktree 判斷                                               │
│                                                                 │
│  強制使用 Worktree（任一條件）：                                 │
│  □ 架構等級 Level 2（新模組/服務/整合）                         │
│  □ --autonomous 模式                                            │
│  □ spec-workflow 並行任務                                       │
│  □ 用戶明確要求隔離                                             │
│                                                                 │
│  建議使用 Worktree（任一條件）：                                 │
│  □ 預期執行時間 > 30 分鐘                                       │
│  □ 涉及核心模組修改                                             │
│  □ 實驗性開發（「試試看」「實驗一下」）                          │
│                                                                 │
│  → 符合條件時，進入 CP0.5 建立 Worktree                         │
│  → 否則，直接進入 CP1                                           │
└─────────────────────────────────────────────────────────────────┘

詳見 CP0.5: Worktree 準備

與其他檢查點的關係

CP0 (北極星錨定) → [CP0.5 Worktree?] → CP1 (Memory 搜尋) → ... → CP3 → ... → CP6 → [CP6.5 完成?]
     ↑                                                              │                    │
     └──────────────────────────────────────────────────────────────┴────────────────────┘
                                    讀取北極星進行比對

Checkpoint 0.5: Worktree 準備 - 隔離環境建立

🔒 條件性檢查點 - 符合條件時強制執行

>

💡 核心價值：為高風險任務建立安全的隔離環境

規則

┌─────────────────────────────────────────────────────────────────┐
│  🔒 Worktree 準備（條件觸發）                                    │
│                                                                 │
│  CP0 北極星錨定後，判斷是否需要隔離環境：                        │
│                                                                 │
│  強制觸發條件（任一）：                                          │
│  • 架構等級 Level 2（新模組/服務/整合）                         │
│  • --autonomous 模式                                            │
│  • spec-workflow 並行任務                                       │
│  • 用戶明確要求隔離                                             │
│                                                                 │
│  建議觸發條件（任一）：                                          │
│  • 預期執行時間 > 30 分鐘                                       │
│  • 涉及核心模組修改                                             │
│  • 實驗性開發（「試試看」「實驗一下」）                          │
│                                                                 │
│  ❌ 不觸發：Level 0 小修改、純探索、Memory 操作                  │
│  ✅ 觸發後：所有後續 CP 在 Worktree 內執行                       │
└─────────────────────────────────────────────────────────────────┘

觸發條件

執行流程

┌─────────────────────────────────────────────────────────────────┐
│                    CP0.5 執行流程                               │
│                                                                 │
│              CP0 北極星錨定完成                                  │
│                       ↓                                         │
│               判斷是否需要 Worktree                              │
│                       │                                         │
│         ┌─────────────┴─────────────┐                           │
│         ↓                           ↓                           │
│      需要                        不需要                         │
│         ↓                           ↓                           │
│   選擇目錄位置                  跳過 CP0.5                       │
│         ↓                           ↓                           │
│   驗證 gitignore               直接進入 CP1                      │
│         ↓                                                       │
│   建立 Worktree                                                 │
│         ↓                                                       │
│   切換到 Worktree                                               │
│         ↓                                                       │
│   安裝依賴                                                      │
│         ↓                                                       │
│   驗證基線測試                                                  │
│         │                                                       │
│    ┌────┴────┐                                                  │
│    ↓         ↓                                                  │
│  通過      失敗                                                 │
│    ↓         ↓                                                  │
│ 進入 CP1   報告問題                                             │
│            詢問是否繼續                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step 1: 選擇目錄位置

優先順序

# 1. 檢查 .worktrees/ 是否存在
ls -d .worktrees 2>/dev/null && echo "使用 .worktrees/"

# 2. 檢查 worktrees/ 是否存在
ls -d worktrees 2>/dev/null && echo "使用 worktrees/"

# 3. 檢查 CLAUDE.md 是否有指定
grep -i "worktree.*director" CLAUDE.md 2>/dev/null

# 4. 預設使用 .worktrees/

選擇邏輯

┌─────────────────────────────────────────────────────────────────┐
│  目錄選擇邏輯                                                   │
│                                                                 │
│  .worktrees/ 存在？                                             │
│       ↓ Yes              ↓ No                                   │
│    使用它           worktrees/ 存在？                           │
│                          ↓ Yes              ↓ No                │
│                       使用它          CLAUDE.md 有指定？        │
│                                            ↓ Yes         ↓ No  │
│                                         依指定     使用 .worktrees/ │
│                                                                 │
│  兩者都存在時，優先使用 .worktrees/（隱藏目錄）                  │
└─────────────────────────────────────────────────────────────────┘

Step 2: 驗證 gitignore

⚠️ 關鍵步驟 - 防止 worktree 內容被意外提交

# 檢查目錄是否已被忽略
git check-ignore -q .worktrees 2>/dev/null

如果沒被忽略

# 立即修復
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: ignore worktrees directory"

為什麼重要

• Worktree 內容若被追蹤，會污染 git status
• 可能意外 commit 實驗性程式碼到主分支
• 造成 repository 混亂

Step 3: 建立 Worktree

命名規則

.worktrees/{task-id}/
         └── feature/{task-id}  ← 分支名稱

task-id 格式：

• spec-workflow 任務：T001, T002
• 一般任務：{日期}-{簡短描述} (例：0115-auth-refactor)
• autonomous 任務：auto-{timestamp}

建立指令

# 取得專案名稱（用於全域位置）
PROJECT=$(basename "$(git rev-parse --show-toplevel)")

# 建立 worktree + 新分支
git worktree add .worktrees/{task-id} -b feature/{task-id}

# 驗證建立成功
git worktree list

Step 4: 切換並安裝依賴

# 切換到 worktree
cd .worktrees/{task-id}

# 自動偵測並安裝依賴
if [ -f package.json ]; then
    npm install
elif [ -f pnpm-lock.yaml ]; then
    pnpm install
elif [ -f yarn.lock ]; then
    yarn install
elif [ -f requirements.txt ]; then
    pip install -r requirements.txt
elif [ -f pyproject.toml ]; then
    poetry install
elif [ -f Cargo.toml ]; then
    cargo build
elif [ -f go.mod ]; then
    go mod download
fi

Step 5: 驗證基線測試

# 執行測試
npm test                    # Node.js
pytest                      # Python
cargo test                  # Rust
go test ./...               # Go

# 預期結果：所有測試通過

測試失敗處理

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️ 基線測試失敗                                                │
│                                                                 │
│  測試結果：5 passed, 2 failed                                   │
│                                                                 │
│  失敗的測試：                                                   │
│  • test_user_login - AssertionError                            │
│  • test_api_response - TimeoutError                            │
│                                                                 │
│  這些測試在建立 Worktree 前就已經失敗。                         │
│  你想要：                                                       │
│                                                                 │
│  A) 繼續（記錄這些是既有問題）                                  │
│  B) 取消（先修復主分支的測試）                                  │
│  C) 忽略失敗的測試繼續                                          │
└─────────────────────────────────────────────────────────────────┘

完成信號

┌─────────────────────────────────────────────────────────────────┐
│  ✅ Worktree 準備完成                                           │
│                                                                 │
│  位置：/path/to/project/.worktrees/{task-id}                    │
│  分支：feature/{task-id}                                        │
│  測試：47 passed, 0 failed                                      │
│                                                                 │
│  → 進入 CP1: Memory 搜尋                                        │
└─────────────────────────────────────────────────────────────────┘

錯誤處理

常見錯誤

回滾機制

# 如果 CP0.5 任何步驟失敗
git worktree remove .worktrees/{task-id} --force 2>/dev/null
git branch -D feature/{task-id} 2>/dev/null

# 報告失敗，回退到 main 分支執行

與其他檢查點的關係

CP0 (北極星錨定)
     ↓
CP0.5 (Worktree 準備) ← 你在這裡
     ↓
CP1 (Memory 搜尋) ← 在 Worktree 內執行
     ↓
... 所有後續 CP 都在 Worktree 內 ...
     ↓
CP6.5 (Worktree 完成) ← 合併或清理

相關資源

• 隔離環境概述
• CP6.5: Worktree 完成
• Git Worktree 官方文檔

Checkpoint 1: 任務開始前 - 主動查 Memory + Skill 推薦

🚨 強制檢查點 - 不可跳過

規則

🔍 任務開始前（強制）

執行任何任務前，必須先搜尋相關經驗和推薦 Skill：

• [ ] 搜尋相關記憶（優先 Memory MCP，回退 Grep）
• [ ] 搜尋失敗經驗（避免重複踩坑）
• [ ] 🆕 搜尋相關 Skill（自動推薦）
• [ ] 有找到 → 閱讀並應用
• [ ] 沒找到 → 記錄「無相關經驗」，繼續執行

❌ 禁止：不查 memory 就開始執行 ✅ 必須：每個任務開始前都執行搜尋

搜尋方式

方式一：Memory MCP（推薦）

若 Memory MCP 可用，使用 FTS5 全文搜尋（更快、更精確）：

# 1. 搜尋相關記憶
memory_search({
    "query": "關鍵字1 OR 關鍵字2",  # 支援 FTS5 語法
    "scope": "global",               # 跨專案搜尋
    "limit": 10
})

# 2. 搜尋類似失敗經驗
failure_search({
    "query": "可能的錯誤類型",
    "limit": 5
})

FTS5 搜尋語法：

• word1 word2 - 同時包含
• word1 OR word2 - 任一包含
• "exact phrase" - 精確匹配

方式二：Grep（回退方案）

若 Memory MCP 不可用：

# 使用 Grep 工具搜尋
Grep(
    pattern="關鍵字1|關鍵字2",
    path=".claude/memory/",
    output_mode="files_with_matches"
)

# 找到後讀取內容
Read(file_path=".claude/memory/learnings/xxx.md")

Skill 推薦（v5.5 新增）

搜尋並推薦相關的 Skill：

# 從任務描述提取關鍵字，搜尋相關 skill
memory_search({
    "query": "skill:* 量化 交易",  # 搜尋 skill 索引
    "limit": 5
})

推薦顯示格式：

🎯 發現相關 Skill:
┌────────────────────────────────────────────────────┐
│ 1. quant-trading (finance)                         │
│    repo: github:miles990/claude-domain-skills      │
│    適用: 量化交易策略開發、回測、風險管理           │
├────────────────────────────────────────────────────┤
│ 2. python (programming-languages)                  │
│    repo: github:miles990/claude-software-skills    │
│    適用: Python 程式設計最佳實踐                   │
└────────────────────────────────────────────────────┘

建議: 此任務可結合以上 skill 提升品質

Skill 索引同步

使用 sync-skills.sh 從 GitHub 同步 skill 索引：

# 同步所有 skill repos
./scripts/sync-skills.sh

# 只同步 software skills
./scripts/sync-skills.sh --software

# 只同步 domain skills
./scripts/sync-skills.sh --domain

# 列出已索引的 skills
./scripts/sync-skills.sh --list

為什麼重要

1. 避免重複踩坑 - 過去的失敗經驗能防止再次犯錯 2. 加速執行 - 過去成功的方法可以直接複用 3. 持續改進 - 每次都站在過去經驗的基礎上 4. 跨專案學習 - Memory MCP 自動共享所有專案經驗 5. 🆕 智能推薦 - 自動發現並推薦相關 Skill

Checkpoint 1.5: 一致性檢查 (Consistency Check)

🚨 強制檢查點 - 不可跳過

核心理念

先找現有的，再決定要不要新建

• ❌ 錯誤：直接寫新的 → 事後發現重複
• ✅ 正確：先搜尋 → 確認沒有 → 才動手

檢查流程

Phase 1: 基礎檢查（必執行） → 偵測是否為架構級變更 → Phase 2: 架構檢查（自動觸發）

---

Phase 1: 基礎檢查（必執行）

🔗 開始寫程式碼前（強制）

在 CP1 (Memory Search) 完成後、實際寫程式碼前：

• [ ] 1. 搜尋現有實作：用關鍵字搜尋 src/ → 有類似則複用，無則記錄「已確認無重複」
• [ ] 2. 檢查專案慣例：閱讀 CLAUDE.md / README.md 確認命名、目錄結構、錯誤處理
• [ ] 3. 檢查 Schema/API：若涉及資料結構或 API，搜尋現有定義確保一致

❌ 禁止：不搜尋就開始寫、發現類似的還另起爐灶 ✅ 必須：先確認「不是重複造輪子」、新程式碼符合既有風格

搜尋範例

1. 搜尋現有實作

# 搜尋功能相關的程式碼
Grep(
    pattern="formatDate|dateFormat|formatTime",
    path="src/",
    output_mode="files_with_matches"
)

# 搜尋類似的 utility 函數
Grep(
    pattern="export (function|const) .*[Ff]ormat",
    path="src/utils/",
    output_mode="content",
    C=3
)

# 找到後閱讀內容
Read(file_path="src/utils/time.ts")

2. 檢查專案慣例

# 閱讀專案規範
Read(file_path="CLAUDE.md")
Read(file_path="docs/CONTRIBUTING.md")

# 找類似功能的實作作為參考
Grep(
    pattern="export (function|class)",
    path="src/utils/",
    output_mode="files_with_matches",
    head_limit=5
)
# 然後閱讀其中一個作為風格參考

3. 檢查 Schema / API

# 搜尋相關型別定義
Grep(
    pattern="interface.*User|type.*User",
    path="src/types/",
    output_mode="content"
)

# 搜尋相關 API 端點
Grep(
    pattern="/api/user|userRouter",
    path="src/",
    output_mode="files_with_matches"
)

決策樹

一致性檢查清單

常見違規場景

---

Phase 2: 架構檢查（自動偵測觸發）

Phase 2 不是每次都執行，而是根據變更範圍自動判斷

觸發條件

以下任一條件成立時，自動觸發架構檢查：

架構檢查項目

🏗️ 架構檢查（觸發時執行）

• [ ] 1. 依賴方向檢查：確認沒有「下層依賴上層」違規（如 repository/ 不應 import controller/）
• [ ] 2. 錯誤處理一致性：搜尋現有模式，新程式碼使用相同 Error 類別
• [ ] 3. 橫切關注點：使用現有 logger/metrics，不要自己造輪子
• [ ] 4. 模式一致性：遵循 .claude/memory/patterns/ 記錄的設計模式

❌ 禁止：違反依賴方向、混用錯誤處理風格 ✅ 必須：使用既有機制、遵循已採用的模式

架構檢查範例

1. 依賴方向檢查

# 搜尋可能的違規依賴
# 假設專案分層：controller → service → repository

# 檢查 repository 是否錯誤依賴 controller
Grep(
    pattern="from.*controller|import.*controller",
    path="src/repositories/",
    output_mode="content"
)

# 檢查 service 是否錯誤依賴 controller
Grep(
    pattern="from.*controller|import.*controller",
    path="src/services/",
    output_mode="content"
)

2. 錯誤處理一致性

# 搜尋現有的錯誤處理模式
Grep(
    pattern="throw new|raise |class.*Error|catch|except",
    path="src/",
    output_mode="content",
    head_limit=20
)

# 找到後確認新程式碼使用相同模式
# 例：專案用 AppError → 新程式碼也應該用 AppError

3. 橫切關注點

# 搜尋現有的 logging 機制
Grep(
    pattern="logger\\.|log\\.|console\\.log",
    path="src/",
    output_mode="files_with_matches"
)

# 若專案有統一的 logger，新程式碼不應該直接用 console.log

4. 模式一致性

# 檢查專案是否有記錄設計模式
Read(file_path=".claude/memory/patterns/design-patterns-in-use.md")

# 或搜尋現有的 pattern 實作
Grep(
    pattern="Repository|Factory|Strategy|Singleton",
    path="src/",
    output_mode="files_with_matches"
)

架構檢查清單

觸發判斷邏輯

Phase 1 完成 → 檢查變更範圍 → 觸發條件判斷（任一為 Yes → Phase 2，否則跳過）

---

與 CP1 的關係

→ 所有檢查完成後才開始寫程式碼

為什麼重要

1. 避免重複造輪子 - 不要寫已經存在的東西 2. 維持程式碼一致性 - 新舊程式碼風格統一 3. 降低維護成本 - 不會有多個做相同事情的實作 4. 加速開發 - 複用比新建更快

Checkpoint 2: 程式碼變更後 - 編譯 + 測試

🚨 強制檢查點 - 不可跳過

規則

┌─────────────────────────────────────────────────────────────────┐
│  🔨 程式碼變更後（強制）                                        │
│                                                                 │
│  任何程式碼變更後，必須驗證：                                   │
│                                                                 │
│  □ 編譯通過（最低門檻，不可跳過）                               │
│    - npm run build / tsc / python -m py_compile                 │
│    - 編譯失敗 → 禁止繼續下一個任務                              │
│                                                                 │
│  □ 相關測試通過（如果有的話）                                   │
│    - npm test -- --related / pytest                             │
│    - 測試失敗 → 修復後才能繼續                                  │
│                                                                 │
│  ❌ 禁止：連續修改多個檔案不驗證                                │
│  ❌ 禁止：編譯失敗還繼續下一個任務                              │
│  ✅ 必須：每次變更後立即驗證                                    │
└─────────────────────────────────────────────────────────────────┘

驗證命令（依專案類型）

Boris Tip #13: 驗證迴圈是王道

給 Claude 驗證工作的方式，品質提升 2-3 倍

自動化驗證策略：

• □ 執行測試：npm test / pytest / go test
• □ 執行構建：npm run build / tsc / cargo build
• □ Lint 檢查：eslint / prettier --check
• □ 型別檢查：tsc --noEmit

驗證失敗 → 不進入下一步，先修復

Checkpoint 3: Milestone 完成後 - 目標確認 + 方向校正

🚨 強制檢查點 - 不可跳過

>

💡 v4.4 強化：整合北極星方向校正，防止專案迷失

規則

┌─────────────────────────────────────────────────────────────────┐
│  🎯 Milestone 完成後（強制）                                    │
│                                                                 │
│  每個 Milestone 完成時，必須回答三個問題：                      │
│                                                                 │
│  1. 現在的目標是什麼？                                          │
│     → 重新確認當前要達成的目標                                  │
│     → 若有北極星：對照北極星的「完成標準」                      │
│                                                                 │
│  2. 方向有沒有偏離目標？                                        │
│     → 檢視已完成的工作是否朝向目標前進                          │
│     → 若有北極星：檢查是否做了「不做清單」的東西                │
│                                                                 │
│  3. 下一步是什麼？                                              │
│     → 明確下一個行動，而非盲目繼續                              │
│     → 若有北極星：下一步是否讓我們更接近完成標準？              │
│                                                                 │
│  ❌ 禁止：用戶說「繼續」就盲目繼續                              │
│  ❌ 禁止：完成後直接跳到下一個而不回顧                          │
│  ✅ 必須：主動報告進度並等待確認                                │
└─────────────────────────────────────────────────────────────────┘

北極星方向校正（v4.4 新增）

若專案有北極星文件，CP3 需額外執行方向校正：

┌─────────────────────────────────────────────────────────────────┐
│  🧭 方向校正（若有北極星）                                      │
│                                                                 │
│  Step 1: 讀取北極星                                             │
│  → .claude/memory/north-star/{project-name}.md                  │
│                                                                 │
│  Step 2: 回答三個關鍵問題                                       │
│                                                                 │
│  Q1: 這次的工作讓「完成標準」更接近打勾了嗎？                   │
│      □ 是 → 繼續                                               │
│      □ 否 → 分析原因                                           │
│                                                                 │
│  Q2: 有沒有做了「不做清單」裡的東西？                           │
│      □ 沒有 → 繼續                                             │
│      □ 有 → Scope Creep 警告                                   │
│                                                                 │
│  Q3: 下一步是否會讓我們更接近北極星？                           │
│      □ 是 → 繼續                                               │
│      □ 不確定 → 需要重新規劃                                   │
│                                                                 │
│  Step 3: 處理偏離                                               │
│  若任何問題答案是負面的：                                       │
│  → 通知用戶偏離情況                                             │
│  → 提供選項：調整回正軌 / 更新北極星 / 繼續但記錄              │
└─────────────────────────────────────────────────────────────────┘

偏離處理選項

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️ 偵測到方向偏離                                              │
│                                                                 │
│  北極星願景：[願景內容]                                         │
│  偏離情況：[描述]                                               │
│                                                                 │
│  請選擇：                                                       │
│  A) 調整回正軌 - 移除偏離的工作，重新聚焦                       │
│  B) 更新北極星 - 這個方向是對的，更新目標                       │
│  C) 繼續並記錄 - 知道偏離了，但這次先繼續                       │
│  D) 暫停討論 - 需要更多思考                                     │
└─────────────────────────────────────────────────────────────────┘

進度報告模板

┌─────────────────────────────────────────────────────┐
│  📊 進度更新                                        │
│                                                     │
│  目標：[原始目標]                                   │
│  進度：███████░░░ 70%                               │
│                                                     │
│  ✅ 已完成：                                        │
│     - [完成項目 1]                                  │
│     - [完成項目 2]                                  │
│                                                     │
│  🔄 進行中：                                        │
│     - [當前項目]                                    │
│                                                     │
│  ⏳ 待完成：                                        │
│     - [待做項目 1]                                  │
│     - [待做項目 2]                                  │
│                                                     │
│  📝 學習記錄：                                      │
│     - 發現：[新發現]                                │
│     - 已儲存到：.claude/memory/learnings/           │
└─────────────────────────────────────────────────────┘

為什麼重要

防止「目標漂移」- 執行過程中不知不覺偏離原始目標

Checkpoint 3.5: Memory 同步

創建 Memory 文件後，立即同步（index.md + Memory MCP）

觸發時機

當執行以下操作後：

• Write 到 .claude/memory/learnings/*.md
• Write 到 .claude/memory/failures/*.md
• Write 到 .claude/memory/decisions/*.md
• Write 到 .claude/memory/patterns/*.md

強制步驟

Step 1: Write memory file (Markdown)
        ↓
Step 2: Edit index.md (添加條目)
        ↓
Step 3: memory_write (同步到 SQLite 索引)  ← Memory MCP
        ↓
Step 4: Verify (確認已更新)

範例

完整流程（Git Memory + Memory MCP）

# Step 1: 創建 memory 文件（詳細內容）
Write(
    file_path=".claude/memory/learnings/2026-01-16-new-learning.md",
    content="..."
)

# Step 2: 立即更新 index.md（不可省略！）
Edit(
    file_path=".claude/memory/index.md",
    old_string="<!-- LEARNINGS_START -->",
    new_string="<!-- LEARNINGS_START -->\n- [New Learning](learnings/2026-01-16-new-learning.md) - tag1, tag2"
)

# Step 3: 同步到 Memory MCP（加速搜尋）
memory_write({
    "key": "learning:2026-01-16:new-learning",
    "content": "一句話摘要，方便 FTS5 搜尋",
    "tags": ["tag1", "tag2"],
    "scope": "global",
    "source": "evolve"
})

# Step 4: 驗證
Read(file_path=".claude/memory/index.md")

Memory MCP 不可用時（回退方案）

# 只執行 Step 1, 2, 4（跳過 Step 3）

雙重記錄的意義

建議：

• Git Memory = 詳細文件（完整 context）
• Memory MCP = 搜尋索引（快速定位）

常見錯誤

背景

此檢查點源自 evolve-trader 專案的實際失敗經驗：

• 創建多個 memory 文件後忘記更新 index.md
• 用戶反饋：「我看 .claude/memory 沒有新的紀錄」
• 根本原因：儲存與索引是兩個分離的動作，容易忽略後者

Checkpoint 4: 涌現檢查 (Optional)

迭代完成後，檢查是否有涌現機會

觸發時機

• 每次迭代完成後（可選）
• 連續成功 3+ 次後（建議）
• 用戶開啟 --emergence 或 --explore 模式

檢查項目

1. 模式識別

是否發現可重用的模式？

問自己：
- 這個解決方案適用於其他類似問題嗎？
- 有沒有步驟可以抽象成通用流程？
- 這個 pattern 出現過幾次了？

2. 跨領域連結

是否發現領域之間的連結？

問自己：
- 這個任務涉及哪些領域？
- 這些領域的組合是否創造新價值？
- 有沒有「意料之外」的發現？

3. 技能蒸餾

是否值得創建新 skill？

蒸餾條件：
- 同類型任務成功 5+ 次
- 形成了可複用的流程
- 現有 skill 不完全匹配

記錄發現

若有值得記錄的涌現，寫入 .claude/memory/discoveries/：

---
date: YYYY-MM-DD
type: connection | pattern | insight | hypothesis
confidence: high | medium | low
related_skills: [skill-a, skill-b]
---

## 發現
[描述發現的內容]

## 觸發情境
[什麼情況下發現的]

## 潛在應用
[可能的應用方向]

涌現等級

詳見 emergence-levels.md

Checkpoint 5: 失敗後驗屍（Failure Post-Mortem）

🚨 強制檢查點 - PDCA Check 失敗時觸發

>

靈感來源：SAGE (Self-Attributing) + GEPA (Reflective Evaluation)

觸發條件

強制輸出格式

每次觸發 CP5 後，必須生成結構化 Lesson 並存入 .claude/memory/lessons/：

---
date: "YYYY-MM-DD"
task: "[任務描述]"
failure_id: "[YYYYMMDD-HHMM-簡短描述]"

classification:
  type: "A|B|C|D|E"  # 見下方類型說明
  confidence: "high|medium|low"

diagnosis:
  symptom: "[具體錯誤現象]"
  error_message: "[錯誤訊息原文]"
  root_cause: "[根本原因分析 - 5 Whys]"

lesson:
  principle: "[一句話通用原則，可在其他場景重用]"
  applicable_to:
    - "[適用場景 1]"
    - "[適用場景 2]"
  not_applicable_when: "[不適用情境]"

correction:
  action_taken: "[採取的修正措施]"
  outcome: "success|partial|failed"
  time_to_fix: "[修復耗時]"

tags: [tag1, tag2, tag3]
---

## 失敗背景

[詳細描述失敗發生的上下文]

## 診斷過程

[記錄分析過程，包括排除的假設]

## 關鍵洞察

[最重要的發現，未來應該記住的事]

失敗類型分類（Type A-E）

Post-Mortem 引導問題

執行 CP5 時，依序回答以下問題：

1. 現象確認

• 發生了什麼？（具體錯誤）
• 預期行為是什麼？
• 實際行為是什麼？

2. 根因分析（5 Whys）

• Why 1: 為什麼失敗？
• Why 2: 為什麼會這樣？
• Why 3: 為什麼沒有預防？
• Why 4: 為什麼沒有偵測到？
• Why 5: 根本原因是什麼？

3. 通用化

• 這個教訓可以泛化到什麼場景？
• 什麼情況下這個教訓不適用？
• 用一句話總結核心原則

4. 預防措施

• 如何避免再次發生？
• 需要更新哪些 Skill？
• 需要添加什麼檢查？

範例

---
date: "2026-01-12"
task: "建立 React 元件測試"
failure_id: "20260112-1430-jest-config-missing"

classification:
  type: "C"
  confidence: "high"

diagnosis:
  symptom: "執行 npm test 時報錯 'Cannot find module jest'"
  error_message: "Error: Cannot find module 'jest' from '/project'"
  root_cause: "專案使用 Vitest 而非 Jest，沒有先檢查測試框架配置"

lesson:
  principle: "執行測試前，先檢查 package.json 的 test script 確認測試框架"
  applicable_to:
    - "任何 JavaScript/TypeScript 專案的測試"
    - "CI/CD 配置"
  not_applicable_when: "已知專案測試框架的情況"

correction:
  action_taken: "改用 npm run test (實際執行 vitest)"
  outcome: "success"
  time_to_fix: "2 分鐘"

tags: [testing, javascript, environment, vitest, jest]
---

## 失敗背景

用戶要求為 React 元件添加測試。直接假設使用 Jest 並執行 `npx jest`。

## 診斷過程

1. 首先懷疑 Jest 未安裝 → 檢查 devDependencies，沒有 jest
2. 檢查 package.json scripts → 發現 `"test": "vitest"`
3. 確認使用 Vitest 而非 Jest

## 關鍵洞察

**不要假設測試框架**。JavaScript 生態有多種選擇（Jest、Vitest、Mocha、Jasmine）。
始終先檢查 `package.json` 的 `scripts.test` 欄位。

整合點

與 PDCA 的整合

Plan → Do → Check
              ↓ (失敗)
           CP5 觸發
              ↓
         生成 Lesson
              ↓
         存入 lessons/
              ↓
           Act (修正)
              ↓
         下一輪 Plan (自動載入相關 Lessons)

與 Plan 階段的整合

在 Plan 階段開始時，除了搜尋 Memory，還要：

# 搜尋相關 Lessons
Grep pattern="[任務關鍵字]" path=".claude/memory/lessons/"

Plan 階段應考慮： 1. 過去類似任務的 Lessons 2. 高頻失敗類型的預防措施 3. 最近的 Lessons（可能揭示系統性問題）

指標追蹤

建議追蹤以下指標評估 CP5 效果：

Memory MCP 整合

除了存入 .claude/memory/lessons/，也同步到 Memory MCP 以加速搜尋：

# 記錄失敗到 SQLite（供跨專案搜尋）
failure_record({
    "error_pattern": "[錯誤類型，如 TypeError: Cannot read properties]",
    "error_message": "[完整錯誤訊息]",
    "solution": "[採取的解決方案]",
    "skill_name": "evolve",
    "project_path": "/path/to/project"
})

效益：

• 下次遇到類似錯誤時，CP1 的 failure_search 可快速找到解法
• 跨專案共享失敗經驗，避免在不同專案重複踩坑
• FTS5 搜尋比 Grep 快 5-6x，Token 節省 91%

護欄

• ❌ 不可跳過 CP5（失敗後必須執行）
• ❌ 不可省略 lesson.principle（必須提煉通用教訓）
• ❌ 不可重複相同 root_cause 超過 3 次（必須系統性解決）
• ✅ 每個 Lesson 必須有 tags 方便搜尋
• ✅ 每個 Lesson 必須記錄 time_to_fix 用於效率分析
• ✅ 同步到 Memory MCP 以加速跨專案搜尋（若可用）

Checkpoint 6: 專案健檢 - 定期方向確認

🏥 選擇性檢查點 - 長期專案建議執行

>

💡 觸發時機：每 N 次 PDCA 迭代後，或用戶要求時

規則

┌─────────────────────────────────────────────────────────────────┐
│  🏥 專案健檢（定期）                                             │
│                                                                 │
│  長期專案容易逐漸偏離方向，定期健檢防止失焦：                     │
│                                                                 │
│  觸發條件（任一）：                                              │
│  • 累計 5 次 PDCA 迭代後                                        │
│  • 距離上次健檢超過 3 天                                        │
│  • 用戶說「檢查一下方向」                                       │
│  • 感覺專案方向不明時                                           │
│                                                                 │
│  健檢內容：                                                     │
│  1. Scope 檢查 - 有沒有做「不做清單」裡的東西？                 │
│  2. 方向檢查 - 離北極星更近了嗎？                               │
│  3. 終止檢查 - 這個專案還值得繼續嗎？                           │
│                                                                 │
│  ✅ 建議：大型專案每週至少一次健檢                               │
│  ✅ 建議：感覺迷失時主動觸發健檢                                 │
└─────────────────────────────────────────────────────────────────┘

觸發條件

健檢三部曲

1. Scope 檢查

┌─────────────────────────────────────────────────────────────────┐
│  📏 Scope 檢查                                                  │
│                                                                 │
│  讀取北極星的「不做清單」，對照目前進度：                        │
│                                                                 │
│  不做清單：                                                     │
│  ❌ [排除項目 1]                                                │
│  ❌ [排除項目 2]                                                │
│                                                                 │
│  問題：我們有沒有不小心做了「不做」的東西？                      │
│                                                                 │
│  若有 Scope Creep：                                             │
│  → 警告用戶                                                     │
│  → 提供選項：                                                   │
│     A) 移除超出範圍的功能                                       │
│     B) 更新北極星，正式納入範圍                                 │
│     C) 繼續，但標記為「額外功能」                               │
└─────────────────────────────────────────────────────────────────┘

2. 方向檢查

┌─────────────────────────────────────────────────────────────────┐
│  🧭 方向檢查                                                    │
│                                                                 │
│  讀取北極星的「完成標準」，評估進度：                            │
│                                                                 │
│  完成標準：                                                     │
│  - [x] [標準 1] ← 已完成                                        │
│  - [ ] [標準 2] ← 未完成                                        │
│  - [ ] [標準 3] ← 未完成                                        │
│                                                                 │
│  問題：最近的工作是否讓我們更接近完成標準？                      │
│                                                                 │
│  若偏離方向：                                                   │
│  → 分析偏離原因                                                 │
│  → 提供選項：                                                   │
│     A) 調整回正軌                                               │
│     B) 更新北極星（方向本身需要調整）                           │
│     C) 暫停並重新評估                                           │
└─────────────────────────────────────────────────────────────────┘

3. 終止檢查

┌─────────────────────────────────────────────────────────────────┐
│  🛑 終止檢查                                                    │
│                                                                 │
│  讀取北極星的「當初為什麼開始」：                                │
│                                                                 │
│  > [當初的動機]                                                 │
│                                                                 │
│  問題：這個動機還存在嗎？專案還值得繼續嗎？                      │
│                                                                 │
│  終止信號（任一）：                                              │
│  • 原始動機已不存在                                             │
│  • 有更好的替代方案出現                                         │
│  • 成本已超過預期收益                                           │
│  • 連續 3 次健檢方向都偏離                                      │
│                                                                 │
│  若建議終止：                                                   │
│  → 提供選項：                                                   │
│     A) 繼續（用戶堅持）                                         │
│     B) 暫停（保留進度，之後再說）                               │
│     C) 放棄（標記為 abandoned）                                 │
│     D) Pivot（重新定義北極星）                                  │
└─────────────────────────────────────────────────────────────────┘

健檢報告模板

┌─────────────────────────────────────────────────────────────────┐
│  🏥 專案健檢報告                                                │
│                                                                 │
│  專案：[專案名稱]                                               │
│  日期：[日期]                                                   │
│  迭代次數：#N（自上次健檢：M 次）                               │
│                                                                 │
│  ═══════════════════════════════════════════════════════════   │
│                                                                 │
│  📏 Scope 檢查：[✅ 正常 | ⚠️ 有 Creep | ❌ 嚴重偏離]          │
│     [說明]                                                      │
│                                                                 │
│  🧭 方向檢查：[✅ 正軌 | ⚠️ 輕微偏離 | ❌ 嚴重偏離]            │
│     完成進度：[2/5] 項                                          │
│     [說明]                                                      │
│                                                                 │
│  🛑 終止檢查：[✅ 繼續 | ⚠️ 需討論 | ❌ 建議終止]              │
│     [說明]                                                      │
│                                                                 │
│  ═══════════════════════════════════════════════════════════   │
│                                                                 │
│  📋 建議行動：                                                  │
│     • [行動 1]                                                  │
│     • [行動 2]                                                  │
│                                                                 │
│  下次健檢：[迭代 #N+5 或 3 天後]                                │
└─────────────────────────────────────────────────────────────────┘

健檢後更新北極星

健檢完成後，更新北極星文件的健康檢查記錄：

## 健康檢查記錄

| 日期 | 迭代 | Scope | 方向 | 結論 |
|------|------|-------|------|------|
| 2026-01-12 | #1 | ✅ | ✅ | 初始建立 |
| 2026-01-15 | #6 | ✅ | ⚠️ | 輕微偏離，已調整 |
| 2026-01-18 | #11 | ⚠️ | ✅ | 移除額外功能 |

CP6 執行流程

┌─────────────────────────────────────────────────────────────────┐
│                     CP6 執行流程                                │
│                                                                 │
│                  觸發條件滿足                                    │
│                       ↓                                         │
│               讀取北極星文件                                     │
│                       ↓                                         │
│         ┌─────────────────────────┐                             │
│         │ 1. Scope 檢查           │                             │
│         │    對照「不做清單」     │                             │
│         └─────────────────────────┘                             │
│                       ↓                                         │
│         ┌─────────────────────────┐                             │
│         │ 2. 方向檢查             │                             │
│         │    對照「完成標準」     │                             │
│         └─────────────────────────┘                             │
│                       ↓                                         │
│         ┌─────────────────────────┐                             │
│         │ 3. 終止檢查             │                             │
│         │    對照「當初為什麼」   │                             │
│         └─────────────────────────┘                             │
│                       ↓                                         │
│               生成健檢報告                                       │
│                       ↓                                         │
│              更新北極星記錄                                      │
│                       ↓                                         │
│         ┌─────────────────────────┐                             │
│         │ 需要用戶決策？          │                             │
│         └─────────────────────────┘                             │
│              ↓ Yes          ↓ No                                │
│        AskUserQuestion    繼續執行                              │
│              ↓                                                  │
│         根據決策行動                                             │
└─────────────────────────────────────────────────────────────────┘

與其他檢查點的關係

CP0 (建立北極星)
     ↓
CP1 → CP1.5 → CP2 → CP3 (方向校正) → ...
                          ↑
                          │ 每 5 次迭代
                          ↓
                    CP6 (專案健檢)
                          │
                          ↓ 讀取
                    北極星文件

為什麼重要

1. 長期專案容易迷失 - 定期檢查防止漸進式偏離 2. Scope Creep 是隱形殺手 - 小功能累積成大問題 3. 及時止損 - 發現專案不值得繼續時果斷終止 4. 保持動力 - 看到進度讓人有成就感

Worktree 清理（v5.1 新增）

若任務使用了 Worktree，CP6 完成後需要執行 CP6.5 進行清理：

┌─────────────────────────────────────────────────────────────────┐
│  🏁 Worktree 清理判斷                                           │
│                                                                 │
│  使用了 Worktree?                                               │
│       ↓ Yes              ↓ No                                   │
│   進入 CP6.5          結束流程                                  │
│       │                                                         │
│       ├── 成功 → 合併 + 清理 Worktree                          │
│       ├── 失敗 → 記錄教訓 + 刪除 Worktree                       │
│       └── 暫停 → 保留 Worktree + 鎖定                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

詳見 CP6.5: Worktree 完成

03-memory

Git-based 記憶系統：版本控制、可追溯、可協作

本模組包含

記憶結構

.claude/memory/
├── index.md          # 快速索引（必須維護）
├── learnings/        # 成功經驗
├── failures/         # 失敗教訓
├── decisions/        # 決策記錄 (ADR)
├── patterns/         # 推理模式
├── strategies/       # 策略記錄
├── discoveries/      # 涌現發現
└── skill-metrics/    # 技能效果追蹤

關鍵操作

# 搜尋
Grep(pattern="關鍵字", path=".claude/memory/")

# 儲存後必須同步 index.md（CP3.5）
Write(...) → Edit(index.md) → Verify

社群貢獻

{{NAME}}

{{DESCRIPTION}}

When to Use

• {{USE_CASE_1}}
• {{USE_CASE_2}}

Instructions

{{INSTRUCTIONS}}

Examples

{{EXAMPLE}}

Notes

{{NOTES}}