Bài 2 — Thiết kế vai trò và hợp đồng giao tiếp giữa các agent

Mỗi agent là một hàm có hợp đồng rõ ràng

Sai lầm phổ biến nhất khi bắt đầu là để các agent "nói chuyện tự do" bằng văn xuôi. Kết quả: reviewer không biết coder đã làm gì, tester không rõ tiêu chí. Giải pháp là coi mỗi agent như một hàm có hợp đồng (contract): đầu vào rõ, đầu ra có cấu trúc, tiêu chí thành công minh bạch.

Định nghĩa từng vai trò bằng bảng trách nhiệm

Điểm mấu chốt ở cột "Không được làm": nó ngăn các vai trò lấn sân, giữ cho review thật sự độc lập.

Hợp đồng đầu ra dạng cấu trúc

Hãy bắt buộc mỗi agent trả về JSON theo schema, thay vì văn xuôi. Ví dụ output của Planner:

{
  "tasks": [
    {
      "id": "T1",
      "title": "Tạo bảng password_reset_tokens",
      "depends_on": [],
      "acceptance": "Migration chạy được, có cột token_hash, expires_at"
    },
    {
      "id": "T2",
      "title": "Endpoint POST /password/reset",
      "depends_on": ["T1"],
      "acceptance": "Trả 200 và tạo token đã hash"
    }
  ]
}

Và output của Reviewer:

{
  "verdict": "changes_requested",
  "issues": [
    {"severity": "high", "line": 42, "msg": "Token lưu plaintext, cần hash"}
  ]
}

Nhờ có verdict, orchestrator (bộ điều phối) biết chính xác nên đi tiếp hay quay lại — không cần "đoán ý" từ văn xuôi.

Các bước thiết kế hợp đồng cho đội của bạn

• Liệt kê các vai trò tối thiểu (thường 4: planner/coder/reviewer/tester).
• Với mỗi vai trò, viết một câu "nhiệm vụ duy nhất" (single responsibility).
• Định nghĩa schema đầu ra bằng JSON, gồm ít nhất một trường trạng thái để máy đọc được (verdict, status, pass).
• Ghi rõ tiêu chí chấp nhận (acceptance) để reviewer/tester có mốc phán xét.
• Viết "điều cấm" cho mỗi vai trò để tránh lấn sân.
• Thử với một task nhỏ, xem output có parse được bằng code không.

System prompt mẫu cho Reviewer

Bạn là Reviewer. Chỉ đọc diff và task, KHÔNG sửa code.
Trả về JSON đúng schema: {verdict, issues[]}.
verdict ∈ {approved, changes_requested}.
Ưu tiên: lỗi logic > bảo mật > hiệu năng > phong cách.
Nếu không chắc, đánh dấu severity=low và nêu câu hỏi.

Khung tư duy: "Ba câu hỏi hợp đồng"

Trước khi triển khai bất kỳ agent nào, tự hỏi:

• Agent này nhận đúng những gì? (không thừa, không thiếu)
• Agent này trả ra cấu trúc gì mà máy đọc được?
• Ai tiêu thụ output này và họ cần trường nào?

Sai lầm thường gặp

• Output văn xuôi tự do: orchestrator phải dùng regex mong manh để đoán trạng thái → dễ vỡ.
• Vai trò chồng lấn: coder vừa viết vừa tự duyệt, làm review mất tính độc lập.
• Thiếu trường trạng thái máy đọc được, buộc bạn phải parse ngôn ngữ tự nhiên.
• Schema quá phức tạp ngay từ đầu: bắt đầu với 3-4 trường cốt lõi, mở rộng dần khi cần.
• Quên "điều cấm": agent tự ý mở rộng phạm vi, phá vỡ ranh giới vai trò.