ECC 完整教學 — Agent Harness Performance Optimization System

第 1 章：專案定位

ECC 是什麼？

ECC 是一套開源的 agent harness performance optimization system (代理人工具鏈效能最佳化系統)，專為 AI coding agents 設計。它不只是一堆設定檔——而是一個涵蓋 skills (技能)、agents (代理)、hooks (鉤子)、rules (規則)、memory (記憶)、learning (學習)、security (安全) 的完整生態系統。

為什麼需要 ECC？

當你使用 Claude Code、Codex、Cursor 等 AI agent 工具時，會面對幾個核心挑戰：

Context window (上下文視窗) 管理：token 預算有限，如何讓 agent 在有限 context 中做最好的事？
工作流一致性：每次新 session 都從零開始，如何保持 memory persistence (記憶持久化)？
品質保證：agent 產出的程式碼品質如何用 hook 和 rule 自動把關？
安全防護：agent 可能執行危險指令，如何做 sandboxing 與 injection 防護？
跨工具鏈一致性：同一套 workflow 能否在 Claude Code、Codex、Cursor、OpenCode 間共用？

ECC 用一個 mono-repo 解決了以上所有問題，而且是 MIT 授權、完全免費。

關鍵數據

指標	數值
GitHub Stars	206K+
Forks	31K+
Agents	63 個
Skills	249 個
Legacy Command Shims	79 個
語言生態系	12+
測試	997+
授權	MIT
版本	v2.0.0-rc.1

第 2 章：安裝指南

前置需求

Claude Code CLI v2.1.0+（或其他支援的 harness）
Node.js（用於 hook scripts 與安裝工具）
Git

1# 確認 Claude Code 版本
2claude --version

方法 A：Plugin 安裝（推薦）

1# 1. 新增 marketplace
2/plugin marketplace add https://github.com/affaan-m/ECC
3
4# 2. 安裝 plugin
5/plugin install ecc@ecc

安裝完成後，Plugin 會自動載入 skills、commands、hooks。

方法 B：手動安裝（完整控制）

 1# 1. Clone repo
 2git clone https://github.com/affaan-m/ECC.git
 3cd ECC
 4
 5# 2. 安裝 dependencies
 6npm install  # 或 pnpm install / yarn install / bun install
 7
 8# 3. 執行安裝腳本
 9./install.sh --profile full
10
11# Windows:
12# .\install.ps1 --profile full
13# 或 npx ecc-install --profile full

方法 C：最小安裝（無 hooks）

如果你只想要 rules、agents、commands 和核心 skills，不想安裝 hooks：

1./install.sh --profile minimal --target claude

日後需要 hooks 時再追加：

1./install.sh --target claude --modules hooks-runtime

安裝 Rules（Plugin 路徑必須手動補裝）

Plugin 無法自動散布 rules，需手動複製：

1mkdir -p ~/.claude/rules/ecc
2cp -R rules/common ~/.claude/rules/ecc/
3cp -R rules/typescript ~/.claude/rules/ecc/   # 選你用的語言
4# cp -R rules/python ~/.claude/rules/ecc/
5# cp -R rules/golang ~/.claude/rules/ecc/

使用 consult 找到正確組件

1npx ecc consult "security reviews" --target claude
2npx ecc consult "mlops training model deployment" --target claude

移除 / 重設

1node scripts/ecc.js list-installed  # 查看已安裝
2node scripts/ecc.js doctor          # 診斷
3node scripts/ecc.js repair          # 修復
4node scripts/uninstall.js --dry-run # 預覽移除
5node scripts/uninstall.js           # 執行移除

警告：不要疊加安裝方法。Plugin 和手動安裝二擇一，否則會造成重複。

第 3 章：核心架構解析

系統架構總覽

ECC 的架構分為六個核心層 (core layers)，每一層負責不同的職責：


graph TB
    subgraph User["使用者層"]
        CLI["Claude Code / Codex / Cursor CLI"]
        Dashboard["ECC Dashboard (Tkinter GUI)"]
    end

    subgraph Plugin["Plugin 層"]
        Manifest[".claude-plugin/plugin.json"]
        Marketplace[".claude-plugin/marketplace.json"]
    end

    subgraph Core["核心元件層"]
        Agents["agents/ (63 個)"]
        Skills["skills/ (249 個)"]
        Commands["commands/ + shims"]
        Rules["rules/ (common + 語言別)"]
    end

    subgraph Runtime["運行時層"]
        Hooks["hooks/hooks.json"]
        Scripts["scripts/ (Node.js)"]
        Memory["memory-persistence"]
        Compact["strategic-compact"]
    end

    subgraph Learning["學習層"]
        CL2["continuous-learning-v2"]
        Instincts["instincts (自動萃取)"]
        Evolve["evolve (聚合為 skills)"]
    end

    subgraph Security["安全層"]
        AgentShield["AgentShield (1282 tests)"]
        PromptDefense["Prompt Defense Baseline"]
        HookGuard["Hook Runtime Controls"]
    end

    CLI --> Plugin
    Dashboard --> Core
    Plugin --> Core
    Core --> Runtime
    Runtime --> Learning
    Runtime --> Security
    Learning -.-> Skills

Agents (代理) 架構

每個 agent 是一份 Markdown 檔案，包含 YAML frontmatter（定義 name、description、tools、model）和任務指引。Claude Code 會根據任務自動或手動 delegate (委派) 給對應 agent。

關鍵 agents：

planner.md — 功能規劃與分解
architect.md — 系統設計決策
code-reviewer.md — 程式碼品質與安全審查
tdd-guide.md — TDD 方法論引導
security-reviewer.md — 弱點分析
build-error-resolver.md — 建構錯誤修復

Skills (技能) 架構

Skills 是 ECC 的主要工作流介面，取代了舊版的 commands。每個 skill 是一個資料夾，內含：

SKILL.md — 觸發條件、使用方式、範例
scripts/ — 可選的輔助腳本

Skills 涵蓋：coding standards、backend/frontend patterns、TDD、security、continuous learning、evaluation、各語言 framework 特定 patterns。

Hooks (鉤子) 系統

Hooks 是 trigger-based automations (觸發式自動化)，定義在 hooks/hooks.json：

事件	用途
`SessionStart`	載入上次 session 的 context 與 memory
`Stop`	儲存 session 狀態、萃取 patterns
`PreToolUse`	攔截危險操作（如 `rm -rf`、dev server 啟動）
`PostToolUse`	自動格式化、type checking
`PreCompact`	Compaction 前儲存狀態

可用環境變數控制：

1export ECC_HOOK_PROFILE=standard      # minimal | standard | strict
2export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder"
3export ECC_SESSION_START_MAX_CHARS=4000

Rules (規則) 架構

Rules 是 always-follow guidelines (永遠遵循的原則)，分為 common/（語言無關）和語言特定（typescript/python/golang/swift/php/arkts）。安裝後放在 ~/.claude/rules/ecc/。

第 4 章：使用方式詳解

基本 Slash Commands

 1# 功能規劃
 2/ecc:plan "Add user authentication"
 3
 4# 程式碼審查
 5/ecc:code-review
 6
 7# TDD 開發
 8/ecc:tdd
 9
10# 建構錯誤修復
11/ecc:build-fix
12
13# E2E 測試
14/ecc:e2e
15
16# 從 session 學習
17/ecc:learn

手動安裝使用較短的 slash 格式：/plan、/code-review、/tdd。

持續學習 (Continuous Learning)

 1# 查看已學到的 instincts
 2/instinct-status
 3
 4# 從其他人的 instincts 匯入
 5/instinct-import <file>
 6
 7# 匯出分享
 8/instinct-export
 9
10# 將 instincts 聚合為 skills
11/evolve

Multi-Agent 協作

需先安裝 ccg-workflow runtime：

 1npx ccg-workflow
 2
 3# 多 agent 任務分解
 4/multi-plan
 5
 6# 多 agent 執行
 7/multi-execute
 8
 9# 後端多服務協作
10/multi-backend
11
12# 前端多服務協作
13/multi-frontend

Dashboard GUI

1npm run dashboard
2# 或
3python3 ./ecc_dashboard.py

提供 Tkinter 桌面介面，含 Agents / Skills / Commands / Rules / Settings 分頁、Dark/Light 主題切換、搜尋過濾。

ECC 2.0 Alpha (Rust 控制平面)

1cd ecc2
2cargo build
3./target/debug/ecc2 dashboard
4./target/debug/ecc2 start
5./target/debug/ecc2 sessions
6./target/debug/ecc2 status

元件查詢

1npx ecc consult "security reviews" --target claude
2npx ecc consult "mlops training" --target claude

第 5 章：應用場景

場景 1：新專案啟動

安裝 ECC → 用 /plan 規劃架構 → 用 /tdd 寫測試 → 用 /code-review 審查 → 用 /learn 萃取 patterns。

場景 2：維護既有大型程式碼庫

安裝 minimal profile → 複製需要的 rules → 用 code-reviewer agent 批量審查 → 用 refactor-cleaner agent 清理 dead code。

場景 3：跨團隊 AI 工作流標準化

用 ECC 的 rules + skills 作為團隊標準 → 將 instincts export/import 在團隊間共享 → 用 AgentShield 確保所有人的設定安全。

場景 4：MLOps / 資料科學

1npx ecc install --profile minimal --target claude --with capability:machine-learning

使用 mle-workflow skill 處理 data contracts、evals、deployment、monitoring。

場景 5：多語言 Monorepo

安裝對應語言 rules（typescript + python + golang），ECC 自動根據檔案類型套用對應規則。搭配 build-error-resolver agent 處理跨語言建構問題。

第 6 章：資安掃描報告

掃描方法

使用 grep 對 ECC 原始碼做 pattern-based 掃描，檢查以下類別：

🟢 整體評級：低風險

ECC 作為一個 agent harness 設定系統，本身不處理使用者資料或網路請求。安全設計良好。

詳細發現

類別	風險	說明
`subprocess` 使用	🟢 低	Python scripts 中使用 `subprocess.run()` 但均以 list argv 呼叫、無 `shell=True`、有 timeout。見 `skills/continuous-learning-v2/scripts/instinct-cli.py`
`child_process` 使用	🟡 中	Hook scripts 中使用 `spawnSync` / `execFileSync`，部分有 `shell: true`（見 `scripts/hooks/stop-format-typecheck.js:69`）。這是 hook 機制必要操作，但 `shell: true` 需注意 injection
`eval()`	🟢 低	僅在 security-audit tool 中作為偵測 pattern，非實際使用
Hardcoded secrets	🟢 低	未發現 hardcoded API keys 或 passwords。API key 均透過 `process.env` / `os.environ` 載入
Network calls	🟢 低	主要用於 GitHub API 整合（GitHub App），透過 `gh auth token` 安全取得
Prompt injection 防護	🟢 良好	`CLAUDE.md` 內建 Prompt Defense Baseline，含 role lock、credential protection、unicode trick 偵測
AgentShield	🟢 加分	內建 1282 測試、102 條靜態分析規則的資安掃描工具

建議

審查 scripts/hooks/stop-format-typecheck.js 中 shell: true 的使用，確認 input 已被 sanitize
定期執行 npx ecc-agentshield scan 確認設定安全性
使用 ECC_HOOK_PROFILE=strict 啟用最嚴格的 hook 防護

第 7 章：FAQ

Q1：ECC 和 Claude Code 的 built-in skills/commands 有什麼不同？

ECC 是社群建立的第三方 plugin，提供比 Claude Code 內建更多的 agents (63 vs 內建約 10+)、更多 skills (249+)、以及 hooks 系統。它是「加法」——增強而非取代內建功能。

Q2：安裝 ECC 會影響我現有的 Claude Code 設定嗎？

不會。Plugin 安裝路徑與你的 ~/.claude/ 設定分開管理。手動安裝時，ECC 用 install-state 追蹤自己安裝的檔案，不會碰到你原有的設定。

Q3：我需要全部 249 個 skills 嗎？

不需要。使用 --profile minimal 只安裝核心，或用 npx ecc consult 查詢你需要的元件再選擇性安裝。

Q4：ECC Pro 和免費版有何差異？

OSS repo 永遠免費 MIT 授權。ECC Pro ($19/seat/mo) 是 hosted GitHub App，針對 private repos 提供 PR audits 等進階功能。

Q5：Hooks 執行太慢怎麼辦？

使用 ECC_HOOK_PROFILE=minimal 減少 hook 數量，或用 ECC_DISABLED_HOOKS 停用特定 hooks。ECC_SESSION_START_MAX_CHARS=4000 可縮減 SessionStart 載入量。

Q6：支援哪些 AI agent 工具？

Claude Code、Codex (OpenAI)、Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Trae、Kiro 等。

Q7：如何貢獻？

參考 CONTRIBUTING.md，依 agent / skill / command / hook / rule 的格式提交 PR。每種類型都有標準模板。

第 8 章：進階技巧

1. Hook Profile 調校

1# 最小化（低 token 消耗）
2export ECC_HOOK_PROFILE=minimal
3
4# 標準（推薦）
5export ECC_HOOK_PROFILE=standard
6
7# 嚴格（CI / 品質要求高的專案）
8export ECC_HOOK_PROFILE=strict

2. Context 管理

1# 限制 SessionStart 載入量
2export ECC_SESSION_START_MAX_CHARS=4000
3
4# 完全關閉（極低 context 的本地模型）
5export ECC_SESSION_START_CONTEXT=off
6
7# 關閉成本估算警告
8export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

3. 自建 Skills

1# 從 git history 萃取 skill
2/skill-create
3
4# 包含 instincts
5/skill-create --instincts

或使用 GitHub App：在 issue 中留言 /skill-creator analyze。

4. Package Manager 設定

1# 設定全域
2node scripts/setup-package-manager.js --global pnpm
3
4# 設定專案級
5node scripts/setup-package-manager.js --project bun
6
7# 偵測目前設定
8node scripts/setup-package-manager.js --detect

5. Selective Install 進階

1# 查看可用 profiles
2cat manifests/install-profiles.json
3
4# 安裝特定 modules
5./install.sh --target claude --modules hooks-runtime
6
7# 排除特定 modules
8./install.sh --profile core --without baseline:hooks --target claude

6. AgentShield 深度掃描

 1# 快速掃描
 2npx ecc-agentshield scan
 3
 4# 自動修復
 5npx ecc-agentshield scan --fix
 6
 7# 三 agent 深度分析（使用 Opus 4.6）
 8npx ecc-agentshield scan --opus --stream
 9
10# 產出 JSON（CI 整合）
11npx ecc-agentshield scan --format json

第 9 章：整合進其他工作流

與 CI/CD 整合

將 AgentShield 加入 GitHub Actions：

1- name: ECC Security Scan
2  run: npx ecc-agentshield scan --format json --exit-code 2

與現有 CLAUDE.md 整合

在你的專案 CLAUDE.md 中引用 ECC skills：

1## Skills
2| File(s) | Skill |
3|---------|-------|
4| `*.tsx` | `react-patterns`, `react-testing` |
5| `*.py`  | `python-patterns`, `python-testing` |

與團隊 Instincts 共享

1# 團隊成員 A 匯出
2/instinct-export  # 產生 instincts.json
3
4# 團隊成員 B 匯入
5/instinct-import instincts.json

與 MCP Servers 整合

ECC 內建 MCP 設定（mcp-configs/mcp-servers.json），可直接啟用 GitHub、Supabase、Vercel、Railway 等整合。

與 Codex / OpenCode 整合

1# 同步 ECC 資產到 Codex
2bash scripts/sync-ecc-to-codex.sh
3
4# OpenCode 已內建 plugin 支援
5# 見 .opencode/ 目錄

第 10 章：重點摘要 Checklist

確認 Claude Code CLI >= v2.1.0
選擇安裝方式：Plugin (/plugin install ecc@ecc) 或手動 (install.sh)
不要同時使用兩種安裝方式
手動複製需要的 rules/ 到 ~/.claude/rules/ecc/
設定 ECC_HOOK_PROFILE（建議 standard）
執行 npx ecc-agentshield scan 確認資安
試用核心指令：/plan、/code-review、/tdd
啟用 Continuous Learning：用 /learn 萃取 session patterns
用 npx ecc consult 探索適合你專案的元件
設定 Package Manager：node scripts/setup-package-manager.js --detect
需要時用 /instinct-export 備份你的 instincts
用 node scripts/ecc.js doctor 定期健檢

第 11 章：進一步閱讀

官方資源

GitHub Repo：https://github.com/affaan-m/ECC
官網：https://ecc.tools
Shorthand Guide：the-shortform-guide.md（必讀，setup 與 philosophy）
Longform Guide：the-longform-guide.md（token optimization、memory、evals、parallelization）
Security Guide：the-security-guide.md（attack vectors、sandboxing、CVEs、AgentShield）

生態系工具

AgentShield：https://github.com/affaan-m/agentshield — 資安掃描工具
ECC Tools GitHub App：https://github.com/marketplace/ecc-tools — PR audits
npm ecc-universal：https://www.npmjs.com/package/ecc-universal — npm 套件
npm ecc-agentshield：https://www.npmjs.com/package/ecc-agentshield — 資安掃描 npm 套件

社群

Discussions：https://github.com/affaan-m/ECC/discussions
Contributing：見 repo 內 CONTRIBUTING.md
Sponsors：https://github.com/sponsors/affaan-m

ECC 完整教學 — Agent Harness Performance Optimization System

Contents

ECC 完整教學 — Agent Harness Performance Optimization System

第 1 章：專案定位

ECC 是什麼？

為什麼需要 ECC？

關鍵數據

第 2 章：安裝指南

前置需求

方法 A：Plugin 安裝（推薦）

方法 B：手動安裝（完整控制）

方法 C：最小安裝（無 hooks）

安裝 Rules（Plugin 路徑必須手動補裝）

使用 consult 找到正確組件

移除 / 重設

第 3 章：核心架構解析

系統架構總覽

Agents (代理) 架構

Skills (技能) 架構

Hooks (鉤子) 系統

Rules (規則) 架構

第 4 章：使用方式詳解

基本 Slash Commands

持續學習 (Continuous Learning)

Multi-Agent 協作

Dashboard GUI

ECC 2.0 Alpha (Rust 控制平面)

元件查詢

第 5 章：應用場景

場景 1：新專案啟動

場景 2：維護既有大型程式碼庫

場景 3：跨團隊 AI 工作流標準化

場景 4：MLOps / 資料科學

場景 5：多語言 Monorepo

第 6 章：資安掃描報告

掃描方法

🟢 整體評級：低風險

詳細發現

建議

第 7 章：FAQ

Q1：ECC 和 Claude Code 的 built-in skills/commands 有什麼不同？

Q2：安裝 ECC 會影響我現有的 Claude Code 設定嗎？

Q3：我需要全部 249 個 skills 嗎？

Q4：ECC Pro 和免費版有何差異？

Q5：Hooks 執行太慢怎麼辦？

Q6：支援哪些 AI agent 工具？

Q7：如何貢獻？

第 8 章：進階技巧

1. Hook Profile 調校

2. Context 管理

3. 自建 Skills

4. Package Manager 設定

5. Selective Install 進階

6. AgentShield 深度掃描

第 9 章：整合進其他工作流

與 CI/CD 整合

與現有 CLAUDE.md 整合

與團隊 Instincts 共享

與 MCP Servers 整合

與 Codex / OpenCode 整合

第 10 章：重點摘要 Checklist

第 11 章：進一步閱讀

官方資源

生態系工具

社群

相關概念延伸閱讀

Related Posts

Comments