Everything Claude Code (ECC) 教學手冊

文件版本：v3.1（2026-08-31 深化與查證更新；新增 Agent 安全威脅情資、可觀測性與斷路器、企業治理章節）
對應 ECC 版本：v2.2.0（CHANGELOG 標記發行日 2026-08-25，主題為「Guided Setup、Antigravity 2.0 原生安裝、Unified Memory Vault」）；前一個大版本為 v2.1.0（2026-07-28，「Plan Canvas, Kimi Harness, and Self-Hosted Compute」）。2026-08-31 覆核：CHANGELOG.md 的 [Unreleased] 區塊為空，v2.2.0 仍是最新已標記版本
適用對象：軟體工程師（初階～資深）、系統架構師、DevOps / SRE、AI 平台工程師、技術主管（導入評估用）
授權：MIT License（開源永久免費；另有 ECC Tools Pro／Enterprise 為選配的託管 GitHub App 服務，詳見 3.2 與附錄 F）
官方 GitHub：https://github.com/affaan-m/ECC（原倉庫名 everything-claude-code 已重新命名為 ECC，舊網址會自動轉導）
官方網站：https://ecc.tools
npm 套件：ecc-universal（安裝器與 CLI）、ecc-agentshield（安全稽核器）
GitHub Marketplace（GitHub App）：https://github.com/marketplace/ecc-tools
Discord 社群：https://discord.gg/36yGMHGFbR
繁體中文官方 README：https://github.com/affaan-m/ECC/blob/main/docs/zh-TW/README.md
社群統計（2026-08-31 以 GitHub REST API 實測）：244,733 Stars ∣ 36,989 Forks ∣ 1,253 Watchers ∣ 331 位貢獻者 ∣ 21+ 語言／框架 Rules 生態系 ∣ 120 個開放 Issue／PR（GitHub open_issues_count 為兩者合計，非純 Issue 數） ∣ 倉庫體積約 48.6 MB ∣ 最後推送 2026-08-30
核心元件規模：68 Agents ∣ 286 Skills ∣ 94 Command Shims（legacy，逐步遷移至 Skills）
程式語言組成：JavaScript 70.3% ∣ Rust 21.4%（ecc2/ 控制平面）∣ Python 4.6% ∣ Shell 2.4% ∣ TypeScript 1.2%
官方指南（現已收錄於 repo 中，非社群媒體貼文）：
— The Shortform Guide（入門首選）
— The Longform Guide（進階深入：Token 最佳化、記憶持久化、Eval、平行化）
— The Security Guide（攻擊面、沙箱化、CVE、AgentShield）
— Commands Quick Reference（94 個指令的完整索引與退役對照）
— MCP Connector Policy（預設連接器准入規則）
獨立參考資料：Anthropic 官方《Claude Code Best Practices》 — ECC 是建構在 Claude Code 原生能力（Plan Mode、Hooks、Skills、Subagents、Checkpoints）之上的一層工程框架，而非取代品；本手冊會在各章節明確標示「Claude Code 原生功能」與「ECC 擴充功能」的分野。

⚠️ 安全前置閱讀：若您的組織正在評估「讓 AI 代理存取內部程式碼庫」的風險，請先閱讀第七章（尤其 7.6 威脅情資、7.7 沙箱化、7.12 最低門檻檢查表）再進行任何安裝。2026 年已有多起針對編碼代理的實證攻擊與 CVE，安全基線應優先於功能導入。

⚠️ 企業導入提醒：ECC 是由單一維護者（Affaan Mustafa）主導、社群共同貢獻的開源專案，並非 Anthropic 官方產品。採用前請參閱第十三章〈企業導入評估與風險考量〉，理解其治理模式、社群爭議（過度工程化批評）與替代方案比較，再決定導入範圍。

⚠️ 數字時效性聲明：本手冊所有元件數量（Agents／Skills／Commands）與社群統計皆為快照，ECC 每週都在變動。請勿以本文任何固定數字作為採購、稽核或合約依據；正式查核請以 npx ecc-universal doctor、ecc list-installed 或 /plugin list ecc@ecc 的實際輸出為準。

📑 目錄

• 第一章：Everything Claude Code 架構總覽
  • 1.1 ECC 是什麼
  • 1.2 與傳統 Prompt Engineering 差異
  • 1.3 Context Engineering 與 Harness Engineering
  • 1.4 ECC 整體架構圖
  • 1.5 Agent / Skills / Hooks / Commands 關係圖
  • 1.6 版本演進歷程
• 第二章：ECC 核心組件解析
  • 2.1 Agents（代理）
  • 2.2 Skills（技能）
  • 2.3 Commands & Hooks
  • 2.4 Rules（規則）
  • 2.5 記憶與上下文管理
  • 2.6 Contexts（動態上下文注入）
  • 2.7 MCP Server 配置
  • 2.8 Claude Code 原生功能與 ECC 擴充功能分工
  • 2.9 Unified Memory Vault（跨 Harness 統一記憶庫）
• 第三章：安裝與環境建置
  • 3.1 前置需求
  • 3.2 Plugin 安裝（推薦）
  • 3.3 手動安裝
  • 3.4 Windows PowerShell 安裝
  • 3.5 跨 Harness 整合（13+ 平台總覽）
  • 3.6 環境變數設定
  • 3.7 Dashboard GUI
  • 3.8 套件管理器偵測
  • 3.9 故障復原與診斷
  • 3.10 自架模型、自訂端點與 GPU 運算
  • 3.11 平台支援分級與跨作業系統相容性
• 第四章：企業級 Web 系統架構設計（搭配 ECC）
  • 4.1 企業系統架構背景
  • 4.2 ECC Agent 分工架構
  • 4.3 Orchestrator 家族
  • 4.4 系統架構圖
  • 4.5 Agent 協作流程
  • 4.6 Rules 與 Skills 的分層治理
  • 4.7 CLAUDE.md 分層策略
  • 4.8 團隊角色與責任邊界
• 第五章：開發流程（AI 驅動）
  • 5.1 AI 驅動開發總覽
  • 5.2 /plan — 需求規劃
  • 5.3 架構設計 — architect Agent
  • 5.4 實作（TDD）— tdd-workflow Skill
  • 5.5 測試 — e2e-testing Skill 與 /test-coverage
  • 5.6 /code-review — 程式碼審查
  • 5.7 部署 — deployment-patterns Skill
  • 5.8 驗證迴圈 — verification-loop 與 eval-harness Skill
  • 5.9 Plan Canvas — 視覺化計畫審查
• 第六章：測試與品質控管
  • 6.1 TDD Skill 實作
  • 6.2 自動 Code Review
  • 6.3 Plankton 程式碼品質
  • 6.4 AgentShield 安全掃描
  • 6.5 CI/CD 整合測試流程
  • 6.6 驗證迴圈與評估框架
• 第七章：安全（SSDLC）
  • 7.1 ECC 安全架構
  • 7.2 安全檢查自動化
  • 7.3 OWASP Top 10 防護
  • 7.4 Secret Detection
  • 7.5 GateGuard 安全閘門
  • 7.6 威脅情資：2026 年代理式編碼的真實攻擊面
  • 7.7 沙箱化與隔離架構
  • 7.8 權限邊界與最小代理權（Least Agency）
  • 7.9 不可信輸入的消毒（Sanitization）
  • 7.10 記憶毒化與長期記憶治理
  • 7.11 MCP 安全與 OWASP MCP Top 10
  • 7.12 企業導入的最低安全門檻檢查表
• 第八章：部署與維運（DevOps）
  • 8.1 CI/CD 整合
  • 8.2 監控與日誌
  • 8.3 AI Agent 監控
  • 8.4 Agent 可觀測性（Observability）
  • 8.5 無人值守迴圈的斷路器（Circuit Breaker）
  • 8.6 成本治理與 Token 預算
• 第九章：系統維護與升級
  • 9.1 ECC 版本升級策略
  • 9.2 Skills / Agents 管理
  • 9.3 相容性與故障排除
  • 9.4 v2.1 → v2.2 升級實務檢查表
• 第十章：最佳實踐（Best Practices）
  • 10.1 避免上下文污染
  • 10.2 Agent 設計原則
  • 10.3 Skill 設計模式
  • 10.4 Token 最佳化
  • 10.5 平行化策略
  • 10.6 Claude Code 原生生產力功能
• 第十一章：常見問題與排錯
  • Q1：Agent 無法理解需求
  • Q2：記憶錯亂 / 重複犯錯
  • Q3：Token 爆掉 / 達到日限
  • Q4：指令失效
  • Q5：Hooks 不運作 / “Duplicate hooks file” 錯誤
  • Q6：能否只使用部分元件？
  • Q7：是否支援 Cursor / OpenCode / Codex / GitHub Copilot / Zed 以外的工具？
  • Q8：是否支援自訂 API 端點或模型閘道？
  • Q9：ECC 配置被清除了怎麼辦？
  • Q10：ECC 是 Anthropic 官方產品嗎？
  • Q11：想自架開源模型，ECC 能用嗎？
  • Q12：Memory Vault 跟 Instinct、CLAUDE.md 有什麼差別？
  • Q13：公司都用 Windows，可以導入 ECC 嗎？
  • Q14：團隊該選哪一種安裝路徑？
• 第十二章：進階應用
  • 12.1 多 Agent 協作（Multi-Agent System）
  • 12.2 與其他 AI 工具整合
  • 12.3 自訂 Agent
  • 12.4 ECC 2.0 Control-Pane Substrate
  • 12.5 NanoClaw v2
  • 12.6 GAN 風格產生器-評估器框架
  • 12.7 Operator Status Snapshots
  • 12.8 Cross-Harness Architecture
  • 12.9 ECC Tools Pro / Enterprise（託管 GitHub App）
  • 12.10 v2.2 新增進階能力（Council Review、Nasiko、Living Docs）
• 第十三章：企業導入評估與風險考量
  • 13.1 採用效益與整體擁有成本
  • 13.2 已知限制與社群爭議
  • 13.3 與 Anthropic 官方最佳實踐的定位關係
  • 13.4 導入決策框架
  • 13.5 替代方案比較
• 附錄
  • A. 常用指令 Cheat Sheet
  • B. Skills 範例模板
  • C. Agent 設計模板
  • D. 跨工具功能對照表
  • E. 檢查清單（Checklist）
  • F. 生態系工具與社群資源
  • G. 版本變更摘要
  • H. 資料來源與查證方法
  • I. 指令退役與遷移對照表
  • J. 環境變數總表

第一章：Everything Claude Code 架構總覽

1.1 ECC 是什麼

Everything Claude Code（ECC，官方 GitHub 倉庫名為 ECC，原名 everything-claude-code）是一套開源的代理控制系統（Agent Harness），其官方定位語是「the agent harness performance optimization system」——一套讓 Claude Code、Codex、Cursor、OpenCode 等 AI 編碼代理具備協調工程流程的框架。專案由 Affaan Mustafa 在 Anthropic × Forum Ventures 舉辦的駭客松中（以 8 小時打造 zenith.chat 獲得冠軍、贏得 1.5 萬美元 API 額度）所使用的個人配置演化而來，經過 10 個月以上的每日實戰淬鍊後開源。

ECC 官方將其核心工作流精煉為一句話：

plan → test → implement → review → verify → remember → improve

以及其設計哲學：

「Optimize the context window. Persist everything else.」 （最佳化上下文窗口，其餘一切都應被持久化保存。）

ECC 不只是一組配置檔，而是一套完整的系統，包含（2026-08-31 查證數字，來源：官方 repo README 與目錄清單）：

⚠️ 版本與數字一致性說明：上表反映 v2.2.0（2026-08-25）發行後的 main 分支現況。實務上官方文件自身就存在數字漂移（README 頁首寫 286 skills、同一份 README 的 「What’s Inside」區塊寫 284 skills），因為目錄內容每週都有社群 PR 併入。先前版本的公告數字依序為：v2.0.0（64 / 261 / 84）→ v2.1.0（67 / 281 / 94）→ v2.2.0（68 / 286 / 94）。企業導入時請一律以實際執行結果為準：npx ecc-universal doctor、ecc list-installed、/plugin list ecc@ecc。

核心定位：

• ✅ 解決 AI 編碼代理在長對話中的「上下文污染」與「遺忘決策」問題
• ✅ 提供持續學習與記憶持久化機制（Continuous Learning v2 / Instinct 系統、Unified Memory Vault）
• ✅ 跨平台支援：Claude Code（原生）、Codex（原生 Plugin）、Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen、Hermes、OpenClaw、Kimi Code、CodeBuddy、JoyCode、Kiro、Trae、Pi 等 13+ Harness（但能力分級差異極大，務必先讀 3.11 支援矩陣）
• ✅ 約 244,700 Stars、約 37,000 Forks、331 位貢獻者（2026-08-31 以 GitHub REST API 實測）
• ✅ MIT License，OSS 版本永久免費；另有 ECC Tools（GitHub App）提供 Pro / Enterprise 託管服務
• ⚠️ 非 Anthropic 官方產品，屬於社群維護的第三方框架——採用前請詳閱第十三章的風險考量

1.2 與傳統 Prompt Engineering 差異

💡 這個比較表呈現的是設計哲學上的差異，而非「有 ECC 才有這些能力」。Claude Code 本身已內建 Plan Mode、Hooks、Skills、Subagents、Checkpoints 等原生機制（見 Anthropic 官方 Best Practices for Claude Code）。ECC 的價值在於：把這些原生積木預先組裝成一套跨語言、跨團隊可複用的標準作業程序，並補上 Anthropic 未提供的安全掃描（AgentShield）、多 Harness 移植（Adapter Layer）、和社群共享的 Skill/Agent 目錄。第 2.8 節會逐項釐清「Claude Code 原生」與「ECC 擴充」的邊界。

1.3 Context Engineering 與 Harness Engineering

Prompt Engineering → Context Engineering → Harness Engineering
    (單一指令)         (上下文管理)          (完整代理控制系統)

Context Engineering 關注如何組織和管理提供給 LLM 的上下文資訊。Anthropic 官方最佳實踐文件明確指出，幾乎所有 Claude Code 的操作建議都源自同一個限制條件：

「Claude 的上下文窗口填充得很快，且效能會隨填充程度下降（performance degrades as context fills）。」

Harness Engineering 則是在此限制之上、更高層級的系統工程，涵蓋：

1. Agent 編排：多代理協作、任務委派、獨立上下文隔離
2. 記憶架構：短期記憶（Session）、長期記憶（Instincts / 統一記憶庫）
3. 品質閘門：自動測試、Code Review、安全掃描、對抗式驗證（Adversarial Review）
4. 效能調校：Token 最佳化、模型路由（haiku/sonnet/opus）、平行化策略

💡 獨立驗證觀點：這與 Anthropic 官方建議的「Explore → Plan → Code → Commit」四階段工作法、以及「給 Claude 一個可驗證的檢查機制（測試、build、截圖比對）」的核心原則高度一致——ECC 可視為將這些原則系統化、模組化、並跨 Harness 標準化後的工程實作。

1.4 ECC 整體架構圖

graph TB
    subgraph "ECC Core System"
        direction TB
        Plugin["🔌 Plugin System<br/>.claude-plugin/"]
        Agents["🤖 Agents (68)<br/>Specialized Subagents"]
        Skills["⚡ Skills (286)<br/>Workflow Definitions"]
        Commands["📋 Commands (94)<br/>Legacy Slash Shims"]
        Hooks["🪝 Hooks<br/>Auto-Triggered Actions"]
        Rules["📏 Rules (21+ 語言)<br/>Always-Follow Guidelines"]
        MCP["🔗 MCP Configs (1 default)<br/>chrome-devtools + opt-in"]
        MemVault["🗃️ Memory Vault<br/>.ecc/memory + ~/.ecc/memory"]
    end

    subgraph "Ecosystem Tools"
        AgentShield["🛡️ AgentShield<br/>Security Auditor"]
        SkillCreator["🏭 Skill Creator<br/>Pattern Extraction"]
        ContinuousLearning["🧠 Continuous Learning v2<br/>Instinct System"]
        Dashboard["📊 Dashboard GUI<br/>Component Explorer"]
        PlanCanvas["🖼️ Plan Canvas<br/>Browser Plan Review"]
        ECC2["🚀 ECC 2.0<br/>Rust Control Plane"]
        Ito["⚙️ Itô GPU Bridge<br/>Self-Hosted Compute"]
        Installer["🧭 Guided Installer (v2.2)<br/>ecc-universal setup / install --guided"]
    end

    subgraph "Supported Harnesses (13+)"
        ClaudeCode["Claude Code<br/>(native)"]
        Codex["OpenAI Codex<br/>(native plugin)"]
        Cursor["Cursor IDE"]
        OpenCode["OpenCode"]
        Gemini["Gemini CLI"]
        Zed["Zed"]
        Copilot["GitHub Copilot"]
        Kimi["Kimi Code"]
        Hermes["Hermes"]
        Others["OpenClaw · Antigravity · Qwen ·<br/>CodeBuddy · JoyCode · Kiro · Trae · Pi"]
    end

    Plugin --> Agents
    Plugin --> Skills
    Plugin --> Commands
    Plugin --> Hooks
    Plugin --> Rules
    Plugin --> MCP

    AgentShield --> Plugin
    SkillCreator --> Skills
    ContinuousLearning --> Skills
    PlanCanvas --> Plugin
    ECC2 --> Plugin
    Ito --> Kimi
    Installer --> Plugin

    ClaudeCode --> Plugin
    Codex --> Plugin
    Cursor --> Plugin
    OpenCode --> Plugin
    Gemini --> Plugin
    Zed --> Plugin
    Copilot --> Plugin
    Kimi --> Plugin
    Hermes --> Plugin
    Others --> Plugin

    ClaudeCode -.-> MemVault
    Codex -.-> MemVault
    Kimi -.-> MemVault
    Hermes -.-> MemVault

💡 圖中虛線代表 v2.2 新增的 Unified Memory Vault：它不經由 Plugin 層，而是各 Harness 直接讀寫的共用 Markdown 記憶庫，因此可以在 Claude Code、Codex、Kimi Code 之間交接工作（詳見 2.9）。

1.5 Agent / Skills / Hooks / Commands 關係圖

graph LR
    subgraph "User Interaction"
        User["👤 開發者"]
    end

    subgraph "Entry Points"
        SlashCmd["/plan, /code-review, /build-fix<br/>Slash Commands"]
        SkillInvoke["Skills Direct Invoke<br/>skills/tdd-workflow/"]
    end

    subgraph "Orchestration"
        Planner["📋 planner agent"]
        Architect["🏗️ architect agent"]
    end

    subgraph "Execution Agents"
        TDDGuide["🧪 tdd-guide"]
        CodeReviewer["🔍 code-reviewer"]
        SecurityReviewer["🔐 security-reviewer"]
        BuildResolver["🔧 build-error-resolver"]
        E2ERunner["🎭 e2e-runner"]
    end

    subgraph "Automation Layer"
        PreHook["PreToolUse Hooks"]
        PostHook["PostToolUse Hooks"]
        StopHook["Stop Hooks<br/>(Session End)"]
        SessionStart["SessionStart Hook"]
    end

    User --> SlashCmd
    User --> SkillInvoke
    SlashCmd --> Planner
    SkillInvoke --> Planner
    Planner --> Architect
    Planner --> TDDGuide
    Planner --> CodeReviewer
    Planner --> SecurityReviewer
    Planner --> BuildResolver
    Planner --> E2ERunner

    SessionStart -->|"載入上下文"| Planner
    PostHook -->|"自動格式化"| TDDGuide
    StopHook -->|"儲存記憶"| ContinuousLearning["🧠 Instinct Extraction"]
    PreHook -->|"安全檢查"| SecurityReviewer

💡 Best Practice：新的工作流程應優先定義為 Skill，不再建立新的 Command。ECC 正在將 commands/ 遷移至 skills/ 體系。

⚠️ 常見錯誤：混淆 Agent 與 Skill。Agent 是執行者（帶角色與工具限制），Skill 是工作流程定義（可被 Agent 調用或直接執行）。

1.6 版本演進歷程

ECC 自 2025 年 9 月起持續快速迭代，以下為主要里程碑（已依官方 Releases／CHANGELOG.md 校正日期與內容）：

⚠️ 版本使用建議：正式環境／CI 應鎖定已標記 Release 的版本（目前為 v2.2.0），並透過 git tag 或 npm 版本鎖定安裝，避免直接追蹤 main 分支的開發中變更。

⚠️ npm 發行落差（重要）：ECC 的 GitHub Release 建立時機被 npm 推廣流程所把關，因此可能出現 CHANGELOG 已標 2.2.0、但 GitHub Releases 頁面的 Latest 仍顯示 v2.1.0 的情況。官方 README 對此的建議是：使用 npm 套件指令前，先執行

npm view ecc-universal version

若仍回報 2.1.0，代表 2.2 的套件尚未推廣至 latest dist-tag，此時請改用 Claude Code 原生 plugin 指令路徑（/plugin marketplace add + /plugin install），不要硬套 2.2 的 ecc-universal 指令。

💡 完整變更記錄請參閱 CHANGELOG.md 及 Releases。

第二章：ECC 核心組件解析

2.1 Agents（代理）

Agent 是 ECC 的核心執行單元，每個 Agent 都是帶有特定角色、工具權限和模型配置的子代理。

2.1.1 Agent 定義格式

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
---

You are a senior code reviewer. Review the provided code for:
1. Code quality and maintainability
2. Security vulnerabilities (OWASP Top 10)
3. Performance issues
4. Test coverage gaps

2.1.2 主要 Agent 分類

截至 2026-08，官方 agents/ 目錄共收錄 68 個 Agent。以下依職能分組列出，完整清單請以 agents/ 目錄或 /plugin list ecc@ecc 查詢結果為準：

規劃與架構

探索與分析

通用品質與治理

安全與測試

文件

語言與框架審查（21 種）

typescript-reviewer、python-reviewer、go-reviewer、java-reviewer、kotlin-reviewer、rust-reviewer、cpp-reviewer、csharp-reviewer、php-reviewer、fsharp-reviewer、swift-reviewer、react-reviewer、vue-reviewer、django-reviewer、fastapi-reviewer、flutter-reviewer、database-reviewer、rag-pipeline-reviewer、healthcare-reviewer、mle-reviewer、network-config-reviewer

建構錯誤修復（Build Resolvers，12 種）

build-error-resolver（通用）、java-build-resolver、go-build-resolver、kotlin-build-resolver、rust-build-resolver、cpp-build-resolver、dart-build-resolver、django-build-resolver、react-build-resolver、swift-build-resolver、pytorch-build-resolver、harmonyos-app-resolver

自動化與產生器-評估器框架

業務、內容與開源治理

💡 相較於 v2.0.0 時期（66 agents），v2.1.0 後新增了 a11y-architect（無障礙架構）、agent-evaluator、code-simplifier、silent-failure-hunter、spec-miner、type-design-analyzer 等多個「Agent 品質治理」類別的新角色——反映 ECC 社群近期的重點從「涵蓋更多語言」轉向「治理與稽核 Agent 本身輸出品質」。

2.1.3 子代理（Sub-agent）設計模式

sequenceDiagram
    participant U as 開發者
    participant M as Main Agent
    participant P as Planner
    participant T as TDD Guide
    participant R as Code Reviewer
    participant S as Security Reviewer

    U->>M: /plan "新增 OAuth 登入"
    M->>P: 委派規劃任務
    P->>P: 分析需求、拆解步驟
    P-->>M: 回傳實作藍圖
    M->>T: 委派 TDD 開發
    T->>T: 定義介面 → 寫測試 → 實作 → 重構
    T-->>M: 回傳實作結果
    M->>R: 委派程式碼審查
    R->>R: 品質、效能、Maintainability 檢查
    R-->>M: 回傳審查報告
    M->>S: 委派安全審查
    S->>S: OWASP Top 10、依賴掃描
    S-->>M: 回傳安全報告
    M-->>U: 整合結果

💡 Best Practice：子代理使用獨立的上下文窗口，不會污染主對話。適合「寫完就扔」的任務。

2.2 Skills（技能）

Skills 是 ECC 的主要工作流程介面（Primary Workflow Surface），替代 legacy 的 commands/。

2.2.1 Skill 目錄結構

skills/
├── tdd-workflow/           # TDD 方法論
│   └── SKILL.md
├── security-review/        # 安全檢查清單
│   └── SKILL.md
├── springboot-patterns/    # Spring Boot 模式 ★ Java
│   └── SKILL.md
├── springboot-security/    # Spring Boot 安全 ★ Java
│   └── SKILL.md
├── springboot-tdd/         # Spring Boot TDD ★ Java
│   └── SKILL.md
├── java-coding-standards/  # Java 編碼標準 ★ Java
│   └── SKILL.md
├── jpa-patterns/           # JPA/Hibernate 模式 ★ Java
│   └── SKILL.md
├── backend-patterns/       # API、資料庫、快取模式
│   └── SKILL.md
├── api-design/             # REST API 設計
│   └── SKILL.md
├── e2e-testing/            # Playwright E2E 測試
│   └── SKILL.md
├── deployment-patterns/    # CI/CD、Docker、Rollback
│   └── SKILL.md
├── docker-patterns/        # Docker Compose、安全
│   └── SKILL.md
├── search-first/           # 研究優先工作流
│   └── SKILL.md
├── continuous-learning-v2/ # Instinct 學習系統
│   └── SKILL.md
├── strategic-compact/      # 策略性壓縮
│   └── SKILL.md
├── security-scan/          # AgentShield 整合
│   └── SKILL.md
├── autonomous-loops/       # 自主迴圈模式
│   └── SKILL.md
├── plankton-code-quality/  # 寫入時品質強制
│   └── SKILL.md
├── mle-workflow/           # 生產 ML Pipeline、評估、部署 ★ 新增
│   └── SKILL.md
├── nestjs-patterns/        # NestJS 框架模式 ★ 新增
│   └── SKILL.md
├── liquid-glass-design/    # iOS 26 Liquid Glass 設計系統 ★ 新增
│   └── SKILL.md
├── foundation-models-on-device/ # Apple 裝置端 LLM ★ 新增
│   └── SKILL.md
├── swift-concurrency-6-2/  # Swift 6.2 並發模式 ★ 新增
│   └── SKILL.md
├── perl-patterns/          # Modern Perl 5.36+ 慣用語法 ★ 新增
│   └── SKILL.md
├── codehealth-mcp/         # CodeScene Code Health（opt-in）★ 新增
│   └── SKILL.md
├── dmux-workflows/         # 多 Agent tmux 編排 ★ 新增
│   └── SKILL.md
├── videodb/                # 影音處理與串流 ★ 新增
│   └── SKILL.md
├── plan-canvas/            # Plan Canvas 視覺化計畫審查 ★ v2.1.0 新增
│   └── SKILL.md
├── ito-compute/            # Itô GPU 運算橋接（RFQ、節點查找）★ v2.1.0 新增
│   └── SKILL.md
├── hermes-imports/         # Hermes operator 匯入 ★ 新增
│   └── SKILL.md
├── openclaw-persona-forge/ # OpenClaw persona 建構 ★ 新增
│   └── SKILL.md
├── github-ops/             # gh CLI 包裝（取代 github MCP）★ 新增
│   └── SKILL.md
├── documentation-lookup/   # Context7 REST API 包裝（取代 context7 MCP）★ 新增
│   └── SKILL.md
├── exa-search/             # Exa 搜尋 API 包裝（取代 exa MCP）★ 新增
│   └── SKILL.md
└── ...（共 286 個，完整清單請查閱官方 repo 或執行 `node scripts/ecc.js list-installed`）

2.2.2 Skill 定義範例（Spring Boot TDD）

---
name: springboot-tdd
description: Test-Driven Development workflow for Spring Boot applications
tags: [java, spring-boot, tdd, testing]
---

# Spring Boot TDD Workflow

## 執行步驟

1. **定義介面**：先寫 Controller/Service Interface
2. **RED**：撰寫失敗的測試案例
   - 使用 `@WebMvcTest` 測試 Controller
   - 使用 `@DataJpaTest` 測試 Repository
   - 使用 Mockito 模擬依賴
3. **GREEN**：實作最小程式碼通過測試
4. **REFACTOR**：重構，保持測試綠燈
5. **驗證覆蓋率**：目標 80%+

## 範例

```java
@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean UserService userService;

    @Test
    void shouldReturnUserById() throws Exception {
        given(userService.findById(1L))
            .willReturn(Optional.of(new User(1L, "Alice")));

        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Alice"));
    }
}
```

2.3 Commands & Hooks

2.3.1 主要指令（Slash Commands）

⚠️ 分辨來源：下表刻意標註每個指令的來源。/compact、/clear、/cost、/model 等是 Claude Code CLI 原生指令，無論是否安裝 ECC 都能使用；ECC 只是在最佳實踐（第十章）中建議「何時使用」。真正屬於 ECC 帶來的，是 /plan、/code-review、/build-fix 等對應到特定 Agent／Skill 的工作流指令，以及 /harness-audit、/loop-start 等 ECC 專屬能力。

🚨 2026 年最重要的變更：部分斜線指令已「退役」
ECC 正在把工作流從「斜線指令」遷移到「Skills」。12 個舊指令（含 /tdd、/e2e、/verify、/docs）已被移出預設安裝，其檔案改置於 repo 的 legacy-command-shims/commands/ 目錄，不會隨 plugin 或 install.sh 安裝。若你照舊教學輸入 /tdd，在新版環境中會得到「找不到指令」。完整對照請見 附錄 I，本手冊第五、六章的流程說明也已同步改寫為 Skill 呼叫方式。

常用指令速查（依來源標註）：

2.3.2 完整指令目錄（94 個，依用途分類）

以下為官方 COMMANDS-QUICK-REF.md 的分類全貌。企業導入時可據此決定要安裝哪些 profile，避免把 94 個指令的描述全部塞進模型上下文。

💡 Session 路徑差異：/save-session 寫入 ~/.claude/session-data/，而較舊的 /sessions 讀取的是 ~/.claude/sessions/。兩者路徑不同，若你發現 /sessions 看不到剛存的 Session，這是已知的歷史包袱，不是壞掉。

官方快速決策指南（直接譯自 COMMANDS-QUICK-REF.md）：

2.3.3 ecc CLI（安裝健康度與回饋）

除了在 Harness 內使用的斜線指令，ECC 另提供一組在終端機執行的管理 CLI。v2.2 的導引式安裝把安裝歸屬（ownership）記錄成台帳，這組指令才得以精確運作。

🔐 隱私設計：ecc feedback 刻意不自動蒐集或上傳診斷資訊，需由使用者自行檢視內容後決定是否提交。企業環境若有資料外流疑慮，可先在隔離環境檢閱產出的檔案。

2.3.4 Hooks 機制

Hooks 在特定工具事件發生時自動觸發，無需手動介入。

Hooks 範例 — 檔案編輯後自動檢查 console.log：

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Hook Runtime Controls：

# 設定 Hook 嚴格度（minimal | standard | strict）
export ECC_HOOK_PROFILE=standard

# 停用特定 Hooks
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

⚠️ 常見錯誤：不要在 plugin.json 中宣告 hooks 欄位！Claude Code v2.1+ 會自動載入 hooks/hooks.json，重複宣告會導致 Duplicate hooks file detected 錯誤。

2.4 Rules（規則）

Rules 是「永遠遵循」的開發準則，按語言／框架組織。截至 2026-08，官方 rules/ 目錄已涵蓋 21 種語言／框架 + 1 個通用包（common/），遠超 v1.9.0 時期宣稱的「12+ 語言生態系」：

rules/
├── common/              # 語言無關的通用原則（必裝）
│   ├── coding-style.md    # 不可變性、檔案組織
│   ├── git-workflow.md    # Commit 格式、PR 流程
│   ├── testing.md         # TDD、80% 覆蓋率需求
│   ├── performance.md     # 模型選擇、上下文管理
│   ├── patterns.md        # 設計模式、骨架專案
│   ├── hooks.md           # Hook 架構、TodoWrite
│   ├── agents.md          # 子代理委派時機
│   └── security.md        # 強制安全檢查
├── typescript/          ├── python/         ├── golang/
├── java/                ├── kotlin/         ├── swift/
├── rust/                ├── cpp/            ├── csharp/
├── php/                 ├── ruby/           ├── dart/
├── perl/                ├── fsharp/         ├── arkts/     # HarmonyOS
├── react/                                    # React（Web）
├── react-native/                             # React Native（行動端）
├── vue/                 ├── angular/        ├── nuxt/
└── web/                                      # 通用 Web 標準

💡 選配原則：Claude Code Plugin 系統無法自動分發 rules/（見 3.2），因此安裝時應只複製 common/ + 專案實際使用的 1–2 個語言／框架包，而非整個 rules/ 目錄——Rules 是「永遠載入」的上下文，複製過多會直接侵蝕可用的上下文窗口。

2.5 記憶與上下文管理

2.5.1 上下文污染問題

長時間對話中，Claude 的 200K Token 窗口會逐漸被舊資訊、失敗嘗試和探索性內容填滿，導致：

• 模型「遺忘」早期決策
• 重複相同的錯誤
• 回應品質下降

2.5.2 ECC 壓縮策略

graph TD
    A["Session 開始"] --> B["SessionStart Hook<br/>載入上次狀態"]
    B --> C["正常開發工作"]
    C --> D{上下文 > 50%?}
    D -->|是| E["strategic-compact Skill<br/>建議 /compact"]
    D -->|否| C
    E --> F["PreCompact Hook<br/>儲存關鍵狀態"]
    F --> G["/compact 執行壓縮"]
    G --> C
    C --> H["Session 結束"]
    H --> I["Stop Hook<br/>Session 摘要"]
    I --> J["evaluate-session.js<br/>萃取 Instincts"]
    J --> K["儲存至 ~/.claude/instincts/"]

2.5.3 Continuous Learning v2（Instinct 系統）

# 查看已學習的 Instincts
/instinct-status

# 匯入他人的 Instincts
/instinct-import <file>

# 匯出你的 Instincts 供分享
/instinct-export

# 將相關 Instincts 聚類為 Skills
/evolve

# 清除過期的 Pending Instincts（30 天 TTL）
/prune

💡 Best Practice：在以下時機執行 /compact：

• 研究/探索完成後，開始實作前
• 完成一個里程碑後，開始下一個前
• Debug 完成後，繼續功能開發前
• 某條路失敗後，嘗試新方法前

⚠️ 不要在實作進行中壓縮 — 你會失去變數名稱、檔案路徑和部分狀態。

2.6 Contexts（動態上下文注入）

ECC 提供動態系統提示注入（Dynamic System Prompt Injection）機制，透過 contexts/ 目錄中的上下文檔案，根據不同工作模式注入最適合的系統行為指引。

2.6.1 可用上下文模式

2.6.2 使用方式

# 在 Session 開始時切換上下文
# SessionStart Hook 會自動載入預設上下文

# 手動切換（在 CLAUDE.md 或 Session 中指定）
# 在專案 CLAUDE.md 中設定預設上下文

上下文注入示意：

graph LR
    A["Session 開始"] --> B{工作模式?}
    B -->|開發| C["contexts/dev.md<br/>建構、TDD、效能"]
    B -->|審查| D["contexts/review.md<br/>品質、安全、規範"]
    B -->|研究| E["contexts/research.md<br/>探索、收集、分析"]
    C --> F["注入系統提示"]
    D --> F
    E --> F
    F --> G["開始工作"]

💡 Best Practice：在 CLAUDE.md 中指定專案預設上下文，根據任務性質動態切換。研究階段用 research，實作階段用 dev，PR 審查用 review。

2.7 MCP Server 配置

ECC 對 MCP（Model Context Protocol）採取的立場，是本手冊最需要更新的一個章節——2026 年 6 月的一次官方稽核（“June 2026 audit”）大幅改寫了預設策略，從「多達 14 個預配置 Server」收斂為「僅 1 個預設連接器」。這個決策本身也是企業導入 ECC 時最值得參考的治理案例：多不代表好，每個 MCP Server 的工具 Schema 都會常駐佔用上下文窗口。

2.7.1 現行唯一預設連接器

2.7.2 被淘汰的六個前預設連接器（2026-06 審查）

💡 上述六個仍可作為選配項目保留在 mcp-configs/mcp-servers.json 中，供需要的使用者手動啟用。

2.7.3 新增連接器的准入原則

ECC 官方訂出兩項門檻，必須同時滿足才能新增為預設連接器（否則一律走 Skill 包裝 CLI/REST API 的路線）：

1. 普遍性（Universal）：幾乎每個 ECC 目標 Harness 的使用者都用得到
2. MCP 真的優於 CLI/API 包裝：任務需要互動式 Session 狀態、串流、驗證握手或結構化瀏覽——單純的無狀態請求/回應應該是 Skill，不是 Server

「Popular（受歡迎）不是理由；job is stateful and universal（任務具狀態性且普遍適用）才是理由。」——MCP-CONNECTOR-POLICY.md

官方另訂出一條數量上限的治理原則：「預設集合永遠維持在十個以下；實務上，2026 年嚴肅的 Harness 所採取的業界預設是 零到兩個連接器，加上 Harness 自帶的內建工具。」這句話對企業很有參考價值：若你的內部平台團隊目前預設幫全公司開了十幾個 MCP Server，你實際上是在用每位工程師的上下文窗口補貼少數人的便利性。

2.7.4 MCP 配置管理

# MCP 配置檔位置（選配連接器目錄）
mcp-configs/mcp-servers.json

# 停用已啟用的預設連接器（install/sync filter，非 live Claude Code toggle）
export ECC_DISABLED_MCPS="chrome-devtools"

# 使用 /mcp 命令在 Claude Code 中即時管理（Claude Code 原生功能）
# Claude Code 會將選擇持久化到 ~/.claude.json

⚠️ Token 影響提醒：每個 MCP 的工具描述都會常駐消耗 Token，啟用過多 MCP 可能將 200K Token 窗口實際可用空間壓縮到約 70K。即使在僅 1 個預設連接器的現況下，若專案另外疊加多個選配 MCP，仍建議整體控制在 < 10 MCPs、< 80 tools。

2.8 Claude Code 原生功能與 ECC 擴充功能分工

企業導入 ECC 前最常見的誤解，是把 Claude Code 平台本身的能力誤認為「ECC 提供的功能」——這會導致評估錯誤（如認為換掉 ECC 就會失去 Plan Mode）、也會導致治理錯誤（如把平台升級才能取得的能力誤植為 ECC 版本紀錄）。下表整理 Anthropic 官方文件與 ECC 官方 repo 的分工邊界：

💡 一句話總結：Claude Code 提供「積木」（Hooks、Skills、Subagents、Plan Mode、Checkpoints 的執行引擎），ECC 提供「預先搭好、可跨團隊複用的積木組合」（具體的 Agent 角色、Skill 工作流、安全掃描規則、跨 Harness 移植層）。導入 ECC 前，建議先讀過 Anthropic 官方 Best Practices for Claude Code，確認團隊已理解原生積木的用法，再評估是否需要 ECC 這層「預組裝」框架（第十三章有完整的決策框架）。

2.9 Unified Memory Vault（跨 Harness 統一記憶庫）

Unified Memory Vault 是 v2.2.0 最具企業價值的新增能力。它要解決的問題很具體：一個團隊往往同時使用多個 Harness（資深工程師用 Claude Code、某些 CI 任務用 Codex、部分成員用 Kimi Code），但每個 Harness 的記憶都是孤島，導致同一個架構決策要在不同工具裡重述一次。Memory Vault 把記憶從「工具內部狀態」拉出來，變成位於檔案系統上、人可閱讀、可納版控的 Markdown。

2.9.1 設計原則與儲存位置

三項核心設計決策：

1. 本地優先、可檢視：不是二進位資料庫、不是雲端服務，而是你可以用 cat 看、用 git diff 審查的 Markdown。企業稽核時這點極為重要。
2. 跨 Harness：同一份記憶可被 Claude Code、Codex、Hermes、OpenClaw、Kimi 讀取。
3. 記憶不是可執行政策：見下方信任邊界。

2.9.2 ecc memory 指令集

# 安裝 CLI（若尚未安裝）
npm install -g ecc-universal

# 初始化（專案範圍）
ecc memory init --scope project

# 寫入一筆記憶（內文必須由 stdin 或檔案傳入）
ecc memory save --title "決定採用 Outbox Pattern" --body-file ./decision.md

# 產生交接摘要（供下一個 Harness 接手）
ecc memory handoff

# 搜尋，並針對目標 Harness 格式化輸出
ecc memory search "outbox" --target-harness codex

# 讀取單筆記憶
ecc memory read

# 健康檢查（權限、格式、損壞偵測）
ecc memory doctor

🔐 **為什麼內文不能直接寫在指令列？**這是刻意的安全設計。記憶內文只接受 --stdin 或 --body-file，不接受作為 CLI 參數值，目的是避免惡意內容透過 shell 展開、歷史紀錄或參數注入路徑流入記憶庫。

2.9.3 信任邊界（企業導入必讀）

「Memory is unreviewed context, not executable policy.」（記憶是未經審查的上下文，不是可執行的政策。）

這句官方聲明的實務含意是：

• 記憶庫內容會被注入模型上下文，因此它是提示注入（prompt injection）的攻擊面。若一個外部貢獻者能將內容寫入 .ecc/memory/，他就能影響所有團員的 Agent 行為。
• 因此，.ecc/memory/ 必須納入 Code Review 範圍，建議在 CODEOWNERS 中指定審查者。
• 不要把安全規則、權限政策、部署授權寫在記憶庫——那些應該寫在 Rules（2.4）或 Hooks（2.3.4），它們才是強制執行的機制。
• 記憶庫不應存放 Secret。ecc memory doctor 會做基本檢查，但不取代 CI 的 Secret 掃描。

2.9.4 選配的 ecc-memory-mcp Server

ECC 另提供一個 stdio MCP Server，將 save / search / read / doctor 四個有界的操作暴露給模型。需特別注意：

• 預設不啟用。這符合 2.7 的連接器政策（不普遍就不預設）。
• 啟用後等於讓模型自行決定何時寫入團隊記憶，請先評估治理風險。
• 對應 Skill：skills/unified-memory/SKILL.md。

2.9.5 已知缺陷：Windows 原生環境的寫入失敗

v2.2.0 修復了一個非常值得記錄的問題，因為它直接影響 Windows 使用者：

• 症狀：在 Windows 搭配 Node 22.12–22.16 或 24.0–24.1 時，ecc memory 的寫入與 --body-file 讀取全數失敗。
• 根因：libuv 在處理基於路徑的 stat()／lstat() 時走 GetFileInformationByName，未回傳 volume serial，而 fstat() 則有回傳；記憶庫的 TOCTOU（time-of-check to time-of-use）防護機制因此認定每一次操作都不一致而全數拒絕。
• 修復：上游已在 libuv 1.51.0 修正；ECC 端則改為要求 BigInt 型別的 stat 值，避免 Windows 檔案 ID 超過 Number.MAX_SAFE_INTEGER 後兩個不同檔案塔縮成同一個身分。
• 實務建議：若你仍在舊版 ECC，請避開上述 Node 版本區間，或直接升級至 v2.2.0。另見 3.11 的 Windows 原生限制與 Issue #2626。

第三章：安裝與環境建置

3.1 前置需求

3.2 Plugin 安裝（推薦）

⚠️ 只選一種安裝路徑（per Harness）：同一個 Harness 只能選一種安裝方式。例如 Claude Code 用 Plugin 安裝後，不要再疊加執行 install.sh --profile full，這會造成重複元件和衝突行為（症狀：指令重複出現、Hook 執行兩次）。若已經疊加安裝，直接跳到「Reset / Uninstall ECC」小節復原，不需要重灌整個環境。

可行的組合：Claude Code Plugin + Codex 原生 Plugin；Claude Code Plugin + Codex legacy sync。
應避免的組合：Claude Code Plugin + 完整手動安裝；Codex sync + Codex marketplace plugin。

3.2.0 v2.2 導引式安裝（Guided Setup）

v2.2.0 起，ECC 提供 manifest 驅動的導引式安裝，是目前官方推薦的新手入口。它會逐步詢問要安裝哪些 Harness、範圍（scope）、Hook 嚴格度與 profile，並把每個被寫入的檔案記進歸屬台帳（ownership ledger），讓後續的 doctor / repair / uninstall 能精準運作。

單一 Harness（Claude Code）設定或更新：

npx ecc-universal setup

此指令會引導完成 Claude Code plugin 的安裝／更新、選擇 scope 與 hook profile。

多 Harness 一次設定（目前支援 Claude Code、Codex、Kimi Code）：

npx ecc-universal install --guided

自動化／CI 用的非互動形式：

npx ecc-universal install --guided \
  --harness claude --harness codex --harness kimi \
  --claude-scope local --claude-hooks standard \
  --profile core --yes

先試跑再決定（強烈建議企業環境先做這步）：

# 預覽將對 Codex 做哪些變更，不實際寫入
npx ecc-universal install --guided --harness codex --dry-run

# 預覽 core profile 安裝到 Kimi 的結果
npx ecc-universal install --profile core --target kimi --dry-run

其他常用別名：

# 依主題諮詢建議的元件組合
npx ecc-universal consult "security reviews" --target claude

# 最小安裝，但額外帶入某個能力群組
npx ecc-universal install --profile minimal --target claude --with capability:machine-learning

# 針對特定 Harness 做健康檢查
npx ecc-universal doctor --target kimi

套件執行器對照：

🚫 常見錯誤：不要執行 npx ecc-install ...
ecc-install 是 ecc-universal 套件內部的執行檔名稱，並不是一個已發布到 npm 的套件。直接 npx ecc-install 會去 npm 抓到不存在（或非官方）的套件，這既會失敗、也是潛在的供應鏈風險。正確入口一律是 ecc-universal。

⚠️ 執行前先確認 npm 版本：如 1.6 所述，GitHub Release 與 npm 推廣之間存在落差。執行導引式安裝前先跑 npm view ecc-universal version；若仍是 2.1.0，請改用下方原生 /plugin 路徑。

進階管理型 adapter 仍走 ecc install --target ...，涵蓋：cursor、antigravity、gemini、opencode、codebuddy、joycode、qwen、zed、hermes、openclaw。

安裝出問題時：使用官方 issue 範本 https://github.com/affaan-m/ECC/issues/new?template=install-problem.yml，或執行 ecc feedback 產生回報內容（不會自動上傳）。

ECC 三個公開標識符

💡 三者名稱不同是有意設計。Anthropic marketplace 安裝以 canonical plugin identifier 為鍵，ECC 使用 ecc@ecc 保持命名簡短。npm 套件維持 ecc-universal 以確保向後相容。

Step 1：安裝 Plugin

# 在 Claude Code 中執行
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

或直接編輯 ~/.claude/settings.json：

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}

Step 2：安裝 Rules（必要）

⚠️ Claude Code Plugin 系統無法自動分發 Rules，必須手動安裝，且只安裝實際會用到的語言包——Rules 是永遠載入的上下文，全裝 21+ 種語言包只會侵蝕上下文窗口。

git clone https://github.com/affaan-m/ECC.git
cd ECC

mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/   # 替換為你實際使用的語言／框架包

Step 3：開始使用

# Plugin 安裝使用命名空間形式
/ecc:plan "Add user authentication"

# 檢查可用指令
/plugin list ecc@ecc

# 已安裝後的重新設定（僅可用於「已安裝」狀態，不能取代首次 /plugin install）
/ecc:configure-ecc

ECC Consult 顧問指令

不確定該用哪些 Skills / Agents？使用官方腳本取得建議（不要使用 npx ecc consult，該別名尚未在 npm 上正式提供）：

# 詢問特定主題的建議安裝內容，並回傳對應 Skill/Agent、profile 與 preview 指令
node scripts/ecc.js consult "security reviews" --target claude
node scripts/ecc.js consult "Spring Boot microservice with Kafka" --target claude

Reset / Uninstall ECC

# 檢查目前已安裝的 ECC 管理元件
node scripts/ecc.js list-installed

# 診斷設定問題
node scripts/ecc.js doctor

# 自動修復遺失/損壞的元件
node scripts/ecc.js repair

# 乾跑模式：列出將被移除的檔案（不實際刪除）
node scripts/ecc.js uninstall --dry-run

# 正式解除安裝
node scripts/ecc.js uninstall
# 等效於：node scripts/uninstall.js

⚠️ 解除安裝只移除 ECC install-state 記錄在案的檔案（rules、hooks、commands、agents、skills）。你的 ~/.claude/settings.json 中的個人設定、以及 ECC 無法證明擁有權的既有檔案都不會被觸碰。若曾經疊加多種安裝方式，官方建議的清理順序是：① 先移除 Claude Code Plugin → ② 從 repo 根目錄執行 node scripts/ecc.js uninstall → ③ 手動刪掉不再需要的 Rules 資料夾 → ④ 重新以單一路徑安裝一次。

若不確定是否需要重新採購或重新設定：解除安裝流程會印出一個非強制性的 20 秒意見回饋表單連結，ECC 不會自動上傳任何診斷資料。

3.3 手動安裝

💡 元件安裝目標路徑不同，請勿混淆：Rules 巢狀放在 ~/.claude/rules/ecc/ 下；Skills 則是 Claude Code 的「直接子目錄」發現機制，必須放在 ~/.claude/skills/ 平面目錄下，不可巢狀在 ~/.claude/skills/ecc/。

git clone https://github.com/affaan-m/ECC.git
cd ECC

# 複製 Agents
cp agents/*.md ~/.claude/agents/

# 複製 Rules（巢狀於 ecc/ 子目錄，common + 語言特定）
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/   # 依你的技術棧選擇

# 複製 Skills（平面目錄，主要工作流程介面）
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/

# 選擇性：加入框架特定 Skills
for s in springboot-patterns springboot-tdd springboot-security java-coding-standards; do
  cp -r skills/$s ~/.claude/skills/
done

# 選擇性：保留 Legacy 指令相容性（已淘汰的 shim 另存於 legacy-command-shims/）
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

安裝 Hooks（務必使用 installer，不要直接複製 hooks.json）：

# macOS / Linux
bash ./install.sh --target claude --modules hooks-runtime

# Windows PowerShell
pwsh -File .\install.ps1 --target claude --modules hooks-runtime

3.4 Windows PowerShell 安裝

# Clone 專案
git clone https://github.com/affaan-m/ECC.git
cd ECC

# 安裝依賴
npm install

# 完整安裝
.\install.ps1 --profile full

# 或安裝特定語言
.\install.ps1 typescript python

# 跨平台 npm entrypoint
npx ecc-install typescript

⚠️ Windows 注意：Claude 配置目錄是 %USERPROFILE%\.claude，不是 ~/claude。

3.5 跨 Harness 整合（13+ 平台總覽）

ECC 官方支援的 Harness 已從早期的 5 種擴展為 13+ 種（v2.2.0 再加入 Pi adapter 與原生 Antigravity 2.0 安裝）。下表為總覽，各平台細節於後續小節說明；能力分級差異請務必搭配 3.11 的支援矩陣一起看：

⚠️ 不要對同一個 Harness 混用官方支援 Feature Parity 假設：不同 Harness 的能力天花板不同（例如 Copilot 沒有 Hook/Subagent API）。導入前務必查閱 3.11、本章與附錄 D 的功能對照表，不要預設「裝了 ECC 就等於 Claude Code 的完整體驗」。找不到原生對應目標的 Harness，可參考 Manual Adaptation Guide 手動移植一小部分 Skill 與工作流程指引。

📌 v2.2 的 OpenCode 路徑遷移（升級者必讀）：OpenCode 的 Home 安裝位置已改為正式的 ~/.config/opencode。升級時 ECC 會：

1. 把舊路徑 ~/.opencode 底下未經修改的 ECC 託管檔案安全搬移過去；
2. 保留使用者自行修改過的舊檔案（不覆蓋、不刪除），由你自行決定如何合併。

另外，OpenCode 的隨附 agents 不再固定綁 Anthropic provider，改為繼承使用者所選的模型。這代表升級後若你沒有在 OpenCode 中選好 provider 與 model，agents 可能無法運作（見 Issue #2617）。

Cursor IDE

# macOS/Linux
./install.sh --target cursor typescript python

# Windows
.\install.ps1 --target cursor typescript python

Cursor 支援項目：

OpenAI Codex

Codex 目前是原生 Plugin 支援（優先推薦），舊有的同步腳本已列為過時的相容性選項：

# 推薦：原生 Codex Marketplace Plugin
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js

# 更新
codex plugin marketplace upgrade ecc
codex plugin add ecc@ecc

# Codex 內建的 ECC 導覽指令
$configure-ecc

⚠️ Codex 的 Plugin 狀態是單一啟用（不像 Claude Code 有 user/project/local 三種 scope），且其原生 Hook 需要明確的信任決策，不使用 ECC 的四種 Hook Profile。

舊版 scripts/sync-ecc-to-codex.sh 路徑僅為已淘汰的相容性選項，適合需要把設定複製並合併進 ~/.codex 的使用者：

# 需先執行過一次 Codex，讓 ~/.codex/config.toml 存在
git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.sh

# 檢查或移除這個舊同步層（不影響 Codex 對話與原生 Plugin 快取）
node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
node scripts/ecc.js uninstall --legacy-codex-sync

詳見 Codex ECC Navigation Guide。

OpenCode

git clone https://github.com/affaan-m/ECC.git
cd ECC

# 需先建置 OpenCode 專用 Plugin payload，再執行完整安裝
npm install && npm run build:opencode && ./install.sh --profile full --target opencode

Gemini CLI

# macOS/Linux
./install.sh --target gemini --profile full

# Windows PowerShell
.\install.ps1 --target gemini --profile full

Gemini 透過 .gemini/GEMINI.md 和共用安裝管道提供實驗性的專案級支援。

Antigravity IDE

# macOS/Linux
./install.sh --target antigravity typescript

# Windows PowerShell
.\install.ps1 --target antigravity typescript

Antigravity 整合包含工作流程、Skills 和扁平化 Rules。v2.2.0 起新增 Antigravity 2.0 的原生安裝路徑，內容寫入 .agents/ 目錄（含 rules、workflows、skills 與適配過的 agents）；舊版 Antigravity 使用的是 .agent/ 目錄。若你同時看到兩個目錄，代表環境曾經跨版本安裝過，請執行 ecc doctor 確認歸屬並以 ecc repair 清理。詳見 Antigravity Guide。

Pi（v2.2.0 新增，thin adapter）

v2.2.0 加入了一個輕量（thin）的 Pi adapter，內容放置於專案的 .pi/ 目錄。定位上這是「檔案放置已驗證，但不主張功能對等」的最小整合：不提供 ECC Hook Runtime、不保證 Agent 委派行為，適合用來把 Rules 與部分 Skills 帶進 Pi 的工作環境，不適合當作主要開發 Harness。

Kimi Code（Moonshot AI 官方合作，v2.1.0 新增）

Kimi Code 是首個與 ECC 有官方合作關係的開源模型 Harness，經 Kimi Code 0.31.x（@moonshot-ai/kimi-code）驗證：

bash ./install.sh --target kimi --profile minimal
node scripts/ecc.js doctor --target kimi
kimi

Kimi Code 原生從 .kimi-code/AGENTS.md（指令）與 .kimi-code/skills/（工作流）發現內容；ECC 會安全地將專案 MCP 設定併入 .kimi-code/mcp.json，但不會更動使用者層級的 ~/.kimi-code/config.toml。Kimi Code 原生支援 Hooks，但 ECC 目前的受管理專案 adapter 尚未替 Kimi 配置 Hook Profile。若需自架 Kimi 模型，請見 3.10 節的 Itô GPU 整合說明。

Hermes / OpenClaw（v2.1.0 新增）

# Hermes
./install.sh --profile minimal --target hermes
# 詳見 docs/HERMES-SETUP.md

# OpenClaw（受管理的 Home 目錄安裝）
./install.sh --profile minimal --target openclaw

💡 Hermes 與 OpenClaw 之間存在遷移路徑，詳見 HERMES-OPENCLAW-MIGRATION.md。

其他 Harness 支援

GitHub Copilot（VS Code）

ECC 透過 Copilot Chat 原生的 instruction 與 prompt 檔案系統提供 GitHub Copilot 支援，無需額外工具：

.github/
├── copilot-instructions.md    # 永遠載入的核心規則
└── prompts/
    ├── plan.prompt.md          # 實作規劃工作流
    ├── tdd.prompt.md           # Red-Green-Improve 循環
    ├── security-review.prompt.md  # OWASP 安全分析
    ├── build-fix.prompt.md     # 建構錯誤修復
    └── refactor.prompt.md      # 死碼清除與簡化

使用方式：

1. 開啟 VS Code 的 Copilot Chat 面板
2. 點擊附件/迴紋針圖示，選擇「Prompt…」
3. 選取想執行的 prompt（如 plan、tdd、security-review）

💡 GitHub Copilot 不具備 Hook 與 Subagent 功能，因此 ECC 的自動化鉤子和 Agent 委派在此環境不可用。但 instruction 和 prompt 層仍能將完整的 ECC 編碼哲學帶入每次 Copilot Chat。

Zed IDE

# macOS/Linux
./install.sh --profile minimal --target zed

# Windows PowerShell
.\install.ps1 --profile minimal --target zed

Zed 透過 .zed/ adapter 提供專案級設定、扁平化 Rules、Agents、Commands 和 Skills。Zed 帳號或 API 金鑰請透過 Zed 自身的 settings UI 設定，ECC 不會將 BYOK/OpenRouter 憑證寫入 repo。

3.6 環境變數設定

# Token 最佳化（強烈推薦）
export MAX_THINKING_TOKENS=10000
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

# 套件管理器偏好
export CLAUDE_PACKAGE_MANAGER=pnpm

# Hook 控制
export ECC_HOOK_PROFILE=standard          # minimal | standard | strict
export ECC_DISABLED_HOOKS=""              # 逗號分隔的 Hook ID

# SessionStart 上下文控制（v2.0.0）
export ECC_SESSION_START_MAX_CHARS=8000   # 上限字元數（預設 8000）
export ECC_SESSION_START_CONTEXT=off      # 完全停用（適用低上下文/本地模型）

# Session 保留天數（v2.0.0）
export ECC_SESSION_RETENTION_DAYS=30      # 設為 0/off/never 保留全部

# 成本警告控制（v2.0.0，訂閱用戶建議 off）
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off  # 僅抑制 API 費率估算，保留上下文/範圍警告

# Agent 資料隔離（多 Harness 共存時）
export ECC_AGENT_DATA_HOME="$HOME/.claude"    # Cursor 設為 $HOME/.cursor/ecc

# 停用特定 MCP（install/sync filter，非 live toggle）
export ECC_DISABLED_MCPS="supabase,railway,vercel"

推薦 ~/.claude/settings.json 設定：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

3.7 Dashboard GUI

ECC v1.10.0 新增桌面儀表板：

# 啟動 Dashboard
npm run dashboard

# 或直接執行
python3 ./ecc_dashboard.py

功能：

• 分頁介面：Agents、Skills、Commands、Rules、Settings
• 深色/淺色主題切換
• 字型自訂（字體家族 & 大小）
• 搜尋與篩選所有元件

💡 實務案例：新進團隊成員可透過 Dashboard GUI 快速瀏覽所有可用的 Agents 和 Skills，了解 ECC 提供的能力範圍。

3.8 套件管理器偵測

ECC Plugin 自動偵測你偏好的套件管理器（npm、pnpm、yarn、bun），偵測優先順序：

設定方式：

# 透過環境變數
export CLAUDE_PACKAGE_MANAGER=pnpm

# 透過全域配置
node scripts/setup-package-manager.js --global pnpm

# 透過專案配置
node scripts/setup-package-manager.js --project bun

# 偵測當前設定
node scripts/setup-package-manager.js --detect

也可以在 Claude Code 中使用 /setup-pm 指令進行互動式設定。

3.9 故障復原與診斷

當本地 ECC 設定被清除或重置時，不需要重新安裝（更不需要重新採購 ECC Tools Pro 訂閱）。ECC 提供內建的診斷與修復工具，從 repo 根目錄執行：

# 步驟 1：檢查已安裝的項目
node scripts/ecc.js list-installed

# 步驟 2：診斷問題
node scripts/ecc.js doctor

# 步驟 3：自動修復（通常可恢復 ECC-managed 檔案）
node scripts/ecc.js repair

若已透過 npm 全域安裝 ecc-universal，上述指令有更簡短的等價形式，且可加上 --target 針對特定 Harness：

ecc list-installed
ecc doctor
ecc doctor --target kimi
ecc repair
ecc uninstall            # 依歸屬台帳安全移除，保留你改過的檔案
ecc feedback             # 產生問題回報內容（不會自動上傳診斷資料）

💡 v2.2 的差異：導引式安裝會建立歸屬台帳（ownership ledger），記錄每個檔案是由哪一次安裝寫入的。因此 v2.2 的 repair 在做選擇性重裝時會合併先前的台帳，不會再留下孤兒檔案；uninstall 也改為依「歸屬證據」判斷，能保留使用者自行修改過的檔案。若只想清掉標記檔而不動內容，需要明確加上 opt-in 參數。

💡 若已透過 /plugin install ecc@ecc 安裝，也可以直接在 Claude Code 對話中使用命名空間指令 /ecc:doctor、/ecc:repair，效果等同上方的 node scripts/ecc.js 指令。

常見復原情境：

⚠️ 注意：帳號或 Marketplace 存取問題（如 ECC Tools 付費方案）需單獨處理，與本地配置修復無關。

3.10 自架模型、自訂端點與 GPU 運算

企業環境常見的兩種延伸需求——「透過內部閘道存取 Claude」與「完全自架開源模型」——ECC 在 v2.1.0 之後都提供了官方支援路徑。

3.10.1 自訂 API 端點／模型閘道

ECC 不會將 Anthropic 官方託管的傳輸設定寫死在框架中。只要 claude CLI 本身能透過閘道正常運作，ECC 的 Hooks、Skills、Commands、Rules 就是模型提供者無關的：

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude

💡 若閘道會重新映射模型名稱，請在 Claude Code 本身設定，而非在 ECC 中設定。詳見 Anthropic 官方 LLM Gateway 文件 與 模型設定文件。

3.10.2 自架開源模型與 Itô GPU 整合（v2.1.0 新增）

ECC 的官方運算合作夥伴 Itô（compute.itomarkets.com）提供了一條「自架 Kimi 開源模型」的參考路徑，但三個層次刻意保持獨立、可替換：

graph LR
    A["1. 取得 GPU 運算資源<br/>Itô 或任何 GPU 供應商"] --> B["2. 部署 Kimi 模型<br/>透過相容 API 端點提供服務"]
    B --> C["3. 執行 Kimi Code + ECC<br/>安裝專案指令與 Skills"]

# 步驟 3：確認 endpoint 設定完成後安裝 ECC
bash ./install.sh --target kimi --profile minimal
node scripts/ecc.js doctor --target kimi
kimi

ecc ito CLI 橋接工具（委派給另外安裝的官方 Itô Client，ECC 不維護第二套 API Client）：

⚠️ 重要邊界（企業採購與合規務必知悉）：贊助連結本身是被動的，不會觸發 RFQ、預訂容量、佈建運算或設定服務。ecc ito find 送出的是真實的即時詢價請求，但不會預訂容量。透過 Itô 的受管理推論服務尚未上線。ECC 完全不提供報價鎖定、採購、工作負載執行或推論路徑本身——這些都是 Itô 平台自己的職責範圍，ECC 只是薄橋接層。任何 GPU 供應商都可以替代使用，ECC 對供應商保持中立。

💡 企業自架建議：若你的資安政策不允許程式碼離開內部網路，此路徑讓你可以完全在自有 GPU 上運行開源模型（如 Kimi），同時仍取得 ECC 的 Agent/Skill/Hook 框架——但務必自行承擔模型品質、延遲與可用性的差異，這與使用 Anthropic 官方託管的 Claude 模型有本質不同的風險輪廓（見 13.1 的 TCO 討論）。

ito-compute-cli 尚未發布至公開套件庫。若要實際使用 ecc ito 橋接，需自行從 Itô 的私有 runtime repo 建置：

# 於 Itô runtime repo 的 cli/ito-compute-cli 目錄
npm ci && npm run check

# 將 ECC 指向建置產物的絕對路徑
export ECC_ITO_CLI_EXECUTABLE=/absolute/path/to/dist/bin/ito.js

ecc ito login 不會繼承 ITO_API_KEY（避免非互動式環境誤用長期金鑰）；auth、find、status 則會轉發該環境變數。ecc ito evals 屬額外閘控功能，需同時滿足：ITO_ENABLE_SIXTYTWO_LIVE=1、傳入 --live-sixtytwo、安裝 sixtytwo-cli==0.3.33、明確指定節點清單，以及提供絕對路徑的設定目錄。相關 MCP 工具為 ito_auth、ito_find、ito_status；對應 Skill 為 skills/ito-compute/SKILL.md。

3.11 平台支援分級與跨作業系統相容性

這一節是企業導入前最該讀的一節。ECC 官方在 README 中提供了兩張誠實度極高的支援矩陣，明確標示哪些 Harness 只是「檔案放對位置」而非「功能對等」。用官方自己的話說：

stable、beta、experimental、instruction-only 是能力陳述（capability statements），不是行銷分級。

3.11.1 Harness 支援分級矩陣

3.11.2 作業系統相容性矩陣

🏢 給企業評估者的三個實務結論：

1. Windows 原生不是首選。若團隊以 Windows 為主，請把 WSL2 列為標準開發環境，可一次繞開 observer daemon 與 Memory Vault 的兩個已知缺陷，也讓 GAN、GateGuard 等 shell-backed 功能正常運作。
2. 不要用 Copilot 評估 ECC。Copilot 只拿得到 instruction 層，缺少 Hook 與 Agent，導入評估若以此為樣本會嚴重低估 ECC 的價值（也會誤判成本）。
3. PoC 一律鎖 Claude Code。先在 stable 平台驗證投資報酬，再視需求把 Rules／Skills 以 adapter 方式推廣到其他 Harness。

3.11.3 跨工具能力對照（摘要）

三個關鍵設計決策，值得企業在制定內部標準時借鏡：

1. 根目錄的 AGENTS.md 是通用的跨工具檔案（Copilot 例外，它讀 .github/copilot-instructions.md）。把團隊共識寫在這裡，可同時被多數 Harness 讀到。
2. DRY adapter 模式：Cursor 直接複用 Claude 的 Hook 腳本，而不是複製一份維護。內部自建工具鏈時也應採同樣做法。
3. SKILL.md + YAML frontmatter 是目前最通用的技能格式，可跨 Claude Code、Codex、OpenCode 使用。Codex 缺少 Hook 的問題，則以 AGENTS.md + model_instructions_file + sandbox 權限三者組合來補償。

第四章：企業級 Web 系統架構設計（搭配 ECC）

4.1 企業系統架構背景

典型企業級 Web Application 技術棧：

4.2 ECC Agent 分工架構

graph TB
    subgraph "ECC Agent Teams"
        direction TB
        
        subgraph "Planning Layer"
            Planner["📋 planner<br/>任務拆解與規劃"]
            Architect["🏗️ architect<br/>架構設計決策"]
        end
        
        subgraph "Backend Team"
            JavaReviewer["☕ java-reviewer<br/>Java/Spring Boot 審查"]
            JavaBuild["🔧 java-build-resolver<br/>Maven/Gradle 問題"]
            DBReviewer["🗄️ database-reviewer<br/>SQL/ORM 審查"]
        end
        
        subgraph "Frontend Team"
            TSReviewer["📘 typescript-reviewer<br/>TypeScript/Vue 審查"]
        end
        
        subgraph "Quality & Security"
            TDDGuide["🧪 tdd-guide<br/>TDD 流程引導"]
            CodeReviewer["🔍 code-reviewer<br/>通用品質審查"]
            SecurityReviewer["🔐 security-reviewer<br/>安全弱點分析"]
            E2ERunner["🎭 e2e-runner<br/>Playwright E2E"]
        end
        
        subgraph "Operations"
            DocUpdater["📝 doc-updater<br/>文件同步"]
            LoopOperator["🔄 loop-operator<br/>自主迴圈執行"]
        end
    end

    Planner --> Architect
    Architect --> JavaReviewer
    Architect --> TSReviewer
    Planner --> TDDGuide
    TDDGuide --> JavaBuild
    TDDGuide --> DBReviewer
    CodeReviewer --> SecurityReviewer
    E2ERunner --> DocUpdater

4.3 Orchestrator 家族

v2.0.0 引入、並在 v2.1.0 持續強化的 Orchestrator 家族（orch-* 動態工作流團隊編排），將原本單一 planner 和 loop-operator 的職責拆分為更細粒度的角色，提供企業級的多 Agent 執行控制：

graph LR
    subgraph "Orchestrator Pipeline"
        OP[orch-planner] --> OF[orch-fanout]
        OF --> W1[Worker A]
        OF --> W2[Worker B]
        OF --> W3[Worker C]
        W1 --> OR[orch-reduce]
        W2 --> OR
        W3 --> OR
        OR --> OG[orch-gate]
        OG -->|pass| Done[✅ 完成]
        OG -->|fail| ORetry[orch-retry]
        ORetry --> OF
    end

💡 Orchestrator vs 傳統 Agent：Orchestrator 本身不產出程式碼，只負責「排程→分派→驗收」。實際生成程式碼的仍是 java-reviewer、typescript-reviewer 等 Worker Agent。此設計遵循 Single Responsibility，並讓失敗隔離在單一 Worker 粒度。

4.4 系統架構圖

graph TB
    subgraph "Frontend (Vue 3 + TypeScript)"
        Vue["Vue 3 SPA"]
        Tailwind["Tailwind CSS"]
        Pinia["Pinia Store"]
    end
    
    subgraph "API Gateway"
        GW["API Gateway<br/>(Rate Limit, Auth)"]
    end
    
    subgraph "Backend Microservices (Spring Boot)"
        AuthSvc["Auth Service<br/>OAuth / JWT"]
        UserSvc["User Service<br/>CRUD"]
        BizSvc["Business Service<br/>Core Logic"]
        NotifySvc["Notification Service<br/>Email/SMS"]
    end
    
    subgraph "Data Layer"
        PG["PostgreSQL"]
        Redis["Redis Cache"]
        Kafka["Kafka<br/>Event Bus"]
    end
    
    subgraph "ECC Agent Overlay"
        ECC_Plan["🤖 ECC /plan<br/>需求 → 任務拆解"]
        ECC_TDD["🤖 tdd-workflow skill<br/>TDD 開發"]
        ECC_Review["🤖 ECC /code-review<br/>品質審查"]
        ECC_Security["🤖 ECC /security-scan<br/>安全掃描"]
        ECC_E2E["🤖 e2e-testing skill<br/>E2E 測試"]
    end
    
    Vue --> GW
    GW --> AuthSvc
    GW --> UserSvc
    GW --> BizSvc
    BizSvc --> NotifySvc
    AuthSvc --> PG
    UserSvc --> PG
    BizSvc --> PG
    BizSvc --> Redis
    BizSvc --> Kafka
    
    ECC_Plan -.->|"規劃"| AuthSvc
    ECC_TDD -.->|"TDD"| UserSvc
    ECC_Review -.->|"審查"| BizSvc
    ECC_Security -.->|"掃描"| GW
    ECC_E2E -.->|"測試"| Vue

4.5 Agent 協作流程

sequenceDiagram
    participant PM as 專案經理
    participant ECC as ECC /plan
    participant Arch as architect agent
    participant BE as java-reviewer
    participant FE as typescript-reviewer
    participant QA as tdd-guide
    participant Sec as security-reviewer

    PM->>ECC: "新增用戶管理模組"
    ECC->>Arch: 委派架構設計
    Arch-->>ECC: API 設計 + DB Schema
    
    par 後端開發
        ECC->>QA: 後端 TDD (Spring Boot)
        QA->>QA: Controller Test → Service Test → Repository Test
        QA->>BE: 委派 Java Code Review
        BE-->>QA: 審查結果 + 建議
    and 前端開發
        ECC->>QA: 前端 TDD (Vue + TypeScript)
        QA->>FE: 委派 TypeScript Review
        FE-->>QA: 審查結果 + 建議
    end
    
    ECC->>Sec: 全模組安全掃描
    Sec-->>ECC: OWASP 報告
    ECC-->>PM: 完整交付報告

💡 Best Practice：使用 /multi-plan 進行多 Agent 任務分解，再用 /multi-execute 平行執行前後端任務，可顯著提升開發效率。

4.6 Rules 與 Skills 的分層治理

技術架構之外，企業導入的成敗往往取決於配置治理：誰有權新增規則、規則放在哪一層、如何避免上下文膨脹。

4.6.1 三層作用域與取捨

⚠️ 企業預設立場：團隊規範一律放專案層並納入版控。使用者層僅保留純個人偏好；本機層僅供短期實驗，不得存放任何影響產出的規則。7.8.1 的 permissions.deny 基線必須放在專案層，否則無法保證每位成員都受同一套限制。

4.6.2 最小上下文原則

ECC 提供 21+ 語言／框架的 Rules 包，但全部安裝會直接壓縮可用上下文。建議的選配策略：

4.6.3 內部 Skill 視為工程資產

自建的 SKILL.md 應比照程式碼管理，而非當成隨手筆記：

4.7 CLAUDE.md 分層策略

CLAUDE.md 是專案的常駐指令，每個 Session 都會載入，因此它同時是最有效的槓桿與最容易被濫用的地方。

4.7.1 該寫什麼、不該寫什麼

4.7.2 分層與匯入

大型專案應避免單一巨型 CLAUDE.md，改用匯入語法組合：

# 專案指引

## 建置與測試
- 後端：`./mvnw verify`
- 前端：`pnpm test`

## 分層規範
@docs/conventions/backend.md
@docs/conventions/frontend.md

4.7.3 常見失效模式

💡 驗證方法：新增規則後，用 /init 重新產生基準、/context 檢視實際佔用，並實測一個原本會犯錯的情境，確認規則確實改變了行為。沒有驗證過的規則等於沒有規則。

4.8 團隊角色與責任邊界

代理式開發引入了新的資產類別（Rules、Skills、Hooks、記憶庫、權限設定），必須明確指定負責人，否則會出現「大家都能改、沒人負責」的治理真空。

⚠️ 最容易被忽略的一項是 Hook 腳本的審查。Hook 在每次工具呼叫時自動執行、無需使用者確認，其權限等同於開發者本人。任何 Hook 變更都應視同「新增一支具有完整檔案系統權限的常駐程式」來審查。

第五章：開發流程（AI 驅動）

5.1 AI 驅動開發總覽

graph LR
    P["/plan<br/>📋 規劃"] --> D["/plan（architect）<br/>🏗️ 設計"]
    D --> I["tdd-workflow<br/>💻 實作"]
    I --> T["e2e-testing<br/>🧪 測試"]
    T --> R["/code-review<br/>🔍 審查"]
    R --> Deploy["deployment-patterns<br/>🚀 部署"]
    Deploy --> Learn["/learn-eval → /evolve<br/>🧠 學習"]
    Learn -.->|"下個迭代"| P

💡 上圖已依 2026 年的指令退役現況重畫：流程中的實作、測試、部署三個環節已不再使用 /tdd、/e2e、/deploy 斜線指令，而是以 Skill 為入口。這也是 ECC 整體的方向：斜線指令常駐佔用上下文，Skill 則是按需載入。

5.2 /plan — 需求規劃

指令範例：

/ecc:plan "Add user authentication with OAuth2 + JWT, supporting Google and GitHub login"

Agent 行為：

1. planner agent 分析需求
2. 拆解為具體實作步驟
3. 識別技術風險與依賴
4. 產出實作藍圖

輸出範例：

## Implementation Plan: OAuth2 + JWT Authentication

### Phase 1: Infrastructure
- [ ] Add Spring Security + OAuth2 Client dependencies
- [ ] Configure application.yml for Google/GitHub OAuth
- [ ] Create JWT utility class

### Phase 2: Backend
- [ ] Implement OAuth2LoginSuccessHandler
- [ ] Create UserService with OAuth user mapping
- [ ] Implement JWT token generation/validation
- [ ] Create AuthController endpoints

### Phase 3: Frontend
- [ ] Create LoginPage.vue with OAuth buttons
- [ ] Implement auth store (Pinia)
- [ ] Add route guards for protected pages
- [ ] Handle token refresh

### Phase 4: Testing
- [ ] Unit tests for JWT utility
- [ ] Integration tests for OAuth flow
- [ ] E2E tests for login/logout

### Risks
- OAuth callback URL configuration per environment
- Token refresh race conditions

5.3 架構設計 — architect Agent

💡 沒有 /design 這個指令。架構設計是由 /plan 委派給 architect agent 完成的，或直接用 /plan-prd、/multi-plan 進入更大規模的規劃流程。

/ecc:plan "Design the authentication module architecture"
# → planner 委派給 architect agent

Agent 行為：architect agent 產出：

• API 端點設計
• 資料模型（Entity / DTO / VO）
• 序列圖（認證流程）
• 安全考量

5.4 實作（TDD）— tdd-workflow Skill

🚨 退役提醒：舊版教學中的 /tdd 指令已退役，現在的正式入口是 tdd-workflow Skill。舊指令檔案仍保留在 repo 的 legacy-command-shims/commands/ ，但不會隨預設安裝。

使用 tdd-workflow skill 實作 AuthService

你也可以直接描述任務，讓模型自行載入對應 Skill（這正是 Skill 優於 Slash Command 的原因：按需載入，不常駐佔用上下文）：

幫我用 TDD 方式實作 AuthService，先寫失敗測試

Skill 行為（tdd-workflow，搭配 tdd-guide agent）：

1. Define interfaces first          → 定義 AuthService 介面
2. Write failing tests (RED)        → 寫 AuthServiceTest，全部 FAIL
3. Implement minimal code (GREEN)   → 實作到剛好通過測試
4. Refactor (IMPROVE)               → 重構、extract method
5. Verify 80%+ coverage             → 確認覆蓋率達標

Spring Boot 實作範例：

// Step 1: Interface
public interface AuthService {
    TokenResponse authenticate(OAuth2AuthenticationToken token);
    TokenResponse refreshToken(String refreshToken);
    void logout(String userId);
}

// Step 2: RED - Failing Test
@ExtendWith(MockitoExtension.class)
class AuthServiceImplTest {
    @Mock JwtTokenProvider jwtProvider;
    @Mock UserRepository userRepo;
    @InjectMocks AuthServiceImpl authService;

    @Test
    void authenticate_shouldReturnTokens_whenOAuthValid() {
        // Given
        var oauthToken = mockOAuth2Token("google", "user@example.com");
        var user = new User(1L, "user@example.com", "Google User");
        when(userRepo.findByEmail("user@example.com")).thenReturn(Optional.of(user));
        when(jwtProvider.generateAccessToken(user)).thenReturn("access-token");
        when(jwtProvider.generateRefreshToken(user)).thenReturn("refresh-token");

        // When
        var result = authService.authenticate(oauthToken);

        // Then
        assertThat(result.accessToken()).isEqualTo("access-token");
        assertThat(result.refreshToken()).isEqualTo("refresh-token");
    }
}

// Step 3: GREEN - Implementation
@Service
@RequiredArgsConstructor
public class AuthServiceImpl implements AuthService {
    private final JwtTokenProvider jwtProvider;
    private final UserRepository userRepo;

    @Override
    public TokenResponse authenticate(OAuth2AuthenticationToken token) {
        String email = token.getPrincipal().getAttribute("email");
        User user = userRepo.findByEmail(email)
            .orElseGet(() -> createNewUser(token));
        return new TokenResponse(
            jwtProvider.generateAccessToken(user),
            jwtProvider.generateRefreshToken(user)
        );
    }
}

5.5 測試 — e2e-testing Skill 與 /test-coverage

🚨 退役提醒：/e2e 指令已退役，改由 e2e-testing Skill 接手。而覆蓋率分析的 /test-coverage 仍是有效指令，後者並未退役。

使用 e2e-testing skill 產生登入流程的 Playwright E2E 測試

若使用特定語言的測試指令，可直接呼叫：/go-test、/kotlin-test、/rust-test、/cpp-test、/flutter-test、/react-test（這些都屬於現行的 94 個指令）。

E2E 測試範例：

import { test, expect } from '@playwright/test';

test.describe('Authentication Flow', () => {
  test('should redirect to Google OAuth and complete login', async ({ page }) => {
    await page.goto('/login');
    await page.click('[data-testid="google-login-btn"]');

    // Mock OAuth callback
    await page.waitForURL('**/oauth2/callback**');

    // Verify redirect to dashboard
    await expect(page).toHaveURL('/dashboard');
    await expect(page.locator('[data-testid="user-avatar"]')).toBeVisible();
  });

  test('should show error on failed authentication', async ({ page }) => {
    await page.goto('/login?error=access_denied');
    await expect(page.locator('.error-message')).toContainText('登入失敗');
  });
});

5.6 /code-review — 程式碼審查

/code-review

Agent 行為（code-reviewer + 語言專用 reviewer）：

• 程式碼品質與可維護性
• 安全弱點（OWASP Top 10）
• 效能問題
• 測試覆蓋率缺口

5.7 部署 — deployment-patterns Skill

💡 沒有 /deploy 這個指令。部署相關的工作流由 deployment-patterns Skill 提供，搭配下方三道閘門。

# 使用 deployment-patterns skill
/security-scan    # 部署前安全掃描
/test-coverage    # 驗證 80%+ 覆蓋率

搭配 e2e-testing Skill 執行關鍵用戶流測試：

使用 e2e-testing skill 跑一次關鍵用戶流程回歸

💡 Best Practice：部署前三道閘門 — Security Scan → E2E → Coverage。全部通過才允許部署。

5.8 驗證迴圈 — verification-loop 與 eval-harness Skill

🚨 退役提醒：/verify 與 /eval 兩個指令均已退役，分別由 verification-loop 與 eval-harness Skill 取代。/checkpoint 仍是有效指令。

ECC 提供持續驗證機制，確保每次變更都通過完整品質閘門：

# 儲存當前驗證狀態的 Checkpoint（現行指令）
/checkpoint

# 執行完整驗證迴圈
使用 verification-loop skill 執行完整驗證

# 依自訂標準評估
使用 eval-harness skill 依驗收標準評估本次變更

驗證迴圈流程：

graph LR
    Build["🔨 Build"] --> Test["🧪 Test"]
    Test --> Lint["📏 Lint"]
    Lint --> TypeCheck["✅ TypeCheck"]
    TypeCheck --> Security["🔐 Security"]
    Security --> Pass{全部通過?}
    Pass -->|是| Done["✅ 驗證完成"]
    Pass -->|否| Fix["🔧 修復問題"]
    Fix --> Build

驗證類型：

Eval Harness 評估指標：

• Pass@k：k 次嘗試中至少一次通過的機率
• Grader Types：自動化 Grader（程式判定）vs 模型 Grader（LLM 判定）
• Checkpoint vs Continuous：Checkpoint 在特定節點驗證；Continuous 在每次變更後驗證

💡 Best Practice：對關鍵功能使用 verification-loop skill 啟用持續驗證。對大型重構使用 /checkpoint 保存狀態後執行一次性驗證。

💡 與 Claude Code 原生機制的關係：Anthropic 官方建議的「給 Claude 一個可驗證的檢查」原則，在平台層有三種對應機制——單一提示內驗證、/goal 持續評估條件、或 Stop Hook 強制阻擋（連續阻擋 8 次後平台會強制結束回合）。ECC 的 verification-loop／eval-harness Skill 可視為在 Stop Hook 機制上，針對「build → test → lint → typecheck → security」這條特定管道預先寫好的實作範本，而非另一套平行機制。

5.9 Plan Canvas — 視覺化計畫審查

Plan Canvas 是 ECC v2.1.0 引入的重大新功能，把 /plan 流程原本「一大段文字往返」的計畫審查，變成瀏覽器內可點選、可標註的視覺化流程。

5.9.1 解決的問題

/plan 最終會停在一個確認關卡（CONFIRM gate），過去只能在終端機裡逐行閱讀落落長的 Markdown 計畫、再用文字描述「我要改第三點」。Plan Canvas 讓審查者可以直接指向要修改的部分，而不必重新用文字描述一次。

5.9.2 運作方式

sequenceDiagram
    participant U as 審查者（瀏覽器）
    participant C as Plan Canvas（loopback-only）
    participant A as Agent（終端機）

    A->>C: /plan 產出計畫，開啟本機瀏覽器分頁
    U->>C: 點選元素／反白文字，附加編號標註
    U->>C: 側邊欄與 Agent 對話（Agent 同時仍在終端機工作）
    U->>C: 點擊「Approve plan」或「Request changes」
    C->>A: 對應 /plan 的 CONFIRM gate 決策
    A->>A: 依決策繼續執行或修改計畫

• 支援 Mermaid 圖表、表格、任務清單原生渲染；檔案變更會即時重新整理頁面
• Model 與 Harness 無關：底層是一份純 CLI + JSON 協定（ecc-plan-canvas），並非只綁定 Claude
• 僅在**本機迴路（loopback-only）**開啟，不會對外網路暴露

5.9.3 使用時機建議

💡 這與 Anthropic 官方建議的「Plan Mode → Ctrl+G 在文字編輯器中直接編輯計畫」是互補而非取代關係：文字編輯器適合工程師快速修改文字，Plan Canvas 適合需要標註特定元素、或涉及非工程關係人參與審查的場景。

第六章：測試與品質控管

6.1 TDD Skill 實作

ECC 的 TDD 工作流程遵循嚴格的 RED → GREEN → REFACTOR 循環：

graph TD
    A["定義介面"] --> B["撰寫失敗測試 (RED)"]
    B --> C["實作最小程式碼 (GREEN)"]
    C --> D["重構 (REFACTOR)"]
    D --> E{覆蓋率 >= 80%?}
    E -->|否| B
    E -->|是| F["提交"]
    F --> G["Code Review"]

可用的 TDD Skills：

6.2 自動 Code Review

code-reviewer agent 自動檢查：

1. 命名規範：是否符合語言慣例
2. 複雜度：方法是否過長、巢狀過深
3. 重複程式碼：DRY 原則
4. 安全性：SQL Injection、XSS、不安全的資料處理
5. 效能：N+1 查詢、不必要的 IO
6. 測試：是否有對應測試、edge case 是否覆蓋

語言專用審查指令：/python-review、/go-review、/kotlin-review、/rust-review、/cpp-review、/flutter-review、/react-review、/vue-review、/fastapi-review。這些會在通用審查之上，額外套用該語言的慣例與常見陷阱。

6.2.1 /santa-loop — 對抗式雙重審查收斂迴圈

ECC 提供一個比單次 Code Review 更嚴格的機制：/santa-loop。它的設計前提是單一審查者（無論人或模型）都會有盲點，因此：

1. 由兩個獨立的模型審查者分別審查同一份變更；
2. 兩者都必須通過，迴圈才收斂；
3. 只要任一方提出未解決的問題，就回到修正階段重跑。

執行 /santa-loop 審查這次的 PR 變更

graph LR
    Code["變更提交"] --> R1["審查者 A<br/>獨立上下文"]
    Code --> R2["審查者 B<br/>獨立上下文"]
    R1 --> Gate{兩者皆通過?}
    R2 --> Gate
    Gate -->|否| Fix["修正"]
    Fix --> Code
    Gate -->|是| Done["收斂，允許合併"]

🏢 企業適用場景：這種「雙人覆核」在金融、醫療、公部門系統本來就是稽核要求。/santa-loop 讓 AI 產出的變更也套用同一套控制原則，是把 ECC 帶進受監理環境時很有說服力的論據。代價是成本至少加倍，建議只套用在高風險模組（認證、金流、權限）而非全部程式碼。

💡 v2.2 延伸：v2.2.0 另外加入了多模型評議審查（multi-model council review），把「兩個審查者」推廣為「一組不同模型組成的評議會」，用模型多樣性降低同源偏誤。詳見 12.10。

6.3 Plankton 程式碼品質

plankton-code-quality skill 在寫入時強制執行程式碼品質：

• PostToolUse Hook 在每次檔案編輯後自動執行
• 自動修復 Linter 違規
• 強制一致的程式碼風格

6.4 AgentShield 安全掃描

# 快速掃描（無需安裝）
npx ecc-agentshield scan

# 自動修復安全問題
npx ecc-agentshield scan --fix

# 深度分析（三個 Opus agent 紅藍對抗）
npx ecc-agentshield scan --opus --stream

# 產生安全配置
npx ecc-agentshield init

掃描範圍：

--opus 模式：三個 Claude Opus agent 進行紅藍對抗 —

1. Attacker：尋找 exploit chain
2. Defender：評估現有防護
3. Auditor：綜合兩者產出優先級風險評估

輸出格式：Terminal（色彩分級 A-F）、JSON（CI Pipeline）、Markdown、HTML

6.5 CI/CD 整合測試流程

graph TD
    A["開發者 Push"] --> B["CI Pipeline 啟動"]
    B --> C["Run Unit Tests"]
    C --> D["Run Integration Tests"]
    D --> E["AgentShield Security Scan"]
    E --> F{"Exit Code?"}
    F -->|"0 or 1"| G["Run E2E Tests"]
    F -->|"2 (Critical)"| H["❌ 阻斷部署"]
    G --> I["Coverage Report"]
    I --> J{"Coverage ≥ 80%?"}
    J -->|是| K["✅ 允許合併"]
    J -->|否| L["❌ 要求提高覆蓋率"]

GitHub Actions 範例：

name: ECC Quality Gate
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run Tests
        run: npm test -- --coverage

      - name: Security Scan
        run: npx ecc-agentshield scan --format json --output security-report.json

      - name: Check Coverage
        run: |
          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "Coverage ${COVERAGE}% is below 80% threshold"
            exit 1
          fi

6.6 驗證迴圈與評估框架

ECC 提供兩個進階的品質驗證機制，源自 Longform Guide 的核心理念。

6.6.1 Verification Loop（持續驗證迴圈）

verification-loop skill 在每次程式碼變更後自動執行完整驗證管道：

graph TD
    subgraph "Verification Loop"
        A["程式碼變更"] --> B["Build Check"]
        B --> C["Unit Test"]
        C --> D["Lint Check"]
        D --> E["Type Check"]
        E --> F["Security Scan"]
        F --> G{全部通過?}
        G -->|否| H["產生修復建議"]
        H --> A
        G -->|是| I["✅ 通過"]
    end

6.6.2 Eval Harness（評估框架）

eval-harness skill 提供結構化的評估機制，讓你定義明確的品質標準：

# 儲存當前驗證狀態（現行指令）
/checkpoint

# 執行驗證與評估（/verify 與 /eval 已退役，改用 Skill）
使用 verification-loop skill 執行驗證
使用 eval-harness skill 依驗收標準評估

評估框架核心概念：

Pass@k 與 Pass^k：兩個容易被混淆的指標

這兩個指標只差一個符號，方向卻完全相反，是評估代理可靠度時最關鍵的觀念差異。假設單次成功率為 70%：

• Pass@k 隨 k 上升：代表「多試幾次總會成功」，適合衡量有人在旁挑選結果的互動式開發。
• Pass^k 隨 k 下降：代表「連續都要成功」，適合衡量無人值守自動化的可靠度。

⚠️ 企業選型的實務意涵：許多團隊用 Pass@k 的漂亮數字說服管理層導入自動化流程，卻在正式上線後發現失敗率遠高於預期——因為無人值守場景真正對應的是 Pass^k。任何要進入 CI 或自動合併流程的代理任務，都應以 Pass^k 設定驗收門檻，並搭配 8.5 的斷路器控制失敗成本。

6.6.3 Learn-Eval（學習評估）

/learn-eval 指令結合學習與評估，從 Session 中擷取模式並在儲存前進行評估：

# 不只學習，還評估學到的模式品質
/learn-eval

這比單純的 /learn 更具品質保障，避免學習到錯誤或低品質的模式。

第七章：安全（SSDLC）

7.1 ECC 安全架構

graph TB
    subgraph "開發階段 (Shift Left)"
        A["Secure Coding Rules<br/>rules/common/security.md"]
        B["Pre-commit Hooks<br/>Secret Detection"]
        C["TDD Security Tests<br/>springboot-security skill"]
    end
    
    subgraph "審查階段"
        D["security-reviewer Agent<br/>OWASP Top 10 分析"]
        E["AgentShield Scan<br/>配置弱點掃描"]
    end
    
    subgraph "部署階段"
        F["CI Security Gate<br/>Exit Code 2 = Block"]
        G["Dependency Scan<br/>CVE 檢查"]
    end
    
    subgraph "運行階段"
        H["Monitoring & Alerts"]
        I["Incident Response"]
    end
    
    A --> B --> C --> D --> E --> F --> G --> H --> I

7.2 安全檢查自動化

ECC 在 SSDLC 各階段提供自動化安全檢查：

7.3 OWASP Top 10 防護

7.4 Secret Detection

ECC 提供多層 Secret Detection：

Layer 1: beforeSubmitPrompt Hook (Cursor)
  → 偵測 prompt 中的 sk-、ghp_、AKIA 模式

Layer 2: beforeTabFileRead Hook (Cursor)
  → 阻止 Tab 讀取 .env、.key、.pem

Layer 3: AgentShield Secrets Detection
  → 14 種 pattern matching 規則

Layer 4: CI Build Gate
  → Exit code 2 阻斷含機密的 commit

⚠️ 常見錯誤：在 .claude/settings.json 中存放 API Key。應使用環境變數或 vault 管理。

7.5 GateGuard 安全閘門

GateGuard 是 ECC v1.10.0 引入的安全閘門機制（來自社群貢獻 PR #1367），提供更精細的安全控制。

7.5.1 GateGuard 功能

• Hook 層級安全閘門：在 PreToolUse 階段攔截潛在危險操作
• 動態風險評估：根據操作類型與上下文計算風險等級
• 可設定的嚴格度：與 ECC_HOOK_PROFILE 整合，支援 minimal / standard / strict 三級
• 整合 AgentShield：與靜態分析和 Secret Detection 協同運作
• 破壞性命令偵測（v2.0.0）：攔截 find -exec rm、rm -rf /、chmod 777、dd if=/dev/zero 等破壞性 shell 命令，即使包裝在 Bash tool 呼叫中亦可辨識
• 路徑排除清單（v2.1.0 新增）：透過 GATEGUARD_EXEMPT_GLOBS 環境變數設定 glob 排除規則，避免誤攔截合法的建構產物清理、測試 fixture 重置等操作
• PostToolUse 派發器整併（v2.1.0）：原本多個獨立的 PostToolUse Hook 行程，整併為同步／非同步兩種派發器，降低每次工具呼叫的行程開銷
• 供應鏈強化（v2.1.0）：pre-commit Secret 掃描新增偵測 sk-ant- 開頭的 Anthropic API Key 洩漏

7.5.2 GateGuard 與 AgentShield 的差異

graph LR
    A["工具操作請求"] --> B["GateGuard<br/>PreToolUse Hook"]
    B --> C{風險評估}
    C -->|低風險| D["允許執行"]
    C -->|中風險| E["警告並允許"]
    C -->|高風險| F["阻斷並通知"]

7.6 威脅情資：2026 年代理式編碼的真實攻擊面

前述 7.1～7.5 描述的是「ECC 幫你檢查你寫的程式碼是否安全」。但企業導入 AI 編碼代理時，還有第二個、且往往被忽略的風險面向——代理本身就是攻擊面。本節整理 2026 年公開揭露的實證事件，作為導入決策的風險基礎。

⚠️ 本節定位：以下為第三方安全研究機構的公開揭露，非 ECC 專案缺陷。列出的目的是協助企業建立正確的威脅模型，而非否定工具價值。所有事件都應與 7.7～7.12 的緩解措施對照閱讀。

7.6.1 Claude Code 平台本身的已知漏洞

企業行動項目：

1. 在資產清冊中把 Claude Code CLI 視為受管軟體，納入版本基線與更新 SLA。
2. 於 CI 或 MDM 中加入版本檢查，阻擋低於基線版本的用戶端。
3. 對「開啟外部 repo」建立標準作業程序：先在隔離環境檢視 .claude/、.mcp.json、.vscode/、.devcontainer/ 等設定檔，再決定是否信任。

💡 與本手冊其他章節的關聯：3.1 前置需求要求 Claude Code v2.1+；從安全角度，這個下限應再提高——建議基線為 2.0.65 以上，以同時涵蓋上述兩個 CVE。

7.6.2 威脅模型：致命三要素（Lethal Trifecta）

安全研究者 Simon Willison 提出的「lethal trifecta」是目前描述代理式風險最簡潔的框架。當以下三個條件同時成立時，資料外洩幾乎必然發生：

graph TB
    A["① 存取私有資料<br/>原始碼、憑證、客戶資料"]
    B["② 接觸不可信內容<br/>Issue、PR、網頁、相依套件、Skill"]
    C["③ 具備對外通訊能力<br/>網路請求、git push、Webhook"]
    D["資料外洩<br/>Data Exfiltration"]

    A --> D
    B --> D
    C --> D

其推論非常實用：只要能切斷任意一條邊，風險就大幅下降。這正是 7.7 沙箱化（切斷 ③）、7.9 消毒（削弱 ②）、7.8 權限邊界（限縮 ①）三節的設計理據。

7.6.3 生態系與供應鏈風險

代理生態系的擴充機制（Skills、MCP、Rules、Plugin）本質上是可執行的第三方內容，其風險等級應等同於 npm 套件，而非等同於文件。

建議的 Skill／MCP 准入流程：

1. 鎖定版本：以 Git tag 或 npm 版本鎖定安裝（呼應 1.6 的版本使用建議），禁止 CI 追蹤 main。
2. 人工審查：任何新增的 SKILL.md、Hook 腳本、MCP 設定，一律走 Pull Request 與雙人審查。
3. 自動掃描：以 npx ecc-agentshield scan 於 PR 階段檢查，並加上 7.9 的隱藏字元／注入樣式規則。
4. 最小安裝：呼應 2.7 的 MCP 精簡政策——ECC 預設僅保留 chrome-devtools 一個連接器，企業自建時也應維持「預設關閉、按需開啟」。

7.7 沙箱化與隔離架構

沙箱化的目標是切斷 7.6.2 的第三條邊：即使代理被誘導執行惡意行為，也無法把資料送出去、無法傷害宿主環境。

7.7.1 四層隔離模型

⚠️ 容器隔離的三個已知限制：（1）容器與宿主共用核心，並非安全邊界的終點；（2）VS Code 等 IDE 擴充仍在宿主執行，容器化 CLI 不代表 IDE 路徑也被隔離；（3)掛載進容器的目錄仍是可外洩的私有資料，掛載範圍必須最小化。

7.7.2 無出口網路的容器範例

以 Docker Compose 建立「可讀寫程式碼、但無法對外通訊」的執行環境：

services:
  agent:
    image: node:22-bookworm-slim
    working_dir: /workspace
    volumes:
      - ./:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    networks:
      - offline
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    read_only: false
    tmpfs:
      - /tmp

networks:
  offline:
    internal: true    # 關鍵：無對外路由

若只需一次性執行，也可直接以 --network=none 啟動：

docker run --rm -it \
  --network=none \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  -v "$PWD":/workspace -w /workspace \
  node:22-bookworm-slim bash

⚠️ 實務取捨：完全無網路會使 Claude Code 無法呼叫 API。實務上常見做法是採出口白名單（egress allowlist）——僅放行 api.anthropic.com 與內部套件鏡像，其餘全阻。這同時可緩解 CVE-2026-21852 的流量重導風險。

7.7.3 Claude Code 原生 /sandbox

Claude Code 內建的 /sandbox 提供 OS 層級隔離，讓代理在邊界內以較高自由度工作（減少逐次核准的疲勞）。它與本節的容器化不是互斥選項：

7.8 權限邊界與最小代理權（Least Agency）

傳統資安談「最小權限（least privilege）」，代理式系統則需要更進一步的最小代理權（least agency）：不只限制「能存取什麼」，還要限制「能自主做到什麼程度」。

7.8.1 permissions.deny 基線設定

在 .claude/settings.json 中建立團隊共用的封鎖基線（建議納入版控並以 Code Review 保護）：

{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.config/gcloud/**)",
      "Read(**/.env*)",
      "Write(~/.ssh/**)",
      "Write(~/.aws/**)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)",
      "Bash(ssh *)",
      "Bash(scp *)",
      "Bash(nc *)"
    ]
  }
}

⚠️ 不要把 API Key 放進 settings.json（呼應 7.4）。此檔案會進版控，應僅存放權限規則；憑證一律走環境變數或密鑰管理服務。

7.8.2 核准邊界設計原則

以 GitHub 對其編碼代理採用的控制模型為參考範本，可歸納出五條企業通用原則：

7.8.3 自主層級與核准模式對照

💡 導入建議：自主層級應該是逐步解鎖的。新團隊從 Manual + 容器起步，累積 4～6 週的稽核日誌後，再逐項放寬到 Auto mode；無人值守迴圈僅開放給已具備 8.4 可觀測性與 8.5 斷路器的專案。

7.9 不可信輸入的消毒（Sanitization）

提示注入的載體通常不是人眼可見的文字。企業級導入應在代理讀取外部內容前，先做機械化消毒。

7.9.1 隱藏字元與注入樣式偵測

# 偵測零寬字元與雙向控制字元（常用於藏匿指令）
grep -Pn '[\x{200B}\x{200C}\x{200D}\x{2060}\x{FEFF}\x{202A}-\x{202E}]' "$FILE"

# 偵測常見的注入載體
grep -Ein '<!--|<script|data:text/html|base64,' "$FILE"

# 偵測高風險關鍵字（外傳與端點劫持）
grep -Ein 'curl |wget |nc |scp |ssh |enableAllProjectMcpServers|ANTHROPIC_BASE_URL' "$FILE"

建議將上述檢查包裝為 PreToolUse Hook，於 WebFetch、Read（外部路徑）觸發時自動執行，命中即阻斷並要求人工確認。

7.9.2 消毒作業原則

💡 解析／執行分離是成本最低、效果最好的結構性防禦：負責閱讀不可信內容的代理沒有任何對外通訊或寫檔工具，即使被注入也無從執行。

7.10 記憶毒化與長期記憶治理

ECC 的核心賣點之一是記憶持久化（2.5 Instinct 系統、2.9 Unified Memory Vault）。但從安全角度，記憶是一個持久化的攻擊面：一次成功的注入，可能被寫入記憶庫並在往後每個 Session 重複生效。

建議治理規則：

1. 記憶庫檔案納入版控與 Code Review，把「記憶」當成程式碼資產管理。
2. 執行過任何不可信輸入的 Session，結束後重置該 Session 的記憶寫入並輪替相關憑證。
3. 對法遵敏感專案，預設關閉長期記憶，僅使用單次 Session 上下文。

7.11 MCP 安全與 OWASP MCP Top 10

MCP 是代理與外部系統之間的橋樑，也因此是權限升級的主要路徑。OWASP 針對 MCP 整理的高風險類別，可作為連接器准入審查的檢查表：

💡 架構層建議：能用 CLI + Skill 解決的整合（如 GitHub、部署平台），優先用 CLI 而非 MCP。這同時降低攻擊面與 Token 消耗——MCP 的工具描述會常駐上下文，數量一多即顯著壓縮可用窗口（詳見 10.4）。實務經驗值為同時啟用的 MCP 少於 10 個、工具總數少於 80 個。

7.12 企業導入的最低安全門檻檢查表

以下為「可以開始用」的最低標準。任一項未達成，不建議在存有正式程式碼或客戶資料的環境中導入。

⚠️ 合規提醒：第 9、10 項的實作細節位於第八章（8.4 可觀測性、8.5 斷路器）。安全與維運在代理式系統中是同一件事，不應由不同團隊各自為政。

第八章：部署與維運（DevOps）

8.1 CI/CD 整合

GitHub Actions 完整範例

name: ECC Enterprise Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build Backend
        run: mvn clean verify -B

      - name: Security Scan (AgentShield)
        run: npx ecc-agentshield scan --format json --output reports/security.json
        continue-on-error: false

      - name: E2E Tests (Playwright)
        run: npx playwright test

      - name: Quality Gate Check
        run: |
          echo "Checking coverage >= 80%..."
          mvn jacoco:check

      - name: Upload Reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: reports/

GitLab CI 範例

stages:
  - build
  - test
  - security
  - deploy

build:
  stage: build
  script:
    - mvn clean compile -B

test:
  stage: test
  script:
    - mvn test -B
    - mvn jacoco:report

security-scan:
  stage: security
  script:
    - npx ecc-agentshield scan --format json
  allow_failure: false

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main
  when: on_success

在 CI 中以非互動模式執行代理

上述兩個範例是「用 CI 驗證人類與代理共同產出的程式碼」。若要讓代理本身成為 CI 的一個步驟（例如自動修 lint、自動補測試、自動撰寫 PR 描述），必須使用非互動（headless）模式，並嚴格收斂權限：

claude -p "修正 ESLint 錯誤，只改 src/ 下的檔案，不要新增相依套件" \
  --output-format json \
  --allowedTools "Read,Edit,Bash(npm run lint:*)" \
  --no-session-persistence

⚠️ CI 中的三個常見錯誤：

1. 把互動模式的核准機制當成安全網。非互動模式下沒有人可以按「拒絕」，權限白名單就是唯一防線。
2. 給予 Bash(*) 全開權限。應收斂到具體命令樣式，如 Bash(npm run test:*)。
3. 讓代理直接推 main。代理應只能推自己的分支並開 PR，由人審查後合併（呼應 7.8.2）。

以 AgentShield 作為建置閘門

# 掃描並輸出 JSON 報告
npx -y ecc-agentshield scan --path . --format json --output reports/security.json

# 自動修復可安全修復的問題
npx -y ecc-agentshield scan --path . --fix

# 深度模式：red-team / blue-team / auditor 三代理對抗式審查
npx -y ecc-agentshield scan --path . --opus

💡 分層執行策略：PR 階段跑標準掃描（快、免費）；release/* 分支與定期排程跑 --opus 深度掃描（慢、耗 Token）。避免在每次 push 都執行深度模式。

8.2 監控與日誌

推薦監控架構：

graph LR
    App["Spring Boot<br/>Application"] --> |"Metrics"| Prometheus["Prometheus"]
    App --> |"Logs"| ELK["ELK Stack"]
    App --> |"Traces"| Jaeger["Jaeger"]
    Prometheus --> Grafana["Grafana<br/>Dashboard"]
    ELK --> Kibana["Kibana<br/>Dashboard"]

8.3 AI Agent 監控

監控 ECC Agent 的使用狀況：

# 檢查 Token 花費
/cost

# 檢查已安裝元件
/plugin list ecc@ecc

# 稽核 Harness 狀態
/harness-audit

# 查看活躍 Loop 狀態
/loop-status

此外，可將狀態快照落地為檔案，納入排程健檢與交接文件（詳見 12.7）：

ecc status --markdown --write status.md
npx ecc-universal doctor

💡 建議節奏：doctor 納入每日排程（偵測安裝漂移與版本落差）；status --markdown 於每次版本升級前後各執行一次，作為升級前後的差異證據（呼應 9.4 升級檢查表）。

8.4 Agent 可觀測性（Observability）

8.2 監控的是應用程式；本節監控的是代理本身的行為。在代理具備寫檔與執行命令能力的前提下，「代理做了什麼」必須與正式系統的稽核日誌等級一致——這也是 7.12 檢查表第 9 項的實作。

8.4.1 最低必要日誌欄位

⚠️ 日誌本身也是敏感資產：input_summary 與 files_touched 可能洩漏商業邏輯，日誌儲存區需比照原始碼的存取控制，並設定保留期限。

8.4.2 匯出至既有可觀測性平台

代理日誌不應獨立成孤島，建議以 OpenTelemetry 匯出，與 8.2 的既有堆疊整併：

graph LR
    Hook["PostToolUse Hook<br/>結構化事件"] --> OTel["OpenTelemetry<br/>Collector"]
    Gate["GateGuard<br/>風險評級"] --> OTel
    Shield["AgentShield<br/>掃描結果"] --> OTel
    OTel --> Metrics["Prometheus<br/>指標"]
    OTel --> Logs["ELK Stack<br/>日誌"]
    OTel --> Traces["Jaeger<br/>追蹤"]
    Metrics --> Dash["Grafana<br/>Agent 行為儀表板"]
    Logs --> Dash

實作要點：於 PostToolUse Hook 中把事件以 JSON Lines 追加寫入指定路徑，再由 Collector 的 filelog receiver 讀取，避免 Hook 直接發網路請求而拖慢每次工具呼叫。

8.4.3 異常偵測基線

8.5 無人值守迴圈的斷路器（Circuit Breaker）

autonomous-loops、/goal、loop-operator 這類長時間無人看管的機制，必須具備可靠終止能力——這是 7.12 檢查表第 10 項的實作。

8.5.1 終止訊號的正確使用

⚠️ 只殺父程序是不夠的。代理常透過 shell 衍生子程序（測試、建置、開發伺服器），只終止父程序會留下孤兒程序繼續佔用資源，甚至持續對外通訊。應以程序群組為單位終止：

const child = spawn(cmd, args, { detached: true });   // 建立獨立程序群組

function terminate(pid) {
  process.kill(-pid, "SIGTERM");                       // 負號 = 整個程序群組
  setTimeout(() => {
    try { process.kill(-pid, "SIGKILL"); } catch { /* 已結束 */ }
  }, 10_000);
}

8.5.2 心跳與失效保護（Dead-man Switch）

長時間任務可能「還活著但已無進展」（重複相同錯誤、等待永不到來的輸入）。心跳機制的設計要點：

💡 隔離優於刪除：停滯的任務常帶有最有價值的除錯資訊。建議把該 worktree 標記為 quarantine/ 並保留，而不是自動清理——這與 12.4 的 Worktree-lifecycle 機制可直接整合。

8.5.3 斷路器決策流程

graph TB
    Loop["自主迴圈執行中"] --> HB{"心跳於 90 秒內更新?"}
    HB -->|否| Quar["標記停滯<br/>隔離工作區"]
    HB -->|是| Budget{"迭代/Token/時長<br/>是否超過上限?"}
    Budget -->|是| Stop["SIGTERM 程序群組<br/>10 秒後 SIGKILL"]
    Budget -->|否| Risk{"GateGuard 出現<br/>高風險事件?"}
    Risk -->|是| Stop
    Risk -->|否| Loop
    Quar --> Review["人工審查"]
    Stop --> Review

8.6 成本治理與 Token 預算

代理式開發的成本結構與傳統開發不同：成本會隨上下文長度與重試次數非線性成長。缺乏治理時，單一失控迴圈即可耗盡團隊當日額度。

建議追蹤的維運 KPI：

💡 與 13.1 的關聯：上述 KPI 是計算整體擁有成本（TCO）的原始資料。導入初期就應開始蒐集，否則半年後將無法客觀回答「這套框架是否值得」。

第九章：系統維護與升級

9.1 ECC 版本升級策略

# 檢查當前版本（main 分支的 VERSION 可能領先於最新 Release Tag，兩者不一定相同）
cat VERSION  # 或查看 CHANGELOG.md
git describe --tags  # 查看目前所在的最近 Release Tag

# 更新到最新「已發行」版本（建議走 tag，而非直接追蹤 main）
cd ECC
git fetch --tags
git checkout v2.2.0   # 鎖定到目前最新穩定 Release，而非 origin/main
npm install

已安裝 npm 套件者的升級路徑：

# 先確認 npm 上的版本（參見 1.6 的發行落差說明）
npm view ecc-universal version

# 重跑導引式設定（v2.2 推薦的升級入口）
npx ecc-universal setup

# 升級後驗證
npx ecc-universal doctor

⚠️ 升級時同樣適用「只選一種安裝路徑」原則：若你是透過 Plugin 安裝，升級只需 /plugin update ecc 或重跑 /plugin install ecc@ecc；不要額外執行 ./install.sh --profile full。只有走「手動安裝」路徑的使用者，才需要重跑 ./install.sh（依 3.3 節指定的語言包，而非 --profile full）。

# 選擇性安裝（v1.9.0+ manifest-driven 安裝，只更新有變更的元件）
node scripts/install-plan.js
node scripts/install-apply.js

ECC CLI 管理指令（v2.0.0）：

# 統一管理入口
node scripts/ecc.js list-installed   # 檢查已安裝元件清單
node scripts/ecc.js doctor           # 診斷設定問題
node scripts/ecc.js repair           # 自動修復遺失/損壞的元件
node scripts/ecc.js uninstall        # 完整移除 ECC 管理的檔案
node scripts/ecc.js version          # 顯示已安裝版本

故障復原：

# 如果本地 ECC 被清除或重置
node scripts/ecc.js list-installed    # 檢查已安裝項目
node scripts/ecc.js doctor           # 診斷問題
node scripts/ecc.js repair           # 修復（通常可恢復）

💡 ecc 指令等同於 node scripts/ecc.js。若已安裝 Plugin（/plugin install ecc@ecc），可直接在 Claude Code 中使用 /ecc:doctor 等命名空間指令。

9.2 Skills / Agents 管理

# 審查 Skills 和 Commands 品質
/skill-stocktake

# 從 Git History 產生 Skills
/skill-create
/skill-create --instincts    # 同時產生 Instincts

# 查看已學習的 Instincts
/instinct-status

# 將 Instincts 演化為 Skills
/evolve

# 清除過期 Instincts
/prune

9.3 相容性與故障排除

9.4 v2.1 → v2.2 升級實務檢查表

v2.2.0 相對 v2.1.0 的差異規模為 108 commits、530 個檔案、+40,299 / −4,679 行，並非小版本修訂。企業環境升級前請逐項確認：

升級前

• 執行 ecc list-installed，記錄目前的安裝路徑與元件清單
• 確認 npm view ecc-universal version 已推廣至 2.2.x（若仍為 2.1.0，請改走 /plugin 路徑）
• 先用 --dry-run 預覽變更：npx ecc-universal install --guided --harness <target> --dry-run
• 備份或 commit 當前的 .claude/、.codex/、.cursor/ 等專案內設定

MCP 預設集合變更（最容易遭殌的一項）

• 確認團隊是否依賴 github、context7、exa、memory、playwright、sequential-thinking 這六個已退出預設集合的連接器
• 若有依賴，在 mcp-configs/mcp-servers.json 中手動重新啟用，或改用對應 Skill（github-ops、documentation-lookup、exa-search）

指令退役

• 搜尋內部文件、CI 腳本與教學材料中的 /tdd、/e2e、/verify、/eval、/docs 等 12 個退役指令（清單見附錄 I）
• 將其改寫為對應 Skill 呼叫

平台與路徑

• OpenCode：確認 ~/.opencode → ~/.config/opencode 的遷移結果，並重新選定 provider / model
• Antigravity：確認是否同時存在 .agent/（舊）與 .agents/（新），必要時以 ecc repair 清理
• Windows 團隊：評估是否改用 WSL2（見 3.11.2）

升級後驗證

• ecc doctor（必要時加 --target <harness>）全數通過
• ecc memory doctor 確認記憶庫可讀寫
• 跑一次 node tests/run-all.js 確認本地環境健康
• 將 .ecc/memory/ 納入 CODEOWNERS 與 Code Review 範圍（見 2.9.3）

第十章：最佳實踐（Best Practices）

10.1 避免上下文污染

10.2 Agent 設計原則

1. 單一職責：每個 Agent 只處理一類任務
2. 最小工具集：只授予必要的 tools 權限
3. 明確角色描述：在 YAML frontmatter 中清楚定義
4. 模型適配：日常用 sonnet、深度推理用 opus
5. 可組合性：Agent 之間可互相委派

10.3 Skill 設計模式

1. Research-First：使用 search-first skill，先研究再寫程式
2. TDD-First：所有新功能先寫測試
3. Security-by-Design：使用語言專用 security skill
4. Verification Loop：持續驗證（build → test → lint → typecheck → security）

10.4 Token 最佳化

💡 訂閱用戶提示：如果你使用 Claude Max/Team 訂閱而非 API 計費，設定 ECC_CONTEXT_MONITOR_COST_WARNINGS=off 可關閉不適用的費率估算提醒，但仍保留上下文範圍與 Token 用量警告。

⚠️ Agent Teams 成本警告：Claude Code 原生的 Agent Teams 功能會產生多個獨立的上下文窗口，每個 teammate 獨立消耗 Token。只在平行任務有明確價值時使用（如多模組工作、平行審查）。簡單順序任務用 subagent 更省。

10.4.1 依任務型態的模型路由

「一律用最強的模型」是成本失控最常見的原因。實務上約 90% 的任務適用 Sonnet，只有明確符合升級條件時才切換至 Opus：

升級至 Opus 的四個觸發條件（符合任一即升級）：

1. Sonnet 首次嘗試已失敗，且失敗原因不是提示不清楚。
2. 變更跨越 5 個以上檔案且彼此有耦合。
3. 涉及難以逆轉的架構決策（資料模型、API 契約、模組邊界）。
4. 屬於安全或資金相關的關鍵路徑。

💡 子代理降級：設定 CLAUDE_CODE_SUBAGENT_MODEL=haiku 後，主代理維持 Sonnet 負責統籌，探索型子代理則以 Haiku 執行——這是投入產出比最高的單一調整。

10.4.2 上下文佔用的四大來源

Token 成本的主因往往不是「講太多話」，而是常駐內容過大：

💡 檢索工具的選擇也影響成本：以語意索引為基礎的搜尋工具（如 mgrep 一類）相較於傳統逐檔 grep，在同等任務下可減少約一半的 Token 消耗——因為它回傳的是相關片段，而非大量需要代理自行過濾的原始命中結果。

10.4.3 進階環境變數調校

⚠️ 調低 MAX_THINKING_TOKENS 的取捨：深度架構推理與複雜除錯確實需要較長的思考預算。建議做法是全域調低、特定任務臨時調高，而非一律維持高值。

10.5 平行化策略

ECC 支援多種平行化模式，可顯著提升大型專案的開發效率。

10.5.1 Git Worktrees 平行化

利用 Git Worktrees 在同一 Repository 的多個分支上同時工作：

# 建立 Worktree
git worktree add ../feature-auth feature/auth
git worktree add ../feature-ui feature/ui

# 在不同 Worktree 中開啟獨立的 Claude Code Session
cd ../feature-auth && claude
cd ../feature-ui && claude

優勢：

• 每個 Worktree 有獨立的上下文窗口，互不污染
• 適合多人協作或一人多功能並行開發
• 合併時使用標準 Git merge 流程

10.5.2 Cascade 方法

逐層委派，讓子代理處理越來越具體的任務：

graph TD
    A["主 Agent<br/>高層規劃"] --> B["模組 A Agent<br/>認證模組"]
    A --> C["模組 B Agent<br/>用戶管理"]
    A --> D["模組 C Agent<br/>通知服務"]
    B --> B1["子任務 A1"]
    B --> B2["子任務 A2"]
    C --> C1["子任務 B1"]
    C --> C2["子任務 B2"]

10.5.3 何時擴展為多實例

💡 Best Practice：優先使用 subagent 委派（最省 Token）。只在任務真正需要並行處理時才升級到 Git Worktrees 或 Agent Teams。

10.5.4 Orchestrator 五階段流水線

多代理協作最常見的失敗原因，是讓多個代理共用同一個上下文，導致彼此干擾。可靠的做法是把流程切成階段，每個階段由獨立代理執行，並以檔案而非對話歷史作為交接介面：

五條執行規則：

1. 每個代理一次輸入、一次輸出，不做多輪即興發揮。
2. 前一階段的產出檔案，就是下一階段的唯一輸入。
3. 不可跳階——沒有 plan.md 就不進 IMPLEMENT。
4. 階段之間執行 /clear，確保上下文乾淨。
5. 所有中間產物落地存檔，作為稽核軌跡與失敗時的重試起點。

💡 與 ECC 的對應：orch-* 編排器族（見 4.3）與 /multi-plan／/multi-execute 即是此模式的預先實作。自建流程時，把上表的五個檔案名稱寫進 CLAUDE.md，就能讓代理自動遵循同一套交接約定。

10.5.5 迭代式檢索（Iterative Retrieval）

委派研究任務給子代理時，常見錯誤是接受第一次回傳的結果就繼續往下做。較可靠的模式是讓主代理扮演審核者：

1. 主代理委派時，傳遞的是目的（為什麼要查、要用來決定什麼），而不只是關鍵字。
2. 子代理回傳後，主代理評估是否足以支撐決策。
3. 不足則帶著具體缺口再次追問，最多三個循環。
4. 三次仍不足，視為「資訊不可得」並明確記錄，而非繼續猜測。

⚠️ 為什麼要設上限：沒有循環上限的檢索會演變成「無範圍的調查」，這正是 10.6.4 列出的失敗模式之一。三次上限迫使流程在「資訊不足」時做出明確決策，而非無限期消耗 Token。

10.5.6 雙實例啟動法

新專案或大型功能的開場，可同時開兩個 Session 分工：

兩者完成後，把實例 2 的產出交給實例 1（或新開的實作 Session）作為輸入。這個做法把「等待研究完成」的閒置時間轉為平行工作。

💡 搭配 --system-prompt 建立角色化終端：可為不同用途預先建立別名，例如 alias claude-review='claude --system-prompt "$(cat ~/.claude/roles/reviewer.md)"'。系統提示的權威層級高於一般使用者訊息，適合放置「絕不可違反」的角色約束。

10.6 Claude Code 原生生產力功能

前面各節談的多是 ECC 疊加的最佳實踐，但 Anthropic 官方文件本身也提供了一套獨立於 ECC 之外、同樣值得企業團隊內化的工作方法。以下摘要幾個容易被忽略、但與 ECC 高度互補的原生機制：

10.6.1 Explore → Plan → Code → Commit 四階段工作法

官方建議把「探索」與「執行」分離，避免 Agent 過早動手解決錯誤的問題：

1. Explore：以 Plan Mode（Shift+Tab 進入）唯讀探索程式庫，不做任何修改
2. Plan：要求產出詳細實作計畫，可用 Ctrl+G 開啟文字編輯器直接修改計畫（或用 ECC 的 Plan Canvas，見 5.9）
3. Code：核准計畫後切出 Plan Mode，依計畫實作並執行測試
4. Commit：請 Agent 撰寫描述性 Commit 訊息並建立 PR

💡 官方特別提醒：範圍清楚、影響小的變更（如修正錯字、加一行 log）應該跳過 Plan Mode 直接執行——「如果你能用一句話描述這個 diff，就跳過計畫階段」。Plan Mode 本身有額外開銷，不是每個任務都值得。

10.6.2 給 Agent 一個可驗證的檢查（Verifiable Check）

官方文件將此列為最重要的單一原則：沒有可驗證的檢查，Agent「看起來做完了」就是唯一訊號，你就會變成人工驗證迴圈本身。給它測試、build exit code、或截圖比對，讓它自己跑檢查、讀結果、修正到通過為止。

10.6.3 對抗式審查（Adversarial Review）

在正式視為完成前，讓一個全新上下文的 Subagent 只看 diff 與驗收標準來審查，而不是讓寫程式的那個 Session 自己審查自己的產出。ECC 的 code-reviewer、security-reviewer 等 Agent（見 2.1）正是這個原則的預先寫好的實作。

10.6.4 常見失敗模式（官方命名）

10.6.5 其他值得團隊採用的原生機制

10.6.6 驗證機制的四個層級

10.6.2 的「可驗證檢查」在平台層有四種強度不同的實作方式，應依任務的自主程度選用：

⚠️ Stop Hook 的平台上限：連續阻擋達 8 次後，平台會強制結束該回合，避免無限迴圈。因此 Stop Hook 的檢查條件必須是代理有能力自行修復的；把不可能在該 Session 內解決的條件（如需人工核准的外部相依）寫進 Stop Hook，只會浪費 8 次重試的 Token。

10.6.7 需求釐清與 Session 衛生

💡 與 ECC 的關係：/plan（5.2）與 Plan Canvas（5.9）可視為此流程的結構化版本——把「訪談 → 規格 → 實作」固化成可審查、可版控的產出，而非仰賴每位工程師的個人習慣。

⚠️ 企業教育訓練建議：導入 ECC 的團隊，建議先讓工程師完整讀過一次 Anthropic 官方 Best Practices for Claude Code，再學習 ECC 疊加的 Skill/Agent/Hook 具體內容——順序反過來，容易讓團隊誤以為「這些都是 ECC 發明的」，導致換工具或換框架時錯估遷移成本。

第十一章：常見問題與排錯

Q1：Agent 無法理解需求

原因：需求描述過於模糊或專業術語不一致

解決：

1. 使用 /plan 先讓 planner 分析需求
2. 提供明確的範例和 edge case
3. 使用 search-first skill 讓 Agent 先研究再回答

Q2：記憶錯亂 / 重複犯錯

原因：上下文資訊相互矛盾或已過期

解決：

1. /compact 壓縮過時資訊
2. /clear 完全重置（在不相關任務間）
3. 調整 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 提早壓縮
4. 使用 /instinct-status 檢查已學習模式

Q3：Token 爆掉 / 達到日限

解決：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

額外措施：

• 保持 < 10 MCPs、< 80 tools 啟用
• 使用 /clear 在不相關任務間
• 使用 /cost 定期監控

Q4：指令失效

最常見的原因：你用的是已退役的指令。/tdd、/e2e、/verify、/eval、/docs 等 12 個指令已被移出預設安裝，改由對應 Skill 接手，完整對照見附錄 I。

其余檢查清單：

1. claude --version 確認 ≥ v2.1.0
2. /plugin list ecc@ecc 確認 Plugin 已安裝
3. 確認 rules 已手動安裝
4. 確認 hooks 未重複宣告
5. multi-* 指令需額外安裝 npx ccg-workflow
6. 執行 ecc doctor 看是否有安裝歸屬問題

Q5：Hooks 不運作 / “Duplicate hooks file” 錯誤

解決：

1. 不要在 .claude-plugin/plugin.json 中加入 "hooks" 欄位
2. Claude Code v2.1+ 會自動載入 hooks/hooks.json
3. 如果手動安裝，使用 installer 而非直接複製

Q6：能否只使用部分元件？

可以。ECC 是模組化的：

• 只複製需要的 agents、skills、rules
• 使用選擇性安裝：./install.sh typescript
• v1.9.0+ 支援 manifest-driven 選擇性安裝

Q7：是否支援 Cursor / OpenCode / Codex / GitHub Copilot / Zed 以外的工具？

是。ECC 目前同時支援 13+ 種 Harness（詳見 3.5），但能力分級差異極大，請務必搭配 3.11 的支援矩陣一起看：

Q8：是否支援自訂 API 端點或模型閘道？

是。ECC 不硬編碼 Anthropic 本機傳輸設定。它透過 Claude Code 的正常 CLI/Plugin 介面本地運行，因此可搭配：

• Anthropic 託管的 Claude Code
• 使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 的官方閘道設定
• 相容的自訂端點（需支援 Anthropic API 協議）

# 最小設定範例
export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude

💡 如果你的閘道重新映射模型名稱，在 Claude Code 中設定而非在 ECC 中設定。ECC 的 Hooks、Skills、Commands 和 Rules 在 claude CLI 正常運作後是模型提供者無關的。

Q9：ECC 配置被清除了怎麼辦？

不要急著重新安裝。按以下步驟操作：

1. node scripts/ecc.js list-installed — 檢查已安裝項目
2. node scripts/ecc.js doctor — 診斷問題
3. node scripts/ecc.js repair — 自動修復

這通常可以恢復 ECC 管理的檔案而無需重建整個設定。如果問題是帳號或 Marketplace 存取（如 ECC Tools），需單獨處理帳單/帳號恢復。

Q10：ECC 是 Anthropic 官方產品嗎？

不是。ECC 是由社群維護者 Affaan Mustafa 發起、331 位貢獻者共同開發的第三方開源專案，並非 Anthropic 官方發行或背書的產品。Anthropic 官方僅提供 Claude Code 平台本身與其 Best Practices 文件；ECC 是建立在該平台之上的社群框架。企業導入前，建議完整閱讀第十三章的風險考量，特別是關於單一核心維護者與治理模式的討論。

Q11：想自架開源模型（而非使用 Anthropic Claude），ECC 能用嗎？

可以，但需要理解這是完全不同的風險輪廓。ECC 提供了 Kimi Code + Itô GPU 的官方參考路徑（見 3.10），也支援任何相容 ANTHROPIC_BASE_URL 協議的自訂閘道。但自架模型的推論品質、延遲、可用性與 Anthropic 官方託管的 Claude 模型並不相同，ECC 的 Agent/Skill 設計都是以 Claude 系列模型的推理能力為基準調校，換成其他開源模型時，實際效果可能有落差，需要自行評估與測試。另請注意：透過 Itô 的受管理推論服務尚未上線，且 ito-compute-cli 尚未發布至公開套件庫，需自行建置（見 3.10.2）。

Q12：Unified Memory Vault 跟 Instinct 系統、CLAUDE.md 有什麼差別？

三者解決的是不同層次的問題，不是三選一：

實務上的分工建議：「永遠要遵守的規則」寫 AGENTS.md（或 Rules）；「這次為什麼這樣決定」寫 Memory Vault；「模型自己摸索出來的手感」交給 Instinct 系統。

Q13：公司都用 Windows，可以導入 ECC 嗎？

可以，但強烈建議以 WSL2 為標準開發環境。Windows 原生環境屬於官方所謂的「有限制地支援」，目前至少有兩個開放中的缺陷：Continuous Learning v2 的 observer daemon（Issue #2489）與 Memory Vault 寫入（Issue #2626）；另外所有 shell-backed 功能（GAN、GateGuard 部分路徑）都需要 Git Bash 或 WSL。改用 WSL2 可一次繞開這些問題，也讓環境與 CI（通常是 Linux）一致。詳見 3.11.2。

Q14：團隊該選哪一種安裝路徑？

一句話：一個 Harness 只選一種，不要疊加。

第十二章：進階應用

12.1 多 Agent 協作（Multi-Agent System）

# 多 Agent 任務分解
/multi-plan "Build complete user management module"

# 多 Agent 協作執行
/multi-execute

# 後端多服務編排
/multi-backend

# 前端多服務編排
/multi-frontend

# 通用多服務工作流
/multi-workflow

⚠️ multi-* 指令需要額外安裝 ccg-workflow：npx ccg-workflow

PM2 服務管理：

# PM2 服務生命週期管理
/pm2

12.2 與其他 AI 工具整合

跨工具功能對照

⚠️ 上表「部分」欄位反映的是能力限縮的 Adapter，並非功能對等——第 2.8 節與附錄 D 有更細的原生 vs. 擴充分工說明。導入前務必實測，不要假設所有 Harness 都能取得 Claude Code 的完整體驗。

關鍵架構決策：

• AGENTS.md 是根目錄的通用跨工具檔案（多數工具都讀取）
• DRY adapter 模式讓 Cursor 重用 Claude Code 的 hook scripts
• SKILL.md 格式（YAML frontmatter）跨 Claude Code、Codex、OpenCode、Kimi Code 共用同一份規格

12.3 自訂 Agent

建立自訂 Agent

---
name: my-api-designer
description: Designs RESTful APIs following company standards
tools: ["Read", "Grep", "Glob"]
model: sonnet
---

You are a senior API designer specializing in RESTful services.

## Your Standards:
1. Follow OpenAPI 3.0 specification
2. Use kebab-case for URL paths
3. Use camelCase for JSON properties
4. Version APIs via URL path (/api/v1/...)
5. Standard error response format:
   { "error": { "code": "ERR_001", "message": "..." } }
6. Pagination: cursor-based for large datasets, offset for small
7. Rate limiting headers: X-RateLimit-Limit, X-RateLimit-Remaining

## Output:
- OpenAPI YAML specification
- Postman collection (optional)
- API documentation in Markdown

儲存位置

~/.claude/agents/my-api-designer.md    # 全域
.claude/agents/my-api-designer.md      # 專案層級

12.4 ECC 2.0 Control-Pane Substrate

ECC v2.0.0 將原先 Alpha 階段的 Rust control-pane 正式納入穩定版。Control-Pane 是 ECC 的底層調度基板，提供跨 Session 的狀態持久化和 Worktree 生命週期管理：

# 在 ecc2/ 目錄中
cd ecc2

# 可用指令
ecc2 dashboard    # 啟動儀表板（含 Session 可視化）
ecc2 start        # 啟動 session
ecc2 sessions     # 列出 sessions（含保留天數管理）
ecc2 status       # Operator 狀態快照
ecc2 stop         # 停止
ecc2 resume       # 恢復（含 worktree replay）
ecc2 daemon       # 背景守護程序
ecc2 worktree     # Worktree-lifecycle 管理

Worktree-Lifecycle Service

v2.0.0 新增的 Worktree-Lifecycle Service 為長時間執行的 Agent Session 提供隔離的 Git 工作樹：

⚠️ Worktree 功能需要 Git 2.20+。ECC 會在 session 啟動時自動檢查版本相容性。

12.5 NanoClaw v2

NanoClaw v2 是 ECC v1.8.0 引入的輕量級 Agent 運行時，提供進階的模型路由和 Session 管理能力。

12.5.1 核心功能

12.5.2 模型路由策略

# 使用 /model-route 根據任務複雜度路由
/model-route

# 手動切換模型
/model sonnet    # 日常任務（~60% 成本節省）
/model opus      # 深度架構推理

graph TD
    A["任務輸入"] --> B{複雜度評估}
    B -->|簡單 / Routine| C["haiku<br/>（最低成本）"]
    B -->|一般 / 開發| D["sonnet<br/>（預設 / 主力）"]
    B -->|複雜 / 架構| E["opus<br/>（深度推理）"]
    C --> F["執行任務"]
    D --> F
    E --> F

12.6 GAN 風格產生器-評估器框架

ECC v1.9.0 引入了受 GAN（Generative Adversarial Network）啟發的產生器-評估器框架（位於 examples/ 目錄），用於提升 AI 產出的品質。

12.6.1 運作原理

graph LR
    G["🔧 Generator Agent<br/>產生程式碼/方案"] --> E["🧪 Evaluator Agent<br/>評估品質"]
    E -->|不及格| G
    E -->|通過| R["✅ 最終結果"]

角色分工：

12.6.2 應用場景

• 程式碼品質：Generator 寫程式碼 → Evaluator 審查品質與安全
• 架構設計：Generator 提出方案 → Evaluator 從可擴展性/安全性評估
• 測試案例：Generator 產生測試 → Evaluator 評估覆蓋率和邊界案例
• 文件撰寫：Generator 撰寫文件 → Evaluator 檢查完整性和準確性

💡 Best Practice：GAN 風格框架適合高品質要求的場景。日常開發不需要此框架，直接使用標準 TDD 工作流即可。

12.7 Operator Status Snapshots

v2.0.0 引入 Operator Status Snapshot——在 Hermes operator story（中央叙事）中即時記錄每個 orchestrator 和 worker 的執行狀態：

{
  "snapshot_ts": "2026-06-14T09:32:17Z",
  "session_id": "ses_abc123",
  "operators": [
    {
      "id": "orch-planner",
      "state": "idle",
      "last_task": "plan:user-auth-module",
      "duration_ms": 4200
    },
    {
      "id": "orch-fanout",
      "state": "active",
      "children": ["java-reviewer", "typescript-reviewer"],
      "progress": "2/3 workers complete"
    },
    {
      "id": "orch-gate",
      "state": "pending",
      "blocked_by": "orch-fanout"
    }
  ]
}

使用方式：

# 查看即時狀態
ecc2 status --json

# 在 Dashboard 中觀察
ecc2 dashboard   # → Operators 分頁

# 在 Hermes 叙事中嵌入快照
/ecc:status      # Session 內指令

💡 Operator Status Snapshot 對於除錯長時間執行的 multi-agent pipeline 特別有用。當某個 Worker 超時或 Gate 持續 pending，可以快速定位阻塞源。

12.8 Cross-Harness Architecture

ECC v2.1.0 正式支援 13+ 種 Harness 的統一架構。所有 Harness 共用同一套 Plugin manifest（plugin.json）和 Rules 來源，但透過 Adapter Layer 轉譯為各 Harness 的原生格式：

graph TB
    subgraph "ECC Core（Harness-Agnostic）"
        Plugin["plugin.json<br/>68 agents · 286 skills · 21+ rule packs"]
        Scripts["scripts/<br/>Hook scripts · Install scripts"]
        MCP["mcp-configs/<br/>1 default + opt-in catalog"]
    end

    subgraph "Adapter Layer"
        AdClaude[".claude/<br/>Claude Code adapter"]
        AdCursor[".cursor/<br/>Cursor adapter"]
        AdCodex[".codex/<br/>Codex adapter"]
        AdCopilot[".github/<br/>Copilot adapter"]
        AdZed[".zed/<br/>Zed adapter"]
        AdKimi[".kimi-code/<br/>Kimi Code adapter"]
        AdHermes[".hermes/ · .openclaw/<br/>Hermes/OpenClaw adapter"]
        AdOther["其他 adapters<br/>(.qwen · .codebuddy · .joycode · .kiro · .trae)"]
    end

    Plugin --> AdClaude
    Plugin --> AdCursor
    Plugin --> AdCodex
    Plugin --> AdCopilot
    Plugin --> AdZed
    Plugin --> AdKimi
    Plugin --> AdHermes
    Plugin --> AdOther

Adapter 職責：

💡 DRY 原則：當你修改 scripts/hooks/pre-commit-security.sh 時，所有支援 Hook 的 Harness 都會自動獲得更新，無需在每個 adapter 目錄重複維護。

12.9 ECC Tools Pro / Enterprise（託管 GitHub App）

除了完全免費的 OSS repo 之外，ECC 官方也維運一個獨立的商業產品線——ECC Tools，以 GitHub App 形式提供託管服務。這是企業導入評估時常被忽略、但值得了解的一塊：

ECC Tools GitHub App 提供的能力（與純 OSS 版本的差異）：

• Skill Creator：從 Git History 自動產生 Skills 的託管服務
• 組織級可視化與管理介面
• 官方明確聲明：OSS 版本永久維持免費，Pro/Enterprise 是資助專案永續發展的商業模式，而非閹割 OSS 功能來逼迫升級

⚠️ 採購注意事項：ECC Tools 的付費方案與本機 ECC 配置是兩套獨立系統。若本機 Claude Code 設定被清除，不代表需要重新採購 Pro/Enterprise 授權；反之，帳務或 Marketplace 存取問題也不會透過 node scripts/ecc.js repair 解決（見 3.9、11 章 Q9）。企業採購前建議直接向官方確認目前的方案內容與定價，而非依賴任何第三方文件（包含本手冊）中的價格數字。

💡 免費額度參考：官方 README 曾標示公開 Repo 免費方案為每月 10 次分析、Pro 為每月 50 次分析。此類額度變動頻繁，請以官方定價頁為準。

12.10 v2.2 新增進階能力（Council Review、Nasiko、Living Docs）

v2.2.0 一次帶進多個仍在成熟中的進階能力。這些功能成熟度不一，本節逐一標示，避免企業誤把實驗性功能排進正式流程。

12.10.1 多模型評議審查（Multi-Model Council Review）

延續 6.2.1 /santa-loop 的對抗式思路，但把「兩個審查者」擴充為一組由不同模型組成的評議會。

• 要解決的問題：同一個模型審查自己（或同源模型）寫的程式碼時，會系統性地漏掉同一類錯誤——這是同源偏誤（correlated blind spots）。
• 做法：讓不同供應商／不同家族的模型各自獨立審查，再彙整意見。
• 企業價值：對受監理產業而言，這是「多重獨立控制」的技術實現，可作為稽核論據。
• 代價：成本隨評議會人數線性上升，且需要同時具備多家 provider 的存取權。

🏢 建議做法：只對高風險變更（認證、金流、權限、個資處理）啟用評議會審查，其餘走一般 /code-review。

12.10.2 Nasiko CLI 生命週期橋接（實驗性）

v2.2.0 加入的 Nasiko CLI lifecycle bridge，讓 ECC 能管理外部 CLI 工具的生命週期（啟動、鎖定、復原）。同版本也修復了此橋接的**鎖定復原（lock recovery）**問題與 tar 驗證強化。

⚠️ 明確標示為實驗性（experimental）。生產環境不建議依賴，評估用途可先在隔離環境試行。

12.10.3 Living Docs 治理

living-docs governance 處理的是一個非常實際的痛點：文件與程式碼失同步。ECC 的做法是把文件視為需要治理的產物，而非一次性產出——搭配 /update-docs、/update-codemaps 兩個現行指令，讓文件更新成為工作流的一環而非事後補救。

💡 這與本手冊本身面對的問題完全相同：一份講述快速迭代開源專案的技術文件，若沒有治理機制，半年內就會半數失效。這也是本手冊在 1.1 明確加上「數字時效性聲明」的原因。

12.10.4 TasteForge 多模態工作流

v2.2.0 引入 TasteForge 多模態工作流，包含 tasteforge-video skill，把影音等非文字素材納入 Agent 的處理範圍。目前定位偏向內容創作與行銷場景（可與 /marketing-campaign 搭配），對一般後端／企業系統開發流程的直接助益有限。

12.10.5 Epic 協作與 PRP 工作流

這兩組指令族在企業多人協作場景中特別實用，但過去的教學材料較少提及：

Epic 協作（GitHub 原生）：/epic-decompose（拆解大型需求）→ /epic-validate（驗證拆解合理性）→ /epic-claim（認領工作項）→ /epic-sync（同步狀態）→ /epic-review（審查）→ /epic-publish（發布）→ /epic-unblock（解除阻塞）。

graph LR
    D["/epic-decompose"] --> V["/epic-validate"]
    V --> C["/epic-claim"]
    C --> S["/epic-sync"]
    S --> R["/epic-review"]
    R --> P["/epic-publish"]
    S -.->|"遇到阻塞"| U["/epic-unblock"]
    U --> S

PRP（Product Requirement Prompt）工作流：/prp-prd（需求文件）→ /prp-plan（計畫）→ /prp-implement（實作）→ /prp-commit（提交）→ /prp-pr（開 PR）。這是一條把「需求 → PR」全程串起來的線性流程，適合規格明確、變異度低的任務。

🏢 選型建議：Epic 族適合多人平行、需要在 GitHub Issue 層級追蹤的專案；PRP 族適合單人端到端、規格已定的任務。兩者不建議混用在同一個工作項上。

12.10.6 其他 v2.2 新增項目速覽

💡 v2.2 的發行流程強化本身就值得學習：新版要求「tag 必須精確落在 origin/main 上」、「npm registry 發生錯誤時 fail-closed（而非略過）」、「在 Linux／macOS／Windows 三平台測試已打包的 artifact」、「先發到 staging dist-tag 驗證後才推廣為 latest」。這是一組相當標準的供應鏈防護實務，值得任何要發布 npm 套件的團隊借鏡。

第十三章：企業導入評估與風險考量

本章是本手冊與多數 ECC 相關文件最大的差異所在——多數官方或社群文件聚焦在「怎麼用」，本章聚焦在「該不該用、用多少、用什麼替代方案」，這是技術白皮書對企業決策者應盡的責任。

13.1 採用效益與整體擁有成本

效益面：ECC 官方與獨立評測都指出，其核心價值是標準化——Claude Code 原生提供 Agents、Hooks、Skills 等「積木」，但把積木組裝成一套跨語言、跨團隊可複用的工作流程，仍需要投入設計與維護成本；ECC 把這塊「組裝工作」開源化、社群化。對於尚未建立內部 Claude Code 使用規範的團隊，直接採用可以省下數週到數月的自建時間。

成本面（TCO，Total Cost of Ownership）需考慮的項目：

13.2 已知限制與社群爭議

誠實呈現社群的批評聲音，是企業技術白皮書應盡的責任。以下整理自獨立第三方報導與評論（見附錄 H 來源清單）：

「過度工程化」批評：獨立評論（如 Medium 上針對 ECC 的分析文章）指出，ECC 的多語言 Rules 架構、內建編排引擎（Orchestrator 家族）等，超出多數團隊實際需要的複雜度，常見的反對意見是「大多數人只需要一份寫得好的 CLAUDE.md，不需要一整套生態系」。這個批評對「小團隊、單一語言棧」的專案尤其成立。

治理模式與維護者風險：ECC 目前由單一核心維護者（Affaan Mustafa）主導開發節奏與架構決策方向，雖已有 331 位貢獻者參與，且社群規模（約 24 萬 Star、Discord 成員數）已達到「即使原作者停止投入，社群也可能接手維護」的量級，但企業導入前仍應評估：

• 若專案更新停滯，內部是否有能力自行維護 Fork？
• 關鍵安全更新（如 AgentShield 規則庫）的回應速度是否符合企業 SLA 要求？
• 目前開放中的 Issue 約 52 件、待審 PR 約 125 件（2026-08-28）。PR 積壓高於 Issue 這件事本身是中性訊號（代表社群踴躍欲試），但也反映審查瓶頸集中於少數人的現實。

治理面的正向訊號：官方 README 中的平台支援矩陣（見 3.11）主動標示哪些 Harness 只是「檔案放對位置」而非功能對等，並直接列出已知缺陷的 Issue 編號（#2419、#2489、#2617、#2626、#2674）。這種「不自我美化」的文件態度在開源專案中並不常見，對企業評估而言是提高可信度的正向因素。

安全回應管道：ECC 提供私密漏洞回報流程（見 SECURITY.md），並備有供應鏈事件應變程序。企業資安團隊在導入前應先確認此流程是否滿足內部的漏洞揭露 SLA 要求。

「多不代表好」的自我修正案例：值得注意的是，ECC 官方自己也在 2026 年 6 月的 MCP 連接器審查中，主動從「14 個預設 MCP」收斂為「1 個」（見 2.7），這說明專案本身具備自我糾錯能力，但也反過來印證了外部批評的合理性——確實存在「為了功能豐富度而過度擴張」的傾向，需要靠事後治理修正。

版本波動與文件時效性：本手冊撰寫過程中即發現多個實例：

• 官方 README 出現過「建議先用 npx 導引安裝」又於同一版本說明中撤回該建議（“published too soon…that recommendation is withdrawn until release 2.2”）的情況；
• CHANGELOG 已標 2.2.0，但 GitHub Releases 頁面的 Latest 可能仍顯示 v2.1.0（因 npm 推廣把關發行建立）；
• 同一份 README 內部數字不一致：頁首寫 286 skills、“What’s Inside” 區塊寫 284 skills。

這顯示活躍社群專案的文件與實際發行節奏可能不同步。企業導入時應以官方 Release Tag 與 CHANGELOG 為準，並以實際執行 ecc doctor / ecc list-installed 的輸出作為稽核證據，而非任何時間點的 README 快照（包含本手冊）。

13.3 與 Anthropic 官方最佳實踐的定位關係

企業決策者常見的錯誤框架是「ECC vs. Claude Code」，但正確的框架應該是「Claude Code 原生能力 + 官方最佳實踐（見 10.6、2.8）」作為必要基礎，ECC 作為選配的加速層：

graph TB
    A["Anthropic 官方平台<br/>Plan Mode / Hooks / Skills / Subagents"] --> B["Anthropic 官方最佳實踐<br/>Explore-Plan-Code-Commit / 可驗證檢查 / 對抗式審查"]
    B --> C{"團隊是否需要<br/>預先組裝的框架？"}
    C -->|需要標準化與安全掃描| D["採用 ECC（全部或選配元件）"]
    C -->|團隊小、需求單純| E["維持精簡 CLAUDE.md + 官方原生機制即可"]

💡 一句話判準：如果團隊還沒有讀過 Anthropic 官方 Best Practices 文件、還沒有建立自己的 CLAUDE.md 慣例，建議先從官方最佳實踐開始，而不是直接跳到安裝一整套 68 Agents／286 Skills 的框架——否則團隊會搞不清楚問題出在「用法不對」還是「工具不對」。

13.4 導入決策框架

13.5 替代方案比較

附錄

A. 常用指令 Cheat Sheet

⚠️ v2.2 重要變更：/tdd、/e2e、/verify、/eval、/orchestrate 等 12 個指令已退役，改以 Skill 形式提供。下表已移除退役指令；完整對照請見附錄 I。

斜線指令（Slash Commands）

Claude Code 原生指令（非 ECC 提供，卸除 ECC 後仍可用）

常用 Skill（以自然語言觸發，非斜線指令）

CLI 與診斷

B. Skills 範例模板

---
name: my-custom-skill
description: A brief description of what this skill does
tags: [java, spring-boot, custom]
---

# My Custom Skill

## Purpose
Explain what this skill accomplishes.

## Prerequisites
- List requirements

## Steps

### Step 1: Analysis
Describe what to analyze first.

### Step 2: Implementation
Provide implementation patterns.

### Step 3: Verification
Explain how to verify correctness.

## Examples

```java
// Provide concrete code examples
```

## Best Practices
- List best practices

## Common Pitfalls
- List common mistakes to avoid

C. Agent 設計模板

---
name: my-custom-agent
description: Brief description of this agent's role
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

You are a [role description].

## Responsibilities
1. First responsibility
2. Second responsibility
3. Third responsibility

## Constraints
- What you should NOT do
- Scope limitations

## Output Format
Describe expected output format.

## Decision Framework
1. When to escalate to human
2. When to delegate to other agents
3. Quality criteria for your work

D. 跨工具功能對照表

完整的支援分級（穩定／Beta／實驗性）與作業系統相容性請見 3.11。本表只列檔案層的具體差異。

⚠️ 不要把「有適配器」等同於「功能對等」。部分 Harness 的適配器僅將檔案放到正確位置，實際能不能被讀取、能不能執行 hooks，取決於該工具本身的能力（見 3.11.1）。

E. 檢查清單（Checklist）

🔰 新進成員快速上手

• 安裝 Claude Code CLI（建議使用最新版，以取得 Plan Mode / Auto Mode / /goal 等原生功能）
• 安裝 Node.js ≥ 18（Windows 原生環境請避開 Node 22.12–22.16 與 24.0–24.1，見 2.9.5）
• 確認安裝路徑：導引式（npx ecc-universal setup）或 Plugin 安裝（見 11 章 Q14）
• Clone ECC repo（若採原始碼安裝）：git clone https://github.com/affaan-m/ECC.git
• 安裝 ECC Plugin：/plugin marketplace add https://github.com/affaan-m/ECC + /plugin install ecc@ecc
• 手動安裝 Rules（僅安裝需要的語言包，見 3.2）：mkdir -p ~/.claude/rules/ecc && cp -R rules/common rules/typescript ~/.claude/rules/ecc/
• 設定環境變數：MAX_THINKING_TOKENS=10000、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
• 執行 ecc doctor 確認安裝健康度
• 瀏覽 Dashboard：npm run dashboard
• 試運行 /plan "Hello World feature"
• 試運行 tdd-workflow Skill（以自然語言觸發，/tdd 已退役）
• 試運行 /code-review

✅ 日常開發檢查

• 開發前執行 /plan 規劃
• 使用 TDD 流程（tdd-workflow Skill）
• 完成後執行 /code-review（高風險變更再加 /santa-loop）
• 部署前執行 /security-scan
• 覆蓋率 ≥ 80%（/test-coverage）
• 不相關任務間使用 /clear
• 邏輯斷點使用 /compact
• 定期檢查 /cost

🔒 安全檢查

程式碼層級

• AgentShield 掃描通過
• 無機密外洩（API Key、Token）
• OWASP Top 10 審查
• 依賴 CVE 掃描
• .env 檔案不在版控中

代理層級（導入前的最低門檻，完整說明見 7.12）

• Claude Code 版本 ≥ 2.0.65（涵蓋 CVE-2025-59536 與 CVE-2026-21852）
• 代理使用專用低權限身分，非開發者個人憑證
• 代理於容器或沙箱中執行，且出口網路採白名單
• permissions.deny 基線已套用並納入版控
• 所有 Skill／MCP／Hook 變更走 PR 與雙人審查
• 外部內容進入上下文前已完成消毒（7.9）
• 具備結構化稽核日誌，可回溯工具呼叫與核准決策（8.4）
• 無人值守迴圈具備斷路器與逾時終止（8.5）
• 記憶庫不含憑證，且定期審閱差異（7.10）
• 已定義事件回應流程（憑證輪替、記憶重置、影響範圍評估）

🚀 部署前檢查

• 所有測試通過
• Security Scan Exit Code ≠ 2
• E2E 測試通過（e2e-testing Skill）
• 覆蓋率 ≥ 80%
• 文件已更新（/update-docs、/update-codemaps）
• Code Review 完成

🔄 v2.1 → v2.2 升級檢查

完整清單見 9.4。最關鍵的五項：

• 確認 npm 實際發行版本：npm view ecc-universal version
• 盤點內部教材與 CI 腳本中的 12 個退役指令（見附錄 I）
• 確認 MCP 預設集合變更不影響現行流程（見 2.7）
• OpenCode 使用者：確認家目錄已從 ~/.opencode 遷至 ~/.config/opencode
• 升級後執行 ecc doctor 並保留輸出作為稽核證據

F. 生態系工具與社群資源

F.1 官方生態系工具

F.2 ECC Discord 社群

ECC v2.0.0 推出官方 Discord 社群（https://discord.gg/36yGMHGFbR），提供：

• #general — 一般討論與公告
• #help — 安裝與使用疑難排解
• #showcase — 展示你的 ECC 專案
• #skills-exchange — 社群分享自訂 Skills
• #contributors — 貢獻者協作頻道

F.3 社群專案

💡 用 ECC 建構了什麼？歡迎開 PR 加入此清單。

F.4 官方與社群贊助

ECC v2.1.0 起正式公開多家官方贊助夥伴，反映專案商業化與永續經營的路徑：

• 個人贊助：GitHub Sponsors ∣ Sponsor Tiers ∣ Sponsorship Program
• 貢獻：詳見 CONTRIBUTING.md
  • 語言專用 Skills（Rust、C#、Kotlin、Java）
  • 框架配置（Rails、FastAPI）
  • DevOps Agents（Kubernetes、Terraform、AWS、Docker）
  • 測試策略（不同框架、Visual Regression）
  • 領域知識（ML、Data Engineering、Mobile）
• 行為準則：CODE_OF_CONDUCT.md
• 安全：SECURITY.md

F.5 官方指南連結

💡 三份官方指南目前已收錄於 repo 根目錄成為正式維護的 Markdown 文件，不再只是社群媒體貼文快照——這也是本次改版的重點修正之一。

🏢 企業資安審查建議順序：SECURITY.md → the-security-guide.md → docs/security/supply-chain-incident-response.md → docs/MCP-CONNECTOR-POLICY.md。這四份文件共同構成 ECC 的安全治理論述，也是導入審查時最常被要求提供的依據。

F.6 多語言文件

ECC 提供多種語言的 README／文件翻譯（截至 2026-08，已達 13 種語言）：

G. 版本變更摘要

📊 v2.1.0 → v2.2.0 變更規模：108 個 commit、530 個檔案變更、+40,299 ／ −4,679 行。這是一個小版號但實質大幅度的版本，企業升級前務必完成 9.4 的檢查清單。

⚠️ 上表數字取自各版本官方 Release Notes 與 CHANGELOG，部分早期版本未在公告中揭露 Agent/Skill/Command 精確數字（以「—」標示），不代表當時不存在該元件。另需注意：官方 README 自身就存在 286 與 284 skills 的不一致（見 1.1），且 GitHub Releases 頁面可能因 npm 推廣把關而尚未建立 v2.2.0 的 Release 條目。

完整記錄：CHANGELOG.md ∣ Releases

H. 資料來源與查證方法

本手冊改版遵循「吸收後重新整理，不逐字轉載」原則撰寫，主要查證管道如下：

一手來源（官方）

• affaan-m/ECC GitHub Repository — 原始碼、目錄結構、README.md、CHANGELOG.md
• ECC README.md（原始檔） — 元件計數、平台支援矩陣、安裝路徑、已知問題 Issue 編號
• ECC CHANGELOG.md（原始檔） — v2.2.0 逐項 Added / Changed / Fixed
• ECC 繁體中文 README — 中文術語對照
• GitHub REST API（repos/affaan-m/ECC、/releases、/tags、/contents/*、/contributors）— 即時統計數字（Stars、Forks、Contributors、開放 Issue／PR 數）與元件目錄計數
• 官方 Releases 頁面與逐版 Release Notes（v1.2.0 ～ v2.2.0）
• 官方文件：docs/MCP-CONNECTOR-POLICY.md、docs/COMMANDS-QUICK-REF.md、the-shortform-guide.md、the-longform-guide.md、the-security-guide.md、SECURITY.md、docs/security/supply-chain-incident-response.md
• npm registry：ecc-universal、ecc-agentshield 的實際發行版本
• ecc.tools 官方網站與 Pricing 頁面

一手來源（Anthropic 官方）

• Anthropic 官方 Best Practices for Claude Code 文件（Plan Mode、Hooks、Skills、Subagents、Checkpoints、Auto Mode、非互動模式等原生功能說明）

二手來源（獨立第三方，用於第十三章風險考量與社群觀點交叉驗證）

• Medium 獨立評論文章〈Everything Claude Code: Inside the 82K-Star Agent Harness That’s Dividing the Developer Community〉
• 其他公開技術部落格對 ECC 的介紹與評測文章（DataCamp、Augment Code 等；用於交叉核對 Star 數成長趨勢與功能描述，非直接引用其表述方式）

安全威脅情資來源（用於 7.6～7.12）

⚠️ 引用原則：上表事件均為第三方公開揭露，本手冊僅摘要其風險含意與緩解措施，不轉載攻擊細節或可利用程式碼。實際修補狀態請以各廠商官方公告為準。

查證方法論

1. 以原始檔優先：所有 GitHub 文件均取 raw.githubusercontent.com 版本，避免網頁渲染層的內容截斷。
2. 交叉比對：README 敘述、CHANGELOG 條目、實際目錄結構三者互相驗證；發現不一致時（如 286 vs. 284 skills）在本文中如實標示，而非擇一採用。
3. 標示成熟度：凡官方標為 experimental / beta 者，本文一律沿用同等標示，不代為升級。
4. 保留 Issue 編號：所有已知缺陷均附上原始 Issue 編號，讀者可自行追蹤修復狀態。

查證時間戳記：2026-08-31（本次 v3.1 改版當日；前一次全面查證為 2026-08-28）。由於 ECC 更新頻率極高，任何具體數字（版本號、元件計數、社群統計）都應被視為「該時間點的快照」，正式導入評估請務必重新查證最新狀態，而非直接沿用本文件數字。

本次改版（v3.1）與前版（v3.0，2026-08-28）的主要差異：

• 上游版本覆核：確認 CHANGELOG.md 的 [Unreleased] 區塊為空，v2.2.0 仍是最新已標記版本，本手冊對應版本維持不變
• 統計數字校正：以 GitHub REST API 實測更新 Stars／Forks／Watchers；並釐清 open_issues_count 為「Issue + PR 合計」的口徑，修正前版分寫的誤導
• 新增 7.6～7.12：威脅情資（Claude Code CVE、致命三要素、供應鏈風險）、沙箱化四層模型、最小代理權、輸入消毒、記憶毒化治理、MCP 安全、企業最低門檻檢查表
• 新增 8.4～8.6：Agent 可觀測性（日誌欄位規範、OpenTelemetry 匯出、異常基線）、無人值守迴圈斷路器（程序群組終止、心跳失效保護）、成本治理與 KPI
• 新增 8.1 子節：CI 中的非互動模式與 AgentShield 建置閘門（含 --opus 三代理對抗式審查與 exit code 2）
• 新增 4.6～4.8：Rules／Skills 分層治理、CLAUDE.md 分層策略與失效模式、團隊角色與責任邊界
• 新增 10.4.1～10.4.3：依任務型態的模型路由表、上下文佔用四大來源、進階環境變數調校
• 新增 10.5.4～10.5.6：Orchestrator 五階段流水線、迭代式檢索、雙實例啟動法
• 新增 10.6.6～10.6.7：驗證機制四個層級、需求釐清與 Session 衛生
• 新增 6.6 子節：Pass@k 與 Pass^k 的數值對照與選用時機
• 附錄更新：附錄 A 新增「Claude Code 原生指令」表；附錄 E 新增代理層級安全最低門檻；附錄 H 新增安全威脅情資來源表

前版改版（v3.0）與 v2.0（2026-08-21）的主要差異：

• 全文對齊 ECC v2.2.0（2026-08-25），新增 v2.2 導引式安裝、Unified Memory Vault、多模型評議審查、Nasiko、living-docs、TasteForge 等內容
• 新增 2.9（Unified Memory Vault）、3.2.0（Guided Setup）、3.11（平台支援分級與跨 OS 相容性）、6.2.1（/santa-loop）、9.4（升級檢查表）、12.10（v2.2 新增進階能力）
• 全面標示 12 個退役指令並改寫為 Skill 呼叫方式，新增附錄 I 遷移對照表
• 新增附錄 J 環境變數總表
• 修正社群統計數字（331 位貢獻者，取代舊的 299+）
• 新增「數字時效性聲明」與 npm 發行落差警示
• 第十三章補入治理正向訊號、PR 積壓觀察、安全回應管道評估項

I. 指令退役與遷移對照表

v2.2 起，下列 12 個斜線指令已退役，其功能改由同名 Skill 提供。Skill 以自然語言觸發（例如「使用 tdd-workflow skill 完成這個功能」），或由 Agent 依情境自動載入。

遷移注意事項

• 退役指令的原始定義檔仍保留在 repo 的 legacy-command-shims/commands/ 目錄，但預設安裝不會包含。若組織有強烈的相容性需求，可自行複製，但不建議長期依賴。
• 團隊內部教材、Onboarding 文件、CI 腳本、以及任何寫死指令字串的自動化流程，都需要一併盤點更新（見 9.4）。
• 為什麼要改？Skill 可以被 Agent 依情境自動載入，而斜線指令必須由人明確輸入。改為 Skill 後，同一份工作流既能被人主動呼叫，也能在 Agent 判斷需要時自動生效——這是設計上的實質改善，而非單純改名。

⚠️ /verify 的名稱衝突：上表退役的是 ECC 提供的 /verify shim。Claude Code 平台本身另有原生 /verify 指令（見附錄 A 的原生指令表與 10.6.6），兩者名稱相同但來源不同。卸除 ECC 後仍可使用原生版本；撰寫團隊教材時建議明確標註「原生」或「ECC」以免混淆。

💡 快速自我檢查：在專案根目錄執行 grep -rn "/tdd\|/e2e\|/verify\|/eval\|/orchestrate" --include="*.md" --include="*.yml" --include="*.yaml" .，即可找出待更新的殘留引用。

J. 環境變數總表

本手冊各章節提及的環境變數彙整如下，方便一次設定與稽核。

ECC 行為控制

Claude Code / 模型路由

Itô 自架運算整合

🔐 機密管理提醒：ANTHROPIC_AUTH_TOKEN、ITO_API_KEY 屬於機密資訊，不得寫入 CLAUDE.md、AGENTS.md、Memory Vault 或任何進版控的檔案。請使用作業系統的機密管理機制（如 macOS Keychain、Windows Credential Manager）或企業級 Secret Manager，並確認 .env 已列入 .gitignore（見附錄 E 安全檢查）。

文件維護：本手冊基於 ECC v2.2.0（2026-08-25 CHANGELOG 發行日）撰寫，並查核至 2026-08-28 的 main 分支現況。ECC 更新頻繁（近乎每週發版），建議定期查閱 官方 CHANGELOG 和 Releases，切勿將本文件中的任何數字（版本號、元件數量、統計數據）視為永久不變的事實。

授權：ECC 使用 MIT License，可自由使用、修改和商用；OSS 版本永久免費。ECC Tools（GitHub App）另提供 Pro / Enterprise 選配託管服務，詳見附錄 F。

社群：約 243,900 Stars、331 位貢獻者（2026-08-28 查證）。歡迎貢獻 Skills、Agents、Hooks 或 Rules。詳見 CONTRIBUTING.md。加入 ECC Discord 社群討論。

追蹤作者：@affaanmustafa（X / Twitter）

本手冊查證方法：內容綜合官方 GitHub repo（原始碼、CHANGELOG、Releases、docs/）、GitHub API 即時統計、Anthropic 官方文件與第三方獨立評論後重新整理撰寫，非逐字轉載官方文件。詳細來源清單見附錄 H。