ECC là gì? Phân tích repo affaan-m/ecc và hướng dẫn sử dụng

ECC là gì? Phân tích repo affaan-m/ecc và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ repo chính thức affaan-m/ECC, file assets/hero.png. Ảnh là PNG, không phải SVG.¹

Tóm tắt nhanh

ECC là một bộ công cụ cấu hình và workflow cho AI coding agent. Repo mô tả ECC là “harness-native operator system for agentic work”, tức một hệ thống giúp các agent như Claude Code, Codex, Cursor, OpenCode, Gemini, Zed và GitHub Copilot làm việc có cấu trúc hơn.²

Nói dễ hiểu: nếu bạn dùng AI để code, ECC giống như một “bộ quy tắc + kỹ năng + hook + agent phụ + kiểm tra bảo mật” cài vào môi trường làm việc. Nó giúp agent biết cách lập kế hoạch, viết test, review code, sửa lỗi build, ghi nhớ kinh nghiệm, quản lý context và tránh một số rủi ro bảo mật.

ECC không phải là model AI và không thay thế Claude, Codex, Cursor hay Copilot. Nó là lớp workflow nằm quanh các công cụ đó.

ECC giải quyết vấn đề gì?

Khi dùng AI coding agent, vấn đề thường không chỉ là model thông minh hay không. Vấn đề thực tế là agent hay gặp các lỗi sau: làm việc không có kế hoạch, quên quy ước dự án, viết code nhưng không test, sửa lỗi này làm hỏng phần khác, quên context sau phiên dài, bật quá nhiều MCP làm tốn context, hoặc chạy lệnh nguy hiểm mà không kiểm tra.

ECC cố gắng giải quyết các vấn đề này bằng cách đóng gói workflow đã dùng thực tế: skills, commands, hooks, rules, memory persistence, continuous learning, subagents, MCP configs và security scanning.²

Hình dung đơn giản

AI coding agent
      ↓
ECC rules: luôn theo chuẩn code, test, security
      ↓
ECC skills: quy trình cụ thể như /plan, /tdd, /code-review
      ↓
ECC hooks: tự nhắc tmux, format code, chạy type-check, lưu memory
      ↓
ECC subagents: planner, reviewer, security reviewer, build fixer
      ↓
ECC memory: ghi lại kinh nghiệm và context cần dùng lại

Điểm quan trọng: ECC không làm bạn mất quyền kiểm soát. Nó thêm quy trình để agent ít đi lệch hơn.

Các thành phần chính của ECC

Skills

Skills là phần quan trọng nhất. Shortform Guide mô tả skills là workflow bundles: các prompt, cấu trúc, file hỗ trợ và codemap được load khi cần một kiểu tác vụ cụ thể.³

Thay vì nhắc đi nhắc lại “hãy lập kế hoạch, viết test, review bảo mật”, bạn gọi skill tương ứng.

Commands

ECC vẫn có lớp commands để gọi nhanh từ slash command. Tuy nhiên, tài liệu nhấn mạnh skills mới là phần bền vững hơn; commands có thể hiểu như lối vào nhanh hoặc shim tương thích cũ.³

Rules

Rules là các quy tắc agent phải luôn nhớ: coding style, security, testing, git workflow, performance và patterns. Shortform Guide mô tả rules folder như nơi chứa các file .md với best practices Claude nên luôn theo.⁴

Ví dụ rule: không hardcode secret, luôn validate input, ưu tiên file nhỏ và module rõ, viết test trước khi deploy, không commit console.log rác, dùng commit message thống nhất.

Hooks

Hooks là automation chạy khi có sự kiện. Shortform Guide liệt kê các hook kiểu PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact và Notification.⁵

Ví dụ: trước khi chạy npm test thì nhắc dùng tmux nếu command dài; sau khi agent sửa file TypeScript thì tự chạy formatter hoặc type-check; khi phiên kết thúc thì lưu bài học vào memory; trước khi compact context thì lưu trạng thái quan trọng.

Người mới không nên bật quá nhiều hooks ngay từ đầu. Minimal profile an toàn hơn.

Subagents

Subagents là agent phụ có phạm vi hẹp. Shortform Guide mô tả subagents là các process mà orchestrator chính có thể giao việc với scope giới hạn.⁶

Cách dùng đúng là giao từng việc rõ ràng cho subagent, không để mọi thứ dồn vào agent chính.

Memory và continuous learning

Longform Guide nói một vấn đề lớn là context rot: phiên càng dài, càng nhiều thông tin cũ làm nhiễu. ECC dùng memory persistence và continuous learning để lưu lại điều quan trọng sau phiên làm việc.⁷

Ví dụ: test phải chạy bằng pnpm test:unit, migration cần chạy qua script riêng, frontend không dùng một số màu hoặc API response luôn theo { data, error }. Các điều đó nên được lưu thành memory hoặc skill để phiên sau không phải nhắc lại.

MCP configs

MCP giúp agent kết nối với công cụ ngoài như GitHub, Supabase, Vercel, Railway, Cloudflare hoặc memory server. Tuy nhiên, README cảnh báo context window rất quý; bật quá nhiều MCP sẽ làm context giảm mạnh. README khuyến nghị giữ dưới 10 MCP enabled và dưới 80 tools active.⁸

AgentShield

ECC có nhắc đến AgentShield, một công cụ scan cấu hình agent để tìm rủi ro bảo mật, cấu hình sai và injection risk. README nêu lệnh:⁹

npx ecc-agentshield scan
npx ecc-agentshield scan --fix
npx ecc-agentshield init

Nó scan CLAUDE.md, settings.json, MCP configs, hooks, agent definitions và skills.

Repo này gồm những gì?

README liệt kê repo có rất nhiều thư mục và file. Các phần dễ hiểu nhất gồm:¹⁰

Với người mới, không cần đọc hết repo. Chỉ cần hiểu: ECC là một bộ toolkit nhiều lớp cho agentic coding.

Cài đặt ECC: nên chọn cách nào?

Cách 1: Claude Code plugin, dễ nhất

README khuyến nghị cài như Claude Code plugin:¹¹

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

Cách này cho bạn truy cập nhanh tới commands, agents, skills và hooks. Lưu ý: plugin không tự phân phối rules do giới hạn của Claude Code plugin system; nếu cần rules, bạn phải copy rules thủ công.¹²

Cách 2: Minimal install, ít rủi ro hơn cho người mới

Nếu bạn không muốn hooks quá mạnh hoặc chỉ muốn rules, agents, commands và core workflow skills, dùng minimal profile:¹³

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

Windows PowerShell:

.\install.ps1 --profile minimal --target claude

Hoặc dùng npm:

npx ecc-install --profile minimal --target claude

Minimal profile cố ý loại hooks-runtime, nên phù hợp để bắt đầu nhẹ nhàng.

Cách 3: Full manual install

Chỉ dùng nếu bạn bỏ qua plugin path:

./install.sh --profile full

Windows:

.\install.ps1 --profile full

Hoặc:

npx ecc-install --profile full

README cảnh báo không nên vừa plugin install vừa full install, vì có thể tạo duplicate skills và duplicate runtime behavior.¹⁴

Cài đặt rules thủ công

Nếu chỉ muốn rules:

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/   # chọn stack bạn dùng

Cách này phù hợp nếu bạn muốn agent theo chuẩn code và security, nhưng chưa muốn bật toàn bộ hook/plugin.

Dùng với Claude Code

Sau khi cài plugin hoặc minimal install, mở Claude Code trong dự án:

claude

Gõ / để xem slash commands. Các command nên thử đầu tiên:

/plan
/tdd
/code-review
/build-fix
/refactor-clean
/quality-gate

Workflow dễ dùng:

1. /plan: yêu cầu agent lập kế hoạch.
2. /tdd: viết test hoặc test case trước.
3. Cho agent implement từng bước.
4. /code-review: review thay đổi.
5. /quality-gate: kiểm tra trước khi commit.

Dùng với Cursor

README cho biết ECC cung cấp hỗ trợ Cursor với hooks, rules, agents, skills, commands và MCP configs theo layout của Cursor.¹⁵

./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

Windows:

.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

Cursor adapter có các hook như beforeShellExecution, afterFileEdit, beforeSubmitPrompt, beforeTabFileRead, giúp chặn secret, auto-format, type-check hoặc audit MCP.¹⁶

Dùng với Codex

README nói Codex App + CLI được hỗ trợ bằng cấu hình tham chiếu, AGENTS.md supplement và shared skills.¹⁷

codex
npm install && bash scripts/sync-ecc-to-codex.sh

Script merge MCP servers theo kiểu add-only, không xóa hoặc sửa server hiện có; có thể dùng --dry-run để xem trước.¹⁷

Dùng với OpenCode

README nói OpenCode có plugin system mạnh, hỗ trợ nhiều event tương tự hooks.¹⁸

npm install -g opencode
opencode

Hoặc cài plugin npm:

npm install ecc-universal

Rồi thêm vào opencode.json:

{
  "plugin": ["ecc-universal"]
}

Lưu ý: plugin npm không tự thêm toàn bộ catalog command/agent/instruction; muốn full setup thì chạy OpenCode trong repo hoặc copy .opencode/ vào dự án.¹⁸

Dùng với GitHub Copilot trong VS Code

ECC cũng hỗ trợ GitHub Copilot thông qua cơ chế file native của VS Code/GitHub Copilot. README nói Copilot đọc hai loại file:¹⁹

• .github/copilot-instructions.md: instructions luôn được đưa vào Copilot Chat;
• .github/prompts/*.prompt.md: prompt file dùng khi cần, ví dụ plan, tdd, code-review.

Điểm cần nhớ: Copilot không có hook system hoặc subagent API, nên hook automation và agent delegation của ECC không khả dụng trong Copilot.²⁰

Khi nào nên dùng ECC?

Nên dùng nếu bạn dùng Claude Code/Codex/Cursor/OpenCode thường xuyên, muốn agent làm việc có quy trình hơn, cần TDD/code review/security review/build fix, muốn memory qua nhiều phiên, hoặc muốn chuẩn hóa workflow cho team.

Không nên dùng full setup ngay nếu bạn mới thử AI coding agent, chưa hiểu hooks, không muốn script tự chạy sau mỗi tool call, hoặc môi trường có secret/production credential nhạy cảm.

Với người mới, chọn minimal profile hoặc chỉ copy rules là hợp lý hơn.

Cách triển khai cho cá nhân

Ngày 1: Cài plugin hoặc minimal profile.
Ngày 2: Dùng /plan, /code-review, /build-fix.
Ngày 3: Thêm rules cho stack chính.
Ngày 4: Bật một vài hooks nhẹ như format/check.
Ngày 5: Dùng AgentShield scan cấu hình.
Ngày 6-7: Giữ lại workflow nào thật sự tiết kiệm thời gian.

Không cần bật mọi thứ cùng lúc.

Cách triển khai cho team

Bước 1: Pilot nhỏ

Chọn 2–3 developer dùng AI coding agent nhiều. Cho họ dùng minimal profile hoặc plugin, nhưng chưa bật full hooks trong toàn team.

Bước 2: Chuẩn hóa rules

Tạo bộ rules nội bộ về security, testing, git workflow, coding style cho stack chính. Không copy mọi rule nếu không dùng.

Bước 3: Chọn skills thật sự cần

Thường nên bắt đầu với planning, TDD, build-fix, code-review, security-review và update-docs.

Bước 4: Kiểm soát MCP

Không bật 20 MCP trong mọi repo. Theo README, quá nhiều MCP có thể làm context window giảm mạnh; nên giữ dưới 10 MCP enabled và dưới 80 tools active.⁸

Bước 5: Bật bảo mật

npx ecc-agentshield scan

Kiểm tra secret trong ~/.claude/settings.json, .mcp.json, MCP env blocks và hook scripts.

Lưu ý bảo mật

SECURITY.md của ECC nhấn mạnh không được commit credential thật, không hardcode PAT/API key/OAuth token trong mcpServers[*].env, và nếu secret lỡ bị commit thì phải rotate ngay rồi rewrite history, không chỉ revert.²¹

Checklist ngắn:

• Không commit ~/.claude/settings.json nếu có secret.
• Không paste token thật vào MCP config mẫu.
• Kiểm tra process đang nghe trên local MCP port trước khi dùng.²²
• Chạy AgentShield định kỳ.
• Không bật hooks không hiểu rõ.
• Không để agent tự deploy production nếu chưa có approval.
• Không bật quá nhiều MCP.
• Review file do agent sửa trước khi commit.

Lỗi thường gặp

TROUBLESHOOTING.md liệt kê nhiều lỗi phổ biến như context overflow, agent not found, hooks không chạy, thiếu Node/Python, plugin không load, package manager detection sai và performance chậm.²³

claude --version
node --version
python3 --version
npm --version
ls -la ~/.claude/plugins/cache/
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
npx ecc-agentshield scan

So sánh ECC với Headroom, RTK, Hermes Agent

ECC gần với “bộ vận hành agentic coding”. Nó không chỉ giảm token mà còn định hình cách agent làm việc.

FAQ

ECC là gì?

ECC là hệ thống workflow cho AI coding agent, gồm skills, commands, hooks, rules, subagents, memory, MCP configs và security scanning. Repo mô tả nó là harness-native operator system for agentic work.²

ECC có phải chỉ dành cho Claude Code không?

Không. README nói ECC hoạt động với Codex, Claude Code, Cursor, OpenCode, Gemini, Zed, GitHub Copilot và các harness khác.²

Người mới nên cài bản nào?

Nên bắt đầu bằng plugin hoặc minimal profile. Nếu chưa hiểu hooks, đừng cài full profile ngay.

ECC có làm AI tự code tốt hơn không?

ECC không làm model thông minh hơn, nhưng giúp model làm việc có quy trình hơn: lập kế hoạch, test, review, nhớ kinh nghiệm và tuân thủ rules.

ECC có rủi ro không?

Có. Vì ECC có hooks, MCP configs và script chạy local, bạn cần kiểm tra bảo mật, không commit secret, không bật thứ không hiểu và dùng AgentShield scan.

Kết luận

affaan-m/ecc là một repo lớn, nhưng ý tưởng cốt lõi khá dễ hiểu: biến AI coding agent từ một chatbot code tự phát thành một hệ thống làm việc có quy trình. Nó cung cấp skills để làm việc theo từng tác vụ, rules để giữ chuẩn dự án, hooks để tự động hóa, subagents để chia việc, memory để học từ phiên trước và AgentShield để kiểm tra rủi ro.

Cách dùng hợp lý là bắt đầu nhỏ: cài plugin hoặc minimal profile, thử /plan, /code-review, /build-fix, thêm rules cho stack chính, rồi mới cân nhắc hooks, MCP và setup team. Đừng bật toàn bộ repo chỉ vì có sẵn; hãy bật đúng phần bạn thật sự cần.

Nguồn tham khảo

Footnotes

1. GitHub raw asset. affaan-m/ECC/assets/hero.png. https://raw.githubusercontent.com/affaan-m/ECC/main/assets/hero.png ↩

2. GitHub / README. affaan-m/ECC. https://github.com/affaan-m/ecc ↩ ↩² ↩³ ↩⁴

3. the-shortform-guide.md, section “Skills and Commands”. https://raw.githubusercontent.com/affaan-m/ecc/main/the-shortform-guide.md ↩ ↩²

4. the-shortform-guide.md, section “Rules and Memory”. https://raw.githubusercontent.com/affaan-m/ecc/main/the-shortform-guide.md ↩

5. the-shortform-guide.md, section “Hooks”. https://raw.githubusercontent.com/affaan-m/ecc/main/the-shortform-guide.md ↩

6. the-shortform-guide.md, section “Subagents”. https://raw.githubusercontent.com/affaan-m/ecc/main/the-shortform-guide.md ↩

7. the-longform-guide.md, section “Context and Memory Management” and “Continuous Learning / Memory”. https://raw.githubusercontent.com/affaan-m/ecc/main/the-longform-guide.md ↩

8. README FAQ/context window note about MCP count and enabled tools. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩ ↩²

9. README AgentShield section. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

10. GitHub README, repository structure and component tree. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

11. README Installation, “Install as Plugin”. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

12. README Installation note: Claude Code plugins cannot distribute rules automatically. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

13. README Quick Start, “Low-context / no-hooks path”. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

14. README installation warning about not mixing plugin install and full installer. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

15. README Cursor IDE Support. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

16. README Cursor hook events and scripts. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

17. README Codex App + CLI Support. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩ ↩²

18. README OpenCode Support. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩ ↩²

19. README GitHub Copilot Support. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

20. README GitHub Copilot limitations. https://raw.githubusercontent.com/affaan-m/ecc/main/README.md ↩

21. SECURITY.md, secrets handling guidance. https://raw.githubusercontent.com/affaan-m/ecc/main/SECURITY.md ↩

22. SECURITY.md, local MCP port guidance. https://raw.githubusercontent.com/affaan-m/ecc/main/SECURITY.md ↩

23. TROUBLESHOOTING.md. https://raw.githubusercontent.com/affaan-m/ecc/main/TROUBLESHOOTING.md ↩