affaan-m/ECC: nâng cấp AI coding agent — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
ECC là bộ công cụ biến AI coding agent thành một hệ thống làm việc có quy trình: lập kế hoạch, viết mã, kiểm thử, review, xác minh và ghi nhớ. Repo phù hợp với dev muốn chuẩn hóa cách dùng Claude Code, Codex hoặc harness khác; cài khá dễ nếu dùng trình hướng dẫn chính thức và đã có Node.js 18 trở lên.
ECC là một hệ thống tối ưu hiệu năng cho AI coding agent. Repo bổ sung skills, agents, memory, hooks, rules và công cụ bảo mật để agent làm việc theo quy trình rõ ràng hơn: lập kế hoạch, kiểm thử, triển khai, review, xác minh, ghi nhớ rồi cải thiện.
Repo phù hợp với lập trình viên dùng Claude Code, Codex, Qoder hoặc một số harness khác. Người mới có thể bắt đầu bằng trình hướng dẫn cài đặt. Người đã có quy trình riêng có thể chọn profile, phạm vi cài đặt và loại hook phù hợp.
Điểm đáng giá nhất là bạn không phải lặp lại một bộ prompt dài cho từng dự án. ECC đóng gói quy trình đó thành plugin và các thành phần dùng lại được. Repo được cấp phép MIT, hiện có khoảng 302257 sao và 44585 fork.
affaan-m/ECC
ECC bổ sung skills, agents, memory, hooks và quy trình kiểm thử cho Claude Code, Codex cùng nhiều AI coding agent.
I.ECC làm được gì
Chuẩn hóa quy trình phát triển với chuỗi
plan -> test -> implement -> review -> verify -> remember -> improve. Agent được định hướng phải suy nghĩ, kiểm tra và đánh giá lại thay vì chỉ sinh mã rồi dừng.Cung cấp 71 agents chuyên biệt. Các agent được phân nhóm cho lập kế hoạch, review, sửa lỗi build, bảo mật, kiến trúc và một số công việc theo lĩnh vực. Lợi ích thực tế là bạn có thể giao đúng loại việc cho đúng workflow thay vì dùng một agent chung cho mọi tình huống.
Cung cấp 314 skills cho TDD, nghiên cứu, bảo mật, tài liệu, frontend, dữ liệu, machine learning và vận hành. Đây là các năng lực có thể gọi lại trong nhiều dự án.
Có 98 command shim kế thừa để giữ các lối vào quen thuộc trong giai đoạn chuyển sang mô hình skills-first. Người đang dùng lệnh cũ có thêm thời gian chuyển đổi mà không phải thay toàn bộ thói quen ngay.
Có hooks và memory ở runtime. Hooks giúp áp dụng một số quy tắc trong phiên làm việc; memory hỗ trợ tóm tắt phiên, ghi nhận điều quan trọng, học liên tục và kiểm soát context.
Có rules chọn lọc theo ngôn ngữ hoặc dự án. Bạn có thể dùng rules chung cùng một bộ cho stack mình đang làm, thay vì nạp mọi quy tắc vào mọi repo.
Có AgentShield để quét prompt, hooks, cấu hình MCP, quyền truy cập, secrets và các file liên quan đến agent. Đây là lớp kiểm tra hữu ích trước khi đưa một cấu hình agent vào dự án thật.
Hỗ trợ nhiều harness. ECC hoạt động tốt nhất với Claude Code, có đường cài native cho Codex và Qoder, đồng thời có adapter giới hạn khả năng cho Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen và một số harness khác. Mức hỗ trợ không giống nhau giữa các harness.
Có nhiều cách cài phù hợp với từng môi trường. Bạn có thể dùng package runner, plugin native của Claude Code, marketplace/plugin native của Codex hoặc plugin Qoder. Trình hướng dẫn có thể kiểm tra lựa chọn và hỏi xác nhận trước khi ghi thay đổi.
II.Cần chuẩn bị gì
Với cách cài universal, cần Node.js 18 trở lên. Repo khai báo package npm
ecc-universalvàpackage.jsonyêu cầu phiên bản Node tối thiểu này.Với plugin Claude Code, cần Git và Claude Code 2.1 trở lên có sẵn trên
PATH. Bạn cũng cần mở được PowerShell hoặc terminal để chạy các lệnh cài đặt.Với Codex native plugin, cần một bản Codex có hỗ trợ marketplace/plugin. Codex lưu trạng thái plugin trong
CODEX_HOMEđang hoạt động và có quyết định trust riêng cho hooks.Với Qoder, cần Qoder CLI nếu cài qua dòng lệnh. MCP server của Qoder cần
npxvà quyền truy cập mạng trong lần sử dụng đầu tiên.Repo cũng khai báo package Python
llm-abstractionvàpyproject.tomlyêu cầu Python 3.11 trở lên. Tư liệu được cung cấp chưa ghi một quy trình cài riêng cho package Python này, nên không nên tự suy đoán thêm lệnh.Một số tích hợp có thể dùng biến cấu hình trong
.env.example, gồmANTHROPIC_API_KEY,GITHUB_TOKEN,ASTRAFLOW_API_KEY,ASTRAFLOW_CN_API_KEY,ATLAS_API_KEY,GITHUB_USER,DEFAULT_BASE_BRANCH,SESSION_SCRIPT,CONFIG_FILEvàENABLE_VERBOSE_LOGGING. Chỉ điền biến nào đúng với tích hợp bạn thực sự dùng.Không bắt buộc phải clone repo nếu bạn dùng universal guided setup. Với đường cài native hoặc khi cần xem rules, scripts và cấu hình trong repo, bạn sẽ cần một bản checkout đã được xem xét.
III.Cài đặt từng bước
- Chọn harnessQuyết định dùng Claude Code, Codex, Qoder hoặc nhiều harness
- Kiểm tra môi trườngXác nhận Node.js, Git và công cụ agent đã có
- Chạy trình càiDùng một phương thức cài phù hợp với harness
- Chọn phạm viChọn scope, profile và hook theo nhu cầu
- Kiểm tra pluginMở phiên mới và xác nhận ECC đã được bật
A.Chọn một phương thức cho từng harness
ECC hỗ trợ nhiều đường cài, nhưng README yêu cầu bạn chọn một đường cho mỗi harness. Với Claude Code, cách khuyến nghị là universal guided setup. Bạn có thể dùng plugin native thay thế. Không nên cài plugin rồi lại chạy một bản cài Claude thủ công đầy đủ trong cùng môi trường.
Nếu dùng Claude Code và Codex cùng lúc, có thể cài ECC một lần cho mỗi harness. Việc cài một lần vào nhiều harness được hỗ trợ; việc chồng nhiều phương thức trong cùng một harness có thể làm trùng skills, commands, hooks hoặc cấu hình.
B.Kiểm tra công cụ trên Windows
Mở PowerShell từ Start menu. Chạy các lệnh sau để kiểm tra phiên bản:
node --version
git --version
claude --versionNếu một lệnh báo không tìm thấy, hãy cài hoặc sửa công cụ đó trước khi chạy ECC. Với Claude Code, Git và Claude Code phải nằm trên PATH. Người mới thường mở terminal trước khi cài Node.js hoặc mở một cửa sổ PowerShell cũ; hãy mở lại PowerShell sau khi sửa PATH.
C.Cài universal cho Claude Code
Chạy trình hướng dẫn chính thức:
npx ecc-universal@2.2.3 setupTrình hướng dẫn này dùng để cài plugin Claude Code, cập nhật ECC, đổi scope và đổi hook profile. Với một cấu hình cá nhân thông thường, chọn Global user, chọn hooks Standard, rồi xác nhận.
Khi wizard hỏi, đọc kỹ scope trước khi đồng ý. Nếu chỉ muốn dùng trong một dự án, không chọn phạm vi rộng hơn nhu cầu. Có thể chạy lại cùng lệnh sau này để cập nhật hoặc thay đổi cấu hình.
Nếu npm báo lỗi version hoặc cache, kiểm tra version trên registry bằng lệnh README cung cấp:
npm view ecc-universal versionECC cũng hỗ trợ các package runner sau:
pnpm dlx ecc-universal@2.2.3 setup
yarn dlx ecc-universal@2.2.3 setup
bunx ecc-universal@2.2.3 setupYarn Classic 1 không có yarn dlx. Trong trường hợp đó, README hướng dẫn dùng npx, cài package global hoặc nâng cấp Yarn để chạy một lần.
D.Cài cho Claude Code, Codex và Kimi Code cùng lúc
Nếu bạn muốn chọn nhiều harness trong một luồng được xem xét, chạy:
npx ecc-universal@2.2.3 install --guidedWizard cho phép chọn Claude Code, Codex và Kimi Code, hiển thị kênh cài và vị trí đích, kiểm tra trước các lựa chọn rồi hỏi một lần xác nhận cuối. Với automation, hãy chỉ rõ từng lựa chọn:
npx ecc-universal@2.2.3 install --guided \
--harness claude --harness codex --harness kimi \
--claude-scope local --claude-hooks standard \
--profile core --yesCác lựa chọn trong lệnh trên có ý nghĩa cụ thể: cài cho ba harness, dùng scope local và hook standard cho Claude, chọn profile core, rồi tự xác nhận. Không dùng nguyên lệnh này nếu bạn chỉ cần một harness hoặc chưa hiểu thư mục đích.
Có thể chạy dry-run để xem thay đổi mà chưa ghi:
npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
npx ecc-universal@2.2.3 install --profile core --target kimi --dry-runMột số lệnh package-name khác:
npx ecc-universal@2.2.3 consult "security reviews" --target claude
npx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning
npx ecc-universal@2.2.3 doctor --target kimiKhông chạy npx ecc-install --profile minimal --target claude. README nói ecc-install chỉ là tên binary bên trong ecc-universal, không phải một package npm được xuất bản riêng.
E.Cài bằng plugin native của Claude Code
Trong Claude Code, chạy:
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@eccHai lệnh này lần lượt thêm marketplace và cài plugin có tên ecc@ecc. Nếu chọn đường này, dừng ở đây và không chạy thêm bản cài Claude thủ công đầy đủ.
Nếu muốn khai báo qua settings.json, thêm cấu hình sau vào ~/.claude/settings.json:
{
"extraKnownMarketplaces": {
"ecc": {
"source": {
"source": "github",
"repo": "affaan-m/ECC"
}
}
},
"enabledPlugins": {
"ecc@ecc": true
}
}Ba tên trong hệ thống có vai trò khác nhau: repo GitHub là affaan-m/ECC, plugin Claude là ecc@ecc, còn package npm là ecc-universal. Không thay tên này cho nhau khi cài.
F.Thêm rules khi cần
Plugin Claude Code không phân phối rules. Nếu muốn dùng rules, clone repo rồi sao chép bộ phù hợp:
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/ # replace with your stackBắt đầu với rules/common và một pack ngôn ngữ hoặc framework đúng với stack. Không chạy ./install.sh --profile full sau khi đã cài plugin, vì README cảnh báo cách này có thể tạo một lớp cài chồng.
G.Cài plugin native cho Codex
Với bản Codex hỗ trợ marketplace/plugin, chạy:
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.jsHai lệnh add có tính idempotent. Khi muốn làm mới, chạy:
codex plugin marketplace upgrade ecc
codex plugin add ecc@eccHooks native của Codex cần bạn quyết định trust rõ ràng. Codex không dùng bốn hook profile của Claude Code. Trong Codex, có thể gọi $configure-ecc cho luồng cấu hình có xét provider.
H.Cài đường sync Codex cũ khi thật sự cần
Đây là đường tương thích đã bị đánh dấu deprecated. Nếu cần dùng, chạy Codex một lần trước để tạo ~/.codex/config.toml, sau đó:
git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.shKhông dùng đường sync cũ cùng native marketplace plugin. Nếu đã có lớp sync và muốn kiểm tra trước khi xóa:
node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
node scripts/ecc.js uninstall --legacy-codex-syncI.Cài cho Qoder
Từ một checkout đã được xem xét, kiểm tra rồi cài plugin bằng Qoder CLI:
qoder plugins validate . --strict
qoder plugins install .
qoder plugins listNếu dùng Qoder IDE, upload ZIP của thư mục gốc repo. Thư mục gốc trong ZIP phải có .qoder-plugin/, cùng skills/, agents/, commands/, hooks/, scripts/ và .mcp.json. Chỉ upload thư mục manifest hoặc một file SKILL.md sẽ thiếu tài nguyên cần thiết.
IV.Kiểm tra đã chạy được chưa
Với Claude Code, mở một phiên mới rồi chạy:
/plugin listKết quả mong đợi là plugin ecc@ecc được bật. Nếu dùng plugin native Codex, chạy:
codex plugin list --json
node scripts/codex/check-plugin-cache.jsKết quả cần cho thấy plugin đã được đăng ký và cache có thể kiểm tra được. Với Qoder, lệnh sau phải liệt kê plugin sau khi cài:
qoder plugins listBạn cũng có thể kiểm tra cấu hình Kimi bằng:
npx ecc-universal@2.2.3 doctor --target kimiNếu wizard báo không tìm thấy Node, Git hoặc Claude Code, đó là lỗi môi trường chứ chưa phải lỗi của ECC. Hãy sửa prerequisite rồi chạy lại.
V.Dùng vào việc thật
A.Dev muốn agent sửa một tính năng có kiểm thử
Một dev làm ứng dụng JavaScript có thể dùng ECC để yêu cầu agent lập kế hoạch trước, viết test, triển khai, chạy kiểm tra rồi review lại. Sau khi cài plugin, hãy giao việc theo hướng rõ đầu ra, chẳng hạn: “Lập kế hoạch cho tính năng đăng nhập, viết test trước, triển khai, chạy test và tự review thay đổi từ một context mới”.
ECC không thay thế test của dự án. Giá trị của nó là biến chuỗi công việc thành thói quen có cấu trúc, giúp giảm trường hợp agent chỉ sửa một file rồi kết luận đã xong.
B.Nhân viên văn phòng cần tự động hóa tài liệu kỹ thuật
Một nhân viên phụ trách tài liệu có thể dùng skill về docs để nhờ agent đọc cấu trúc dự án, đề xuất nội dung, tạo bản nháp và kiểm tra các phần còn thiếu. Câu lệnh mẫu có thể là: “Đọc cấu trúc hiện có, lập danh sách phần tài liệu còn thiếu, viết bản nháp hướng dẫn cài đặt và nêu rõ chỗ nào chưa có thông tin”.
Kết quả nên được xem như bản nháp để người phụ trách duyệt. ECC hỗ trợ quy trình research và review, nhưng không tự biến thông tin chưa kiểm chứng thành sự thật.
C.Chủ shop muốn kiểm tra một thay đổi trên website
Chủ shop có thể nhờ dev dùng ECC kiểm tra một thay đổi giao diện hoặc luồng đặt hàng. Ví dụ: “Review thay đổi trang thanh toán, tập trung vào lỗi dễ làm khách không hoàn tất đơn, kiểm tra test hiện có và đề xuất test còn thiếu”.
Kết quả thực tế phụ thuộc vào mã nguồn, test và harness đang dùng. ECC cung cấp agents cho review, build repair và security; nó không tự biết quy trình kinh doanh riêng nếu bạn chưa mô tả trong dự án.
D.Nhóm dev cần kiểm tra bảo mật trước khi dùng MCP
Trước khi đưa một MCP config, hook hoặc prompt vào repo chung, nhóm có thể dùng AgentShield để kiểm tra prompt, hooks, MCP config, permissions, secrets và agent files. Câu lệnh yêu cầu nên nêu rõ phạm vi: “Kiểm tra cấu hình agent và MCP trong repo, tìm secret bị lộ, quyền quá rộng và prompt có dấu hiệu nguy hiểm; chỉ đề xuất thay đổi, chưa sửa file”.
Cách làm này giữ người dùng trong vòng duyệt. Không nên cấp quyền rộng hoặc đưa API key thật vào prompt chỉ để chạy nhanh.
ECC giúp agent làm việc như một quy trình kỹ thuật có kiểm tra, thay vì một hộp chat chỉ sinh mã.
Ông T
Chỉ cài ECC từ repo, package, plugin và kênh chính thức được README nêu.
Không đưa API key vào prompt hoặc commit vào repo.
Xem kỹ scope, hook profile và quyền trust trước khi xác nhận.
VI.Lỗi hay gặp và cách xử lý
A.Cài trùng nhiều phương thức
Dấu hiệu thường thấy là skills, commands, hooks hoặc cấu hình bị lặp. Nguyên nhân là cài plugin rồi lại chạy full manual install, hoặc dùng Codex sync cùng native plugin. Chọn một phương thức cho mỗi harness; nếu đã chồng lớp, dùng dry-run của đường gỡ phù hợp và xem lại file trước khi xóa.
B.Node, Git hoặc Claude Code không có trên PATH
Lệnh node --version, git --version hoặc claude --version báo không tìm thấy. Hãy cài hoặc sửa công cụ tương ứng, mở lại terminal rồi kiểm tra lại. Claude Code plugin yêu cầu Claude Code 2.1 trở lên.
C.npm báo lỗi version hoặc cache
Kiểm tra version registry bằng npm view ecc-universal version. Đừng tự đổi sang tên package ecc-install, vì đó không phải package npm độc lập. Nếu muốn dùng version cụ thể, giữ đúng package ecc-universal và version được README hướng dẫn.
D.Claude báo marketplace hoặc scope đã tồn tại
Claude Code tự quản lý các lỗi marketplace, plugin và scope. Nếu native command báo đã tồn tại hoặc xung đột scope, dùng guided setup 2.2 hoặc xử lý scope đang xung đột; không cài thêm bản manual để “ghi đè”.
E.Plugin Qoder thiếu tài nguyên
Nếu upload chỉ .qoder-plugin/ hoặc một SKILL.md, Qoder sẽ thiếu các thư mục cần thiết. Tạo ZIP từ thư mục gốc sao cho có cả .qoder-plugin/, skills/, agents/, commands/, hooks/, scripts/ và .mcp.json. MCP của Qoder cũng cần npx và mạng ở lần đầu dùng.
VII.Có nên dùng không
Nên dùng nếu bạn thường xuyên làm việc với Claude Code, Codex hoặc Qoder và muốn agent có quy trình lặp lại, có review, có memory và có kiểm tra bảo mật. Bộ 71 agents, 314 skills, hooks, rules và AgentShield giúp ECC rộng hơn một bộ prompt đơn lẻ.
Giới hạn là mức hỗ trợ khác nhau giữa các harness. Claude Code là môi trường được hỗ trợ tốt nhất; một số adapter khác chỉ có capability giới hạn. Hooks của Codex có cơ chế trust riêng, còn Qoder có yêu cầu đóng gói plugin riêng. Vì vậy, hãy kiểm tra đúng support path trước khi áp dụng cho nhóm.
ECC cũng có nhiều thành phần, nên người mới có thể thấy nhiều lựa chọn về scope, profile, target và hook. Cách an toàn là bắt đầu bằng guided setup, dùng profile nhỏ, kiểm tra bằng dry-run và chỉ thêm rules hoặc capability thật sự cần.
Nếu bạn chỉ cần một prompt ngắn để sửa một lỗi nhỏ, ECC có thể là quá nhiều. Nếu dự án có mã nguồn nhạy cảm, API key hoặc quyền agent rộng, hãy ưu tiên review cấu hình, secrets và quyền trust trước khi bật tự động hóa. OSS của repo được cấp phép MIT; thông tin về dịch vụ hosted cho private repos thuộc ECC Pro, còn quy trình OSS trong repo vẫn là phần bạn tự cài và tự kiểm soát.
Câu hỏi thường gặp
ECC có miễn phí không?
Repo OSS được cấp phép MIT và phần OSS được mô tả là miễn phí. README cũng nêu ECC Pro là GitHub App hosted cho private repos, nhưng chi tiết giá không phải là phần cài đặt OSS này.
ECC có cần GPU không?
Tư liệu được cung cấp không nói ECC cần GPU. Phần chuẩn bị được nêu tập trung vào Node.js, Git, harness như Claude Code hoặc Codex, và một số yêu cầu riêng của Qoder.
ECC chạy được trên Windows không?
Có hướng dẫn Windows dùng PowerShell, Node.js, Git và Claude Code. README chưa khẳng định mọi harness hoặc mọi adapter đều có mức hỗ trợ giống nhau trên Windows.
Có cần clone repo để cài ECC không?
Không cần clone nếu dùng `npx ecc-universal@2.2.3 setup`. Bạn cần checkout khi muốn dùng rules, scripts, plugin Qoder hoặc đường sync Codex cũ.
ECC có an toàn khi dùng API key không?
Repo có AgentShield để quét secrets, permissions, prompt, hooks và MCP config. Tuy vậy, bạn vẫn phải tự kiểm tra quyền, không đưa key vào prompt và chỉ điền các biến môi trường cần thiết.
Có thể cài ECC cho Claude Code và Codex cùng lúc không?
Có. README hỗ trợ Claude Code plugin cùng Codex native plugin, nhưng cảnh báo không chồng nhiều phương thức trong cùng một harness.
ECC khác gì một bộ prompt thông thường?
ECC đóng gói agents, skills, hooks, memory, rules và quy trình kiểm tra thành một hệ thống dùng lại được. Tư liệu không đưa ra so sánh cụ thể với một công cụ khác, nên chưa thể kết luận hơn kém trong mọi trường hợp.


