Xây dựng Harness cho Coding Agent từ đầu

Định nghĩa

Harness cho coding agent là bộ khung (framework) tạo ra "môi trường sống" giữa AI và máy tính — bao gồm các công cụ đọc/ghi file, thực thi lệnh shell, và kiểm soát quyền hạn — cho phép AI biến từ "trò chuyện" sang "lập trình thực sự" bằng cách tương tác trực tiếp với codebase thay vì chỉ sinh văn bản.

Giải thích chi tiết

Tại sao Coding Agent cần Harness riêng?

Lập trình không chỉ là viết text. Code đòi hỏi độ chính xác tuyệt đối đến từng dòng, cần chạy thử (compile/test) để xác minh, và có tác dụng phụ vĩnh viễn (ghi đè file).

Nếu chỉ dùng Prompt Engineering (Level 0) hoặc RAG (Level 1), AI chỉ có thể "khuyên" bạn sửa code. Để AI tự sửa và kiểm tra kết quả, bạn cần Level 2: Harness Engineering — tạo ra một "bộ đệm an toàn" (sandbox) nơi AI có thể:

• Đọc file với độ chính xác đến số dòng
• Thực thi lệnh và đọc kết quả trả về
• Sửa file mà không làm hỏng cấu trúc

Harness là cầu nối giữa "suy nghĩ" của LLM và "thực thi" của máy tính.

Kiến trúc từ vụ leak Claude Code (512K lines)

Khi source code của Claude Code bị leak (512K dòng TypeScript), cộng đồng mới thấy rõ: đây không phải một script đơn giản gọi API, mà là một hệ thống phần mềm hoàn chỉnh với ba tầng:

Tầng UI (React/TypeScript): Giao diện terminal tương tác, hiển thị streaming response theo thời gian thực. Không chỉ là "chat" — mà là trình biên tập với syntax highlighting và diff viewer.

Tầng Core (Agent Loop): Vòng lặp suy luận - hành động - quan sát. Claude không trả về câu trả lời ngay; nó trả về thought (suy nghĩ nội bộ) rồi mới đến action (gọi tool). Mỗi action phải tuân theo schema Zod nghiêm ngặt — ví dụ lệnh sửa file phải chỉ định chính xác start_line, end_line, replacement.

Tầng Runtime (Node.js Sandbox): Thực thi lệnh shell trong môi trường có kiểm soát, với timeout, giới hạn network, và backup tự động trước mỗi lần ghi file.

Điểm then chốt: Claude Code xử lý permission như first-class citizen. Mỗi lệnh ghi file đều kiểm tra ACL (Access Control List), tạo backup git tự động, và yêu cầu xác nhận nếu ảnh hưởng đến file quan trọng.

Các thành phần bắt buộc của Coding Harness

Agent-Computer Interface (ACI) cho File System

AI không "nhìn" thấy folder như con người. Harness phải cung cấp các primitive:

• view(path, view_range): Xem file từ dòng 50-80 (không phải toàn bộ file 10K dòng)
• edit(path, old_str, new_str): Sửa bằng cách thay thế chuỗi, giữ nguyên indent và formatting
• search(query, path): Grep với regex để tìm định nghĩa hàm

Khác với con người mở IDE, AI dùng harness như một remote control với độ chính xác tuyệt đối.

Execution Environment với Feedback Loop

Coding agent cần "biết" code có chạy được không:

• Shell Tool: Chạy npm test, pytest, gcc với timeout (tránh infinite loop)
• LSP Integration: Kết nối Language Server Protocol để biết type errors, undefined variables (không chỉ dựa vào pattern matching)
• Exit Code Parsing: Harness phân tích stdout/stderr, đưa kết quả vào context window cho lượt suy luận tiếp theo

Đây là feedback loop khép kín: AI viết code → chạy test → thấy lỗi → sửa lại. Không có harness, vòng lặp này đòi hỏi người dùng copy-paste liên tục.

Permission & Safety Model

Coding agent có quyền hủy hoại: rm -rf / hoặc ghi đè file production. Harness phải có:

• Read-only default: AI chỉ đọc trừ khi được cấp quyền explicit
• Sandbox: Chạy trong Docker/container, không access network trừ khi cần
• Git checkpoint: Tự động git stash hoặc tạo branch trước khi sửa, cho phép rollback
• Audit log: Ghi lại mọi thao tác (compliance cho doanh nghiệp)

State & Session Management

Coding task kéo dài 30 phút đến nhiều giờ. Harness cần:

• Conversation Memory: Lịch sử các lệnh đã chạy, file đã đọc
• Working Directory State: Theo dõi external changes (người dùng sửa file bên ngoài)
• Cost Tracking: Theo dõi token usage, số lượt tool call (tránh bill bất ngờ)

Pattern Multi-Agent trong Coding (Anthropic DAW)

Paper từ Anthropic về "Dollar-A-Day Worker" (chi phí 124.70 USD/ngày cho agent) chứng minh: thay vì một agent khổng lồ, hiệu quả hơn khi dùng 3 agent chuyên biệt trong harness:

Planner Agent: Phân tích yêu cầu "refactor authentication module" → chia thành subtasks: (1) update middleware, (2) modify tests, (3) update docs.

Implementation Agent: Chỉ tập trung viết code, không lo planning. Dùng model nhỏ hơn (tiết kiệm token), chuyên về coding style cụ thể của codebase.

Validation Agent: Chạy test suite, static analysis, security scan. Báo cáo lỗi về Planner nếu fail.

Harness ở đây đóng vai trò orchestrator: điều phối message queue giữa các agent, quản lý shared state (file system), tránh race condition khi hai agent cùng sửa một file.

Meta-Harness: Khi AI tự thiết kế Harness

Paper từ Stanford (arxiv 2603.28052) đề xuất khái niệm Meta-Harness: AI đọc code của chính harness, phát hiện bottleneck (ví dụ: tool view quá chậm), và đề xuất cải tiến (thêm caching layer).

Đây là bước tiến hóa: từ "agent chạy trong harness" sang "agent cải tiến chính harness chứa nó". ClaudeKit và các nền tảng mới đã bắt đầu áp dụng pattern này.

Ví dụ thực tế

Xây dựng Minimal Coding Agent với Python và Docker

Một implementation tối giản cho thấy harness hoạt động như thế nào:

Architecture: Docker container (sandbox) + Python service (harness) + OpenAI API.

Tool Schema (định nghĩa bằng Pydantic):

• view: đọc file với line range
• edit: thay thế text
• bash: chạy shell command với timeout 30s
• python: execute Python code để test logic nhỏ

Agent Loop:

1. LLM nhận prompt: "Fix the bug in auth.py"
2. LLM gọi `view` đọc auth.py (dòng 1-50)  
3. LLM suy nghĩ: "Lỗi ở dòng 34, thiếu null check"
4. LLM gọi `edit` với old_str và new_str cụ thể
5. LLM gọi `bash("pytest tests/test_auth.py")`
6. Harness parse exit code: 0 (pass) → kết thúc | 1 (fail) → đưa stderr vào context, lặp lại

Safety: Overlay filesystem — mọi thay đổi ghi vào layer riêng, có thể discard nếu agent lỗi.

Phân tích Claude Code từ Source Leak

Từ 512K dòng code leaked, ta thấy các quyết định thiết kế then chốt:

Typed Tool Contracts: Không dùng text mô tả tool, mà dùng Zod schema. Ví dụ tool edit yêu cầu chính xác 3 tham số: file_path, old_string, new_string. Điều này loại bỏ ambiguity — AI không thể "quên" chỉ định file cần sửa.

Streaming Architecture: Response không chờ hoàn thiện mà stream từng token, cho phép UI hiển thị "thinking" animation ngay lập tức, cải thiện perceived performance.

File Watcher: Harness theo dõi file system events (inotify/epoll). Nếu người dùng sửa file bằng VS Code trong khi agent đang chạy, harness thông báo "external change detected", tránh conflict.

Command Palette Pattern: Mỗi tool là một "command" có thể được gọi linh hoạt, không hard-code workflow. Agent có thể kết hợp view → bash(grep) → edit → bash(git diff) theo bất kỳ trình tự nào phù hợp với task.

Enterprise Coding Agent cho Codebase Nội bộ

Tình huống: Ngân hàng X có codebase Java 10 năm tuổi, cần modernize sang Spring Boot 3.

Harness tùy chỉnh:

• Private LLM: Chạy trên internal GPU (không leak data ra OpenAI)
• Custom Tools: Kết nối với internal Maven repository, SonarQube instance
• Approval Gates: Mọi lệnh edit vào file src/main/security/ đều đòi hỏi approval từ security team qua Slack integration
• Audit Trail: Mỗi thao tác agent log vào ELK stack, đáp ứng SOC2 compliance

Kết quả: Agent tự động refactor 200+ file, chạy regression test suite (mất 2 giờ), chỉ đưa các thay đổi pass test lên pull request cho human review.

Ứng dụng

Cho Developer cá nhân

• Automation hàng ngày: Tự động refactor code cũ, generate unit tests cho legacy code, hoặc tạo documentation từ source code.
• Bug hunting: Agent tự động reproduce bug từ issue description, tìm root cause bằng cách trace qua call stack.

Cho Tech Lead / Engineering Manager

• Standardize practices: Harness có thể enforce coding conventions (ví dụ: không cho phép commit nếu chưa có docstring, kiểm tra qua view + python tool).
• Automated first-pass review: Agent chạy static analysis, security scan, performance check trước khi đến tay senior dev.

Cho Doanh nghiệp / Platform Engineering

• Internal Developer Platform (IDP): Tích hợp AI agent vào Jenkins/GitLab CI, tự động sửa lỗi dependency conflict.
• Legacy modernization: Xử lý codebase khổng lồ (hàng triệu dòng) mà human không thể đọc hết trong thời gian ngắn.
• Security & Compliance: Harness đảm bảo agent không thể exfiltrate data (network isolation), không xóa nhầm production (ACLs), và mọi thao tác đều có log audit.

So sánh

Kết luận: Harness là điều kiện tiên quyết để AI trở thành "software engineer" thay vì chỉ là "technical writer". Không có harness, AI chỉ là autocomplete nâng cao; có harness đúng cách, AI trở thành đồng nghiệp có thể tự chỉnh sửa, kiểm tra, và chịu trách nhiệm với công việc — nhưng đòi hỏi engineering rigor để không trở thành "autonomous disaster".

Bài viết liên quan

Cùng cụm

Đọc tiếp