Thiết kế hệ thống Claude Code với 48 agents chuyên biệt cho workflow dev thực tế

Vì sao 48 agents chuyên biệt đáng quan tâm lúc này

Dùng AI viết code không còn vấn đề “model có biết syntax không”. Vấn đề mới: AI làm sai scope, sửa lan man, bỏ qua security, build không chạy, test không đủ, context phình to sau vài phiên. Một prompt “hãy implement feature X” thường tạo output nhìn ổn nhưng khó merge.

Bài toán thực tế trong team backend/DevOps: một task nhỏ vẫn cần nhiều vai. Có người đọc requirement, người thiết kế, người viết code, người review, người chạy test, người soi security, người sửa CI. Nếu dồn hết vào một Claude Code session, model phải làm quá nhiều việc cùng lúc. Kết quả: reasoning lẫn lộn.

Ý tưởng 48 agents chuyên biệt xử lý đúng điểm này: chia workflow dev thành nhiều vai nhỏ, mỗi agent có nhiệm vụ, context, tiêu chí dừng riêng. Không thần thánh. Nhưng nếu cấu hình đúng, nó biến Claude Code từ “chatbot biết code” thành pipeline kỹ thuật có kiểm soát.

Kiến trúc kỹ thuật: nhiều agent nhỏ tốt hơn một prompt lớn

Một hệ thống Claude Code nhiều agent thường không phải 48 model khác nhau. Thường là 48 “role configuration”: prompt hệ thống, phạm vi file, checklist, output format, rule gọi tool. Model nền có thể vẫn là Claude, nhưng hành vi khác nhau nhờ cấu hình.

Ví dụ nhóm agent hợp lý:

• planner: đọc issue, chia task, xác định file cần đụng
• researcher: đọc codebase, docs, ADR, ticket liên quan trước khi viết code
• implementer: chỉ sửa code theo plan
• code-reviewer: review diff, không viết feature mới
• build-fixer: chạy build/test, sửa lỗi compile hoặc lint
• security-scanner: soi auth, input validation, secret, injection, SSRF
• test-writer: thêm unit/integration test
• memory-curator: tóm tắt quyết định quan trọng sau phiên làm việc

Điểm khác biệt so với workflow “một prompt dài”: mỗi agent có constraint hẹp. Agent review không được tự ý refactor lớn. Agent build-fixer không được đổi behavior business. Agent security chỉ báo risk hoặc patch nhỏ, không viết lại module. Constraint hẹp giúp giảm hallucination và giảm “AI sửa quá tay”.

Một cấu hình đơn giản có thể bắt đầu bằng file YAML như sau:

# .claude/agents/security-scanner.yaml
name: security-scanner
description: "Review security risks in code changes before merge"
scope:
  files:
    - "src/**/*.ts"
    - "src/**/*.js"
    - "app/**/*.py"
    - "api/**/*.go"
  exclude:
    - "node_modules/**"
    - "dist/**"
    - "coverage/**"

rules:
  - "Do not implement new business features"
  - "Focus on authz/authn, input validation, injection, SSRF, secrets, unsafe deserialization"
  - "Flag risk with severity: critical, high, medium, low"
  - "When patching, keep diff minimal"
  - "If evidence is missing, say 'not enough evidence' instead of guessing"

output_format: |
  ## Security Review
  - Summary:
  - Findings:
    - Severity:
      File:
      Line:
      Risk:
      Fix:
  - Safe to merge: yes/no

Planner agent có config khác:

# .claude/agents/planner.yaml
name: planner
description: "Create implementation plan before code changes"
rules:
  - "Read existing code before proposing changes"
  - "List files likely affected"
  - "Break work into steps smaller than 30 minutes"
  - "Do not edit files"
  - "Ask for clarification if requirement changes database schema or public API"

output_format: |
  ## Plan
  Goal:
  Constraints:
  Files to inspect:
  Steps:
  Risks:
  Tests needed:

Workflow chạy nên theo thứ tự cứng, không để agent tự nhảy vai:

# 1. nghiên cứu codebase
claude-code agent run researcher --task "Add password reset API"

# 2. lập plan
claude-code agent run planner --task "Add password reset API"

# 3. implement theo plan đã duyệt
claude-code agent run implementer --task "Implement approved plan in PLAN.md"

# 4. viết test
claude-code agent run test-writer --task "Add tests for changed behavior"

# 5. chạy build và sửa lỗi nhỏ
claude-code agent run build-fixer --task "Run tests and fix build/lint errors"

# 6. review code
claude-code agent run code-reviewer --task "Review current diff"

# 7. scan security
claude-code agent run security-scanner --task "Scan current diff before merge"

Command trên mang tính minh họa. Tên CLI tùy setup Claude Code cụ thể. Phần quan trọng không phải command, mà là contract giữa các agent.

Có 3 nguyên tắc thiết kế đáng giữ:

1. Research trước khi code.
Nguồn gốc hệ thống được nhắc đến có điểm đáng chú ý: ưu tiên nghiên cứu trước khi viết code. Đây là khác biệt lớn. AI thường sai vì sửa file đầu tiên nó thấy. Với repo lớn, agent phải đọc route, service, model, test hiện có trước. Bắt buộc output “Files inspected” giúp audit được nó có hiểu codebase không.

2. Memory cần curate, không dump toàn bộ chat.
“Khả năng học liên tục từ mỗi phiên” nghe hấp dẫn, nhưng nếu lưu bừa mọi thứ vào memory, context nhiễu rất nhanh. Memory tốt chỉ lưu decision bền: convention, kiến trúc, naming, known pitfalls, command test. Không lưu log chat, output lỗi tạm thời, ý tưởng bị reject.

Ví dụ memory record nên ngắn:

# .claude/memory/project.md

## Backend conventions
- API errors use `AppError` with `code`, `message`, `status`.
- Do not throw raw Error from controllers.
- All write endpoints require `requireAuth` middleware.
- PostgreSQL migrations live in `db/migrations`, filename format: `YYYYMMDDHHMM_description.sql`.

## Test commands
- Unit tests: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`

3. Security scan nằm sau diff, không nằm sau production incident.
Security agent không thay thế pentest. Nhưng nó bắt lỗi phổ biến: thiếu authorization ở endpoint mới, log token, query string ghép tay, endpoint nội bộ không guard. Nếu agent chỉ scan sau khi code đã có diff, nó có bằng chứng cụ thể hơn, ít đoán mò hơn.

Use case thực tế: team backend nhỏ dùng agent pipeline để merge an toàn hơn

Giả sử team 5 backend engineers đang maintain API Node.js + PostgreSQL. Sprint có task: thêm password reset flow. Nếu dùng Claude Code kiểu chat đơn, prompt thường là:

“Implement password reset API with email token.”

Kết quả có thể tạo endpoint, bảng token, email service, test sơ sài. Nhưng rủi ro nằm ở chi tiết: token có hash không, TTL bao lâu, token dùng một lần chưa, rate limit có không, endpoint reset có leak user existence không, migration rollback có đúng không.

Với workflow nhiều agent, task bị ép qua pipeline:

• researcher đọc auth module hiện có, mail adapter, migration style
• planner đề xuất bảng password_reset_tokens, TTL 15 phút, token hash bằng SHA-256, không lưu plain token
• implementer sửa controller/service/migration theo plan
• test-writer thêm test cho token expired, token reused, email không tồn tại
• build-fixer chạy pnpm test, pnpm typecheck
• security-scanner check user enumeration, token leakage, missing rate limit
• code-reviewer bắt naming, transaction, edge case

Kết quả không phải “AI code nhanh hơn 10x”. Kết quả thực tế hơn: diff dễ review hơn, lỗi loại phổ biến bị bắt sớm hơn, context quyết định được lưu lại cho task sau. Senior engineer vẫn phải duyệt plan và diff. Nhưng thời gian họ dùng chuyển từ gõ boilerplate sang kiểm soát thiết kế.

Use case khác: DevOps sửa pipeline build. Agent build-fixer chỉ được đọc log CI, sửa config nhỏ, không đụng business code. Agent reviewer kiểm tra nó có disable test hay bỏ lint để “fix xanh” không. Constraint này cực quan trọng, vì AI rất hay chọn đường ngắn: tắt rule thay vì sửa nguyên nhân.

Cách bắt đầu nhỏ, không cần đủ 48 agents

48 agents nghe lớn. Không nên copy nguyên bộ rồi bật hết. Team nên bắt đầu với 6 agent có ROI cao nhất:

1. researcher
2. planner
3. implementer
4. test-writer
5. build-fixer
6. security-scanner

Sau 2-3 tuần, xem log task nào lặp lại nhiều rồi tách thêm agent. Ví dụ repo có nhiều migration lỗi thì thêm migration-reviewer. Team frontend nhiều accessibility issue thì thêm a11y-reviewer. Team platform hay đụng Terraform thì thêm terraform-plan-reviewer.

Mỗi agent cần 4 thứ:

• nhiệm vụ rõ
• quyền sửa file rõ
• output format cố định
• tiêu chí dừng rõ

Nếu agent không có tiêu chí dừng, nó sẽ tiếp tục “cải thiện” đến khi phá scope. Ví dụ build-fixer nên có rule: “sửa tối đa 3 file, nếu lỗi liên quan design thì dừng và báo”. Đây là guardrail đơn giản nhưng hữu dụng.

Một checklist agent tốt:

## Agent Definition Checklist

- [ ] Agent có một nhiệm vụ chính, không kiêm nhiều vai
- [ ] Có danh sách file được phép đọc/sửa
- [ ] Có rule "không làm gì"
- [ ] Có output format để người review đọc nhanh
- [ ] Có command kiểm chứng kết quả
- [ ] Có mức escalation khi thiếu context

Kết luận: agent nhiều không quan trọng bằng boundary rõ

48 agents chuyên biệt đáng học vì tư duy hệ thống: chia việc AI theo role kỹ thuật, ép research trước code, lưu memory có chọn lọc, scan security trước merge.

Takeaway cụ thể:

• Đừng bắt một Claude session làm planner, coder, reviewer, security cùng lúc.
• Bắt đầu với 6 agent lõi, chạy theo pipeline cố định.
• Memory chỉ lưu convention và decision bền, không lưu rác phiên chat.

AI coding hiệu quả không đến từ prompt dài hơn. Nó đến từ workflow có boundary, evidence, và bước kiểm chứng rõ.