Kiến trúc Claude Code: Thiết kế agentic harness từ bên trong

Toàn bộ kiến trúc Claude Code không dựa vào các framework agent phức tạp hay nhiều tầng trừu tượng chồng chéo, mà dựa trên một agentic harness tối giản tập trung vào vòng lặp phản hồi môi trường (feedback loop).

Bản chất của harness là lớp mã nguồn bọc quanh các mô hình ngôn ngữ lớn (như Claude 3.5 Sonnet hay Claude 3.7 Sonnet) để quản lý toàn bộ vòng đời thông điệp, thực thi công cụ, kiểm soát cửa sổ ngữ cảnh và duy trì ranh giới an toàn.

Thay vì cố gắng dự đoán mọi đường đi của dữ liệu thông qua các workflow cố định, hệ thống cho phép mô hình ngôn ngữ lớn (LLM) tự định hướng quy trình, ra quyết định sử dụng công cụ và tự điều chỉnh dựa trên kết quả phản hồi thực tế từ môi trường như output của lệnh Bash hay kết quả chạy test.

Harness giữ vai trò điểm tựa điều khiển runtime: nó điều phối các tham số giới hạn lượt chạy, ngân sách token, đồng thời thiết lập ranh giới phân quyền chặt chẽ để đảm bảo tác vụ chạy tự chủ nhưng không bị chệch hướng hay gây ra hậu quả ngoài dự kiến.

Vì sao phần lớn AI agent thất bại và bước chuyển sang agentic loop

Phần lớn AI agent thất bại trên môi trường sản xuất không phải vì mô hình kém thông minh, mà vì các tầng trừu tượng dày đặc trong các framework phổ biến tự tạo ra quá nhiều điểm mù. Khi prompt và response thực tế bị bọc kín bên dưới hàng tầng class và chuỗi gọi hàm, việc kiểm thử và lần vết lỗi (debug) trở thành cơn ác mộng. Một sai lệch nhỏ ở bước phân tích kết quả công cụ nếu không được phát hiện ngay sẽ tích tụ qua từng lượt chạy (compounding errors), rồi làm sập toàn bộ tác vụ sau vài chục bước.

Để tránh cái bẫy này, kiến trúc hệ thống cần phân biệt rõ ràng giữa hai mô hình: Workflows và Agents. Workflows là các hệ thống mà ở đó LLM và công cụ được điều phối qua các đường dẫn mã định sẵn (predefined code paths), mang lại tính dự đoán cao và sự ổn định cho các tác vụ cố định. Ngược lại, Agents là các hệ thống mà LLM tự động linh hoạt điều khiển quy trình và công cụ của chính nó, duy trì quyền kiểm soát cách thức hoàn thành mục tiêu dựa trên phản hồi môi trường.

Chuyển sang mô hình agent tự chủ đồng nghĩa với việc chấp nhận bài toán đánh đổi (trade-offs): hệ thống sẽ đánh đổi độ trễ (latency) và chi phí token cao hơn để đổi lấy khả năng xử lý các bài toán mở, phức tạp không thể đoán trước số bước thực thi. Mô hình này phát huy hiệu quả cao trong các tác vụ mở rộng như giải quyết các issue lập trình thực tế trên tập đánh giá SWE-bench, nơi LLM phải liên tục đọc mã, sửa lỗi và chạy lại kiểm thử cho đến khi thành công.

Năm trụ cột thiết kế cốt lõi của Claude Code

Thiết kế hạ tầng của Claude Code tuân thủ 5 trụ cột cốt lõi được đúc kết từ thực tiễn xây dựng hệ thống agent tại Anthropic, định hình nên một agentic harness có khả năng vận hành tin cậy ở cấp độ sản xuất.

Thứ nhất, Simplicity (Sự tối giản) ưu tiên sử dụng các thiết kế đơn giản, có khả năng lắp ghép (composable patterns) thay vì xây dựng các lớp trừu tượng dày đặc. Việc giữ mã nguồn đơn giản giúp bạn dễ dàng kiểm soát luồng dữ liệu và phát hiện lỗi phát sinh khi vận hành. Trụ cột này đi đôi với Transparency (Tính minh bạch), hiển thị rõ ràng các bước lập kế hoạch và các khối suy luận (thinking blocks) cho người dùng và kỹ sư theo dõi. Việc minh bạch hóa quy trình tư duy giúp tăng độ tin cậy và hỗ trợ can thiệp kịp thời khi agent có dấu hiệu đi sai hướng.

Thứ ba, ACI Design (Thiết kế Giao diện Agent-Computer) đòi hỏi sự đầu tư kỹ lưỡng cho việc thiết kế công cụ (tool definitions, docstrings) tương tự như thiết kế giao diện người-máy (HCI). Việc áp dụng triết lý Poka-yoke (chống lỗi) trong thiết kế ACI giúp giảm thiểu đáng kể tỷ lệ model gọi sai công cụ. Song song với đó là Ground Truth Verification (Xác minh thực địa), hệ thống luôn thu thập phản hồi thực tế từ môi trường tại từng lượt chạy (turn)—chẳng hạn như kết quả thực thi lệnh Bash, mã lỗi linter hay kết quả từ các bộ kiểm thử tự động—để LLM đánh giá chính xác tiến độ công việc thay vì tự suy diễn.

Sau cùng, trụ cột Bounded Autonomy (Tự chủ có ranh giới) thiết lập giới hạn nghiêm ngặt cho mức độ tự chủ của agent. Bạn kiểm soát quá trình thực thi thông qua các tham số giới hạn lượt chạy tối đa (max_turns), ngân sách tài chính tối đa (max_budget_usd), cùng cơ chế điểm kiểm soát có con người duyệt (human checkpoints) đối với các thao tác có tính ảnh hưởng cao.

Bên trong harness: Vòng lặp TAOR và triết lý radical simplicity

Trái tim của agentic harness là vòng lặp TAOR (Think - Act - Observe - Repeat). Mỗi lượt chạy (turn) trong SDK/CLI trải qua 5 bước tuần tự: (1) Harness nhận prompt cùng với system prompt, định nghĩa công cụ và lịch sử hội thoại, phát đi SystemMessage chứa thông tin khởi tạo (init); (2) Claude đánh giá trạng thái hiện tại và phản hồi bằng văn bản hoặc yêu cầu gọi công cụ (AssistantMessage); (3) Harness thực thi các công cụ được yêu cầu và thu thập kết quả; (4) Phản hồi kết quả công cụ trở lại cho Claude dưới dạng UserMessage để lặp lại chu kỳ; (5) Khi Claude tạo phản hồi không chứa yêu cầu gọi công cụ, harness trả về kết quả cuối cùng kèm theo ResultMessage.

Trong suốt quá trình này, SDK phát ra một luồng tin nhắn stream gồm 5 loại thông điệp cốt lõi để quản lý vòng đời: SystemMessage (xử lý sự kiện vòng đời như khởi tạo init, nén ngữ cảnh compact_boundary, thông tin hệ thống), AssistantMessage (chứa văn bản phản hồi hoặc khối tool_use), UserMessage (chứa khối tool_result trả về từ công cụ), StreamEvent (chứa các sự kiện stream thô như text deltas khi bật partial messages), và ResultMessage (đánh dấu kết thúc vòng lặp, chứa kết quả văn bản cuối cùng, chi phí token, ID phiên và subtype).

Trạng thái kết thúc trong ResultMessage được phân định rõ qua thuộc tính subtype: trường hợp hoàn thành tác vụ trả về success; khi chạm ngưỡng cài đặt sẽ trả về error_max_turns hoặc error_max_budget_usd; nếu chuỗi thử lại tạo output có cấu trúc thất bại sẽ ghi nhận error_max_structured_output_retries; đặc biệt khi tiến trình ngắt đột ngột do sự cố hệ thống, harness phát ra error_during_execution (trong đó các chỉ số token tiêu thụ có thể bị zeroed và stop_reason mang giá trị null).

Bạn có thể điều khiển chính xác hành vi runtime của vòng lặp thông qua các tham số như max_turns (giới hạn số lượt gọi công cụ), max_budget_usd (giới hạn mức chi tiêu tối đa) và các mức độ suy luận effort (low, medium, high, xhigh, max) để cân bằng giữa độ sâu lý giải và chi phí token.

Dưới đây là ví dụ mã khởi tạo một query có kiểm soát lượt và ngân sách:

python

from claude_agent_sdk import query, ClaudeAgentOptions
 
async for message in query(
    prompt="Refactor auth module",
    options=ClaudeAgentOptions(
        max_turns=30,
        max_budget_usd=2.0,
        effort="high"
    )
):
    pass

Bộ công cụ nguyên thủy: Sức mạnh của sự tinh giản

Claude Code được trang bị một bộ công cụ nguyên thủy (Primitive Tools) tinh gọn nhưng đầy đủ chức năng, được chia thành các nhóm rõ ràng:

Thao tác tệp: Read (đọc tệp), Edit (sửa tệp bằng cách thay chuỗi), Write (ghi mới tệp).
Tìm kiếm: Glob (tìm tệp theo pattern), Grep (tìm nội dung tệp bằng regex).
Thực thi: Bash và PowerShell (chạy lệnh shell, script, thao tác git).
Tương tác web: WebSearch (tìm kiếm web), WebFetch (tải và xử lý trang web).
Khám phá & Điều phối: ToolSearch (tìm kiếm công cụ theo yêu cầu), Agent (khởi tạo sub-agent), Skill (gọi kỹ năng tái sử dụng), AskUserQuestion (hỏi người dùng), TaskCreate và TaskUpdate (theo dõi tác vụ).

Nhằm tối ưu hóa Giao diện Agent-Computer (ACI), các công cụ được thiết kế dựa trên kỹ thuật Prompt Engineering chặt chẽ: cung cấp ví dụ sử dụng, xử lý trường hợp biên. Triết lý Poka-yoke được áp dụng triệt để để loại bỏ lỗi hệ thống, tiêu biểu là việc bắt buộc chuyển đổi tham số đường dẫn tệp từ dạng tương đối sang đường dẫn tuyệt đối (absolute filepaths), loại bỏ hoàn toàn tình trạng model bị lạc hướng làm việc khi di chuyển khỏi thư mục gốc. Đồng thời, hệ thống giảm tối đa chi phí định dạng (Formatting Overhead) bằng cách tránh bắt model phải tính toán số dòng trong header của diff hoặc viết mã trong JSON escaping phức tạp.

Một điểm quan trọng trong cơ chế vận hành runtime là cách harness quản lý tính đồng thời (concurrency): các công cụ chỉ đọc (read-only) được phép thực thi song song để tối ưu hóa thời gian phản hồi, trong khi các công cụ làm thay đổi trạng thái hệ thống phải thực thi tuần tự nhằm triệt tiêu hoàn toàn nguy cơ xung đột dữ liệu (race conditions) trên hệ thống tệp. Đối với các công cụ tùy chỉnh (custom tools), mặc định harness sẽ thực thi tuần tự trừ khi bạn chủ động đánh dấu thuộc tính readOnlyHint trong phần khai báo metadata của công cụ.

Các công cụ trong cùng một turn được điều phối thực thi theo cơ chế sau:

Nhóm công cụ	Các công cụ tiêu biểu	Cơ chế thực thi trong Turn
Đọc & Tìm kiếm	`Read`, `Glob`, `Grep`, `WebSearch`	Song song (Concurrent / Read-only)
Ghi & Thay đổi trạng thái	`Edit`, `Write`, `Bash`	Tuần tự (Sequential) để tránh xung đột
Điều phối & Tự chủ	`Agent`, `AskUserQuestion`, `Skill`	Theo luồng kiểm soát hoặc chuyển sang Sub-agent

Kinh tế học ngữ cảnh và hệ thống bộ nhớ phân tầng

Cửa sổ ngữ cảnh (Context Window) là tài nguyên đắt giá nhất trong các phiên làm việc kéo dài của agent. Cửa sổ ngữ cảnh không tự động reset giữa các turn mà tích lũy liên tục từ System prompt, nội dung file CLAUDE.md, định nghĩa công cụ (tool schemas), đến lịch sử hội thoại và output từ các công cụ (như đọc file lớn hay log Bash dài).

Để tối ưu hóa chi phí và độ trễ, Claude Code tích hợp cơ chế Prompt Caching. Các thành phần tĩnh hoặc ít thay đổi ở đầu request như System prompt, tệp CLAUDE.md và các tool schema được tự động lưu vào cache, giúp giảm đáng kể chi phí token và độ trễ cho các lượt gọi lặp lại trong phiên.

Khi lịch sử hội thoại tích tụ vượt ngưỡng cửa sổ ngữ cảnh, hệ thống kích hoạt cơ chế Automatic Compaction (Tự động nén ngữ cảnh). SDK/CLI sẽ phát đi thông điệp SystemMessage với subtype compact_boundary và tóm tắt toàn bộ lịch sử hội thoại cũ để giải phóng không gian. Bạn có thể điều khiển nội dung nén thông qua file CLAUDE.md bằng cách chỉ định các thông tin bắt buộc giữ lại (như mục tiêu tác vụ, đường dẫn tệp đã sửa, kết quả test, lý do ra quyết định). Ngoài ra, bạn có thể chủ động kích hoạt nén thủ công bằng lệnh /compact hoặc can thiệp thông qua hook PreCompact.

Cơ chế mở rộng: Sub-agents, Hooks và Model Context Protocol

Khả năng mở rộng của Claude Code dựa trên ba trụ cột kỹ thuật chính: Sub-agents, hệ thống Hooks và giao thức MCP.

Sub-agents (Agent phụ) mang lại khả năng cô lập ngữ cảnh (context isolation) gần như triệt để. Khi nhận một tác vụ con, sub-agent được khởi tạo với một cửa sổ ngữ cảnh mới hoàn toàn độc lập, xử lý công việc và chỉ trả về kết quả tóm tắt cho agent cha. Điều này giúp ngăn chặn hiện tượng phình ngữ cảnh (context rot) và suy giảm hiệu năng của agent chính.

Hệ thống Hooks cho phép can thiệp vào vòng đời vận hành theo các sự kiện: Per-session (SessionStart, SessionEnd), Per-turn (UserPromptSubmit, Stop), hoặc Per-tool (PreToolUse, PostToolUse). Hook hỗ trợ hai dạng cấu hình: Exec form (command + args) và Shell form. Trong đó, Exec form thực thi trực tiếp tiến trình trên PATH mà không thông qua trình thông dịch shell, loại bỏ hoàn toàn các nguy cơ tấn công chèn lệnh (shell injection) và lỗi ký tự đặc biệt khi truyền các biến đường dẫn như ${CLAUDE_PROJECT_DIR}. Bằng cách trả về các cấu trúc JSON Output, hook có thể can thiệp trực tiếp vào luồng kiểm soát thông qua permissionDecision (allow, deny, ask, defer), thay đổi tham số đầu vào bằng updatedInput, hoặc chèn thêm dữ liệu vào cửa sổ ngữ cảnh qua additionalContext (được đưa vào dưới dạng thẻ <system-reminder> giúp model đọc hiểu mà không hiển thị thành tin nhắn chat trên UI).

Model Context Protocol (MCP) & Tool Search giúp kết nối hệ thống với các công cụ bên ngoài linh hoạt. Nhờ cơ chế Tool Search, hệ thống tải các schema của công cụ MCP theo yêu cầu (on-demand) thay vì nạp toàn bộ schema vào ngữ cảnh ban đầu, giúp tiết kiệm không gian bộ nhớ đáng kể.

Kiến trúc phân quyền và ranh giới an toàn đa tầng

Để đảm bảo tính an toàn khi thực thi tác vụ tự chủ, Claude Code xây dựng mô hình phân quyền đa tầng dựa trên các chế độ permission_mode:

default: Yêu cầu xác thực dựa trên callback canUseTool hoặc hiển thị prompt hỏi người dùng.
acceptEdits: Tự động duyệt các thao tác sửa đổi tệp và các lệnh hệ thống tệp thông dụng (mkdir, cp, mv), giúp tăng tốc độ làm việc.
plan: Cho phép khám phá và lập kế hoạch nhưng cấm hoàn toàn hành vi tự động sửa đổi mã nguồn.
dontAsk: Từ chối cứng (hard deny) tất cả các lệnh cần xác thực mà không hỏi người dùng, thích hợp cho môi trường headless chạy tự động.
auto: Sử dụng một mô hình classifier riêng biệt để đánh giá độ an toàn của các lệnh Shell và truy cập mạng trước khi cho phép.
bypassPermissions: Bỏ qua mọi bước kiểm tra phân quyền, chỉ sử dụng trong môi trường cô lập tuyệt đối như Docker hay CI.

Thứ tự đánh giá quy tắc (Rule Evaluation Order) tuân thủ hệ thống thứ bậc ưu tiên nghiêm ngặt: danh sách cấm cứng disallowed_tools luôn được kiểm tra đầu tiên để chặn ngay lập tức, tiếp theo đến danh sách tự động duyệt allowed_tools, và cuối cùng mới xét đến chế độ phân quyền permission_mode hiện hành. Đối với doanh nghiệp, quản trị viên có thể thiết lập cấu hình allowManagedHooksOnly để chặn toàn bộ hook cá nhân hoặc plugin từ phía người dùng, đảm bảo tuân thủ tuyệt đối các chính sách bảo mật cấp tổ chức.

Bài học kiến trúc cho AI Engineer khi xây dựng hệ thống agent

Xây dựng một hệ thống agent chạy ổn định trong sản xuất không đòi hỏi những đồ thị trừu tượng phức tạp. Điểm mấu chốt nằm ở thiết kế của chính agentic harness: giữ vòng lặp phản hồi minh bạch, thiết kế công cụ (ACI) thật sự thân thiện với token của LLM, quản lý chặt chẽ ngân sách ngữ cảnh qua bộ nhớ nén, và luôn khóa chặt ranh giới an toàn bằng phân quyền nhiều lớp.

Nếu bài toán của bạn có luồng nghiệp vụ cố định, hãy dùng workflow tuyến tính để tiết kiệm token và đảm bảo tính ổn định. Chỉ khi đối mặt với những tác vụ mở và phi tuyến tính như gỡ lỗi mã nguồn hay bảo trì hệ thống, việc để agent chạy tự chủ trong một harness được kiểm soát chặt mới thực sự đáng giá từng xu token bạn bỏ ra.