Phân tích ngược Claude Code Agent Teams: Kiến trúc và giao thức

Giới thiệu

Claude Code (v2.1.47) có một tính năng thử nghiệm mang tên Agent Teams: nhiều phiên Claude Code phối hợp xử lý công việc chung theo mô hình trưởng nhóm và các thành viên. Tôi đang xây dựng Hive, một công cụ điều phối nhiều agent lập trình có mục tiêu tương tự nhưng kiến trúc rất khác, nên tôi muốn hiểu cách tiếp cận của Anthropic vận hành bên trong ra sao.

Bài viết này ghi lại những gì tôi tìm hiểu được thông qua:

1. Đọc tài liệu chính thức
2. Xem xét những dấu vết thực tế mà các phiên làm việc nhóm trước đó để lại trên đĩa
3. Để Claude phân tích tệp nhị phân Claude Code (v2.1.47) nhằm tìm hiểu chi tiết triển khai (ha!)

Mục lục

• 1. Tổng quan kiến trúc
• 2. Danh sách tác vụ dùng chung
• 3. Giao tiếp giữa các agent
• 4. Khởi tạo agent và vòng đời
• 5. Cơ chế kiểm soát chất lượng và hook
• 6. Bài toán chi phí token
• 7. Tóm tắt kiến trúc
• Nguồn tham khảo

1. Tổng quan kiến trúc

Một nhóm agent gồm bốn thành phần:

Toàn bộ lớp phối hợp đều dựa trên tệp. Hệ thống tệp tại ~/.claude/ là nền tảng phối hợp duy nhất:

~/.claude/
├── teams/{team-name}/
│   ├── config.json                  # team membership registry
│   └── inboxes/{agent-name}.json    # per-agent mailbox
└── tasks/{team-name}/
    ├── .lock                        # flock() for concurrent task claiming
    ├── .highwatermark               # auto-increment counter
    ├── 1.json                       # individual task files
    ├── 2.json
    └── ...

Về bản chất, đây là một thiết kế phi tập trung. Trưởng nhóm cũng chỉ là một phiên Claude khác có thêm các công cụ (TeamCreate, TeamDelete, SendMessage). Không có tiến trình chạy nền. Sự phối hợp hình thành từ việc cùng truy cập các tệp dùng chung.

Trong một phiên đang hoạt động, nếu bạn yêu cầu Claude tạo một nhóm để thực hiện một tác vụ nào đó, rồi chạy nội dung sau trong một cửa sổ khác, bạn có thể quan sát hệ thống tệp cập nhật theo thời gian thực.

watch -n 0.5 'tree ~/.claude/teams/ 2>/dev/null; echo "---"; tree ~/.claude/tasks/ 2>/dev/null'

Ví dụ, với câu lệnh sau:

can you spawn an agent team to examine this codebase?
  - have one look for bugs
  - have one look for complexity
  - have one look for good things to call out and play devil's advocate against the other two agents

Tôi quan sát được như sau:

teams
└── code-review
    ├── config.json
    └── inboxes
        ├── bug-hunter.json
        ├── complexity-analyst.json
        ├── devils-advocate.json
        └── team-lead.json

Cấu hình nhóm

Cấu hình nhóm tại ~/.claude/teams/{team-name}/config.json chứa một mảng members mà các thành viên đọc để biết về nhau:

{
  "members": [
    { "name": "team-lead", "agentId": "abc-123", "agentType": "leader" },
    {
      "name": "researcher",
      "agentId": "def-456",
      "agentType": "general-purpose"
    }
  ]
}

Tên là cơ chế định địa chỉ chính (UUID có tồn tại nhưng không được dùng để định tuyến). Mọi hoạt động nhắn tin và giao tác vụ đều dùng trường name.

2. Danh sách tác vụ dùng chung

Định dạng tệp

Mỗi tác vụ được lưu thành một tệp JSON riêng trong ~/.claude/tasks/{team-name}/. Đây là một ví dụ thực tế từ một phiên trước đó:

{
  "id": "1",
  "subject": "Hunt for bugs across the codebase",
  "description": "...",
  "activeForm": "Hunting for bugs",
  "owner": "bug-hunter",
  "status": "completed",
  "blocks": [],
  "blockedBy": []
}

Lược đồ tác vụ:

Kiểm soát đồng thời

Hai tệp đặc biệt phục vụ việc phối hợp:

• .lock: Một tệp 0 byte dùng để loại trừ tương hỗ ở cấp hệ thống tệp (flock()). Có trong cả 42 thư mục tác vụ mà tôi quan sát được trên máy của mình.
• .highwatermark: Chứa một số nguyên duy nhất (ví dụ: "3", "13"). Đây là ID tác vụ khả dụng tiếp theo cho cơ chế tự động tăng.

Nhận tác vụ

Việc nhận tác vụ dùng cơ chế khóa tệp để ngăn tình trạng tranh chấp. Các thành viên ưu tiên nhận tác vụ có ID nhỏ nhất trước. Một tác vụ có mảng blockedBy không rỗng chỉ có thể được nhận khi tất cả tác vụ đang chặn nó đã ở trạng thái kết thúc.

Quan sát: Phần lớn thư mục tác vụ đều trống

Trong số 42 thư mục tác vụ trên máy của tôi, chỉ có 5 thư mục chứa các tệp JSON tác vụ thực sự. 37 thư mục còn lại chỉ có .lock và .highwatermark. Điều này có thể có nghĩa là các tác vụ được dọn dẹp sau khi hoàn thành, hoặc đây là những phiên mà Claude dùng danh sách tác vụ nội bộ (có sẵn từ khi tính năng danh sách tác vụ ra mắt) mà không chia nhỏ thành các tệp tác vụ con.

3. Giao tiếp giữa các agent

Mô hình hộp thư

Mỗi agent có một tệp chứa mảng JSON tại ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Đây là một hộp thư đến thực tế từ một phiên trước đó, trong đó trưởng nhóm giao việc cho một controlplane-agent:

[
  {
    "from": "team-lead",
    "text": "{\"type\":\"task_assignment\",\"taskId\":\"1\",\"subject\":\"Phase 2: Control-plane - remove participants/presence\",\"description\":\"Remove multiplayer code from the control-plane package...\",\"assignedBy\":\"team-lead\",\"timestamp\":\"2026-02-18T02:37:16.890Z\"}",
    "timestamp": "2026-02-18T02:37:16.890Z",
    "read": false
  }
]

Chú ý cách mã hóa JSON lồng trong JSON: trường text là một chuỗi JSON chứa một đối tượng thông điệp đã được tuần tự hóa. Phần bao bên ngoài có các trường from, text, timestamp và read.

Các loại thông điệp

Trường type bên trong phần dữ liệu text hỗ trợ:

Cơ chế chuyển tin

Luồng ghi: Bên gửi thêm một mục mới vào tệp mảng JSON trong hộp thư đến của bên nhận.

Luồng đọc: Bên nhận thăm dò tệp hộp thư đến của chính mình. Các thông điệp mới được chèn vào dưới dạng các lượt hội thoại tổng hợp (chúng xuất hiện như thể do người dùng gửi).

Gửi quảng bá: Thực sự ghi cùng một thông điệp vào tệp hộp thư đến của từng thành viên. Chi phí token tăng tuyến tính theo quy mô nhóm.

Giao tiếp chỉ là ghi nối vào tệp + đọc tệp. Độ trễ giữa lúc gửi và nhận phụ thuộc vào khoảng thời gian giữa các lần thăm dò của bên nhận.

Khả năng theo dõi tin nhắn riêng giữa các thành viên

Khi một thành viên gửi tin nhắn riêng cho thành viên khác, một bản tóm tắt ngắn được đưa vào thông báo trạng thái nhàn rỗi gửi cho trưởng nhóm. Nhờ đó, trưởng nhóm có thể theo dõi việc cộng tác giữa các thành viên mà không nhận toàn bộ nội dung tin nhắn.

4. Khởi tạo agent và vòng đời

Cách các thành viên được tạo

Mỗi thành viên là một tiến trình CLI claude riêng biệt. Trưởng nhóm khởi tạo chúng qua công cụ Task với các tham số team_name và name. Các biến môi trường được thiết lập trên tiến trình được khởi tạo:

• CLAUDE_CODE_TEAM_NAME: được tự động thiết lập cho các thành viên được khởi tạo
• CLAUDE_CODE_PLAN_MODE_REQUIRED: được đặt thành true nếu cần phê duyệt kế hoạch

Khởi tạo ngữ cảnh

Các thành viên nạp cùng ngữ cảnh dự án như bất kỳ phiên mới nào:

• Các tệp CLAUDE.md từ thư mục làm việc
• Các máy chủ MCP
• Các skill
• Câu lệnh khởi tạo từ trưởng nhóm

Lịch sử hội thoại của trưởng nhóm KHÔNG được chuyển sang. Mỗi thành viên bắt đầu một phiên mới, chỉ có câu lệnh khởi tạo làm ngữ cảnh.

Triển khai nội bộ

Qua việc phân tích tệp nhị phân Claude Code v2.1.47, ngữ cảnh của thành viên được quản lý qua AsyncLocalStorage với các trường sau:

• agentId, agentName, teamName
• parentSessionId, color
• planModeRequired

Các hàm nội bộ chính:

• isTeammate() / isTeamLead(): nhận diện vai trò
• waitForTeammatesToBecomeIdle(): cơ chế đồng bộ hóa cơ sở dành cho trưởng nhóm
• getTeammateContext() / setDynamicTeamContext(): quản lý ngữ cảnh khi chạy

Phát hiện trạng thái nhàn rỗi

Sau mỗi lượt LLM, thành viên tự động chuyển sang trạng thái nhàn rỗi và gửi một idle_notification cho trưởng nhóm. Đây là trạng thái nghỉ bình thường, không phải lỗi hay tình trạng ngừng cập nhật. Gửi tin nhắn cho một thành viên đang nhàn rỗi sẽ đánh thức thành viên đó (chu kỳ thăm dò tiếp theo sẽ nhận được tin nhắn trong hộp thư đến).

Giao thức dừng

1. Trưởng nhóm gửi shutdown_request cho một thành viên
2. Thành viên có thể chấp thuận (thoát có kiểm soát) hoặc từ chối (tiếp tục làm việc và nêu lý do)
3. Việc dọn dẹp nhóm qua TeamDelete sẽ xóa ~/.claude/teams/{team-name}/ và ~/.claude/tasks/{team-name}/
4. Dọn dẹp sẽ thất bại nếu vẫn còn thành viên đang hoạt động; phải dừng các thành viên đó trước

Kế thừa quyền

Các thành viên kế thừa chế độ quyền của trưởng nhóm tại thời điểm khởi tạo. Nếu trưởng nhóm chạy với --dangerously-skip-permissions, mọi thành viên cũng vậy. Có thể thay đổi chế độ của từng thành viên sau khi khởi tạo, nhưng không thể cấu hình riêng cho từng thành viên ngay lúc khởi tạo.

5. Cơ chế kiểm soát chất lượng và hook

Agent Teams tích hợp với hệ thống hook của Claude Code để thực thi các yêu cầu về chất lượng:

Hook TeammateIdle

Được kích hoạt khi một thành viên sắp chuyển sang trạng thái nhàn rỗi. Mã thoát 2 gửi nội dung stderr làm phản hồi và ngăn thành viên chuyển sang trạng thái nhàn rỗi, buộc thành viên tiếp tục làm việc.

{
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "my-project"
}

Hook TaskCompleted

Được kích hoạt khi một tác vụ đang được đánh dấu hoàn thành. Mã thoát 2 ngăn việc hoàn thành và gửi lại nội dung stderr làm phản hồi.

{
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "my-project"
}

Hook này được kích hoạt trong hai trường hợp: (1) khi bất kỳ agent nào chủ động đánh dấu một tác vụ là đã hoàn thành qua TaskUpdate, hoặc (2) khi một thành viên trong nhóm agent kết thúc lượt trong khi có các tác vụ đang thực hiện.

Các loại trình xử lý hook

6. Bài toán chi phí token

Các nhóm agent sử dụng lượng token nhiều gấp khoảng 7 lần so với các phiên thông thường khi các thành viên chạy ở chế độ lập kế hoạch. Mỗi thành viên duy trì một cửa sổ ngữ cảnh đầy đủ của riêng mình dưới dạng một phiên chạy Claude riêng biệt.

Mức cơ sở để tham khảo

• Chi phí sử dụng Claude Code trung bình: ~6 USD/lập trình viên/ngày
• Nhóm agent: chi phí tăng thêm so với mức cơ sở gần như tỷ lệ thuận với quy mô nhóm

7. Tóm tắt kiến trúc

Nguồn tham khảo

Tài liệu chính thức

• Các nhóm phiên Claude Code: Kiến trúc
• Chế độ tương tác — Danh sách tác vụ
• Nhóm agent — Giao và nhận tác vụ
• Nhóm agent — Ngữ cảnh và giao tiếp
• Nhóm agent — Dừng các thành viên
• Nhóm agent — Dọn dẹp nhóm
• Nhóm agent — Quyền
• Nhóm agent — Giới hạn
• Nhóm agent — Các phương pháp thực hành tốt nhất
• Các hook
• Chi phí — Chi phí token của nhóm agent
• Cài đặt
• Các agent con

Các dấu vết trên đĩa (Claude Code v2.1.47)

Quan sát được tại /Users/tau/.claude/:

• Các thư mục nhóm có các tệp config.json và inboxes/{agent-name}.json
• Các thư mục tác vụ có .lock, .highwatermark và từng tệp JSON tác vụ riêng
• Thông điệp giao tác vụ mẫu từ team-lead đến cp-agent, có dấu thời gian 2026-02-18T02:37:16.890Z

Phân tích tệp nhị phân

Tệp nhị phân Claude Code v2.1.47. Các hàm nội bộ được xác định qua phân tích chuỗi: getTeamName, getAgentName, getAgentId, isTeammate, isTeamLead, waitForTeammatesToBecomeIdle, getTeammateContext, setDynamicTeamContext, createTeammateContext. Các trường ngữ cảnh AsyncLocalStorage: agentId, agentName, teamName, parentSessionId, color, planModeRequired.

Mã nguồn Hive

• Tài liệu thiết kế kỹ thuật Hive