# ECC: nâng cấp AI agent thành hệ thống kỹ thuật — hướng dẫn cài đặt và dùng

> ECC là bộ công cụ mã nguồn mở giúp AI agent lập kế hoạch, viết mã, kiểm thử, tự review, ghi nhớ và cải thiện quy trình. Repo phù hợp nhất với Claude Code, đồng thời có đường cài đặt cho Codex và Kimi Code; cách cài khá đơn giản nếu máy đã có Node.js và công cụ tương ứng.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-06 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/ecc-nang-cap-ai-agent-huong-dan-cai-dat

ECC là một hệ thống tối ưu hiệu suất cho AI agent, giúp agent làm việc theo quy trình kỹ thuật có tổ chức thay vì chỉ nhận một prompt rồi viết mã. Repo cung cấp skills, agents, hooks, rules, memory và công cụ quét bảo mật để hỗ trợ từ lập kế hoạch đến kiểm tra kết quả.

ECC phù hợp với lập trình viên, nhóm phát triển phần mềm, người mới dùng Claude Code hoặc Codex và những ai muốn biến các quy trình lặp lại thành kỹ năng dùng lại được. Điểm đáng giá nhất là bạn cài một lần, sau đó agent có thể lập kế hoạch, kiểm thử, review trong ngữ cảnh mới, ghi nhớ điều quan trọng và dần cải thiện cách làm việc.

Repo hiện có khoảng 302257 sao và 44585 fork. Dự án dùng giấy phép MIT, có mã nguồn JavaScript chính và vẫn còn được cập nhật. ECC hoạt động tốt nhất với Claude Code, có đường tích hợp native cho Codex và có các adapter giới hạn khả năng cho nhiều harness khác.

```repo
- repo | affaan-m/ECC
- kind | Skill
- desc | ECC bổ sung kỹ năng, bộ nhớ, quy trình kiểm thử và bảo mật cho Claude Code, Codex cùng nhiều AI agent khác.
- stars | 302k
- lang | JavaScript
- license | MIT
```

## ECC làm được gì

- **Đưa agent vào quy trình kỹ thuật có thứ tự.** ECC tổ chức chuỗi `plan -> test -> implement -> review -> verify -> remember -> improve`. Nhờ vậy, agent có xu hướng làm rõ kế hoạch, kiểm tra thay đổi và nhìn lại kết quả thay vì chỉ trả về một đoạn mã.

- **Cung cấp nhiều agent chuyên môn.** Repo có 71 agents cho lập kế hoạch, review, sửa lỗi build, bảo mật, kiến trúc và các công việc theo miền. Bạn có thể dùng đúng loại agent cho từng việc thay vì giao mọi nhiệm vụ cho một phiên làm việc chung.

- **Cung cấp thư viện kỹ năng dùng lại.** ECC có 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à phần hữu ích khi bạn thường xuyên làm những việc giống nhau nhưng không muốn viết lại hướng dẫn trong từng prompt.

- **Giữ lại kinh nghiệm giữa các phiên.** Hooks, memory, session summaries, continuous learning và instincts giúp agent lưu những điều cần thiết, kiểm soát ngữ cảnh và biến các cách làm hiệu quả thành quy trình có thể tái sử dụng.

- **Hỗ trợ command và cách gọi quen thuộc.** Repo có 98 legacy command shims, tạo các điểm vào thuận tiện trong giai đoạn ECC chuyển sang mô hình skills-first. Người đã quen với command cũ có thể tiếp tục làm việc trong khi chuyển dần sang skills.

- **Áp dụng rules theo nhu cầu.** Bạn có thể bật `rules/common` cùng một bộ rule theo ngôn ngữ hoặc framework đang dùng. Cách này giúp agent tuân thủ các tiêu chuẩn phù hợp mà không phải nạp mọi rule vào mọi dự án.

- **Quét rủi ro bằng AgentShield.** AgentShield kiểm tra prompt, hooks, cấu hình MCP, quyền truy cập, secrets và các file 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.

- **Dùng được với nhiều harness.** Claude Code là đường tích hợp chính. Repo cũng có native plugin cho Codex, đường guided setup cho Claude Code, Codex và Kimi Code, cùng adapter cho Cursor, Antigravity, Gemini, OpenCode, CodeBuddy, JoyCode, Qwen, Zed, Hermes và OpenClaw. Khả năng của từng harness không hoàn toàn giống nhau.

- **Có thể cấu hình lại sau khi cài.** Wizard cho phép thay đổi scope, cập nhật ECC hoặc đổi hook profile. Với Claude Code, bạn có thể chọn phạm vi user, project hoặc local trong quy trình guided setup.

## Cần chuẩn bị gì

- Máy có Node.js 18 trở lên nếu dùng gói `ecc-universal`. Đây là yêu cầu bắt buộc của universal package.
- Git nếu bạn cài plugin Claude Code theo cách native, clone repo để cài rule, hoặc dùng đường cài đặt Codex cũ.
- Claude Code 2.1 trở lên nằm trên `PATH` nếu bạn dùng Claude Code plugin setup.
- PowerShell trên Windows nếu đi theo hướng dẫn Windows trong README. Repo có quy trình chạy trên Windows.
- Codex nếu muốn cài native plugin cho Codex. Codex quản lý trạng thái plugin trong `CODEX_HOME` đang hoạt động.
- Python 3.11 trở lên nếu bạn sử dụng phần Python của repo, vì `pyproject.toml` yêu cầu phiên bản này.
- Kết nối mạng khi cài gói hoặc dùng các thành phần cần tải tài nguyên. Đường Qoder MCP được README ghi rõ cần `npx` và mạng ở lần dùng đầu tiên.
- Một API key chỉ khi tính năng hoặc provider bạn chọn yêu cầu. File `.env.example` liệt kê các tên `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, `ASTRAFLOW_API_KEY`, `ASTRAFLOW_CN_API_KEY` và `ATLAS_API_KEY`. README được cung cấp không nói mọi key đều bắt buộc.

```note
Chỉ cài ECC từ các kênh chính thức được README nêu. Không dùng bản re-upload hoặc mirror không rõ nguồn gốc. Đặc biệt, hãy xem kỹ trước khi chạy package code và không dán API key vào prompt, log hoặc file chia sẻ công khai.
```

## Cài đặt từng bước

```steps
- Kiểm tra môi trường | Xác nhận Node.js, Git và công cụ agent đã có trên PATH
- Chọn một đường cài | Dùng guided setup cho Claude Code, Codex hoặc Kimi Code
- Chạy trình cài đặt | Cài plugin và chọn scope, profile phù hợp
- Xác minh plugin | Kiểm tra danh sách plugin hoặc chạy lệnh doctor/dry-run
- Thêm rule nếu cần | Sao chép rule chung và rule theo stack từ một checkout đã xem xét
```

### Kiểm tra công cụ trước khi cài

Trên Windows, mở PowerShell từ Start Menu. Trên macOS hoặc Linux, mở terminal. Kiểm tra các công cụ trước khi chạy wizard:

```powershell
node --version
git --version
claude --version
```

Ba lệnh này chỉ kiểm tra phiên bản. Nếu một lệnh báo không tìm thấy, bạn cần cài hoặc sửa PATH của công cụ đó rồi mới chạy ECC. Với guided setup cho Claude Code, README yêu cầu Node.js 18 trở lên, Git và Claude Code 2.1 trở lên.

### Cài guided setup cho Claude Code

Đây là đường được README khuyến nghị cho plugin Claude Code:

```bash
npx ecc-universal@2.2.3 setup
```

Wizard sẽ kiểm kê marketplace chính thức và các scope Claude hiện có trước khi thay đổi. Với thiết lập cá nhân thông thường trên Windows, chọn **Global user**, chọn hook **Standard**, rồi xác nhận. Sau khi cài, mở một phiên Claude Code mới.

Bạn cũng có thể dùng package runner khác:

```bash
pnpm dlx ecc-universal@2.2.3 setup
yarn dlx ecc-universal@2.2.3 setup
bunx ecc-universal@2.2.3 setup
```

Yarn Classic 1 không có `yarn dlx`. Khi đó README gợi ý dùng `npx`, cài package global hoặc nâng cấp Yarn để chạy một lần.

Nếu npm báo lỗi version hoặc cache, kiểm tra version trên registry:

```bash
npm view ecc-universal version
```

Nếu muốn cài nhiều harness trong một quy trình có xem xét, dùng:

```bash
npx ecc-universal@2.2.3 install --guided
```

Wizard cho phép chọn Claude Code, Codex và Kimi Code, hiển thị kênh cài đặt cùng đích đến, chạy preflight trước lần ghi đầu tiên và hỏi xác nhận cuối.

### Cài native plugin cho Claude Code

Nếu bạn chọn cách native, mở Claude Code rồi chạy:

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

Hai lệnh này lần lượt thêm marketplace và cài plugin `ecc@ecc`. Sau khi chọn đường native, dừng ở đó. Không chạy thêm một bản cài thủ công đầy đủ vào Claude Code, vì có thể làm trùng skills, commands, hooks hoặc cấu hình.

Sau khi plugin đã cài, lệnh cấu hình bên trong Claude Code là:

```text
/ecc:configure-ecc
```

Lệnh này chỉ dùng được sau lần cài plugin đầu tiên. Nó không thay thế lệnh `/plugin` tích hợp sẵn của Claude Code.

### Cài native plugin cho Codex

Với Codex hiện đại, README cung cấp các lệnh sau:

```bash
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js
```

Hai lệnh `add` có tính idempotent, nên có thể chạy lại để kiểm tra hoặc cập nhật theo quy trình của Codex. Codex chỉ có một trạng thái plugin đang bật trong `CODEX_HOME`, không có các scope `user`, `project`, `local` như Claude Code. Hook native của Codex cần bạn quyết định tin cậy rõ ràng.

Trong Codex, dùng skill sau khi plugin đã cài:

```text
$configure-ecc
```

Nếu muốn cập nhật plugin native về sau, README nêu quy trình:

```bash
codex plugin marketplace upgrade ecc
codex plugin add ecc@ecc
```

### Dùng đường cài đặt Codex cũ khi thật sự cần

README vẫn giữ đường sync cũ cho người cần sao chép và hợp nhất cấu hình vào `~/.codex`. Hãy chạy Codex ít nhất một lần để `~/.codex/config.toml` tồn tại, sau đó clone repo và cài dependency:

```bash
git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.sh
```

Đây là đường tương thích cũ, không cần dùng nếu bạn đã chọn native plugin. Không dùng native marketplace plugin chồng lên đường sync cũ.

Để kiểm tra trước khi gỡ lớp legacy:

```bash
node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
```

Nếu kết quả phù hợp, có thể gỡ lớp đó bằng:

```bash
node scripts/ecc.js uninstall --legacy-codex-sync
```

### Thêm rules từ một checkout

Plugin Claude Code không phân phối `rules`. Nếu cần rule, clone repo rồi sao chép rule chung và rule theo stack:

```bash
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 stack
```

Thay `rules/typescript` bằng pack phù hợp với stack của bạn. README khuyên bắt đầu với `rules/common` và chỉ một pack ngôn ngữ hoặc framework thực sự dùng. Nếu đã cài plugin, không chạy thêm `./install.sh --profile full`.

## Kiểm tra đã chạy được chưa

Với Claude Code trên Windows, mở phiên mới và chạy:

```text
/plugin list
```

Kết quả mong đợi là plugin `ecc@ecc` đã được bật. Nếu dùng Codex, kiểm tra JSON danh sách plugin:

```bash
codex plugin list --json
```

Sau đó kiểm tra cache:

```bash
node scripts/codex/check-plugin-cache.js
```

Nếu chưa muốn ghi thay đổi, dùng dry-run để xem lựa chọn có hợp lệ không:

```bash
npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
npx ecc-universal@2.2.3 install --profile core --target kimi --dry-run
```

README cũng có lệnh doctor cho Kimi Code:

```bash
npx ecc-universal@2.2.3 doctor --target kimi
```

Nếu cài bị trùng hoặc cấu hình có vẻ lặp, đừng cài lại ngay. README hướng dẫn đi tới phần Reset / Uninstall ECC và kiểm tra lớp cài hiện có trước.

## Dùng vào việc thật

### Lập kế hoạch một tính năng trước khi viết mã

Một dev nhận yêu cầu thêm chức năng xuất hóa đơn cho ứng dụng bán hàng. Thay vì yêu cầu agent viết ngay, bạn có thể giao việc theo hướng lập kế hoạch:

```text
Hãy phân tích yêu cầu xuất hóa đơn. Trước tiên hãy lập kế hoạch, xác định các file cần sửa, rủi ro và cách kiểm thử. Chưa viết mã cho đến khi kế hoạch rõ ràng.
```

ECC cung cấp agents và skills cho planning, architecture, testing và domain work. Kết quả mong đợi là một kế hoạch có phạm vi, điểm cần kiểm tra và hướng triển khai rõ hơn.

### Sửa lỗi build và kiểm tra thay đổi

Một nhóm vừa nâng cấp dependency và pipeline không còn build được. Người phụ trách có thể yêu cầu agent tập trung vào build repair:

```text
Hãy điều tra lỗi build hiện tại. Chỉ ra nguyên nhân, đề xuất thay đổi nhỏ nhất, chạy hoặc bổ sung kiểm thử phù hợp, rồi tự review thay đổi từ một ngữ cảnh mới.
```

ECC được thiết kế để đi qua các bước test, implement, review và verify. Lợi ích thực tế là agent phải chứng minh thay đổi có thể kiểm tra được thay vì chỉ nói rằng lỗi đã được sửa.

### Review bảo mật cho một repo có MCP và hooks

Một dev chuẩn bị đưa cấu hình MCP, hooks và file agent vào dự án nội bộ. Có thể yêu cầu kiểm tra tập trung:

```text
Hãy review cấu hình agent hiện tại cho prompt injection, quyền truy cập quá rộng, secrets, MCP config và hooks. Liệt kê rủi ro theo mức độ và đề xuất cách giảm quyền an toàn hơn.
```

AgentShield được đưa vào để quét prompts, hooks, MCP config, permissions, secrets và agent files. Kết quả phù hợp để làm checklist trước khi chia sẻ cấu hình hoặc chạy trong repo quan trọng.

### Chuẩn hóa công việc lặp lại của nhóm

Một nhóm thường xuyên tạo tài liệu release, viết test và review pull request. Thay vì ghi lại hướng dẫn dài trong từng cuộc trò chuyện, nhóm có thể chọn skills tương ứng, thêm `rules/common` và một rules pack theo stack, rồi yêu cầu agent dùng đúng quy trình.

```text
Hãy dùng quy trình review của dự án: kiểm tra thay đổi, đối chiếu test, rà soát bảo mật, ghi lại điểm chưa chắc chắn và tạo bản tóm tắt để người phụ trách duyệt.
```

Hooks, memory, session summaries và continuous learning giúp các phiên sau giữ lại những điều cần thiết. Kết quả là các thành viên nhận được cách làm nhất quán hơn giữa nhiều phiên làm việc.

> Khi agent biết lập kế hoạch, kiểm tra và ghi nhớ, bạn đang xây một quy trình kỹ thuật chứ không chỉ gọi một chatbot.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Lệnh `node`, `git` hoặc `claude` không được nhận diện

Đây thường là lỗi công cụ chưa cài hoặc chưa có trên `PATH`. Chạy lại các lệnh kiểm tra phiên bản; nếu lệnh nào thất bại, cài hoặc sửa công cụ đó trước khi chạy wizard. Với Claude Code, cần phiên bản 2.1 trở lên theo README.

### Npm báo lỗi version hoặc cache

Đừng tự đoán tên package hoặc đổi sang một nguồn không rõ. Kiểm tra version bằng:

```bash
npm view ecc-universal version
```

Sau đó dùng đúng package name `ecc-universal` và version được README hướng dẫn. README cũng lưu ý version pin không thay thế việc xem xét source và tính toàn vẹn của registry.

### Plugin hoặc command bị trùng

Nguyên nhân thường là cài nhiều phương thức vào cùng một harness, chẳng hạn plugin Claude Code cùng bản cài thủ công, hoặc Codex native plugin cùng đường sync cũ. ECC khuyên chỉ chọn một đường cho mỗi harness. Nếu đã cài chồng, dùng quy trình Reset / Uninstall ECC hoặc các lệnh kiểm tra trước khi sửa tiếp.

### Claude Code báo marketplace hoặc scope đã tồn tại

Đây là phần do Claude Code quản lý. ECC không can thiệp được parser tích hợp của Claude Code. Hãy kiểm tra scope plugin đang có, hoặc dùng guided setup 2.2 để xử lý scope; không thêm một bản manual install khác.

### Chạy đường Codex cũ nhưng thiếu cấu hình

Đường `scripts/sync-ecc-to-codex.sh` yêu cầu Codex đã chạy ít nhất một lần để `~/.codex/config.toml` tồn tại. Nếu chưa có file này, mở Codex trước rồi mới chạy sync. Khi muốn gỡ, hãy dùng `--dry-run` trước để xem các file sẽ bị tác động.

## Có nên dùng không

ECC đáng dùng nếu bạn đã dùng Claude Code hoặc Codex thường xuyên và muốn agent làm việc theo quy trình ổn định hơn. Số lượng skills, agents, hooks, memory và rules rất lớn, phù hợp với dự án cần planning, test, review, security hoặc tài liệu lặp lại. Giấy phép MIT cũng thuận lợi cho việc thử nghiệm và tích hợp nội bộ.

Giới hạn chính là độ phức tạp. ECC không phải một chatbot độc lập; hiệu quả phụ thuộc vào harness, phiên bản, scope, hook profile và cách bạn chọn skills. README cũng nói rõ các harness khác nhau có mức hỗ trợ khác nhau, nên không nên mặc định rằng Cursor, OpenCode, Gemini, Zed hay các adapter khác có đầy đủ tính năng như Claude Code.

Bạn cũng cần tránh cài chồng nhiều phương thức. Nếu chỉ cần một prompt đơn giản, một script nhỏ hoặc một extension có phạm vi hẹp, ECC có thể nhiều hơn nhu cầu. Nếu dự án cần quy trình agent có kiểm thử, review, bộ nhớ, rule và kiểm tra bảo mật, đây là lựa chọn đáng thử. Hãy bắt đầu bằng guided setup, chọn ít rule cần thiết và kiểm tra dry-run trước khi đưa vào repo quan trọng.

## Câu hỏi thường gặp

### ECC có miễn phí không?

Repo là mã nguồn mở theo giấy phép MIT và phần OSS được README mô tả là miễn phí. ECC Pro là GitHub App lưu trữ cho private repo, có mức phí riêng; bạn không cần mua ECC Pro để dùng phần mã nguồn mở.

### ECC có cần GPU không?

Tư liệu được cung cấp không nói ECC cần GPU. README tập trung vào Node.js, Git, Claude Code, Codex, Kimi Code và các harness tương ứng, nên chưa có cơ sở để khẳng định yêu cầu GPU.

### ECC chạy được trên Windows không?

Có hướng dẫn Windows dùng PowerShell. README yêu cầu kiểm tra Node.js, Git và Claude Code rồi chạy `npx ecc-universal@2.2.3 setup`.

### Có cần API key ngay khi cài không?

README chỉ liệt kê các biến như `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, `ASTRAFLOW_API_KEY` và `ATLAS_API_KEY` trong `.env.example`. Tư liệu không nói tất cả đều bắt buộc cho lần cài plugin, nên key nào cần phụ thuộc vào provider hoặc tính năng bạn chọn.

### Có thể cài ECC cho Claude Code và Codex cùng lúc không?

Có. README nói Claude Code plugin và Codex native plugin có thể dùng cùng nhau. Tuy nhiên, mỗi harness chỉ nên chọn một phương thức cài; không chồng Claude manual install hoặc Codex sync với phương thức native tương ứng.

### ECC có an toàn với dữ liệu riêng tư không?

README cảnh báo chỉ cài từ các kênh chính thức và có AgentShield để quét prompt, hooks, MCP config, permissions, secrets và agent files. Tư liệu không cam kết rằng mọi dữ liệu đều được giữ cục bộ hoặc không bao giờ rời máy, nên bạn vẫn cần tự kiểm tra quyền và API key.

### ECC khác gì một bộ prompt thông thường?

ECC là một hệ thống gồm agents, skills, hooks, memory, rules, commands và AgentShield. Mục tiêu là đưa agent qua planning, test, implementation, review, verification và learning, thay vì chỉ cung cấp một prompt đơn lẻ.
