# ECC: bộ khung kỹ thuật giúp AI viết code có kế hoạch, có kiểm thử — hướng dẫn cài đặt và dùng

> ECC là hệ thống tối ưu cho các "agent harness" như Claude Code và Codex. Nó bổ sung sẵn 71 agent, 314 skill, hook, bộ nhớ và công cụ quét bảo mật AgentShield. Cài bằng một lệnh npx và làm theo trình hướng dẫn trên màn hình, cần Node.js 18 trở lên nên người mới làm được.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-25 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ecc-bo-khung-ky-thuat-cho-claude-code-codex

ECC là một bộ công cụ mã nguồn mở (giấy phép MIT) cài thêm vào trợ lý AI viết code như Claude Code hay Codex. Nó biến trợ lý từ chỗ "chỉ biết viết code theo câu lệnh" thành chỗ làm việc theo quy trình: lập kế hoạch, viết test, làm, tự rà soát, kiểm tra, ghi nhớ và rút kinh nghiệm.

Tác giả tóm quy trình đó trong một dòng: plan, test, implement, review, verify, remember, improve. Thay vì lần nào bạn cũng phải dặn lại "nhớ viết test trước" hay "nhớ kiểm tra bảo mật", bạn cài ECC một lần và các thói quen đó nằm sẵn trong cách trợ lý làm việc.

Repo này hợp với lập trình viên đang dùng Claude Code hằng ngày, và cả người mới muốn trợ lý AI làm việc cẩn thận hơn. Điểm đáng giá nhất là cài đặt có trình hướng dẫn: bạn chạy một lệnh, trả lời vài câu hỏi là xong, không cần tự copy từng thư mục. Repo hiện có khoảng 302.058 sao và 44.559 fork, và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | affaan-m/ECC
- kind | Plugin
- desc | ECC là bộ plugin mã nguồn mở thêm agent, skill, hook và bộ nhớ cho Claude Code, Codex và các công cụ AI viết code khác, giúp AI làm việc có quy trình.
- stars | 302k
- lang | JavaScript
- license | MIT
```

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

ECC không phải một công cụ đơn lẻ mà là cả một hộp đồ nghề. Theo README, bạn nhận được:

- **71 agent chuyên biệt.** Mỗi agent lo một mảng như lập kế hoạch, rà soát code, sửa lỗi build, bảo mật, kiến trúc, hoặc một lĩnh vực chuyên môn. Lợi ích: bạn không phải viết prompt dài để "đóng vai" chuyên gia, vì vai đã được chuẩn bị sẵn.
- **314 skill.** Đây là các bộ hướng dẫn làm việc đóng gói sẵn, gồm TDD (viết test trước), nghiên cứu, bảo mật, tài liệu, frontend, dữ liệu, học máy, vận hành và nhiều thứ khác. Trợ lý gọi đúng skill khi cần nên kết quả ổn định hơn.
- **98 lệnh tắt (command shim).** Đây là các lối vào tiện tay trong lúc ECC chuyển dần sang hướng lấy skill làm chính.
- **Hook và bộ nhớ.** Hook giúp thực thi quy tắc, tóm tắt phiên làm việc, học liên tục và kiểm soát ngữ cảnh. Nhờ vậy trợ lý đỡ "quên" những gì quan trọng giữa các phiên.
- **Rules (quy tắc).** Là các chuẩn bạn muốn trợ lý luôn tuân theo, và bạn chọn theo ngôn ngữ hoặc dự án. Bạn chỉ lấy gói nào mình dùng, không bị nhồi cả đống.
- **AgentShield.** Công cụ quét prompt, hook, cấu hình MCP, quyền truy cập, bí mật (secret) và các file agent. Với người cho AI chạm vào code thật, đây là lớp kiểm tra đáng có.

ECC chạy tốt nhất với Claude Code. Codex và Qoder có đường cài plugin gốc. Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen và vài công cụ khác có bộ chuyển đổi nhưng bị giới hạn chức năng. README nhắc bạn xem bảng trạng thái hỗ trợ trước khi mong đợi mọi thứ chạy giống hệt Claude Code.

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

Theo README và package.json, bạn cần:

- **Node.js 18 trở lên.** Gói chung (ecc-universal) yêu cầu mức này.
- **Git** có trong PATH, nếu bạn cài plugin cho Claude Code.
- **Claude Code phiên bản 2.1 trở lên** có trong PATH, nếu bạn dùng với Claude Code.
- Một cửa sổ terminal. Trên Windows, README khuyên mở **PowerShell** từ menu Start.

README không đòi GPU hay cấu hình máy riêng. File .env.example của repo có liệt kê vài biến như ANTHROPIC_API_KEY hay GITHUB_TOKEN. Mình không thấy README nói bạn bắt buộc điền chúng để cài bằng trình hướng dẫn, nên đừng điền nếu chưa cần.

Repo có thêm một gói Python tên llm-abstraction (cần Python 3.11 trở lên), nhưng README phần cài đặt chính không dùng tới nó. Bạn có thể bỏ qua khi mới bắt đầu.

```note
Chỉ cài ECC từ nguồn chính thức: kho GitHub của tác giả, gói npm ecc-universal và ecc-agentshield, plugin có tên ecc@ecc, và trang ecc.tools. README cảnh báo các bản đăng lại hoặc bản sao của bên thứ ba không được dự án kiểm duyệt và có thể chứa mã độc.
```

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

Có nhiều đường cài. Mình chọn đường README gọi là khuyến nghị: trình hướng dẫn cho Claude Code.

```steps
- Kiểm tra công cụ | Chạy node, git, claude với cờ --version để chắc đã cài
- Chạy trình cài | Gõ lệnh npx ecc-universal@2.2.3 setup
- Chọn tuỳ chọn | Chọn Global user, hook Standard rồi xác nhận
- Mở phiên Claude Code mới | Bắt đầu phiên mới để plugin được nạp
- Xác nhận plugin | Gõ /plugin list và tìm ecc@ecc
```

### Kiểm tra Node.js, Git và Claude Code

Mở terminal (Windows: PowerShell từ menu Start). Gõ ba lệnh dưới đây. Mỗi lệnh phải in ra một số phiên bản. Nếu báo "không tìm thấy lệnh", hãy cài hoặc sửa công cụ đó trước, đừng chạy tiếp.

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

### Chạy trình hướng dẫn cài đặt

Lệnh này tải gói ecc-universal bản 2.2.3 và mở trình hướng dẫn. Bạn không cần clone repo về máy.

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

Trình này kiểm tra các nơi Claude Code đã cài plugin, rồi cài, cập nhật hoặc chuyển ecc@ecc sang phạm vi bạn chọn. Nếu dùng pnpm, Yarn 2 trở lên hoặc Bun, README có lệnh tương đương:

```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, nên dùng npx hoặc nâng cấp Yarn.

Nếu npm báo lỗi phiên bản hoặc bộ nhớ đệm, kiểm tra phiên bản đang có trên registry rồi thử lại:

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

### Chọn tuỳ chọn trong trình cài

Với một máy cá nhân thông thường, README gợi ý chọn **Global user**, chọn hook **Standard**, rồi xác nhận. Người mới cứ làm theo gợi ý này là ổn.

### Mở phiên Claude Code mới

Đóng phiên cũ nếu đang mở, rồi bắt đầu phiên Claude Code mới. Sau đó đi tiếp sang phần kiểm tra.

### Cách khác: lệnh plugin gốc trong Claude Code

Nếu bạn thích gõ ngay trong Claude Code, README cho hai lệnh sau. Chúng cho kết quả giống nhau với trình hướng dẫn:

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

Hoặc bạn có thể khai báo trong file ~/.claude/settings.json:

```json
{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}
```

Chọn một cách thôi. README nhấn mạnh: **không cài chồng nhiều cách vào cùng một công cụ**, vì skill, lệnh và hook có thể bị nhân đôi.

### Thêm rules (tuỳ chọn)

Plugin của Claude Code không phân phối được rules, nên bạn tự thêm gói nào cần. README bắt đầu bằng rules/common cộng một gói theo ngôn ngữ bạn dùng. Ví dụ dưới đây dùng gói typescript, bạn thay bằng ngăn xếp của mình:

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

Các lệnh mkdir và cp kiểu này chạy trong Bash. Trên PowerShell thuần bạn cần lệnh tương đương mà README chưa ghi, nên người dùng Windows có thể mở Git Bash cho bước này. Nếu đã cài plugin, đừng chạy ./install.sh --profile full sau đó.

### Dùng với Codex

Nếu bạn dùng Codex bản mới, README có đường cài plugin gốc:

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

Lệnh cuối chạy từ thư mục repo đã clone. Muốn cấu hình nhiều công cụ cùng lúc (Claude Code, Codex, Kimi Code) trong một luồng có xác nhận, dùng:

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

Bạn có thể chạy thử không ghi gì (dry run) để xem trước:

```bash
npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
```

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

Sau khi cài, mở phiên Claude Code mới và gõ:

```text
/plugin list
```

Nếu thấy ecc@ecc ở trạng thái bật (enabled) là thành công. Với Codex, lệnh codex plugin list --json cho bạn danh sách plugin, và script check-plugin-cache.js kiểm tra bộ nhớ đệm plugin.

Ngoài ra README có lệnh chẩn đoán:

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

Lệnh này ví dụ cho Kimi Code. Mình chưa thấy README nói rõ kết quả in ra trông thế nào, nên tiêu chí chắc chắn nhất vẫn là thấy ecc@ecc trong /plugin list.

Sau khi cài, trong Claude Code có skill cấu hình lại tên /ecc:configure-ecc, dùng được khi bạn muốn đổi phạm vi hoặc hồ sơ hook.

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

README chủ yếu mô tả hệ thống và cách cài, không có kịch bản từng bước cho từng nghề. Các tình huống dưới đây là cách mình áp dụng đúng những gì ECC nói là có: agent lập kế hoạch, rà soát, bảo mật, skill TDD, và công cụ consult.

### Dev mới: làm tính năng nhỏ nhưng có kế hoạch và test

Bạn vừa học lập trình và muốn thêm chức năng "xuất danh sách khách hàng" vào dự án. Thay vì bảo trợ lý "viết cho tôi đi", bạn mở Claude Code trong thư mục dự án và nói:

```text
Hãy lập kế hoạch trước, viết test trước rồi mới làm chức năng xuất danh sách khách hàng ra file CSV. Làm xong hãy tự rà soát lại.
```

Vì ECC có agent lập kế hoạch, rà soát và skill TDD, trợ lý có sẵn công cụ để đi đúng quy trình đó. Kết quả mong đợi là một kế hoạch ngắn, bộ test, phần code và một lượt tự soát lại. Bạn nhìn theo là học được cách làm việc của người có nghề.

> Đừng dặn AI từng thói quen tốt mỗi lần, hãy cài thói quen đó một lần.
>
> — Ông T

### Chủ shop có nhờ dev thuê ngoài: soát bảo mật cấu hình

Bạn là chủ shop online và dev thuê ngoài để lại một dự án có cấu hình Claude Code, hook và MCP. Bạn không đọc nổi code nhưng muốn biết có gì nguy hiểm không. ECC kèm AgentShield, thứ quét prompt, hook, cấu hình MCP, quyền và bí mật. README cũng cho biết gói ecc-agentshield trên npm là nguồn chính thức. Cách chạy chi tiết README đoạn mình đọc được chưa nêu, nên bạn xem tài liệu của AgentShield trong repo trước. Kết quả bạn nhận là một bản báo cáo những điểm đáng ngờ để mang đi hỏi người làm.

### Dev: hỏi ECC nên dùng skill nào

314 skill nghe nhiều và dễ bị lạc. README có lệnh consult để hỏi theo chủ đề:

```bash
npx ecc-universal@2.2.3 consult "security reviews" --target claude
```

Bạn gõ chủ đề (ví dụ "security reviews") và chọn đích là claude. Dùng khi bạn có bài toán rõ nhưng chưa biết skill hay agent nào hợp.

### Nhóm nhỏ: cài gọn chỉ phần cần dùng

Công ty nhỏ không muốn nạp cả kho. README có hồ sơ cài tối thiểu:

```bash
npx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning
```

Lệnh này cài hồ sơ minimal cho Claude Code và thêm khả năng học máy. Bạn thay phần --with theo nhu cầu, miễn là đúng tên khả năng trong tài liệu repo.

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

### Lệnh node, git hoặc claude báo không tìm thấy

Đây là lỗi hay gặp nhất với người mới. README nói rõ: nếu một lệnh kiểm tra phiên bản không chạy, hãy cài hoặc sửa công cụ đó rồi mới chạy lại ECC setup. Sau khi cài xong, mở cửa sổ terminal mới để PATH được nạp.

### Gõ npx ecc-install bị lỗi

README cảnh báo: ecc-install chỉ là tên một file chạy bên trong gói ecc-universal, không phải gói npm riêng. Hãy dùng đúng lệnh npx ecc-universal@2.2.3 setup.

### Skill, lệnh hoặc hook bị nhân đôi

Nguyên nhân thường là bạn cài ECC hai lần vào cùng một công cụ, ví dụ plugin cộng cài thủ công đầy đủ. Làm theo README: dùng danh sách và chẩn đoán trước khi cài lại. Chạy các lệnh sau từ thư mục repo đã clone:

```bash
node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair
```

README nói thao tác này thường khôi phục các file do ECC quản lý mà không phải dựng lại từ đầu. README còn có mục Reset / Uninstall ECC để xem nếu cần gỡ hẳn.

### Lệnh /plugin báo marketplace hoặc plugin đã tồn tại

Đây là lỗi của chính Claude Code, ECC không can thiệp được. README bảo dùng trình hướng dẫn setup, hoặc tự giải quyết phạm vi plugin đang xung đột, và không chồng cài thủ công lên trên.

### npm báo lỗi phiên bản hoặc cache

Chạy npm view ecc-universal version để xem bản đang có, rồi thử lại. Nếu vẫn lỗi, README mời bạn mở mẫu báo lỗi cài đặt trên GitHub hoặc chạy ecc feedback. README nói ECC không tự gửi dữ liệu chẩn đoán.

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

**Điểm mạnh.** Cài một lần là có cả quy trình: kế hoạch, test, rà soát, bảo mật. Có trình hướng dẫn nên người mới cũng làm được, giấy phép MIT, và repo cập nhật đều. Hỗ trợ nhiều công cụ nên bạn không bị khoá vào một chỗ.

**Giới hạn.** Hệ thống rất lớn: 71 agent, 314 skill, 98 lệnh tắt. Người mới dễ choáng, nên bắt đầu với hồ sơ tối thiểu hoặc chỉ plugin chuẩn. Chức năng đầy đủ nhất ở Claude Code, các công cụ khác bị giới hạn, và README dặn xem bảng hỗ trợ trước. Bạn không nên cài chồng nhiều cách vào cùng một công cụ. Ngoài ra, hook và quy tắc chạy ngầm sẽ làm trợ lý chậm lại hoặc "khó tính" hơn cách bạn quen, và README chưa nói gì về chi phí token của việc đó.

Về tiền: bản mã nguồn mở miễn phí. README có nhắc gói ECC Pro dành cho kho riêng tư (GitHub App, trả theo chỗ ngồi), nhưng đó là tuỳ chọn.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần trợ lý trả lời vài câu code lặt vặt, ECC là thừa. Nếu bạn muốn một công cụ nhỏ làm đúng một việc, hãy tìm skill đơn lẻ. ECC đáng dùng khi bạn làm dự án thật, cần quy trình ổn định và muốn AI "có kỷ luật".

Vì ECC chạy hook và cấu hình trong môi trường code của bạn, hãy chỉ cài từ nguồn chính thức, đọc kỹ các lựa chọn trong trình cài, và thử dry-run khi chưa chắc.

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

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

Có. Repo là mã nguồn mở theo giấy phép MIT và README nói bản mã nguồn mở này miễn phí mãi mãi. README có nhắc ECC Pro là GitHub App trả phí cho kho riêng tư, nhưng bạn không cần nó để dùng bản gốc.

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

Tư liệu không nhắc yêu cầu GPU. Điều README đòi hỏi là Node.js 18 trở lên, cùng Git và Claude Code 2.1 trở lên nếu bạn cài plugin cho Claude Code.

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

Có. README có hẳn phần hướng dẫn cho người mới trên Windows: mở PowerShell, kiểm tra node, git, claude rồi chạy npx ecc-universal@2.2.3 setup. Riêng bước thêm rules dùng lệnh kiểu Bash, nên người dùng Windows có thể cần Git Bash.

### ECC khác gì việc tự viết prompt?

ECC đóng gói sẵn quy trình thành agent, skill, hook và bộ nhớ, nên bạn không phải dặn lại mỗi lần. Tác giả mô tả quy trình là lập kế hoạch, test, làm, rà soát, kiểm tra, ghi nhớ và cải thiện. So sánh chi tiết với công cụ khác thì tư liệu chưa có.

### Dùng được với công cụ nào ngoài Claude Code?

README nói ECC chạy tốt nhất với Claude Code, có đường cài plugin gốc cho Codex và Qoder, và bộ chuyển đổi bị giới hạn cho Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen cùng một số công cụ khác. Hãy xem bảng trạng thái hỗ trợ trước khi mong đợi đầy đủ tính năng.

### Dữ liệu và bảo mật có an toàn không?

README nói ECC không tự động tải dữ liệu chẩn đoán lên và kèm AgentShield để quét cấu hình, quyền và bí mật. README cũng cảnh báo bản sao của bên thứ ba có thể chứa mã độc, nên chỉ cài từ nguồn chính thức. Các chi tiết xử lý dữ liệu khác tư liệu chưa nêu.

### Cài hai lần có sao không?

Cài chồng nhiều cách vào cùng một công cụ có thể làm skill, lệnh hoặc hook bị nhân đôi. README khuyên chọn một cách cho mỗi công cụ. Nếu lỡ chồng, dùng list-installed, doctor và repair, hoặc xem mục Reset / Uninstall trong README.
