Chương 11
Multi-Agent & Agent Orchestration

Cho đến trước chương này, workflow chuẩn là một agent duy nhất đọc spec, lập kế hoạch, viết code, chạy test và tự sửa lỗi. Cách làm đó rất hiệu quả cho feature nhỏ hoặc bounded context ngắn.

Khi dự án lớn hơn, cần frontend, backend, testing chạy đồng thời và context của một feature vượt giới hạn cửa sổ nhớ, mô hình single-agent bắt đầu bộc lộ giới hạn kiến trúc. Vấn đề không phải agent kém thông minh, mà do bài toán thực tế đòi hỏi chuyên môn hóa và song song hóa.

Kỹ sư giỏi trong tương lai không phải là người code nhanh nhất, mà là người biết tổ chức đội ngũ AI hiệu quả nhất: phân việc đúng, resolve conflict đúng thời điểm và đảm bảo output đi đúng hướng sản phẩm.

Context window dù 200K hay 2M tokens vẫn là tài nguyên hữu hạn. Một codebase production thường gồm frontend, backend, DB schema, tests và specs; khi dồn mọi thứ vào cùng context, không gian cho reasoning chất lượng cao bị co lại rất nhanh.

Điểm quan trọng là scale context không giải quyết triệt để. Khi enterprise codebase tăng lên hàng trăm nghìn dòng, lượng tokens tăng nhanh hơn khả năng giữ tập trung của một agent duy nhất.

frontend/src/ ~15,000 lines
backend/src/  ~25,000 lines
shared/types/ ~3,000 lines
tests/        ~12,000 lines
docs/specs/   ~8,000 lines

Enterprise scale: 500K+ lines ~7.5M tokens - vẫn không fit kể cả context 1M.

Khi một model phải track quá nhiều concerns cùng lúc, attention bị phân tán và chất lượng suy luận theo từng concern giảm. Agent có thể làm nhiều thứ, nhưng làm đồng thời CSS animation, SQL optimization, business logic và test strategy trong một session thường dẫn đến output "đủ dùng" chứ không xuất sắc.

Chuyên môn hóa không phải vì agent thiếu intelligence; đó là cơ chế để dồn attention vào một domain, giữ best-practice context sâu và giảm rework ở integration phase.

Nhiều task trong một feature cycle độc lập tự nhiên: backend API, frontend scaffolding, docs hoặc worker service có thể triển khai song song ngay sau khi contract được define. Đây là lợi ích trực tiếp lên developer experience vì giảm idle time.

Thất bại phổ biến nhất của multi-agent không nằm ở chất lượng từng agent, mà nằm ở communication drift. Khi backend đổi field hoặc schema mà frontend không biết ngay, integration sẽ đổ vỡ vì assumptions lệch nhau.

POST /auth/register -> Response { user_id, created_at }
GET /orders -> Response { orders, meta }
Known breaking change: "order_list" -> "orders"
Impact: Frontend parser phải update ngay.

Xung đột thường xảy ra trên shared resources như `api_contracts.yaml`, DB schema hoặc config hệ thống. Protocol đúng là mọi write vào shared artifacts phải qua approval của Lead Agent.

Mỗi agent cần domain rõ ràng, overlap thấp, coupling giao tiếp tối thiểu và có khả năng fail/restart độc lập. Không phải dự án nào cũng cần tăng số lượng agent, vì orchestration overhead cũng là chi phí thật.

Trong AI-assisted development, knowledge transfer là điểm nghẽn lớn: conventions, performance patterns, security gotchas và domain idioms thường nằm trong đầu senior chứ không nằm trong README. SKILL.md biến kiến thức ngầm đó thành quy tắc thực thi được.

SKILL.md không phải tutorial để con người đọc; nó là playbook vận hành để agent làm đúng chuẩn senior ngay cả khi người chạy agent còn mới với codebase.

Một skill tối thiểu cần metadata, role rõ, workflow từng bước, patterns/anti-patterns và checklist tự kiểm tra. Cấu trúc này buộc knowledge phải cụ thể thay vì chung chung.

---
name: [Skill Name]
version: 1.0.0
author: @senior-dev
domain: [backend|frontend|testing|database|security|devops]
tools: [Cline, Cursor, Claude Code]
trigger: [Khi nào agent apply skill]
---
ROLE -> EXPERTISE -> WORKFLOW -> PATTERNS -> ANTI-PATTERNS -> CHECKLIST

Skill này xử lý pain point lớn ở backend data layer: query chậm, index sai thứ tự, pagination kém hiệu quả và N+1. Agent buộc phải đi qua quy trình phân tích access pattern, cardinality và kiểm chứng bằng EXPLAIN ANALYZE.

Mục tiêu của skill này là chuẩn hóa kiểm tra OWASP Top 10 ngay ở lúc implement endpoint, không đợi đến audit muộn. Checklist bắt buộc gồm authentication, authorization, input validation, rate limiting, error leakage, SQL injection và logging dữ liệu nhạy cảm.

Skill mẫu hoàn chỉnh đặt target cụ thể cho Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1 và bundle per route < 150KB gzipped. Nhờ target định lượng, agent có tiêu chuẩn pass/fail rõ.

Patterns:
- Dynamic import cho component nặng
- Dùng Next.js Image thay vì img thường
- useMemo/useCallback để tránh re-render thừa

Anti-patterns:
- useEffect không deps array
- Inline object/function props không memo
- import toàn bộ lodash

Custom skills thường cho ROI cao nhất vì chứa domain knowledge riêng của công ty. Workflow chuẩn: xác định pain point lặp lại, phỏng vấn senior để lấy pattern thật, viết draft theo template, test với agent và iterate 2-3 vòng đến khi stable.

Pre-commit đóng vai trò quality gate cho AI-generated code: format, lint, type-check, secret scan và unit tests trước khi ghi lịch sử Git. Mục tiêu là chuyển effort review của con người sang logic và kiến trúc thay vì style lỗi vặt.

Flow chuẩn: gofmt/prettier -> golangci-lint -> go vet -> gitleaks -> go test -tags=unit
Nếu bước nào fail: chặn commit ngay.
Nếu auto-format có thay đổi: git add -u để re-stage.

Self-healing loop vận hành theo chu trình: hook phát hiện test fail, thu log lỗi, gọi fixer agent với constraints rõ, re-run tests và chỉ cho commit đi tiếp khi pass. Nếu vượt ngưỡng số lần thử thì dừng và escalate cho human review.

Cấu hình hooks trong `.claude/settings.json` cho phép chèn automation vào PreToolUse/PostToolUse: checkpoint trước khi write/edit, auto-format theo ngôn ngữ sau khi write và tự tạo coverage report sau các lệnh test.

PreToolUse: matcher Write|Edit -> append git checkpoint log
PostToolUse: Write.*\.go$ -> gofmt + go vet
PostToolUse: Write.*\.(ts|tsx)$ -> prettier --write
PostToolUse: Bash.*go test -> generate coverage.html

Lab chọn feature Export Report to PDF vì tách tự nhiên thành ba concerns độc lập: UI/UX, business logic và worker xử lý PDF + storage. Đây là điều kiện lý tưởng để thực hành multi-agent orchestration thực chiến.

Lead phải khóa contract trước khi giao việc để sub-agents có thể làm độc lập mà không tạo coupling ngầm. Contract gồm API giữa UI-Backend, job structure giữa Logic-Worker và shared types dùng chung TypeScript/Go.

POST /api/reports/export
Request: { report_type, date_range, format:"pdf" }
Response: { job_id, status_url }

GET /api/reports/jobs/:id
Response: { status: pending|processing|done|failed, download_url?, error? }

ExportJob: { id, report_data, metadata, output_path }

Sau khi contract rõ, Agent A xây UI polling mỗi 3 giây và xử lý loading/error/success; Agent B dựng handlers + query DB + enqueue Kafka; Agent C dựng Kafka consumer, render PDF A4, upload S3 và cập nhật job status.

Khi A/B/C báo DONE, lead làm integration check theo contract, chạy test tích hợp và xử lý mismatch tại điểm giao nhau. Conflict tiêu biểu trong lab là khác biệt naming convention giữa backend và worker (`report_data` vs `reportData`).

Trong team agent, MCP không chỉ để truy cập external resources mà còn để mượn capability liên-agent theo access policy. Ví dụ Frontend Agent cần verify UI bằng dữ liệu thật nhưng chỉ được DB read-only, không được write trực tiếp.

lead-agent: database read_write, github repo:read/issues:write, filesystem .sdd+src+tests
frontend-agent: database read_only (public), filesystem frontend/src + shared_context
backend-agent: database read_write, kafka produce(export-jobs), filesystem backend + .sdd
worker-agent: database read_write, kafka consume(export-jobs), s3 write (non-prod buckets)

Thiết kế này cho phép tách biệt trách nhiệm, giảm blast radius khi sai sót và hỗ trợ audit trail rõ ràng ở cấp quyền truy cập.

Một mô hình advanced là agent publish MCP server để chia sẻ capability cho agent khác. Ví dụ Backend Agent expose `report-data` MCP server; Frontend/Worker gọi qua interface này thay vì đụng trực tiếp DB schema hoặc query logic nội bộ.

@server.tool()
async def get_report_data(report_type, from_date, to_date):
    data = await report_service.fetch(report_type, from_date, to_date)
    return data.to_dict()

# Frontend session gọi MCP server của Backend để preview/report validation.