Evolve

⚠️ This file has moved

The Self-Evolving Agent skill has been reorganized into an atomic architecture.

New Location

👉 [skills/SKILL.md](./skills/SKILL.md)

Quick Links

Why the Change?

• Easier to maintain: Small modules > monolithic file
• Easier to contribute: Community content in community/ directories
• Easier to learn: Read modules progressively
• Easier to extend: Add new modules without touching existing content

Migration

If you were using the old SKILL.md, simply update your imports:

Old: SKILL.md (2000+ lines)
New: skills/SKILL.md (entry point) + skills/*/_base/*.md (modules)

ADR-001: 整合 CP5 失敗後驗屍機制

狀態

已接受 (Accepted)

背景

Self-Evolving Agent 原有 4 個強制檢查點 (CP1-CP4)：

• CP1: 任務開始前搜尋 Memory
• CP2: 程式碼變更後驗證
• CP3: Milestone 完成後確認方向
• CP4: 迭代完成後涌現檢查

然而，當 PDCA Check 階段失敗時，缺乏結構化的失敗分析機制。失敗經驗雖然會記錄到 failures/，但格式不統一，缺乏可搜尋性和可複用性。

決策

新增 Checkpoint 5 (CP5): 失敗後驗屍 (Failure Post-Mortem)

觸發條件

• PDCA Check 失敗時
• 測試/構建失敗時
• 連續 2 次嘗試失敗時
• 用戶反饋「不對」時

強制輸出

每次觸發 CP5 必須生成結構化 Lesson 到 .claude/memory/lessons/，包含：

• 失敗分類 (Type A-E)
• 5 Whys 根因分析
• 可泛化的 lesson.principle
• 修正措施和結果

失敗分類

理由

1. 結構化學習: 統一的 Lesson 格式讓失敗經驗可搜尋、可複用 2. 防止重複犯錯: 明確的 applicable_to 和 not_applicable_when 欄位 3. 量化改進: 可追蹤 重複失敗率 和 修復成功率 4. 與 PDCA 整合: 下一輪 Plan 自動載入相關 Lessons

替代方案

1. 只用現有 failures/ 目錄 - 拒絕，格式不統一 2. 外部服務記錄 - 拒絕，違反 Git-based 原則 3. 只記錄不分類 - 拒絕，缺乏診斷指導

後果

正面

• 失敗經驗成為結構化知識
• PDCA 循環更加完整
• 可追蹤學習效果指標

負面

• 每次失敗需要額外時間寫 Lesson
• 新增目錄 lessons/ 增加結構複雜度

風險

• Lesson 品質取決於 AI 的分析能力
• 需要用戶配合觸發 CP5

參考

• SAGE (Self-Attributing) - 自我歸因框架
• GEPA (Genetic Pareto) - 反思評估

Discoveries (涌現發現記錄)

此目錄用於記錄在執行任務過程中的意外發現和涌現現象。

記錄時機

當發現以下情況時，應該記錄：

1. 連結發現 (connection) - 發現兩個看似無關的 skill 或概念可以組合 2. 模式發現 (pattern) - 發現可重複使用的模式 3. 洞察發現 (insight) - 對某個問題有了新的理解 4. 假設發現 (hypothesis) - 值得驗證的假設

檔案命名

YYYY-MM-DD-discovery-name.md

例如：2026-01-07-marketing-gamification-connection.md

檔案格式

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

## 發現

[描述發現的內容]

## 觸發情境

[什麼情況下發現的]

## 潛在應用

[可能的應用方向]

## 後續行動

- [ ] 驗證假設
- [ ] 建立新 skill
- [ ] 整合到現有機制

相關文檔

• 涌現機制設計
• SKILL.md - 涌現觸發條件

錯誤宣稱測試通過

情境

在增加測試覆蓋任務中，新增了 3 個 bats 測試文件後，宣稱「測試全部通過」。

錯誤

• bats 未安裝，實際上新增的測試完全沒有運行
• 只運行了 --quick 模式（6 個基本檢查）
• 錯誤地將「快速驗證通過」等同於「所有測試通過」

根本原因

1. 未驗證前提條件：沒有確認 bats 是否安裝就宣稱測試通過 2. 混淆不同測試層級：quick validation ≠ full test suite 3. 過早下結論：在實際驗證完成前就報告結果

正確做法

# 1. 先確認測試工具是否可用
command -v bats && echo "bats available" || echo "bats NOT installed"

# 2. 運行完整測試並查看結果
./tests/run_tests.sh

# 3. 確認所有測試通過後才報告
# "73/73 測試全部通過" 而非 "測試通過"

教訓

1. 驗證再報告：任何宣稱都需要實際執行結果支持 2. 明確範圍：報告時說明測試的具體範圍和數量 3. 承認限制：如果某些測試無法運行，明確說明

專案記憶索引

搜尋：Grep pattern="關鍵字" path=".claude/memory/"

研究報告

<!-- RESEARCH_START -->

• Everything Claude Code 分析 - claude-code, plugin, hooks, eval-harness, continuous-learning, agents, competitor, twitter-guide, session-management, parallelization, orchestrator, pass-at-k
• 多 Agent 研究框架綜合報告 - multi-agent, collaboration, evolve-skill, synthesis, architecture
• 多 Agent 協作架構研究 - multi-agent, architecture, state-management, collaboration-modes
• 認知科學視角：多 Agent 框架 - multi-agent, cognitive-science, thinking-methodologies, role-design
• 產業視角：多 Agent 框架分析 - multi-agent, autogen, crewai, langgraph, metagpt, design-patterns
• MCP 進階設計模式詳解 - mcp, full-ai-processing, progressive-discovery, code-execution, detailed
• MCP Server 設計模式比較 - mcp, design-patterns, data-tools, code-execution, workflow, architecture
• Knowledge Nexus 專案分析 - mcp, knowledge-management, go, mcp-data-tools, spec-workflow

<!-- RESEARCH_END -->

最近學習

<!-- LEARNINGS_START -->

• Code Execution Skill 開發 - code-execution, mcp, token-optimization, skill-design
• SDD 規格驅動開發 - 高見龍 - sdd, spec-driven, methodology, ai-collaboration, kaochenlong
• 版本發布工作流教訓 - release, macos, sed, plugin-cache, bash, version-update
• Memory MCP 整合設計 - memory, mcp, integration, sqlite, evolve
• Galgame Skill 通用化經驗 - skill-design, generalization, galgame, character-design, abstraction
• Flame Game Engine Skill 開發 - flame, flutter, dart, 2d-games, skill-creation
• ~~skillpkg 分層載入機制研究~~ - ⚠️ 已封存 (skillpkg 已棄用)
• ~~Evolve Token 優化研究~~ - ⚠️ 已封存 (skillpkg 已棄用)
• 深度訪談模式 - Benson Sun 技巧 - goal-analysis, deep-interview, spec, requirements, benson-sun
• code-simplifier Plugin 整合 - code-simplifier, plugin, refactoring, technical-debt, boris-cherny
• 自我進化流程：修改 Skill 的正確順序 - self-evolution, skill-modification, workflow, source-of-truth
• Makefile 優化 + 探索模式 - makefile, automation, explore-mode, level-1, memory-stats
• CHANGELOG 自動生成腳本 - changelog, automation, bash, conventional-commits, git
• 競品分析研究洞察 - competitor-analysis, market-research, agentic-ai, strategy
• 自動化和測試改進 v4.1.0 - automation, testing, makefile, quickstart, fallback
• 專業 Skill 專案的必備元素 - skill-project, professional, automation, ci-cd, documentation
• 原子化架構（從 makepad-skills 學習） - architecture, atomic-design, skill-design, makepad-skills
• Claude Agent SDK 架構分析 - claude-agent-sdk, architecture, comparison, production
• Boris Cherny Claude Code Tips - claude-code, best-practices, verification, subagents, large-codebase, file-suggestion
• Claude Starter Kit CLI - cli, scaffold, npx, multi-select domains

<!-- LEARNINGS_END -->

北極星與計劃

<!-- PLANS_START -->

• 北極星: 多 Agent 研究框架 - multi-agent, collaboration, evolve-skill, research ✅ 已完成
• 北極星: SQLite Memory 系統 - sqlite, memory, ecosystem, token-optimization
• PDCA Plan: SQLite 統一架構 - sqlite, mcp-server, skillpkg, architecture

<!-- PLANS_END -->

重要決策

<!-- DECISIONS_START -->

• ADR-001: 整合 CP5 失敗後驗屍機制 - checkpoint, failure-handling, learning, pdca

<!-- DECISIONS_END -->

失敗經驗

<!-- FAILURES_START -->

• 錯誤宣稱測試通過 - testing, verification, communication, false-positive

<!-- FAILURES_END -->

推理模式

<!-- PATTERNS_START --> <!-- PATTERNS_END -->

策略記錄

<!-- STRATEGIES_START -->

• Subagent 策略 - verify-app, code-simplifier, build-validator (Boris Tip #8)

<!-- STRATEGIES_END -->

涌現發現 (v3.6 新增)

<!-- DISCOVERIES_START --> <!-- DISCOVERIES_END -->

詳見：discoveries/README.md

技能效果追蹤 (v3.6 新增)

• 技能排行榜
• 涌現指標

標籤索引

<!-- TAGS_START -->

• deep-interview: deep-interview-mode
• goal-analysis: deep-interview-mode
• spec: deep-interview-mode
• benson-sun: deep-interview-mode
• architecture: claude-agent-sdk-analysis
• best-practices: boris-cherny-tips
• teleport: boris-cherny-tips
• permissions: boris-cherny-tips
• claude-agent-sdk: claude-agent-sdk-analysis
• claude-code: boris-cherny-tips
• cli: claude-starter-kit-cli
• comparison: claude-agent-sdk-analysis
• production: claude-agent-sdk-analysis
• scaffold: claude-starter-kit-cli
• subagents: boris-cherny-tips
• verification: boris-cherny-tips
• workflow: boris-cherny-tips
• large-codebase: boris-cherny-tips
• file-suggestion: boris-cherny-tips

<!-- TAGS_END -->

Boris Cherny 的 Claude Code 使用技巧

情境

Boris Cherny 是 Claude Code 的創作者，他分享了 13 條個人使用技巧。

核心洞察

最重要的一條（Tip #13）

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

Boris 使用 Chrome extension 讓 Claude 測試 UI，開啟瀏覽器、測試、迭代直到成功。

平行化策略（Tips #1, #2）

• 本地跑 5 個 Claude（終端分頁 1-5）
• 雲端 claude.ai/code 另外跑 5-10 個
• 每個專注不同任務
• `--teleport` 命令：在本地和網頁會話之間切換
• iOS app：早上透過手機啟動會話，稍後查看進度

團隊協作（Tips #4, #5）

• 單一 CLAUDE.md 存入 git，每週更新
• PR 上 @.claude tag 自動更新（GitHub Action）

模型選擇

預設使用 Opus 4.5 + thinking 模式：雖然較慢，但品質更高，減少返工反而更快完成。

工作流程優化

長時間任務處理（Tip #12）

• Stop hook 驗證 background agent 工作
• ralph-wiggum plugin 做確定性處理
• --permission-mode=dontAsk 或 sandbox 避免阻塞

MCP 整合（Tip #11）

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://slack.mcp.anthropic.com/mcp"
    }
  }
}

整合 Slack, BigQuery, Sentry 等工具。

大型 Codebase 優化（Boris 轉推 by @leocooout）

Great tip for bigger codebases - Boris Cherny, 2026-01-10

TikTok iOS 工程師分享的優化技巧：將檔案搜尋時間從 8 秒降到 200 毫秒。

問題：預設的 fast filesystem traversal 對小專案很好，但大型專案會變慢。

解決方案：使用自訂索引系統，透過 settings.json 配置：

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

效果：在 Claude 中提及任何檔案都幾乎瞬間完成。

適用場景：

• 大型 monorepo（如 TikTok）
• 檔案數量超過數萬個的專案
• 檔案搜尋明顯變慢時

對 self-evolving-agent 的改進建議

1. 強化驗證迴圈

• PDCA Check 階段加入自動測試執行
• 整合 verify-app 概念

2. Subagents 策略池

• 加入 code-simplifier 策略
• 加入 build-validator 策略

3. Hooks 整合

• PostToolUse hook 自動格式化
• Stop hook 處理長時間進化任務

4. ralph-wiggum 整合

• 長時間任務使用 ralph-wiggum loop

核心哲學（2026-01-12 更新）

AI 是可調度的能力，而非單純的工具

Boris 的核心理念：

• 像調度計算資源一樣分配認知
• 優化吞吐量而非僅僅是對話
• 將 AI 視為可調度的能力（schedulable capability）

這解釋了為什麼他會平行運行 5-10 個 Claude：不是為了「聊得更快」，而是為了最大化整體產出。

驗證

✅ 已記錄完整 13 條技巧 ✅ 提出具體改進建議 ✅ 2026-01-12 補充：teleport、permissions、Opus thinking、哲學觀 ✅ 2026-01-12 補充：大型 codebase 優化（fileSuggestion 自訂配置）

相關檔案

• SKILL.md - self-evolving-agent 技能定義
• .claude/memory/strategies/ - 策略記錄
• .claude/memory/learnings/2026-01-12-code-simplifier-integration.md - code-simplifier 整合

Claude Agent SDK 架構分析

情境

@boringmarketer 在 X 上分享 Claude Agent SDK 的架構圖，引發社群討論。

Agent SDK 架構

GOAL: "handle this lead"
        ↓
AGENT LOOP: observe → think → act → learn → repeat
        ↓
┌─────────────┬─────────────┬─────────────┐
│ SUBAGENTS   │ SKILLS      │ TOOLS       │
│ code-review │ lead-research│ Built-in    │
│ test-runner │ email-draft │ MCP         │
│ researcher  │ (auto-invoke)│ Custom      │
│ (parallel)  │ (domain     │ (your       │
│             │  expertise) │  functions) │
└─────────────┴─────────────┴─────────────┘
        ↓
HOOKS: guard rails, logging, human-in-the-loop
        ↓
STRUCTURED OUTPUT: validated JSON matching schema

社群討論重點

Claude Code vs Agent SDK 的使用時機

Matt Stockton 的工作流程

"prototype your agent with the same building blocks directly in Claude Code - and then when it's working, there's a fairly easy path to using the SDK to run it in 'production'"

建議路徑： 1. 在 Claude Code 中原型驗證 2. 確認可行後遷移到 Agent SDK 3. 部署為生產環境服務

self-evolving-agent 對應關係

洞察

我們已經實現的

• ✅ Agent Loop（PDCA）
• ✅ Subagent 策略
• ✅ Skill 自動習得
• ✅ Hooks 整合
• ✅ 結構化輸出

可以加強的

• 🔄 更明確的「導出到 Agent SDK」路徑
• 🔄 背景執行模式（ralph-wiggum 已部分實現）
• 🔄 更豐富的 Subagent 策略池

建議發展方向

驗證

✅ 分析完成 ✅ 與現有架構對比完成 ✅ 提出改進方向

相關檔案

• SKILL.md - self-evolving-agent 技能定義
• .claude/memory/strategies/subagents.md - Subagent 策略
• .claude/memory/learnings/2025-01-07-boris-cherny-claude-code-tips.md - Boris 技巧

Claude Starter Kit CLI 開發經驗

情境

需要建立一個簡單的一鍵安裝工具，讓用戶快速設置 Claude Code 專案配置。

需求分析

用戶期望

• npx claude-starter-kit 一鍵安裝
• 簡單的 CLI 控制腳手架配置
• 支援多種專業領域（不只技術領域）

領域分類

架構決策

選擇方案 C：混合模式

• 核心內建：CLAUDE.md, 基本 rules, memory 系統模板
• 擴展下載：透過 skillpkg 安裝專業技能包

優點

1. 離線可用（核心功能） 2. 按需下載（節省空間） 3. 擴展性強（新領域只需新增 skill）

技術實作

目錄結構

cli/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts          # 入口點
    ├── commands/
    │   └── init.ts       # 主要初始化命令
    ├── templates/
    │   └── index.ts      # 內建模板
    └── domains/
        └── index.ts      # 領域配置

關鍵依賴

{
  "commander": "^12.0.0",
  "inquirer": "^9.0.0",
  "chalk": "^5.3.0",
  "ora": "^8.0.0"
}

預設模式

遇到的問題

TypeScript 類型錯誤

問題：PRESETS.skills.includes() 報錯 never 類型 原因：TypeScript 無法推斷 object literal 的類型 解決：加入明確的類型註解

const PRESETS: Record<string, {
  name: string;
  components: string[];
  skills: string[];
  domains: string[];
}> = { ... };

使用方式

# 快速安裝（推薦配置）
npx claude-starter-kit -y

# 互動式安裝
npx claude-starter-kit

# 指定預設
npx claude-starter-kit --preset full

# 跳過技能安裝
npx claude-starter-kit --no-install

相關檔案

• https://github.com/miles990/claude-starter-kit
• /Users/user/Workspace/claude-starter-kit/cli/

下一步

• 建立 claude-business-skills 專案
• 建立 claude-creative-skills 專案
• 發布到 npm

從 makepad-skills 學習原子化架構

情境

用戶發現了 https://github.com/ZhangHanDong/makepad-skills 這個 repo，想要借鏡其設計來改進 self-evolving-agent。

學習重點

makepad-skills 的設計亮點

1. 原子化架構

• 將知識拆分成獨立模組（00-06 + 99）
• 每個模組有 _base/ 和 community/ 分離
• 官方更新不會覆蓋社群貢獻

2. 自我進化機制

• Self-Evolution: 累積 patterns
• Self-Correction: 失敗時自動修正
• Self-Validation: 驗證與框架版本相容
• Personalization: 適應專案風格

3. Hook 驅動觸發

• Pre-tool: 偵測版本
• Post-failure: 識別錯誤
• Session-end: 提示記錄學習

4. 一行安裝

• curl | bash 模式
• 自動備份現有安裝

與 self-evolving-agent 的差異

實作的改進

1. 原子化改造 (v4.0.0)

• 從 2027 行 SKILL.md 拆分成模組化結構
• 7 個模組：00-getting-started 到 99-evolution
• 每個模組有 _base/ 和 community/ 目錄

2. 一行安裝腳本

   curl -fsSL .../install.sh | bash -s -- --with-hooks --with-memory

3. Hook 整合

• PostToolUse: 提醒驗證變更
• Stop: 提醒記錄學習

決定不採用的設計

• ❌ 版本相容性驗證（那是 Makepad 特定需求）
• ❌ 知識分類路由（我們有更完整的多階路由）

效果

• SKILL.md: 2027 → 191 行 (主入口)
• 模組化：11 個獨立 markdown 文件
• 社群貢獻：不會與官方更新衝突
• 安裝：一行命令完成

相關資源

• makepad-skills
• 原子化設計靈感來源

專業 Skill 專案的必備元素

情境

使用 /evolve 自我改進 self-evolving-agent 專案時，識別並修復了多個盲點，提升了專案的專業度。

發現的盲點清單

關鍵缺失

1. 缺少 .gitignore - 會導致不必要的文件被提交 2. 缺少 CLAUDE.md - AI 無法理解專案約束 3. 硬編碼絕對路徑 - skillpkg.json 中的路徑不可攜

文檔不一致

4. 過時的架構描述 - README 仍提到已移除的 community/ 目錄

專業度缺口

5. 缺少 CI - 沒有自動化驗證 6. 缺少驗證腳本 - 用戶無法快速確認安裝是否成功 7. 缺少故障排除指南 - 遇到問題無處可查

解決方案

1. 基礎文件補全

• 創建 .gitignore（排除 OS、編輯器、臨時文件）
• 創建 CLAUDE.md（專案約束、設計原則、禁止事項）
• 修復 skillpkg.json（移除硬編碼路徑，添加版本和描述）

2. 文檔更新

• 更新 README.md（移除 community 引用，更新貢獻指南）
• 添加 docs/TROUBLESHOOTING.md（常見問題解答）

3. 自動化提升

• 添加 .github/workflows/ci.yml（GitHub Actions CI）
• 創建 scripts/verify-install.sh（安裝驗證）
• 創建 scripts/validate-all.sh（一鍵全面驗證）

4. 版本管理

• 更新版本號到 v4.0.1
• 更新 CHANGELOG.md

專業 Skill 專案 Checklist

✅ .gitignore - 排除不必要文件
✅ CLAUDE.md - AI 約束文件
✅ README.md - 快速上手指南
✅ CHANGELOG.md - 變更記錄
✅ LICENSE - 授權協議
✅ docs/TROUBLESHOOTING.md - 故障排除
✅ .github/workflows/ci.yml - CI 自動化
✅ scripts/verify-install.sh - 安裝驗證
✅ scripts/validate-all.sh - 全面驗證
✅ skillpkg.json - 版本和描述（無硬編碼路徑）

效果

• 從 8 個通過 + 2 個警告 → 全部通過
• 添加 5 個新文件，更新 6 個現有文件
• v4.0.0 → v4.0.1

關鍵洞察

專業度 = 可預測性 + 可維護性 + 可自動化

• 可預測性：用戶知道會得到什麼（清晰的文檔）
• 可維護性：問題容易定位和修復（故障排除指南）
• 可自動化：減少人工操作（CI + 驗證腳本）

自動化和測試改進 (v4.1.0)

情境

繼 v4.0.1 專業度提升後，進一步增強專案的：

• 自動化程度
• 測試覆蓋
• 智能化（fallback 機制）
• 使用便利性

解決方案

1. 測試框架

創建了完整的測試套件：

tests/
├── test_skills.bats   # Bats-core 測試（完整）
└── run_tests.sh       # 測試執行器

支援兩種模式：

• --quick - 快速驗證（無外部依賴）
• --bats - 完整 bats 測試

2. Makefile 統一入口

提供了一致的命令介面：

make help       # 顯示所有命令
make test       # 執行測試
make validate   # 全面驗證
make install TARGET=/path  # 安裝到目標

3. Quick Start 腳本

一鍵設置新專案：

./scripts/quickstart.sh /path/to/project

自動完成：

• 安裝 skill
• 初始化記憶系統
• 創建 CLAUDE.md
• 設置 hooks

4. Fallback 機制

為 skill acquisition 添加了多層降級策略：

關鍵洞察

自動化 = 減少決策點 + 減少重複勞動

• Makefile 減少「要輸入什麼命令」的決策
• Quick Start 減少設置新專案的重複勞動
• Fallback 機制減少「找不到 skill 怎麼辦」的決策

效果

• v4.0.1 → v4.1.0
• 新增 6 個文件
• 測試覆蓋：6 項快速驗證 + 12 項 bats 測試
• CI 新增 quick-test job

CHANGELOG 自動生成腳本

情境

使用 /evolve 執行 Phase 1 P1 任務：建立 CHANGELOG 自動生成腳本，作為「吃自己的狗糧」的第一個真實任務。

解決方案

創建 scripts/generate-changelog.sh：

功能

• 解析 git log 中的 conventional commits
• 自動分類：feat→Added, fix→Fixed, docs→Documentation, refactor→Changed, chore→Maintenance
• 支援 scope 解析：feat(v4.2.0): 會正確提取描述
• 生成 Keep a Changelog 格式輸出

參數

--all        # 生成所有 commits
--since TAG  # 從指定 tag 開始
--preview    # 預覽不寫入
--output     # 指定輸出檔案
--help       # 顯示幫助

核心實現

# Conventional Commits 正則解析
if [[ "$MESSAGE" =~ ^feat(\(.+\))?:\ (.+) ]]; then
    FEAT_COMMITS+=("- ${BASH_REMATCH[2]} (\`${HASH}\`)")
fi

驗證

✅ --help 正常顯示
✅ --preview 模式正常
✅ --since TAG 正確過濾
✅ --all 生成完整記錄
✅ feat/fix/docs/refactor/chore 全部正確分類

學習重點

1. Bash 正則: [[ "$str" =~ ^pattern(.*)$ ]] 配合 BASH_REMATCH 提取群組 2. 陣列操作: declare -a ARR=() + ARR+=("item") + ${#ARR[@]} 計數 3. Git log 格式: --pretty=format:"%s|%h|%ai" 自訂輸出格式 4. Keep a Changelog: 標準格式是 ## [version] - date + ### Added/Fixed/Changed

產出

• scripts/generate-changelog.sh - 193 行 bash 腳本
• 支援 7 種 commit 類型 + other 分類
• 完整的 --help 說明

效果

首次使用 /evolve 完成真實任務，產生了：

• 1 個新腳本
• 1 筆 learning 記錄
• PDCA 完整執行一輪

code-simplifier Plugin 整合

情境

Boris Cherny (Claude Code 創作者) 開源了 Claude Code 團隊內部使用的 code-simplifier agent，可用於重構和清理技術債。

安裝方式

claude plugin install code-simplifier

核心功能

code-simplifier 是一個專注於程式碼簡化的 agent：

簡化原則

1. 保持功能不變 - 只改「如何做」 2. 套用專案標準 - 讀取 CLAUDE.md 規範 3. 提升清晰度 - 減少複雜度、消除冗餘 4. 維持平衡 - 避免過度簡化

重要：避免的模式

• ❌ 巢狀三元運算 → 改用 switch/if-else
• ❌ 過度聰明的 one-liner
• ❌ 移除有助於組織的抽象

與 evolve 的整合

整合點：PDCA Check 階段

Do (寫程式碼)
    ↓
Check (功能驗證通過)
    ↓
呼叫 code-simplifier
    ↓
再次 Check (確保功能不變)
    ↓
Act (記錄)

使用時機

驗證結果

✅ Plugin 安裝成功 ✅ 整合文件已建立：skills/05-integration/_base/code-simplifier.md ✅ 與現有 Boris Tips 記錄一致

注意事項

1. 先有測試覆蓋再簡化 2. 小範圍開始 3. 重大簡化前先 commit 4. 簡化前後都要驗證

相關檔案

• skills/05-integration/_base/code-simplifier.md - 完整整合指南
• .claude/memory/learnings/2025-01-07-boris-cherny-claude-code-tips.md - Boris 其他技巧

競品分析研究洞察

情境

為 self-evolving-agent 進行全面競品分析，涵蓋 IDE 工具、Multi-Agent 框架、Self-Evolving 研究三大類別。

關鍵發現

市場數據

• Agentic AI 市場: 2025 $7.8B → 2030 $52B
• 企業採用率: 2026 年將達 40% (Gartner)
• Multi-Agent 詢問量: 年增 1,445%

競爭格局

獨特定位

Self-Evolving Agent 是唯一整合以下三者的 Claude Code Skill： 1. PDCA 執行循環 2. Git-based Memory 3. 涌現機制 (4 Level)

學到的知識

1. GEPA 方法論

OpenAI 的 Genetic Pareto 框架：

• 評估 → 反思 → 修訂 → 迭代
• 可用於 Prompt 自動優化
• 未來可整合到我們的知識蒸餾流程

2. 記憶系統比較

3. 市場趨勢

• 2026: 專業垂直 Agent 將主導
• 2027: 自我改進 Agent 生態成熟
• 2028+: 人機協作進入認知夥伴模式

戰略建議

短期 (0-3 月)

• P0: 視覺化儀表板
• P0: VS Code 擴展
• P1: Cursor Rules 相容

中期 (3-6 月)

• P0: Agent SDK 導出功能
• P1: Multi-Agent 支持
• P1: Benchmark 套件

長期 (6-12 月)

• P0: GEPA 整合
• P1: 跨 Agent 記憶共享
• P1: 領域 Skill 市場

產出

• 完整報告: docs/competitor-analysis-2026-01.md

驗證

✅ 涵蓋 4 大類競品共 10+ 產品 ✅ 建立功能對比矩陣 ✅ SWOT 分析完成 ✅ 短/中/長期建議明確

深度訪談模式 - 從 Benson Sun 學到的技巧

情境

在 X (Twitter) 上看到 Benson Sun (@BensonTWN) 分享的 Claude Code prompt 技巧。

核心洞察

寫 spec 最大的問題是「你不知道自己漏了什麼」

這正好補足 evolve 原本的盲點：

• 我們有「失敗後學習」(CP5 Failure Post-Mortem)
• 但缺少「開始前預防」的深度訪談機制

解決方案

整合「深度訪談模式」到 01-core/_base/goal-analysis.md：

1. 訪談執行邏輯

讓 Claude 扮演資深技術顧問，用 AskUserQuestion 進行多輪訪談。

2. Ultrathink 分析（每個問題前）

• 這個規格可能隱藏的假設是什麼？
• 哪些邊界情況沒有被考慮到？
• 技術債務可能在哪裡累積？
• 這個設計決策的二階、三階效應是什麼？

3. 觸發條件

4. 訪談問題類型

• 隱藏假設探索
• 邊界情況
• 技術債務預防
• 二階/三階效應

驗證

✅ 已更新 skills/01-core/_base/goal-analysis.md ✅ 新增完整的深度訪談流程、問題範本、結束條件、產出格式

注意事項

• 問題要深入且不流於表面
• 設定 10 個問題上限避免疲勞
• 訪談產出應整理為結構化的 goal_specification

原始 Prompt（Benson Sun 版本）

閱讀這份 SPEC 文件，然後使用 AskUserQuestionTool 對我進行深度訪談，
涵蓋所有面向：技術實作、UI/UX、潛在疑慮、設計取捨等。
問題必須深入且不流於表面。

請啟用 ultrathink 模式：在每個問題之前，先進行深度思考分析，包括：
- 這個規格可能隱藏的假設是什麼？
- 哪些邊界情況沒有被考慮到？
- 技術債務可能在哪裡累積？
- 這個設計決策的二階、三階效應是什麼？

持續訪談直到所有關鍵面向都被釐清，然後將完整的規格寫入檔案。

Evolve Skill Token 使用量優化研究

情境

用戶反饋使用 evolve skill 的專案 token 使用量過高，需要研究優化方式。

問題發現

數據對比

根本原因

skillpkg 在安裝 skill 時，會將所有子模組內容內嵌合併到單一 SKILL.md：

• 原始結構：原子化模組（多個目錄/檔案）
• 安裝後：所有內容合併到一個巨大 SKILL.md
• 結果：每次 /evolve 都載入 ~27K tokens 的 context

Token 分佈（主要消耗）

1. 檢查點模組 (02-checkpoints)：~6 個檔案，含詳細流程圖 2. 核心流程 (01-core)：PDCA、目標分析等完整說明 3. 整合模組 (05-integration)：各種 MCP 整合說明 4. ASCII 圖表：多處重複的流程圖

優化方案

方案 1：分層載入架構（推薦 ⭐）

SKILL.md (精簡核心 ~3KB)
├── 只保留：基本流程、檢查點列表、模組索引
└── 其他內容按需載入

執行時按需讀取：
├── 遇到 CP1 → Read(02-checkpoints/_base/cp1-memory-search.md)
├── 遇到 PDCA → Read(01-core/_base/pdca-cycle.md)
└── 需要整合 → Read(05-integration/_base/xxx.md)

預期效果：初始載入從 27K → ~1K tokens (96% 降低)

方案 2：skillpkg 配置

# SKILL.md frontmatter
inline_modules: false  # 告訴 skillpkg 不要合併子模組

需要 skillpkg 支援此功能。

方案 3：內容精簡

• 移除重複 ASCII 流程圖
• 合併相似範例
• 使用引用替代內嵌

方案 4：動態載入機制

load_skill("evolve", mode="minimal")  # 只載入核心
# 執行中按需載入模組

建議行動優先級

1. 短期：精簡 SKILL.md 主文件 2. 中期：實作分層載入邏輯 3. 長期：修改 skillpkg 支援不合併模式

驗證

✅ 確認問題根因：skillpkg 合併機制 ✅ 提出多個可行優化方案 ✅ 估算預期改善效果

相關檔案

• skills/SKILL.md - 源碼版本（14.7 KB）
• ~/.claude/skills/evolve/SKILL.md - 安裝版本（106.8 KB）

Flame Game Engine Skill 開發

背景

用戶需要一個能指導使用 Flame 引擎開發 2D 遊戲的 Skill，涵蓋完整遊戲開發流程，適合各經驗程度的開發者。

研究發現

Flame 引擎核心特點

1. 架構: 基於 Flutter 的模組化 2D 遊戲引擎 2. 核心系統:

• Flame Component System (FCS) - 類似 ECS 的元件架構
• Game Loop - 內建遊戲循環管理
• CameraComponent - 攝影機與視口系統

3. 最新版本: v1.33.0 (2025-10)

關鍵概念

Bridge Packages

• flame_audio: 音訊播放
• flame_forge2d: Box2D 物理引擎
• flame_tiled: Tiled 地圖編輯器支援
• flame_rive / flame_lottie: 動畫支援
• flame_bloc / flame_riverpod: 狀態管理

設計模式

1. 元件生命週期: onLoad → onMount → update/render → onRemove 2. 碰撞偵測: CollisionCallbacks mixin + Hitbox 3. 輸入處理: TapCallbacks, DragCallbacks, KeyboardHandler mixins 4. 攝影機跟隨: camera.follow() 配合 setBounds()

Skill 設計決策

涵蓋範圍

• 核心架構與設定
• 元件系統（FCS）
• 輸入處理（觸控、鍵盤、搖桿）
• 碰撞偵測
• 攝影機系統
• 精靈動畫
• 效果系統
• 音訊整合
• 遊戲狀態與 Overlay
• 常見設計模式
• 效能優化

排除範圍

• 3D 遊戲開發
• 多人連線/後端
• 遊戲上架流程

學到的教訓

1. Context7 很有用: 能快速獲取最新的程式碼範例和文檔 2. 官方教程結構清晰: Flame 有 4 個官方教程（Bare Game, Klondike, Ember Quest, Space Shooter） 3. 社群資源: awesome-flame repo 有大量社群貢獻的範例

參考資料

• Flame Docs
• Flame GitHub
• Awesome Flame

Makefile 優化 + 探索模式發現

情境

使用 /evolve --explore 執行 Level 1 任務：優化 Makefile，整合 changelog 生成腳本。

主要任務

整合 changelog 腳本

將 scripts/generate-changelog.sh 整合到 Makefile：

changelog: ## Generate CHANGELOG.md (preview mode)
	@./scripts/generate-changelog.sh --preview

changelog-save: ## Generate and save CHANGELOG.md
	@./scripts/generate-changelog.sh --all --output CHANGELOG.md

changelog-since: ## Generate changelog since a tag
	# make changelog-since TAG=v4.1.0

探索模式發現（Level 1 涌現）

完成主要任務後，主動發現並實作了額外的自動化機會：

Memory 管理命令

memory-stats: ## Show memory system statistics
	# 顯示各類記憶檔案數量
	# 顯示 index.md 狀態

memory-recent: ## Show recently modified memory files
	# 列出最近 7 天修改的記憶文件

效益

學習重點

1. Level 1 探索模式的價值

完成任務後「探索」帶來額外發現

• 主要任務：整合 changelog ✅
• 涌現發現：memory-stats, memory-recent 命令
• 關鍵：探索模式讓 AI 主動尋找「還能做什麼」

2. Makefile 設計原則

自動化 = 減少決策點 + 減少重複勞動

• 用 make 統一所有常用操作
• 用 ## 註解自動生成 help
• 提供 preview 模式避免誤操作

驗證

✅ make help - 顯示所有命令（含新增）
✅ make changelog - 正確調用腳本
✅ make memory-stats - 正確統計數量
✅ make memory-recent - 正確顯示最近文件
✅ make recent - 替代原 changelog 快速檢視

效果

首次 Level 1 探索模式：

• 主要任務完成：1 項
• 涌現發現：2 個額外自動化命令
• 這證明 --explore flag 確實能促進額外發現

自我進化流程：修改 Skill 的正確順序

情境

當 AI 需要修改 skill 本身時（例如新增 checkpoint、更新流程），需要遵循特定順序。

問題

錯誤順序會導致：

• 專案原始碼與安裝版不同步
• Source of truth 被覆蓋
• 難以追蹤變更歷史

正確流程

1. 更新專案原始碼
   └─ /Users/user/Workspace/self-evolving-agent/skills/*.md

2. Git commit
   └─ 記錄變更，建立歷史追蹤

3. 更新安裝版（如需要）
   └─ ~/.claude/skills/evolve/SKILL.md

為什麼這個順序

原則：永遠先更新 source of truth，再同步衍生物

實際案例

新增 CP1.5 一致性檢查時：

• ❌ 錯誤：先改 ~/.claude/skills/evolve/SKILL.md
• ✅ 正確：先改 skills/02-checkpoints/_base/cp1.5-consistency-check.md + commit

為什麼不需要變成 Checkpoint

1. 頻率太低 - 幾週才發生一次 2. 已有社會約束 - 錯了會被指正 3. 複雜度不成比例 - 規範成本 > 收益

結論

這是一個「知道就好」的流程，記錄在 Memory 供查閱，而非強制 Checkpoint。

skillpkg 分層載入機制研究

目的：找出 evolve skill token 優化方案

背景問題

安裝後的 evolve skill 從源碼 8.9KB 膨脹到 106.8KB（12 倍）

核心發現

1. 膨脹原因

2. skillpkg 已支援的功能

✅ 子目錄安裝

skillpkg install user/repo#path/to/skill

✅ 依賴管理

# SKILL.md frontmatter
dependencies:
  skills:
    - user/other-skill

✅ 循環依賴檢測

✅ 反向依賴追蹤（防止誤刪被依賴 skill）

3. 尚未支援（需要 PR 貢獻）

❌ 按需載入 - 無法只載入 SKILL.md 主檔 ❌ 文件過濾 - 無法排除 .md 文檔、測試檔 ❌ 去重機制 - 無 symlink 或 hardlink 優化

可行方案

方案 A：子目錄拆分（無需改 skillpkg）

self-evolving-agent/
├── skills/
│   ├── SKILL.md              # 核心 (8.9KB)
│   ├── checkpoints/
│   │   └── SKILL.md          # 獨立 skill
│   └── integration/
│       └── SKILL.md          # 獨立 skill

使用方式：

skillpkg install miles990/self-evolving-agent#skills           # 只裝核心
skillpkg install miles990/self-evolving-agent#skills/checkpoints  # 需要時加裝

方案 B：貢獻 skillpkg PR

在 SkillInstallOptions 加入：

{
  essentialOnly: true,          // 只裝 SKILL.md
  skipPatterns: ['*.md'],       // 跳過文檔
  categories: ['instruction']   // 只要特定分類
}

方案 C：手動管理（當前做法）

直接複製 SKILL.md 到 ~/.claude/skills/evolve/

建議

1. 短期：使用方案 C（手動同步源碼 SKILL.md） 2. 中期：重構為方案 A 架構（子目錄拆分） 3. 長期：向 skillpkg 提交 PR 支援分層載入

相關文件

• /Users/user/Workspace/skillpkg/packages/core/src/sync/syncer.ts - 同步邏輯
• /Users/user/Workspace/skillpkg/packages/core/src/dependency/dependency-resolver.ts - 依賴解析
• /Users/user/Workspace/skillpkg/packages/core/src/store/store-manager.ts - 存儲管理

Galgame Skill 通用化經驗

將專案專用 skill 抽象為通用框架的設計模式

背景

從 Dead Romance 專案的 galgame-creator skill (v3.0.0) 提煉出通用的 galgame-master skill (v1.0.0)。

關鍵決策

1. 移除專案綁定

2. 保留核心價值

• 34 種角色類型庫：這是最有價值的資產，完整保留
• 角色公式：Dere + 關係 + 身份 + 特殊屬性
• 好感度進展系統：Lv0-Lv5 的對話變化
• 反差設計原則：表面 vs 私底下

3. 新增通用模組

• 世界觀初始化模板
• 劇本架構系統（共通路線 → 個人路線 → 多結局）
• 內容分級系統（G/R15/R15+/R18 可選）
• 專案目錄結構建議

設計模式

從專用到通用的抽象步驟

1. 識別硬編碼：找出所有專案特定的內容 2. 提取參數：將固定值改為可配置選項 3. 保留核心：確保核心價值（角色類型庫）完整 4. 添加框架：補充通用場景所需的模板 5. 文檔完善：讓任何專案都能快速上手

Skill 分層策略

全域 Skill (galgame-master)
├── 角色類型庫（34 種）
├── 劇本架構模板
├── 對話生成系統
└── 美術指示框架

專案 Skill (galgame-creator)
├── 繼承全域 Skill
├── 專案專屬角色
├── 特定世界觀設定
└── 自訂內容分級

檔案位置

• 全域 Skill: ~/.claude/skills/galgame-master/SKILL.md
• 專案 Skill: <project>/.claude/skills/galgame-creator/SKILL.md

標籤

skill-design, generalization, galgame, character-design, abstraction

Memory MCP 整合設計

情境

需要將 claude-memory-mcp（SQLite Memory 系統）整合到 evolve skill 流程中，讓生態系更聰明、更專業。

問題

原本 evolve 的記憶系統是純 Git-based（.claude/memory/），搜尋依賴 Grep，存在以下問題： 1. 搜尋速度較慢（~20ms vs FTS5 的 ~3.5ms） 2. Token 消耗高（~2300 vs ~200） 3. 無法追蹤 Skill 使用成功率 4. 失敗經驗無法跨專案共享

解決方案

Skill Script 整合（最佳方案）：

• 在 05-integration/_base/memory-mcp.md 建立整合指南
• 更新關鍵檢查點（CP1, CP3.5, CP5）加入 Memory MCP 呼叫
• 保留 Git Memory 作為詳細記錄，Memory MCP 作為搜尋索引

為什麼不用 CLI？

• Claude Code 的 MCP 是 stdio 模式，CLI 無法共用連線
• AI 已經可以直接呼叫 MCP 工具，不需要額外中介

整合架構

CP0 ─► skill_usage_start()     # 開始追蹤
CP1 ─► memory_search()         # 搜尋經驗（取代 Grep）
    ─► failure_search()        # 搜尋失敗解法
CP3.5 ► memory_write()         # 記錄學習（雙重記錄）
CP5 ─► failure_record()        # 記錄失敗
結束 ─► skill_usage_end()      # 結束追蹤，計算成功率

驗證

• [x] 建立 skills/05-integration/_base/memory-mcp.md
• [x] 更新 CP1 加入 memory_search + failure_search
• [x] 更新 CP3.5 加入 memory_write
• [x] 更新 CP5 加入 failure_record
• [x] 更新 05-integration/README.md

注意事項

1. 雙重記錄：Git Memory（詳細）+ Memory MCP（索引）並存 2. 回退機制：若 MCP 不可用，回退到 Grep 搜尋 3. Key 命名：使用 learning:YYYY-MM-DD:slug 格式 4. 跨專案：scope 設為 "global" 實現跨專案共享

相關檔案

• skills/05-integration/_base/memory-mcp.md - 整合指南
• skills/02-checkpoints/_base/cp1-memory-search.md - CP1 更新
• skills/02-checkpoints/_base/cp3.5-memory-sync.md - CP3.5 更新
• skills/02-checkpoints/_base/cp5-failure-postmortem.md - CP5 更新

版本發布工作流教訓

情境

執行 v5.9.2 發布時遇到多個技術問題。

教訓 1: macOS sed 正則表達式

問題: sed -i '' "s/[0-9]\+/.../" 在 macOS 上不工作

原因: macOS sed 預設使用 BRE (Basic Regular Expression)，\+ 是 GNU sed 的 BRE 擴展，macOS 不支援

解決方案:

# ❌ 錯誤 - macOS 不支援
sed -i '' "s/[0-9]\+\.[0-9]\+/.../"

# ✅ 正確 - 使用 -E 啟用 ERE
sed -i '' -E "s/[0-9]+\.[0-9]+/.../"

記住: macOS sed 用 -E，Linux sed 用 -r 來啟用 ERE

教訓 2: cp 不複製隱藏目錄

問題: cp -r source/* dest/ 不會複製 .hidden 目錄

原因: Shell glob * 預設不匹配以 . 開頭的檔案/目錄

解決方案:

# 方法 1: 分開複製
cp -r source/* dest/
cp -r source/.hidden dest/

# 方法 2: 使用 rsync
rsync -av source/ dest/

# 方法 3: 設定 shell 選項 (bash)
shopt -s dotglob
cp -r source/* dest/

教訓 3: Plugin Cache 更新流程

正確流程: 1. 清除舊 cache: rm -rf ~/.claude/plugins/cache/<plugin-name> 2. 建立版本目錄: mkdir -p ~/.claude/plugins/cache/<plugin-name>/<skill>/<version> 3. 複製所有檔案（包括隱藏目錄） 4. 驗證 .claude-plugin/plugin.json 存在且版本正確

驗證命令:

cat ~/.claude/plugins/cache/<plugin>/evolve/<version>/.claude-plugin/plugin.json

改進建議

考慮在 install.sh 中增加全域 plugin 安裝選項：

./install.sh --global  # 安裝到 ~/.claude/plugins/cache/
./install.sh           # 安裝到當前專案 .claude/skills/

SDD 規格驅動開發 - 高見龍

核心理念

「在開始之前，先定義什麼叫『完成』」

解決 Vibe Coding 的三大問題： 1. 程式碼風格不一致 2. AI 未主動告知漏掉的需求 3. AI 說「完成了」卻忽視測試失敗

三階段流程

Requirements (requirements.md)
    ↓ 使用者故事 + EARS 驗收標準
Design (design.md)
    ↓ 架構圖、資料模型、API 設計
Tasks (tasks.md)
    ↓ 可追蹤的小任務
實作

EARS 格式

結構化的驗收標準寫法：

「當使用者輸入正確 Email 和密碼時，系統應將使用者導向首頁」

三層級分類

與 Self-Evolving Agent 整合

適用情境

適合 SDD：

• 既有系統漸進式改進
• 複雜新專案
• 團隊協作

可用 Vibe Coding：

• 小型 POC
• 一次性工具

關鍵洞察

1. SDD 會減慢初期開發但提升長期品質 2. 工程師角色轉變：編碼者 → 規格定義者 3. 工具在演進，但 SDD 思維方式具永久價值

Code Execution Skill 開發記錄

日期: 2026-01-23 類型: Skill 創建 標籤: code-execution, mcp, token-optimization, skill-design

---

背景

研究 MCP 設計模式後，發現 Code Execution 模式（Anthropic 2025 提出）可大幅減少 Token 消耗（98%+）。決定將此模式封裝為獨立 Skill。

核心概念

Code Execution 模式的本質

傳統 Tool Calling：
  Model → Tool → Model → Tool → Model → ...
  每次結果都傳回 Model，消耗大量 Context

Code Execution：
  Model → 生成程式碼 → 執行環境處理 → 精簡結果
  資料處理在執行環境中完成，只回傳最終結果

效率對比

Skill 設計決策

1. 觸發時機

明確定義何時使用：

• ✅ 3+ 步驟工作流程
• ✅ 迴圈處理多項目
• ✅ 條件分支邏輯
• ❌ 單一 Tool 呼叫
• ❌ 簡單 Q&A

2. 三種執行模式

1. Claude Code 內建 — 直接撰寫 Python/Bash 處理 2. Programmatic Tool Calling — API beta 功能 3. CLI 批次腳本 — 當 MCP Server 提供 CLI 時

3. 撰寫指南四原則

1. 資料處理在本地 2. 批次優於逐一 3. 提前過濾 4. 錯誤處理

與 evolve 整合

在 PDCA 各階段的應用：

Plan: 識別是否適合 Code Execution
Do: 撰寫批次處理程式碼
Check: 驗證結果，評估 Token 節省
Act: 記錄成功模式

學到的經驗

1. Anthropic 已官方支援 — advanced-tool-use-2025-11-20 beta 2. Claude Code 本身就是執行環境 — 不需要額外建立 3. 安全性是關鍵 — 需要沙箱、限制、錯誤處理

產出

• Skill 檔案: .claude/skills/code-execution/SKILL.md
• 整合文檔: 更新 05-integration/README.md
• 研究報告: .claude/memory/research/2026-01-23-mcp-advanced-patterns-detail.md

參考資源

• Code Execution with MCP - Anthropic
• Programmatic Tool Calling - Claude Docs
• Claude Code Sandboxing

🌟 北極星：Flame Game Development Skill

一句話願景

讓 AI 能完整指導使用 Flame 引擎開發 2D 遊戲

完成標準（Done = 什麼？）

• [x] 涵蓋 Flame 核心概念（Component、Game Loop、Sprite）
• [x] 包含通用 2D 遊戲開發模式（不限定類型）
• [x] 適合 Flutter/Dart 初學者到進階者使用
• [x] 提供實際可用的程式碼範例與最佳實踐

不做清單（Scope 護欄）

• ❌ 3D 遊戲開發
• ❌ 後端/連線功能（多人連線、伺服器）
• ❌ 遊戲上架流程（App Store/Play Store 發布）

當初為什麼開始？

想要一個能幫助快速上手 Flame 引擎的 Skill，讓 AI 能有系統地指導遊戲開發，從原型到完整遊戲。

---

健康檢查記錄

北極星：智能 Skill 生態系 MVP

建立日期：2026-01-16

狀態：✅ 已完成

完成日期：2026-01-16

版本：MVP (Phase 0.5)

願景

讓 AI 自動發現、推薦、組合最適合的 skill — 從「用戶選擇 skill」到「AI 智能推薦 skill」。

設計原則

• 不改 sqlite-memory-mcp：使用現有 23 個 tools
• 只改 evolve skill：降低風險和複雜度
• 用腳本達成同步：不需要新的 MCP 功能
• 80% 效果，20% 工作量

完成標準（Definition of Done）

核心功能

• [x] 自動判斷 scope（global vs project:xxx）
• [x] Skill 索引腳本（從 GitHub 同步到 sqlite-memory）
• [x] CP1 智能推薦（搜尋並顯示相關 skill）
• [x] 整合文檔更新

驗收標準

• [x] /evolve 建立量化交易系統 能自動推薦 quant-trading skill
• [x] 記錄經驗時能正確判斷 scope
• [x] 跨專案能搜尋到其他專案的 global 經驗

統計

• 已索引 Skills: 78 個（54 software + 24 domain）
• 總記憶數: 100 筆
• Skill Repos: 2 個（claude-software-skills, claude-domain-skills）

不做清單（Out of Scope）

• ❌ 不修改 sqlite-memory-mcp npm 包
• ❌ 不新增 MCP tools
• ❌ 不實作自動安裝 skill
• ❌ 不實作多 skill 並行執行
• ❌ 不建立 Web UI 儀表板

已完成的實作

1. Scope 自動判斷

• 文件：skills/03-memory/_base/scope-detection.md
• 判斷規則：專案專屬 vs 通用經驗
• 預設：global（寧可多分享）

2. Skill 同步腳本

• 文件：scripts/sync-skills.sh
• 功能：從 GitHub repos 同步 skill metadata 到 sqlite-memory
• 命令：--software, --domain, --list, --clear

3. CP1 推薦整合

• 文件：skills/02-checkpoints/_base/cp1-memory-search.md
• 新增：Skill 推薦顯示格式
• 搜尋：memory_search({query: "skill:* 關鍵字"})

4. 整合文檔

• 文件：skills/05-integration/_base/skill-ecosystem.md
• 完整說明生態系架構和使用方式

使用方式

# 同步 skill 索引
./scripts/sync-skills.sh

# 搜尋相關 skill
memory_search({query: "skill:* 量化 交易"})

未來擴展（Phase 1+）

MVP 驗證成功後，可考慮：

• 擴展 sqlite-memory schema（需發布新版）
• 自動安裝/更新 skill
• 多 skill 協作執行
• 效果度量儀表板

🌟 北極星：多 Agent 協作研究框架

一句話願景

建立多 Agent 協作研究框架，讓複雜主題能被多角度同時探索並整合成完整報告

完成標準（Done = 什麼？）

• [x] 完成理論研究報告（多角度架構設計）
• [x] 認知科學視角深度研究（完成）
• [x] 提出可行的架構設計方案（綜合報告含實作路線圖）
• [x] 各視角研究報告存檔為 .md
• [x] 匯總報告整合各方觀點

不做清單（Scope 護欄）

• ❌ 不寫實作程式碼（純研究發想）
• ❌ 不考慮 API 成本問題
• ❌ 不做效能基準測試

當初為什麼開始？

探索如何讓多個 Agent 從不同角度同時使用 evolve skill 進行研究，最後由匯總 Agent 整合成果，提升研究的深度和廣度。

---

健康檢查記錄

研究產出

綜合報告（2026-01-23）

文件位置：.claude/memory/research/2026-01-23-multi-agent-research-framework-synthesis.md

四大共識發現： 1. 混合式架構最佳（Map-Reduce + 動態協調） 2. 4-5 角色是認知負荷最佳配置 3. 狀態管理是核心挑戰（雙寫模式解決） 4. 漸進式複雜度原則

架構視角（2026-01-23）

文件位置：.claude/memory/research/2026-01-23-multi-agent-collaboration-architecture.md

核心貢獻：

• 三種協作模式分析（並行/順序/混合）
• SQLite + Git 雙層狀態管理設計
• Evolve Skill 整合點映射

認知科學視角（2026-01-23）

文件位置：docs/research/cognitive-perspective-multi-agent-framework.md

核心發現： 1. 有效的多 Agent 協作不是增加視角數量，而是設計互補的認知模式 2. 推薦「4-5 角色」配置（認知負荷最佳） 3. 群體迷思防範需要結構化對抗機制

方法論比較：

• Six Thinking Hats（適合決策和創意）
• Devil's Advocate（適合風險審查）
• Red/Blue Team（適合安全評估）
• Dialectical Thinking（適合理論創新）

推薦起點配置：4 角色菱形結構

       協調整合者
          ╱ ╲
數據研究員    機會探索者
          ╲ ╱
      風險評估師

產業視角（2026-01-23）

文件位置：docs/research/multi-agent-frameworks-industry-perspective.md

核心貢獻：

• 5 大主流框架深度分析（AutoGen, CrewAI, LangGraph, MetaGPT, ChatDev）
• 6 種核心設計模式
• 成本警告：多 Agent = 15 倍 Token 消耗

工作流視角（2026-01-23）

核心貢獻：

• 與 Evolve Skill PDCA 循環整合設計
• Checkpoint 機制應用
• Task API 並行執行模式

北極星：SQLite Memory 系統

建立日期：2026-01-16

狀態：✅ 已完成

完成日期：2026-01-16

願景

讓整個 AI 助手生態系變得更聰明 — 透過統一的 SQLite Memory 系統，實現：

• 跨專案知識共享（學一次，處處可用）
• Token 使用優化（精確查詢取代全文載入）
• Context 無縫傳遞（Skill 間共享狀態）
• 集體智慧累積（失敗經驗共享、智能推薦）

完成標準（Definition of Done）

核心功能

• [x] SQLite 資料庫 schema 設計並初始化
• [x] Memory MCP Server 提供 tools (23 個工具)
• [x] FTS5 全文搜尋功能
• [x] Context 表支援跨 Skill 共享
• [x] 遷移現有 filesystem memory (22 筆)

整合

• [x] 更新 evolve skill CP1 使用 SQLite（memory_search + failure_search）
• [x] 更新 evolve skill CP3.5 使用 SQLite（memory_write）
• [x] 更新 evolve skill CP5 使用 SQLite（failure_record）
• [x] 建立整合指南（05-integration/_base/memory-mcp.md）
• [x] 提供 fallback 到 filesystem（離線支援）

生態系

• [x] 跨專案知識自動共享 (scope: global)
• [x] Skill 效果追蹤功能 (skill_usage_start/end)
• [x] 失敗經驗自動索引 (failure_record/search)

品質

• [x] 效能測試通過（FTS5 ~3.5ms vs Grep ~20ms）
• [x] 文檔完整 (05-integration/_base/memory-mcp.md)
• [x] npm 發布 (sqlite-memory-mcp v1.0.2)

不做清單（Out of Scope）

• ❌ 不使用 Redis（效能測試證明 SQLite 更適合）
• ❌ 不建立遠端同步（先專注本地）
• ❌ 不改變 filesystem memory 格式（保持相容）
• ❌ 不強制遷移（漸進式採用）

動機

問題

1. Token 浪費：每次搜尋載入完整文件（~2300 tokens） 2. Context 斷層：Skill 間無法共享狀態 3. 知識孤島：跨專案經驗無法自動共用 4. 重複學習：相同問題在不同專案重複解決

效益（已驗證）

• Token 節省：55-91%
• 搜尋速度：提升 5-6x
• Context Switch：根本解決
• 生態系智能化：集體學習、失敗共享、智能推薦

成功指標

SQLite 統一架構 - PDCA Plan

建立日期：2026-01-16

狀態：計劃中

北極星：sqlite-memory-system.md

願景

單一資料庫統一管理整個 AI 助手生態系 — 整合 Memory、skillpkg、Context、失敗經驗。

架構設計

統一資料庫位置

~/.claude/claude.db

Schema 設計

-- 1. Memory 表 (原 evolve memory)
CREATE TABLE memory (
    id INTEGER PRIMARY KEY,
    key TEXT UNIQUE NOT NULL,
    content TEXT NOT NULL,
    tags TEXT,                        -- JSON array
    scope TEXT DEFAULT 'global',      -- 'global' | 'project:{name}'
    source TEXT,                      -- 'evolve' | 'skillpkg' | 'manual'
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 2. Skills 表 (取代 .skillpkg/state.json)
CREATE TABLE skills (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    version TEXT NOT NULL,
    source TEXT NOT NULL,
    project_path TEXT,
    installed_by TEXT,
    installed_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_used_at DATETIME,
    use_count INTEGER DEFAULT 0
);

-- 3. Skill Usage 表 (效果追蹤)
CREATE TABLE skill_usage (
    id INTEGER PRIMARY KEY,
    skill_name TEXT NOT NULL,
    project_path TEXT,
    started_at DATETIME,
    completed_at DATETIME,
    success BOOLEAN,
    outcome TEXT,
    tokens_used INTEGER,
    notes TEXT,
    FOREIGN KEY (skill_name) REFERENCES skills(name)
);

-- 4. Failures 表 (失敗經驗共享)
CREATE TABLE failures (
    id INTEGER PRIMARY KEY,
    error_pattern TEXT NOT NULL,
    error_message TEXT,
    solution TEXT,
    skill_name TEXT,
    project_path TEXT,
    occurrence_count INTEGER DEFAULT 1,
    last_seen_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 5. Context 表 (跨 Skill 狀態)
CREATE TABLE context (
    id INTEGER PRIMARY KEY,
    session_id TEXT NOT NULL,
    key TEXT NOT NULL,
    value TEXT NOT NULL,
    skill_name TEXT,
    expires_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(session_id, key)
);

-- Indexes
CREATE INDEX idx_memory_scope ON memory(scope);
CREATE INDEX idx_memory_source ON memory(source);
CREATE INDEX idx_skills_name ON skills(name);
CREATE INDEX idx_skill_usage_skill ON skill_usage(skill_name);
CREATE INDEX idx_failures_pattern ON failures(error_pattern);
CREATE INDEX idx_context_session ON context(session_id);

-- FTS5 全文搜尋
CREATE VIRTUAL TABLE memory_fts USING fts5(key, content, tags);
CREATE VIRTUAL TABLE failures_fts USING fts5(error_pattern, error_message, solution);

MCP Server 設計

工具清單

Server 架構

claude-memory-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts           # MCP Server 入口
│   ├── database.ts        # SQLite 連接管理
│   ├── tools/
│   │   ├── memory.ts      # memory_* 工具
│   │   ├── skills.ts      # skill_* 工具
│   │   ├── failures.ts    # failure_* 工具
│   │   └── context.ts     # context_* 工具
│   └── migrations/
│       └── 001_initial.sql
└── README.md

實作階段

Phase 1: 核心基礎 (MCP Server)

工作項目:

• [ ] 建立 MCP Server 專案結構
• [ ] 實作 SQLite 連接管理
• [ ] 實作 memory_* 工具
• [ ] 實作 FTS5 搜尋
• [ ] 單元測試

驗收標準:

• memory_write/read/search 正常運作
• FTS5 搜尋 < 5ms
• 無外部相依 (pure SQLite)

Phase 2: 遷移 evolve memory

工作項目:

• [ ] 撰寫遷移腳本
• [ ] 遷移現有 .claude/memory/*.md
• [ ] 更新 evolve skill CP1 使用新工具
• [ ] 更新 evolve skill CP3.5 使用新工具
• [ ] 保留 filesystem fallback

驗收標準:

• 所有現有 memory 成功遷移
• Token 使用減少 > 50%
• 搜尋速度提升 > 3x

Phase 3: skillpkg 整合

工作項目:

• [ ] 實作 skill_* 工具
• [ ] 修改 skillpkg StateManager
• [ ] 遷移現有 state.json
• [ ] 效果追蹤功能

驗收標準:

• skillpkg 正常運作
• 跨專案 skill 可見
• 使用統計可查詢

Phase 4: 失敗經驗系統

工作項目:

• [ ] 實作 failure_* 工具
• [ ] 建立失敗模式識別
• [ ] 整合到 evolve skill
• [ ] 自動建議解法

驗收標準:

• 錯誤可索引
• 解法可搜尋
• 重複錯誤自動提示

Phase 5: 智能推薦

工作項目:

• [ ] 實作 skill_recommend 工具
• [ ] 基於歷史成功率推薦
• [ ] 基於專案類型推薦
• [ ] 整合到 Claude Code

驗收標準:

• 推薦準確率 > 70%
• 回應時間 < 10ms

效益預估

風險與緩解

成功標準

• [ ] MCP Server 運作穩定
• [ ] Token 使用減少 > 50%
• [ ] 搜尋速度 < 5ms
• [ ] 跨專案 memory 可用
• [ ] Skill 效果可追蹤
• [ ] 失敗經驗可搜尋

Everything Claude Code 專案分析

概述

Anthropic x Forum Ventures 駭客松冠軍整理的 Claude Code 配置集合，經過 10+ 個月實戰打磨。用於建構 zenith.chat 全程使用 Claude Code。

專案結構

everything-claude-code/
├── agents/           # 專門化子代理
├── skills/           # 工作流定義
├── commands/         # Slash 命令
├── rules/            # 強制遵守規則
├── hooks/            # 觸發式自動化
├── scripts/          # 跨平台 Node.js 工具
├── contexts/         # 動態 System Prompt 注入
├── mcp-configs/      # MCP Server 配置
└── .claude-plugin/   # Plugin 清單

核心亮點

1. Hooks 系統設計

{
  "PreToolUse": [
    "攔截危險操作 (dev server outside tmux)",
    "建議使用 tmux",
    "阻擋隨意創建 .md 文件",
    "Strategic Compact 建議"
  ],
  "PostToolUse": [
    "自動 Prettier 格式化",
    "TypeScript 型別檢查",
    "console.log 警告",
    "PR 創建後提示"
  ],
  "SessionStart": ["載入前次 Context"],
  "SessionEnd": ["持久化 Session 狀態", "提取可重用 Pattern"],
  "PreCompact": ["Compact 前保存狀態"],
  "Stop": ["檢查 console.log"]
}

啟發：完整的生命週期 Hook 覆蓋，特別是 PreCompact 和 SessionEnd 的狀態保存機制。

2. Eval Harness 框架

評估驅動開發 (EDD) - 把 Eval 當作 AI 開發的單元測試：

三種 Grader：

• Code-Based: 確定性檢查 (grep, npm test)
• Model-Based: Claude 評估開放式輸出
• Human: 標記需要人工審查

整合建議：可強化我們的 CP2 驗證階段，加入 pass@k 指標追蹤。

3. Agent 分工

特色：強調 PROACTIVELY 使用，不需用戶提示。

4. Continuous Learning

Session 結束時自動提取 Pattern：

patterns_to_detect: [
  "error_resolution",      // 錯誤解決方式
  "user_corrections",      // 用戶糾正
  "workarounds",           // 框架/庫的變通方案
  "debugging_techniques",  // 除錯技巧
  "project_specific"       // 專案慣例
]

儲存為 ~/.claude/skills/learned/[pattern-name].md

5. Context 管理最佳實踐

• 保持 < 10 個 MCP 啟用
• 避免使用 context window 最後 20%
• 模型選擇：Haiku (輕量 90% Sonnet 能力) / Sonnet (主力) / Opus (深度推理)

6. Verification Loop

六階段驗證流程： 1. Build Verification 2. Type Check 3. Lint Check 4. Test Suite (80% coverage) 5. Security Scan (secrets, console.log) 6. Diff Review

與 Self-Evolving Agent 比較

互補性分析

他們有，我們可借鑑：

• 跨平台 Node.js Hooks
• Eval Harness (pass@k 指標)
• Package Manager 自動偵測
• Strategic Compact 建議
• Context 動態注入

我們有，他們沒有：

• 北極星錨定系統
• PDCA 迭代框架
• Worktree 隔離模式
• 多策略重試機制
• 涌現機制檢查
• 架構等級判斷

整合優先度

關鍵引用

"Eval-Driven Development treats evals as the unit tests of AI development"

"Context Window: Don't enable all MCPs at once. Your 200k context window can shrink to 70k with too many tools enabled."

"Rule of thumb: Have 20-30 MCPs configured, Keep under 10 enabled per project, Under 80 tools active"

資源連結

• Shorthand Guide: https://x.com/affaanmustafa/status/2012378465664745795
• Longform Guide: https://x.com/affaanmustafa/status/2014040193557471352
• zenith.chat: https://zenith.chat

---

Twitter 指南深度分析

Shorthand Guide 重點

Session 狀態管理

Session 文件格式：~/.claude/sessions/YYYY-MM-DD-topic.tmp

# Session: [topic]
## Current State
[What you're working on]
## Completed
[Done items]
## Blockers
[Issues]
## Key Decisions
[Choices made]
## Context for Next Session
[Handoff notes]

指令權威層級

System prompt (最高) > User messages > Tool results (最低)

CLI Context Switching

# 每日開發
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
# PR 審查模式
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
# 研究/探索模式
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

動態 System Prompt 注入

claude --system-prompt "$(cat memory.md)"

---

Longform Guide 核心洞察

1. Strategic Compact（策略性壓縮）

時機選擇：

• 探索完成後 / 執行開始前
• Milestone 完成後 / 下一階段前
• 偵錯循環後 / 實施修復前
• 主要決策後

2. Memory Persistence Hooks

{
  "hooks": {
    "PreCompact": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/memory-persistence/pre-compact.sh"}]
    }],
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/memory-persistence/session-start.sh"}]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/memory-persistence/session-end.sh"}]
    }]
  }
}

3. Token 優化策略

4. mgrep vs grep 性能比較

• 成本減少 50%
• 速度提升 2x
• 76% 勝率

5. Eval Pattern Types

Checkpoint-Based（適合線性工作流）：

• 設置明確檢查點
• 驗證失敗必須修復才能繼續
• 適合有清晰里程碑的功能實作

Continuous（適合長時間 Session）：

• 每 N 分鐘或重大變更後執行
• 完整測試套件 + lint
• 適合探索性重構或維護

6. pass@k 實際數據

選擇指南：

• pass@k：只需要能工作就好
• pass^k：需要一致性和確定性輸出

7. 8 步 Eval Roadmap

1. 早期開始 - 從真實失敗中取 20-50 個簡單任務 2. 將用戶報告的失敗轉為測試案例 3. 寫明確任務 - 兩個專家應得出相同結論 4. 建立平衡問題集 - 測試應該和不應該發生的行為 5. 建立穩健框架 - 每次試驗從乾淨環境開始 6. 評估 agent 產出，而非過程 7. 閱讀多次試驗的記錄 8. 監控飽和度 - 100% 通過率意味著需要更多測試

8. 並行化最佳實踐

Cascade Method：

• 在右邊新標籤開啟新任務
• 從左到右掃描，最舊到最新
• 保持一致的方向流
• 專注最多 3-4 個任務

Git Worktrees 並行：

# 創建並行工作樹
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-refactor refactor-branch

# 每個工作樹獲得自己的 Claude 實例
cd ../project-feature-a && claude

好處：

• 實例間無 git 衝突
• 每個都有乾淨工作目錄
• 易於比較輸出
• 可對相同任務進行不同方法的基準測試

9. Two-Instance Kickoff Pattern

Instance 1: Scaffolding Agent

• 建立專案結構
• 設置配置（CLAUDE.md, rules, agents）
• 建立慣例
• 搭好骨架

Instance 2: Deep Research Agent

• 連接所有服務、網路搜尋
• 創建詳細 PRD
• 創建架構 Mermaid 圖
• 編譯實際文檔參考

10. llms.txt Pattern

許多文檔網站提供 LLM 優化版本：

https://www.helius.dev/docs/llms.txt

可直接餵給 Claude 的乾淨文檔格式。

11. Orchestrator Sequential Phases

Phase 1: RESEARCH (use Explore agent)
- Gather context
- Identify patterns
- Output: research-summary.md

Phase 2: PLAN (use planner agent)
- Read research-summary.md
- Create implementation plan
- Output: plan.md

Phase 3: IMPLEMENT (use tdd-guide agent)
- Read plan.md
- Write tests first
- Implement code
- Output: code changes

Phase 4: REVIEW (use code-reviewer agent)
- Review all changes
- Output: review-comments.md

Phase 5: VERIFY (use build-error-resolver if needed)
- Run tests
- Fix issues
- Output: done or loop back

關鍵規則： 1. 每個 agent 接收一個清晰輸入，產出一個清晰輸出 2. 輸出成為下一階段的輸入 3. 永不跳過階段 4. 用 /clear 在 agent 間保持上下文清新 5. 將中間輸出存入文件（不只是記憶）

12. Agent Abstraction Tierlist

Tier 1: Direct Buffs (易用)

• Subagents - 防止上下文腐爛
• Metaprompting - 3 分鐘 prompt → 20 分鐘任務
• 開始時多問用戶

Tier 2: High Skill Floor (難精通)

• Long-running agents - 需理解 15 min vs 1.5 hr vs 4 hr 任務權衡
• Parallel multi-agent - 只適合高度複雜或良好分割的任務
• Role-based multi-agent - 模型演進太快
• Computer use agents - 非常早期

要點：從 Tier 1 開始，有真正需求才升級到 Tier 2。

13. Sub-Agent Context Problem

問題：Sub-agent 只知道字面查詢，不知道背後的 PURPOSE/REASONING。

Iterative Retrieval Pattern： 1. Orchestrator dispatch 帶 query + objective 2. Sub-agent 返回 summary 3. 評估是否足夠？ 4. 不足夠 → 追問 → sub-agent 取答案 5. 最多 3 個循環

14. MCP 優化技巧

用 CLI 命令取代 MCP 節省 Context Window：

# 不要一直載入 GitHub MCP
# 改用 /gh-pr 命令包裝 gh pr create

With lazy loading，context window 問題大部分解決。但 token 成本仍可用 CLI + skills 方法優化。

---

參考資源

• Anthropic: Demystifying evals for AI agents (Jan 2026)
• Anthropic: "Claude Code Best Practices" (Apr 2025)
• Fireworks AI: "Eval Driven Development with Claude Code" (Aug 2025)
• YK: 32 Claude Code Tips (Dec 2025)
• Addy Osmani: "My LLM coding workflow going into 2026"
• @PerceptualPeak: Sub-Agent Context Negotiation
• @menhguin: Agent Abstractions Tierlist
• @omarsar0: Compound Effects Philosophy
• RLanceMartin: Session Reflection Pattern
• @alexhillman: Self-Improving Memory System

---

驗證

• [x] 完整分析 agents/, skills/, hooks/, rules/
• [x] 識別可借鑑的設計模式
• [x] 與 Self-Evolving Agent 比較
• [x] 提出整合優先度建議
• [x] 研究 Shorthand Guide (Twitter)
• [x] 研究 Longform Guide (Twitter)
• [x] 整合兩篇指南核心洞察

Knowledge Nexus 專案分析報告

專案: github.com/miles990/knowledge-nexus 分析日期: 2026-01-23 版本: 0.1.0

---

一、專案概述

1.1 定位與願景

Personal Knowledge MCP Server — 將個人收集的知識碎片轉化為 Claude Code 可主動查詢的養分。

解決的痛點：

1.2 技術棧

---

二、架構分析

2.1 整體架構

┌─────────────────────────────────────────────────┐
│              Knowledge Nexus                     │
├─────────────────────────────────────────────────┤
│  CLI (kn)  │  Browser Ext  │  MCP  │  Hooks    │
└──────┬─────┴───────┬───────┴───┬───┴─────┬─────┘
       │             │           │         │
       └─────────────┴─────┬─────┴─────────┘
                           ▼
┌─────────────────────────────────────────────────┐
│                  Core Server                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ REST API │  │   MCP    │  │ WebSocket│      │
│  │ :8765    │  │  stdio   │  │  (未來)  │      │
│  └──────────┘  └──────────┘  └──────────┘      │
│                      │                          │
│  ┌──────────────────────────────────────────┐  │
│  │           Service Layer                   │  │
│  │  Knowledge │ Session │ Project │ Insights │  │
│  └──────────────────────────────────────────┘  │
│                      │                          │
│  ┌──────────────────────────────────────────┐  │
│  │              Data Layer                   │  │
│  │     SQLite + FTS4    │   (Vector DB 未來)│  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

2.2 目錄結構（標準 Go 佈局）

knowledge-nexus/
├── cmd/kn/              # CLI 入口
├── internal/
│   ├── config/          # 配置管理
│   ├── db/              # 資料庫層（Repository）
│   ├── service/         # 業務邏輯層
│   ├── server/          # REST API
│   ├── mcp/             # MCP Server
│   └── cli/             # CLI 命令
├── extension/           # Chrome Extension
├── hooks/               # Claude Code Hooks
├── docs/skills/         # 開發過程中產生的 Skills
└── .spec-workflow/      # spec-workflow 規劃文件

---

三、MCP Data Tools 模式（重點）

3.1 什麼是 MCP Data Tools 模式

核心理念：MCP Tools 只負責提供結構化資料，讓 Claude 做分析和決策。

傳統模式 vs Data Tools 模式：

3.2 實作範例

傳統模式（Server 做 AI 分析）：

// ❌ 傳統：Server 調用 AI API 做分析
func GetInsights(ctx context.Context) (string, error) {
    data := fetchData()
    // 調用 OpenAI API 分析
    response := openai.Analyze(data)  // 需要 API key + 成本
    return response.Summary, nil
}

MCP Data Tools 模式：

// ✅ Data Tools：Server 只提供資料，Claude 分析
func GetKnowledgeInsights(ctx context.Context) (*KnowledgeInsights, error) {
    return &KnowledgeInsights{
        TotalEntries:   count,
        EntriesByType:  typeMap,      // 結構化資料
        TopTags:        topTags,      // 結構化資料
        ContentStats:   stats,        // 結構化資料
    }, nil
}
// Claude 收到資料後自己分析、產生洞察

3.3 Knowledge Nexus 的應用

AI 處理流水線：

┌─────────────────────────────────────────────────────┐
│                    Claude Code                       │
│  ┌─────────────────────────────────────────────┐   │
│  │  1. 調用 get_pending_knowledge               │   │
│  │  2. 收到待處理的 raw content                 │   │
│  │  3. Claude 自己分析、生成 markdown + summary │   │
│  │  4. 調用 update_markdown_content 儲存結果    │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│              Knowledge Nexus MCP Server              │
│  - 只負責 CRUD                                      │
│  - 不調用任何外部 AI API                            │
│  - 讓 Claude 成為 AI 引擎                           │
└─────────────────────────────────────────────────────┘

3.4 優點總結

1. 零額外 API 成本 - 利用現有的 Claude 對話 2. 無需管理 API Key - Server 端無敏感資訊 3. 更靈活的分析 - Claude 可根據上下文調整分析方式 4. 即時迭代 - 不需要修改 Server 就能改變分析邏輯 5. 本地優先 - 所有資料和處理都在本地

---

四、實作品質評估

4.1 程式碼品質

4.2 亮點設計

1. 大型回應處理 - 防止 Claude Code 處理大型 MCP 回應時卡住 2. 短 ID 支援 - 8 字元前綴匹配，提升 CLI 體驗 3. spec-workflow 整合 - 完整的規劃驅動開發

---

五、提供的 MCP Tools（17 個）

---

六、開發進度

---

七、綜合評分

---

八、未來建議

短期

• 完成 Browser Extension MVP
• 強化 AI 處理流程

中期

• 實作語義搜尋（Chroma Vector DB）
• AI 對話匯入功能

長期

• 同步機制（iCloud/Git-based）
• 知識圖譜視覺化

---

九、與 Self-Evolving Agent 整合建議

---

關鍵學習

1. MCP Data Tools 模式 - 讓 Claude 成為 AI 引擎，零額外成本 2. 大型回應處理 - 50KB 限制 + 檔案落地機制 3. spec-workflow 規劃驅動 - 完整的需求→設計→任務流程

MCP 進階設計模式詳解

分析日期: 2026-01-23 涵蓋模式: Full AI Processing、Progressive Discovery、Code Execution

---

一、Full AI Processing 模式

1.1 核心概念

定義：Server 端整合 AI API（如 OpenAI、Claude API），在 Server 內部完成資料分析和處理，只回傳最終結論給 Client。

┌─────────────────────────────────────────────────────────────┐
│                    Client (User/App)                         │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  request: get_document_summary(doc_id: "123")         │  │
│  │  response: "這份文件討論了三個主要議題..."             │  │
│  └───────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 MCP Server (Full AI Processing)              │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  1. 接收請求                                         │    │
│  │  2. 從資料庫讀取原始文件（可能 50,000+ tokens）      │    │
│  │  3. 調用 OpenAI API 進行分析                        │    │
│  │  4. 回傳精簡的分析結果（~500 tokens）               │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  需要配置：OPENAI_API_KEY、模型選擇、Prompt Engineering     │
└─────────────────────────────────────────────────────────────┘

1.2 實作範例（Go）

// Full AI Processing 模式的 MCP Tool
type DocumentSummaryTool struct {
    db       *Database
    aiClient *openai.Client  // Server 持有 AI Client
}

func (t *DocumentSummaryTool) Execute(ctx context.Context, req SummaryRequest) (*SummaryResponse, error) {
    // 1. 從資料庫讀取大量原始資料
    doc, err := t.db.GetDocument(ctx, req.DocID)
    if err != nil {
        return nil, err
    }

    // 2. Server 端調用 AI API 分析
    completion, err := t.aiClient.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
        Model: "gpt-4",
        Messages: []openai.ChatCompletionMessage{
            {Role: "system", Content: "你是文件分析專家，請提供簡潔摘要。"},
            {Role: "user", Content: doc.Content},  // 大量資料只在 Server 端處理
        },
    })
    if err != nil {
        return nil, err
    }

    // 3. 只回傳精簡結果給 Client
    return &SummaryResponse{
        Summary:    completion.Choices[0].Message.Content,  // ~500 tokens
        KeyPoints:  extractKeyPoints(completion),
        Confidence: 0.95,
    }, nil
}

1.3 優缺點分析

1.4 適用場景

✅ 適合：
├── 企業級應用（需要一致性和安全性）
├── 大量資料的批次處理（ETL pipeline）
├── 敏感資料分析（不能傳到 Client）
├── 需要特定模型/prompt 的專業分析
└── 非對話式的背景處理任務

❌ 不適合：
├── 個人工具（成本考量）
├── 需要靈活調整分析邏輯的場景
├── 預算有限的專案
└── 本地優先的隱私敏感應用

1.5 與 Data Tools 模式對比

                    Data Tools                Full AI Processing
                    ──────────                ──────────────────
AI 處理位置         Client (Claude)           Server (OpenAI/etc)

MCP Server 回傳：
Data Tools:                          Full AI Processing:
{                                    {
  "entries": [...大量資料...],         "summary": "簡潔結論",
  "stats": {...}                       "confidence": 0.95
}                                    }
(Client Claude 自己分析)              (已分析完成)

Token 消耗: 高                       Token 消耗: 低
API 成本: 零                         API 成本: 每次都產生
彈性: 高                             彈性: 低

---

二、Progressive Discovery 模式（Strata Pattern）

2.1 核心概念

定義：分層揭露 Tool 資訊，讓 AI Agent 逐步縮小範圍，避免一次載入所有 Tool 定義造成 Context Window 爆炸。

解決的問題：

當你暴露更多 Tools 給 AI Agent，效能會下降。銷售 AI 可能在處理簡單的「獲取所有潛在客戶」任務時掙扎，同時燒掉昂貴的 tokens 處理不相關的 Tool 描述。

傳統模式：一次載入所有 Tool 定義
┌─────────────────────────────────────────────────────────────────┐
│  Context Window                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Tool 1: create_user(name, email, role, department, ...)    │ │
│  │ Tool 2: update_user(id, name, email, role, ...)            │ │
│  │ ... 還有 95 個 Tools ...                                    │ │
│  │ Tool 100: generate_report(type, range, format, ...)        │ │
│  └────────────────────────────────────────────────────────────┘ │
│  ❌ 大量 tokens 浪費在不相關的 Tool 定義                         │
└─────────────────────────────────────────────────────────────────┘

Progressive Discovery：分層按需載入
┌─────────────────────────────────────────────────────────────────┐
│  Stage 1: 只載入類別                                             │
│  │ discover_categories() → ["users", "orders", "reports"]       │
│                              ↓ Agent 選擇 "users"               │
│  Stage 2: 載入該類別的動作名稱                                   │
│  │ get_actions("users") → ["create", "update", "delete"]        │
│                              ↓ Agent 選擇 "create"              │
│  Stage 3: 載入完整參數 Schema                                    │
│  │ get_action_details("users.create") → { full JSON schema }    │
│  ✅ 只載入需要的 Tool 定義                                       │
└─────────────────────────────────────────────────────────────────┘

2.2 四階段流程

Stage 1: discover_server_categories()
──────────────────────────────────────
輸入: 無
輸出: ["user_management", "order_processing", "reporting"]
Token 成本: ~50 tokens

                    ↓

Stage 2: get_category_actions(category)
───────────────────────────────────────
輸入: "user_management"
輸出: [
  { "name": "create_user", "desc": "建立新用戶" },
  { "name": "update_user", "desc": "更新用戶資料" },
  { "name": "delete_user", "desc": "刪除用戶" }
]
Token 成本: ~100 tokens（無完整 schema）

                    ↓

Stage 3: get_action_details(action_name)
────────────────────────────────────────
輸入: "create_user"
輸出: {
  "name": "create_user",
  "description": "建立新用戶帳號",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "role": { "enum": ["admin", "user", "guest"] }
    },
    "required": ["name", "email"]
  }
}
Token 成本: ~200 tokens（完整 schema）

                    ↓

Stage 4: execute_action(action_name, params)
────────────────────────────────────────────
輸入: "create_user", { "name": "John", "email": "..." }
輸出: { "id": "usr_123", "status": "created" }

2.3 實作範例（Go）

// Progressive Discovery MCP Server

type ProgressiveServer struct {
    categories map[string]Category
}

// Stage 1: 發現類別
func (s *ProgressiveServer) DiscoverCategories(ctx context.Context) ([]CategoryInfo, error) {
    var result []CategoryInfo
    for name, cat := range s.categories {
        result = append(result, CategoryInfo{
            Name:        name,
            Description: cat.Description,
            ActionCount: len(cat.Actions),
        })
    }
    return result, nil  // 只回傳名稱和描述，不回傳 schema
}

// Stage 2: 獲取類別內的動作列表
func (s *ProgressiveServer) GetCategoryActions(ctx context.Context, category string) ([]ActionInfo, error) {
    cat, ok := s.categories[category]
    if !ok {
        return nil, fmt.Errorf("category %s not found", category)
    }

    var result []ActionInfo
    for name, action := range cat.Actions {
        result = append(result, ActionInfo{
            Name:        name,
            Description: action.Description,
            // 注意：不包含 Schema！
        })
    }
    return result, nil
}

// Stage 3: 獲取特定動作的完整定義
func (s *ProgressiveServer) GetActionDetails(ctx context.Context, category, action string) (*ActionDetails, error) {
    cat := s.categories[category]
    act := cat.Actions[action]

    return &ActionDetails{
        Name:        act.Name,
        Description: act.Description,
        InputSchema: act.Schema,  // 此時才回傳完整 Schema
    }, nil
}

// Stage 4: 執行動作
func (s *ProgressiveServer) ExecuteAction(ctx context.Context, category, action string, params any) (any, error) {
    cat := s.categories[category]
    act := cat.Actions[action]
    return act.Handler(ctx, params)
}

2.4 Token 效率對比

場景：100 個 Tools，每個 Tool 的 Schema 約 200 tokens

傳統模式：
  載入所有 Tools = 100 × 200 = 20,000 tokens
  每次對話都消耗這些 tokens

Progressive Discovery：
  Stage 1: ~50 tokens   (類別列表)
  Stage 2: ~100 tokens  (動作列表)
  Stage 3: ~200 tokens  (單一 Schema)
  ──────────────────────
  總計:   ~350 tokens   (98% 減少！)

2.5 優缺點分析

2.6 適用場景

✅ 適合：
├── 企業級多功能 MCP Server（100+ Tools）
├── 需要智能 Tool 選擇的複雜系統
├── 多租戶系統（不同用戶看到不同 Tools）
└── 動態 Tool 註冊的平台

❌ 不適合：
├── 小型專案（< 20 Tools）
├── 簡單的單一用途 Server
├── 需要最低延遲的場景
└── AI Agent 能力有限時

---

三、Code Execution 模式

3.1 核心概念

定義：Agent 不直接呼叫 MCP Tools，而是撰寫程式碼（TypeScript/JavaScript/Python）來操作 Tools，資料處理在執行環境中完成，只有最終結果回傳給 Model。

來源：Anthropic 於 2025 年提出的 "Code Execution with MCP"

3.2 傳統 vs Code Execution 對比

傳統 Tool Calling 模式：

  Model ──┬── call tool_1() ──→ result_1 (5,000 tokens) ──┐
          │                                                │
          │   ← 回傳 Model，消耗 Context ←─────────────────┘
          │
          ├── call tool_2(result_1) ──→ result_2 (3,000 tokens)
          │   ← 回傳 Model，消耗 Context ←─────────────────┘
          │
          └── ... 重複 10 次 ...

  總計：~150,000 tokens（每次結果都經過 Model）


Code Execution 模式：

  Model ──→ 生成程式碼 ──→ 執行環境
                            │
          ┌─────────────────┴─────────────────┐
          │  // 在執行環境中處理               │
          │  const data1 = await mcp.tool_1() │
          │  const data2 = await mcp.tool_2() │
          │  const filtered = data1.filter()  │
          │  const result = summarize(merged) │
          │  return result  // 只回傳最終結果 │
          └─────────────────┬─────────────────┘
                            │
                            ▼
  Model ←── 只收到精簡結果 (~2,000 tokens) ←──┘

  總計：~2,000 tokens（98.7% 減少！）

3.3 系統架構

┌─────────────────────────────────────────────────────────────────┐
│                        AI Agent (Claude)                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  理解任務 → 撰寫程式碼 → 等待執行結果 → 繼續對話          │  │
│  └───────────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────────┘
                            │ 傳送程式碼
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Code Execution Environment                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  • 安全沙箱（Sandboxed Runtime）                          │  │
│  │  • 支援 TypeScript / JavaScript / Python                  │  │
│  │  • MCP Client SDK 內建                                    │  │
│  │  • 可存取本地檔案系統（受限）                             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                            │                                     │
│                            │ MCP Protocol                        │
│                            ▼                                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    MCP Servers                             │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐      │  │
│  │  │ Files   │  │ Database│  │ API     │  │ Custom  │      │  │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘      │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

3.4 實作範例

傳統 Tool Calling（對比用）：

// 傳統方式：每個步驟都要 Model 參與

// Step 1: Model 決定呼叫 get_orders
const orders = await mcp.call('get_orders', { limit: 1000 });
// → 1000 筆資料傳回 Model（~30,000 tokens）

// Step 2: Model 分析後決定呼叫 get_products
const products = await mcp.call('get_products', { ids: productIds });
// → 產品資料傳回 Model（~10,000 tokens）

// Step 3: Model 分析後決定呼叫 get_categories
const categories = await mcp.call('get_categories', { ids: categoryIds });
// → 類別資料傳回 Model（~5,000 tokens）

// 總計：~45,000+ tokens，多次 Model 往返

Code Execution 方式：

// Code Execution：Model 生成一段程式碼，一次執行完成

async function analyzeOrdersByCategory() {
  // 所有資料處理都在執行環境中完成
  const orders = await mcp.call('db', 'get_orders', { limit: 1000 });
  const productIds = [...new Set(orders.map(o => o.product_id))];

  const products = await mcp.call('db', 'get_products', { ids: productIds });
  const productMap = new Map(products.map(p => [p.id, p]));

  const categoryIds = [...new Set(products.map(p => p.category_id))];
  const categories = await mcp.call('db', 'get_categories', { ids: categoryIds });
  const categoryMap = new Map(categories.map(c => [c.id, c]));

  // 複雜的資料處理邏輯
  const analysis = orders.reduce((acc, order) => {
    const product = productMap.get(order.product_id);
    const category = categoryMap.get(product?.category_id);
    const categoryName = category?.name || 'Unknown';

    if (!acc[categoryName]) {
      acc[categoryName] = { count: 0, revenue: 0, products: new Set() };
    }
    acc[categoryName].count++;
    acc[categoryName].revenue += order.amount;
    acc[categoryName].products.add(order.product_id);

    return acc;
  }, {});

  // 只回傳精簡的分析結果
  return Object.entries(analysis)
    .map(([name, data]) => ({
      category: name,
      orderCount: data.count,
      totalRevenue: data.revenue,
      uniqueProducts: data.products.size
    }))
    .sort((a, b) => b.totalRevenue - a.totalRevenue);
}

// 回傳給 Model：~500 tokens（vs 45,000+ tokens）

複雜流程控制：

// Code Execution 的強大之處：迴圈、條件、錯誤處理

async function processAllCustomers() {
  const customers = await mcp.call('crm', 'list_customers', { status: 'active' });
  const results = [];

  for (const customer of customers) {
    try {
      // 條件邏輯
      if (customer.tier === 'enterprise') {
        const usage = await mcp.call('billing', 'get_usage', { id: customer.id });
        const forecast = await mcp.call('analytics', 'forecast', {
          customerId: customer.id,
          months: 3
        });

        if (usage.current > usage.limit * 0.8) {
          // 自動發送警告
          await mcp.call('notifications', 'send', {
            to: customer.email,
            template: 'usage_warning',
            data: { usage, forecast }
          });
          results.push({ customer: customer.id, action: 'warned' });
        }
      }
    } catch (error) {
      // 錯誤處理
      results.push({ customer: customer.id, error: error.message });
    }
  }

  return {
    processed: customers.length,
    actions: results.filter(r => r.action).length,
    errors: results.filter(r => r.error).length,
    details: results
  };
}

3.5 優缺點分析

3.6 安全性設計

┌─────────────────────────────────────────────────────────────────┐
│                    Security Sandbox Design                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Sandboxed Runtime                      │    │
│  │  • 受限的檔案系統存取                                    │    │
│  │  • 網路請求白名單                                        │    │
│  │  • 執行時間限制                                          │    │
│  │  • 記憶體限制                                            │    │
│  │  • 禁止系統呼叫                                          │    │
│  │  • 只能透過 MCP 存取外部資源                             │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  允許：                                                          │
│  ✅ 資料處理和轉換                                              │
│  ✅ 透過 MCP 呼叫已授權的 Tools                                 │
│  ✅ 本地運算（排序、過濾、聚合）                                │
│                                                                  │
│  禁止：                                                          │
│  ❌ 直接網路請求（繞過 MCP）                                    │
│  ❌ 檔案系統寫入（除指定目錄）                                  │
│  ❌ 執行系統命令                                                │
│  ❌ 存取環境變數和敏感資訊                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

3.7 生態系統支援（2025-2026）

3.8 適用場景

✅ 強烈推薦：
├── 多步驟資料處理流程
├── 需要迴圈處理大量項目
├── 複雜的條件分支邏輯
├── ETL 類型的資料轉換
├── 批次操作（如批次更新、批次通知）
└── 需要錯誤處理和重試邏輯

⚠️ 視情況：
├── 中等複雜度的 3-5 步驟任務
├── 需要即時互動的場景
└── 安全性要求極高的環境

❌ 不推薦：
├── 單一 Tool 呼叫
├── 簡單的 Q&A 場景
├── 沒有執行環境的情況
└── AI Agent 程式能力有限

---

四、三種模式效率對比

4.1 Token 效率矩陣

4.2 模式選擇決策樹

                        開始
                          │
          ┌───────────────┴───────────────┐
          │ Tools 數量超過 50 個嗎？       │
          └───────────────┬───────────────┘
                  ↙ No          Yes ↘
                  │           考慮 Progressive
                  │           Discovery
                  ↓
          ┌───────────────────────────────┐
          │ 任務涉及多步驟資料處理嗎？     │
          └───────────────┬───────────────┘
                  ↙ No          Yes ↘
                  │           ┌──────────┐
                  │           │有執行環境?│
                  │           └────┬─────┘
                  │         ↙ No    Yes ↘
                  │    Full AI    Code Execution
                  │    Processing    (最佳)
                  ↓
          ┌───────────────────────────────┐
          │ 需要 Server 端 AI 處理嗎？     │
          └───────────────┬───────────────┘
                  ↙ No          Yes ↘
           Data Tools      Full AI Processing
           (最簡單)        (一致性分析)

---

五、模式組合建議

5.1 常見組合

5.2 混合架構範例

Progressive Discovery + Full AI Processing + Code Execution

1. Agent 透過 Progressive Discovery 找到需要的 Tool
   └── discover → "analytics" → "generate_insights"

2. 該 Tool 內部使用 Full AI Processing
   └── Server 調用 AI API 分析大量資料

3. 多個 Tools 組合時使用 Code Execution
   └── Agent 寫程式碼串接多個分析結果

效果：
- Tool 發現階段：最小 token 消耗（Progressive）
- 單一分析階段：Server 端處理（Full AI）
- 組合階段：Client 端優化（Code Exec）

---

六、關鍵學習總結

2026 年趨勢： 1. Code Execution 快速成為主流 2. 混合模式越來越常見 3. Progressive Discovery 在企業端普及

---

參考資源

• Code Execution with MCP - Anthropic
• Less is More: MCP Design Patterns - Klavis AI
• MCP Best Practices
• 15 Best Practices for MCP Servers - The New Stack