Everything Claude Code (ECC) 教學手冊

版本：v2.0.0（2026 年 6 月）
適用對象：軟體工程師（初階～資深）、架構師、DevOps / SRE、AI 工程師
授權：MIT License
官方 GitHub：https://github.com/affaan-m/ECC
官方網站：https://ecc.tools
GitHub Marketplace：https://github.com/marketplace/ecc-tools
Discord 社群：https://discord.gg/36yGMHGFbR
社群統計：224K+ Stars ∣ 34.3K+ Forks ∣ 289+ Contributors ∣ 12+ 語言生態系
官方指南：
— Shorthand Guide（入門首選）
— Longform Guide（進階深入）
— Security Guide（安全防護）

📑 目錄

• 第一章：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 配置
• 第三章：安裝與環境建置
  • 3.1 前置需求
  • 3.2 Plugin 安裝（推薦）
  • 3.3 手動安裝
  • 3.4 Windows PowerShell 安裝
  • 3.5 跨 Harness 整合（Cursor / Codex / Copilot / Zed / OpenCode）
  • 3.6 環境變數設定
  • 3.7 Dashboard GUI
  • 3.8 套件管理器偵測
  • 3.9 故障復原與診斷
• 第四章：企業級 Web 系統架構設計（搭配 ECC）
  • 4.1 企業系統架構背景
  • 4.2 ECC Agent 分工架構
  • 4.3 Orchestrator 家族（v2.0.0）
  • 4.4 系統架構圖
  • 4.5 Agent 協作流程
• 第五章：開發流程（AI 驅動）
  • 5.1 AI 驅動開發總覽
  • 5.2 /plan — 需求規劃
  • 5.3 /design — 架構設計
  • 5.4 /implement（TDD）— 實作
  • 5.5 /test — 測試
  • 5.6 /code-review — 程式碼審查
  • 5.7 /deploy — 部署
  • 5.8 /verify — 驗證迴圈
• 第六章：測試與品質控管
  • 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 安全閘門
• 第八章：部署與維運（DevOps）
  • 8.1 CI/CD 整合
  • 8.2 監控與日誌
  • 8.3 AI Agent 監控
• 第九章：系統維護與升級
  • 9.1 ECC 版本升級策略
  • 9.2 Skills / Agents 管理
  • 9.3 相容性與故障排除
• 第十章：最佳實踐（Best Practices）
  • 10.1 避免上下文污染
  • 10.2 Agent 設計原則
  • 10.3 Skill 設計模式
  • 10.4 Token 最佳化
  • 10.5 平行化策略
• 第十一章：常見問題與排錯
• 第十二章：進階應用
  • 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
• 附錄
  • A. 常用指令 Cheat Sheet
  • B. Skills 範例模板
  • C. Agent 設計模板
  • D. 跨工具功能對照表
  • E. 檢查清單（Checklist）
  • F. 生態系工具與社群資源
  • G. 版本變更摘要

第一章：Everything Claude Code 架構總覽

1.1 ECC 是什麼

Everything Claude Code（ECC）是一個開源的 Agent Harness Operating System（代理控制操作系統），由 Anthropic 黑客松冠軍 Affaan Mustafa 建立。

ECC 不只是一組配置檔，而是一套完整的系統，包含：

核心定位：

• ✅ 解決 AI 編碼代理在長對話中的「上下文污染」與「遺忘決策」問題
• ✅ 提供持續學習與記憶持久化機制
• ✅ 跨平台支援：Claude Code、Codex、Cursor、OpenCode、Gemini、Zed、GitHub Copilot、CodeBuddy、Kiro、Trae、Qwen
• ✅ 224K+ Stars、34.3K+ Forks、289+ Contributors
• ✅ 在 Anthropic × Forum Ventures Hackathon 中獲得冠軍
• ✅ v2.0.0 正式畢業為 Agent Harness Operating System

1.2 與傳統 Prompt Engineering 差異

1.3 Context Engineering 與 Harness Engineering

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

Context Engineering 關注如何組織和管理提供給 LLM 的上下文資訊。Harness Engineering 則是更高層級的系統工程，涵蓋：

1. Agent 編排：多代理協作、任務委派
2. 記憶架構：短期記憶（Session）、長期記憶（Instincts）
3. 品質閘門：自動測試、Code Review、安全掃描
4. 效能調校：Token 最佳化、模型路由

1.4 ECC 整體架構圖

graph TB
    subgraph "ECC Core System"
        direction TB
        Plugin["🔌 Plugin System<br/>.claude-plugin/"]
        Agents["🤖 Agents (67)<br/>Specialized Subagents"]
        Skills["⚡ Skills (277)<br/>Workflow Definitions"]
        Commands["📋 Commands (92)<br/>Legacy Slash Shims"]
        Hooks["🪝 Hooks (8 events)<br/>Auto-Triggered Actions"]
        Rules["📏 Rules (34)<br/>Always-Follow Guidelines"]
        MCP["🔗 MCP Configs (14)<br/>External Service Integration"]
    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"]
        ECC2["🚀 ECC 2.0<br/>Rust Control Plane"]
    end

    subgraph "Supported Harnesses"
        ClaudeCode["Claude Code"]
        Cursor["Cursor IDE"]
        Codex["OpenAI Codex"]
        OpenCode["OpenCode"]
        Gemini["Gemini"]
        Zed["Zed"]
        Copilot["GitHub Copilot"]
    end

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

    AgentShield --> Plugin
    SkillCreator --> Skills
    ContinuousLearning --> Skills
    ECC2 --> Plugin

    ClaudeCode --> Plugin
    Cursor --> Plugin
    Codex --> Plugin
    OpenCode --> Plugin
    Gemini --> Plugin
    Zed --> Plugin
    Copilot --> Plugin

1.5 Agent / Skills / Hooks / Commands 關係圖

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

    subgraph "Entry Points"
        SlashCmd["/plan, /tdd, /code-review<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 月起持續快速迭代，以下為主要里程碑：

💡 完整變更記錄請參閱 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 分類

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
└── ...（共 277 個）

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）

2.3.2 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 是「永遠遵循」的開發準則，按語言組織：

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/          # TypeScript/JavaScript
├── python/              # Python
├── golang/              # Go
├── swift/               # Swift
└── php/                 # PHP

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 提供 14 個預配置的 MCP（Model Context Protocol）Server 整合，擴展 Agent 與外部服務的互動能力。

2.7.1 預配置 MCP Servers

2.7.2 MCP 配置管理

# MCP 配置檔位置
mcp-configs/mcp-servers.json

# 停用不需要的 MCP（避免 Token 浪費）
# 注意：ECC_DISABLED_MCPS 是 install/sync filter，非 live Claude Code toggle
export ECC_DISABLED_MCPS="supabase,railway,vercel"

# 使用 /mcp 命令在 Claude Code 中即時停用
# Claude Code 會將選擇持久化到 ~/.claude.json

⚠️ MCP Connector Policy（v2.0.0）：ECC 現在僅預設啟用 1 個連接器（chrome-devtools），其餘全部為 opt-in catalog entry。詳見 MCP-CONNECTOR-POLICY.md。每個 MCP 的工具描述都會消耗 Token，啟用過多 MCP 會將 200K Token 窗口壓縮到約 70K。建議每專案啟用 < 10 MCPs、< 80 tools。

第三章：安裝與環境建置

3.1 前置需求

3.2 Plugin 安裝（推薦）

⚠️ 只選一種安裝路徑：大多數使用者應使用 Plugin 安裝，然後只手動複製需要的 Rules 資料夾。不要 疊加多種安裝方式（例如先 /plugin install 再跑 install.sh --profile full），這會造成重複元件和衝突行為。

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，必須手動安裝。

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

# 安裝依賴
npm install

# macOS/Linux — 完整安裝
./install.sh --profile full

# 或只安裝特定語言
./install.sh typescript python golang

Step 3：開始使用

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

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

ECC Consult 顧問指令

不確定該用哪些 Skills / Agents？使用 npx ecc consult 取得建議：

# 詢問特定主題的建議安裝內容
npx ecc consult "Spring Boot microservice with Kafka" --target claude

# 快速比較不同 Harness 的能力
npx ecc consult "compare cursor vs codex for TDD workflow"

Reset / Uninstall ECC

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

# 正式解除安裝
node scripts/uninstall.js

# 或使用 ecc CLI
node scripts/ecc.js uninstall

⚠️ 解除安裝只移除 ECC 管理的檔案（rules, hooks, commands, agents, skills）。你的 ~/.claude/settings.json 中的個人設定不會被影響。

3.3 手動安裝

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

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

# 複製 Rules（common + 語言特定）
mkdir -p ~/.claude/rules
cp -r ECC/rules/common ~/.claude/rules/
cp -r ECC/rules/typescript ~/.claude/rules/  # 依你的技術棧選擇
cp -r ECC/rules/python ~/.claude/rules/

# 複製 Skills（主要工作流程介面）
cp -r ECC/.agents/skills/* ~/.claude/skills/
cp -r ECC/skills/search-first ~/.claude/skills/

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

# 選擇性：保留 Legacy 指令相容性
mkdir -p ~/.claude/commands
cp ECC/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 整合（Cursor / Codex / Copilot / Zed / OpenCode）

Cursor IDE

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

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

Cursor 支援項目：

OpenAI Codex

# 在 ECC repo 根目錄執行 Codex CLI
codex

# 或自動同步 ECC 資產到 ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh

OpenCode

# 安裝 OpenCode
npm install -g opencode

# 在 ECC repo 根目錄執行
cd ECC
opencode

# 或以 npm package 安裝
npm install ecc-universal

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，位於 .agent/ 目錄中。詳見 Antigravity Guide。

其他 IDE 支援

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 提供內建的診斷與修復工具：

# 步驟 1：檢查已安裝的項目
ecc list-installed

# 步驟 2：診斷問題
ecc doctor

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

常見復原情境：

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

第四章：企業級 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.0.0 將原本單一 planner 和 loop-operator 拆分為 Orchestrator 家族（orch-*），提供企業級的多 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["🤖 ECC /tdd<br/>TDD 開發"]
        ECC_Review["🤖 ECC /code-review<br/>品質審查"]
        ECC_Security["🤖 ECC /security-scan<br/>安全掃描"]
        ECC_E2E["🤖 ECC /e2e<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 平行執行前後端任務，可顯著提升開發效率。

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

5.1 AI 驅動開發總覽

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

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 /design — 架構設計

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

Agent 行為：architect agent 產出：

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

5.4 /implement（TDD）— 實作

/tdd

Agent 行為（tdd-guide）：

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 /test — 測試

/e2e      # 產生 Playwright E2E 測試

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 /deploy — 部署

# 使用 deployment-patterns skill
/security-scan    # 部署前安全掃描
/e2e              # 關鍵用戶流測試
/test-coverage    # 驗證 80%+ 覆蓋率

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

5.8 /verify — 驗證迴圈

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

# 儲存當前驗證狀態的 Checkpoint
/checkpoint

# 執行完整驗證迴圈
/verify

# 根據自定義標準評估
/eval

驗證迴圈流程：

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 保存狀態後執行一次性驗證。

第六章：測試與品質控管

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 是否覆蓋

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

評估框架核心概念：

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 呼叫中亦可辨識

7.5.2 GateGuard 與 AgentShield 的差異

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

第八章：部署與維運（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

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

第九章：系統維護與升級

9.1 ECC 版本升級策略

# 檢查當前版本
cat VERSION  # 或查看 CHANGELOG.md

# 更新到最新版
cd ECC
git pull origin main
npm install

# 重新執行安裝
./install.sh --profile full  # macOS/Linux
.\install.ps1 --profile full  # Windows

# 使用選擇性安裝（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 相容性與故障排除

第十章：最佳實踐（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 成本警告：Agent Teams 會產生多個獨立的上下文窗口，每個 teammate 獨立消耗 Token。只在平行任務有明確價值時使用（如多模組工作、平行審查）。簡單順序任務用 subagent 更省。

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。

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

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：指令失效

檢查清單：

1. claude --version 確認 ≥ v2.1.0
2. /plugin list ecc@ecc 確認 Plugin 已安裝
3. 確認 rules 已手動安裝
4. 確認 hooks 未重複宣告
5. multi-* 指令需額外安裝 npx ccg-workflow

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 v2.0.0 同時支援 11 種 Harness：

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. ecc list-installed — 檢查已安裝項目
2. ecc doctor — 診斷問題
3. ecc repair — 自動修復

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

第十二章：進階應用

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 工具整合

跨工具功能對照

關鍵架構決策：

• AGENTS.md 是根目錄的通用跨工具檔案（四個工具都讀取）
• DRY adapter 模式讓 Cursor 重用 Claude Code 的 hook scripts
• SKILL.md 格式（YAML frontmatter）跨 Claude Code、Codex、OpenCode

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.0.0 正式支援 11 種 Harness 的統一架構。所有 Harness 共用同一套 Plugin manifest（plugin.json）和 Rules 來源，但透過 Adapter Layer 轉譯為各 Harness 的原生格式：

graph TB
    subgraph "ECC Core（Harness-Agnostic）"
        Plugin["plugin.json<br/>67 agents · 277 skills · 34 rules"]
        Scripts["scripts/<br/>Hook scripts · Install scripts"]
        MCP["mcp-configs/<br/>14 MCP server 定義"]
    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"]
        AdOther["其他 adapters"]
    end

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

Adapter 職責：

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

附錄

A. 常用指令 Cheat Sheet

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. 跨工具功能對照表

E. 檢查清單（Checklist）

🔰 新進成員快速上手

• 安裝 Claude Code CLI ≥ v2.1.0
• 安裝 Node.js ≥ 18
• Clone ECC repo：git clone https://github.com/affaan-m/ECC.git
• 安裝依賴：npm install
• 安裝 ECC Plugin：/plugin marketplace add + /plugin install ecc@ecc
• 手動安裝 Rules：./install.sh --profile full（或 .\install.ps1 --profile full）
• 設定環境變數：MAX_THINKING_TOKENS=10000、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
• 瀏覽 Dashboard：npm run dashboard
• 試運行 /ecc:plan "Hello World feature"
• 試運行 /tdd
• 試運行 /code-review

✅ 日常開發檢查

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

🔒 安全檢查

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

🚀 部署前檢查

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

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 贊助與貢獻

• 贊助：GitHub Sponsors ∣ Sponsor Tiers
• 貢獻：詳見 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 官方指南連結

F.6 多語言文件

ECC 提供多種語言的 README 翻譯：

G. 版本變更摘要

完整記錄：CHANGELOG.md ∣ Releases

文件維護：本手冊基於 ECC v2.0.0（2026 年 6 月）撰寫。ECC 更新頻繁，建議定期查閱 官方 CHANGELOG 和 Releases。

授權：ECC 使用 MIT License，可自由使用、修改和商用。

社群：224K+ Stars、289+ Contributors。歡迎貢獻 Skills、Agents、Hooks 或 Rules。詳見 CONTRIBUTING.md。加入 ECC Discord 社群討論。

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