Harness Engineering: bộ khung giúp AI Agent viết code đáng tin hơn
Bài viết trên Viblo lý giải vì sao cùng một model nhưng kết quả khác hẳn nhau, và cách dựng harness cấp dự án chỉ với bốn file.

Nếu đã làm việc với Claude Code, Cursor, Codex hay Windsurf một thời gian, khả năng cao bạn từng gặp cảnh agent sửa xong một tính năng nhưng làm vỡ ba bài test khác, hoặc tuyên bố đã hoàn thành trong khi ứng dụng còn chưa build nổi. Bài viết của tác giả Nguyễn Anh trên Viblo cho rằng nguyên nhân thường không nằm ở model mà ở môi trường model đang làm việc, và đó là lý do khái niệm harness engineering đang được nhắc tới nhiều hơn. Theo bài gốc, cả OpenAI, Anthropic lẫn cộng đồng đều đã có những bài viết riêng về chủ đề này.
Chẩn đoán sai phổ biến: đổi model thay vì sửa môi trường
Bài gốc mở đầu bằng ba tình huống quen thuộc với người dùng coding agent: agent sửa một tính năng và làm hỏng vài bài test khác; agent báo xong trong khi ứng dụng chưa chạy được; sang phiên làm việc mới, agent không còn nhớ hôm trước đã làm gì và bắt đầu lại từ đầu. Hệ quả là lập trình viên mất nhiều thời gian dọn dẹp hơn là thời gian tự viết code.
Phản xạ đầu tiên thường là kết luận model chưa đủ giỏi và đi tìm model mạnh hơn. Tác giả cho rằng trong phần lớn trường hợp, vấn đề nằm ở harness — lớp môi trường, công cụ, tài liệu hướng dẫn và cơ chế kiểm chứng bao quanh agent — chứ không phải ở năng lực của model.
Thí nghiệm của Anthropic: cùng model, hai kết quả
Theo bài gốc, Anthropic công bố một thí nghiệm trong bài viết Harness design for long-running apps. Họ dùng cùng model Claude Opus 4.5 và cùng một prompt: tạo công cụ làm game 2D phong cách retro, có level editor, sprite editor, hành vi cho entity và chế độ chơi thử.
| Cách chạy | Thời gian | Chi phí | Kết quả |
|---|---|---|---|
| Agent chạy một mình | 20 phút | 9 USD | Giao diện trông ổn nhưng game không chơi được, entity không phản hồi input |
| Có harness đầy đủ | 6 giờ | 200 USD | Game editor chơi được thật |
Chi phí cao hơn khoảng 20 lần, nhưng một bên là sản phẩm hỏng còn một bên là sản phẩm dùng được. Điểm mấu chốt mà tác giả rút ra: model không đổi, thứ thay đổi là harness bao quanh nó.
Bài gốc cũng dẫn một ví dụ từ phía OpenAI trong bài Harness engineering: leveraging Codex in an agent-first world: một nhóm đã xây và ship bản beta nội bộ của sản phẩm với 0 dòng code viết tay. Vai trò kỹ sư dịch chuyển từ tự viết code sang thiết kế môi trường để agent viết code đúng. Cần lưu ý đây là thông tin được tác giả bài Viblo dẫn lại từ tài liệu của OpenAI, không phải kết quả đo lường độc lập.
Harness là gì và khác gì agent framework
Theo định nghĩa trong bài, harness (agent harness) là toàn bộ môi trường, công cụ, tài liệu hướng dẫn và cơ chế kiểm chứng tự động được dựng bao quanh một AI agent. Tác giả đưa ra công thức dễ nhớ: LLM là động cơ, harness là khung xe và vô lăng, ghép lại thành chiếc xe tự lái.
Về bản chất, LLM là bộ sinh văn bản một lượt: hỏi thì trả lời rồi dừng. Tự nó không duyệt được codebase, không chạy test, không thấy lỗi để sửa lại. Harness cung cấp khả năng hành động thông qua tool, khả năng quan sát kết quả, và vòng lặp tự sửa sai trong một không gian an toàn.
Bài gốc cũng phân biệt rõ harness với agent framework:
| Tiêu chí | Agent Framework (LangChain, LangGraph, CrewAI…) | Agent Harness (Claude Code, Cursor…) |
|---|---|---|
| Mục tiêu | Cung cấp khối trừu tượng để dev tự lắp | Một agent lắp sẵn, chạy được ngay |
| Lấy ai làm trung tâm | Con người, người lắp ráp | Chính agent |
| Có phải viết code để lắp | Có | Không, chỉ cần đưa mục tiêu |
| Trừu tượng cốt lõi | Thư viện, SDK, class API | Vòng lặp có giới hạn, tool registry, lớp phân quyền, quản lý context |
Điểm tác giả nhấn mạnh: Claude Code, Cursor, Codex hay Windsurf đều đã là harness, nhưng đó mới là phần chung của công cụ. Phần harness ở cấp dự án — quy tắc, trạng thái, tiêu chí thế nào là xong — vẫn là việc của người dùng.
Năm hệ thống con của một harness hoàn chỉnh
Instructions — chỉ dẫn. Agent cần biết phải làm gì, theo thứ tự nào, đọc gì trước khi bắt đầu. Sai lầm hay gặp là nhồi mọi thứ vào một file khổng lồ. Bài gốc khuyên dùng progressive disclosure: file AGENTS.md hoặc CLAUDE.md đóng vai trò bản đồ, còn chi tiết nằm trong docs/ để agent đọc khi cần. Nguyên tắc đi kèm là kho mã phải là nguồn chân lý duy nhất: thứ gì agent không thấy trong repo thì với agent, nó không tồn tại. Quyết định nằm trong Slack hay trong đầu người quản lý đều vô hình với agent.
State — trạng thái. Context window có hạn và mỗi phiên agent khởi động với trí nhớ trống. Vì vậy tiến độ phải được ghi xuống đĩa: progress.md, feature_list.json, git log, ghi chú bàn giao. Phiên sau đọc lại và tiếp tục đúng chỗ phiên trước dừng.
Verification — kiểm chứng. Agent rất hay tuyên bố hoàn thành quá sớm vì sự tự tin không đồng nghĩa với sự chính xác. Trong harness, chỉ bộ test pass mới được tính là bằng chứng: test, lint, type check, chạy thử, và tốt nhất là kiểm thử đầu–cuối. Không có harness, bước xác minh là agent nói nó ổn; có harness, bước đó là tests pass, lint clean, types correct.
Scope — phạm vi. Agent có xu hướng ôm đồm: làm dở ba việc thay vì làm xong một. Quy tắc trong bài là mỗi lần một tính năng, với định nghĩa hoàn thành rõ ràng. feature_list.json là ranh giới phạm vi mà máy đọc được và agent không thể lờ đi; agent cũng không được tự viết lại danh sách để che giấu việc chưa xong. Scope còn bao gồm sandbox và phân quyền: agent chỉ được đụng vào những gì nó được phép.
Session Lifecycle — vòng đời phiên. Mỗi phiên cần khởi tạo bài bản ở đầu, ví dụ chạy init.sh để kiểm tra môi trường khoẻ trước khi bắt tay làm, và dọn dẹp ở cuối để lại đường khởi động lại sạch cho phiên sau.
Một phiên agent có kỷ luật trông như thế nào
Theo bài gốc, vòng đời một phiên gồm bốn chặng. Bắt đầu: đọc AGENTS.md, chạy init.sh, đọc progress.md, đọc feature_list.json, xem git log. Chọn: lấy một tính năng chưa hoàn thành. Thực hiện: code, chạy xác minh, lỗi thì sửa và chạy lại, pass thì ghi nhận bằng chứng. Kết thúc: cập nhật progress.md và feature_list.json, ghi lại vấn đề còn tồn đọng, commit chỉ khi an toàn, và để lại trạng thái sạch.
Bắt đầu với bốn file
Tác giả cho rằng không cần công cụ gì phức tạp để bắt đầu. Cấu trúc tối thiểu:
YOUR-PROJECT/
├── AGENTS.md # Sổ tay vận hành cho agent (hoặc CLAUDE.md)
├── init.sh # Kiểm tra môi trường + chạy lint/test
├── feature_list.json # Danh sách tính năng & trạng thái
├── progress.md # Nhật ký các phiên
└── src/
Trong đó AGENTS.md nêu vài quy tắc ngắn: luôn chạy ./init.sh trước khi tuyên bố xong, chỉ làm một tính năng tại một thời điểm (tính năng đang active trong feature_list.json), cập nhật progress.md ở cuối mỗi phiên. init.sh chỉ cần npm install, npm run lint, npm test và in ra thông báo môi trường đã sẵn sàng. feature_list.json giữ danh sách tính năng kèm trạng thái, còn progress.md ghi lại phiên nào làm gì, đang làm gì, còn lại gì.
Harness Kit: đóng gói harness thành một lệnh cài
Giữ bốn file nhất quán qua nhiều dự án là việc thủ công nhàm chán, nên tác giả phát triển Harness Kit — một lớp governance cho các AI coding agent. Theo mô tả trong bài, kit chỉ dùng thư viện chuẩn của Python 3.8+, không phụ thuộc thư viện ngoài, mã nguồn mở theo giấy phép MIT, và dùng được với Claude Code, Cursor, Codex, Windsurf, Antigravity — bất kỳ công cụ nào đọc file chỉ dẫn.
Lệnh cài đặt nêu trong bài, chạy ở thư mục gốc dự án (yêu cầu Python 3.8+ và git):
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex
Sau khi cài, dự án có 6 file: AGENTS.md (quy tắc agent đọc đầu mỗi phiên), feature_list.json (tính năng, trạng thái, phụ thuộc), progress.md (agent ghi tiến độ), init.sh hoặc init.ps1 (script xác minh), session-handoff.md (ngữ cảnh bàn giao), và hk.py (CLI quản lý hàng đợi tính năng và chấm điểm harness). Nếu công cụ của bạn đọc CLAUDE.md thay vì AGENTS.md, bài gốc hướng dẫn thêm cờ --agent-file CLAUDE.md.
Có hai cách làm việc. Cách thứ nhất là nói chuyện với agent bằng ngôn ngữ tự nhiên, ví dụ yêu cầu đọc AGENTS.md và triển khai tính năng đang active trong feature_list.json, hoặc thông báo đã xong tính năng hiện tại và yêu cầu chạy init.sh, cập nhật progress.md rồi chuyển sang tính năng kế tiếp — không cần plugin hay extension. Cách thứ hai là dùng hk.py từ terminal, CI hoặc script:
py hk.py feature "User authentication" # thêm tính năng -> F-001
py hk.py start F-001 # đặt làm tính năng active
py hk.py status # xem hàng đợi + gợi ý bước tiếp theo
py hk.py done # chạy init script rồi đánh dấu hoàn thành
py hk.py audit # chấm điểm harness (0-100)
py hk.py audit --html report.html # xuất báo cáo HTML
Trên macOS hoặc Linux, thay py bằng python3. Tác giả đánh giá cao lệnh done vì nó chạy script xác minh trước khi đánh dấu hoàn thành, đúng tinh thần không có bằng chứng thì chưa xong.
Nếu cài với cờ --full, kit bổ sung thư mục harness/ gồm 7 module Python — một runtime agent tối giản để người đọc hiểu và tuỳ biến những gì diễn ra bên trong các công cụ như Claude Code: vòng lặp có giới hạn số vòng, quản lý context với cơ chế nén các lượt cũ, lưu trạng thái bền bỉ bằng log JSONL append-only, lắp prompt thân thiện với cache (phần tĩnh trước, phần động sau), tool registry với ba cấp quyền Read-only, Workspace Write và Full Access, sub-agent chỉ trả bản tóm tắt về agent cha, và hook pre-tool/post-tool.
Bài gốc cũng liệt kê vài bẫy khi tự thiết kế harness: đừng gắn nhãn an toàn tĩnh cho tool (cùng một tool shell, chạy git diff thì an toàn nhưng chạy rm -rf thì không — phải phân loại theo tham số tại thời điểm chạy); nhớ vô hiệu hoá cache khi file thay đổi, nếu không các tool khác sẽ đọc phải dữ liệu cũ; và cẩn thận với giới hạn bộ nhớ âm thầm, vì bản tóm tắt dài có thể bị cắt mà không báo lỗi, nên lưu con trỏ ngắn thay vì đoạn tóm tắt dài.
Vì sao đáng quan tâm với độc giả Việt Nam
Phần lớn nội dung về AI coding agent hiện nay đến từ blog kỹ thuật tiếng Anh, trong khi phần việc thực sự tạo ra khác biệt lại nằm ở cấp dự án: quy tắc, trạng thái, tiêu chí hoàn thành. Đó là những thứ một nhóm nhỏ hoặc một lập trình viên độc lập hoàn toàn kiểm soát được mà không cần ngân sách hạ tầng.
Bài gốc còn đáng chú ý ở khía cạnh tài nguyên tiếng Việt: tác giả viết bằng tiếng Việt, phát hành công cụ mã nguồn mở, và có thêm trang Learn Harness Engineering gồm 6 giai đoạn, 12 bài giảng, 6 dự án thực hành xoay quanh việc xây một ứng dụng Electron từ đầu — bắt đầu bằng so sánh giữa chỉ dùng prompt và ưu tiên quy tắc, kết thúc bằng một harness hoàn chỉnh kèm nghiên cứu ablation. Trang học cũng có sẵn mẫu AGENTS.md, CLAUDE.md, feature_list.json, init.sh và checklist cho khởi tạo, xác minh, bàn giao.
Với các nhóm đang dùng coding agent trong công việc hằng ngày, thông điệp có thể rút gọn: chi phí token chỉ là một phần của phương trình, phần còn lại là chi phí dọn dẹp khi agent làm sai mà không ai phát hiện.
Ai nên dùng và cách thử nhanh
Bài gốc hướng tới người đã dùng quen ít nhất một coding agent và đang gặp vấn đề về tính nhất quán giữa các phiên. Cách thử nhẹ nhất, theo đúng hướng dẫn trong bài:
- Tạo
AGENTS.mdvới vài quy tắc ngắn, không cố viết thành bách khoa toàn thư. - Tạo
init.shchạy lint và test của dự án. - Tạo
feature_list.jsonvới danh sách tính năng và trạng thái. - Tạo
progress.mdvà yêu cầu agent cập nhật ở cuối mỗi phiên. - Chỉ khi thấy cần chuẩn hoá qua nhiều dự án mới cân nhắc cài Harness Kit, và có thể chạy
hk.py auditđể xem harness hiện tại đang thiếu gì.
Lưu ý và hạn chế
Bài gốc là bài đăng trên blog cá nhân của tác giả trên Viblo, đồng thời là bài giới thiệu cho Harness Kit và trang Learn Harness Engineering do chính tác giả phát triển. Độc giả nên cân nhắc yếu tố này khi đọc phần đánh giá về công cụ.
Các số liệu về thí nghiệm của Anthropic (20 phút và 9 USD so với 6 giờ và 200 USD, model Claude Opus 4.5) được tác giả dẫn lại từ bài Harness design for long-running apps; bài Viblo không nêu phương pháp đo, cấu hình máy hay phiên bản công cụ, và đây không phải kết quả kiểm chứng độc lập. Tương tự, thông tin về nhóm của OpenAI ship bản beta nội bộ với 0 dòng code viết tay là nội dung được dẫn lại từ bài của OpenAI.
Về Harness Kit, bài gốc nêu giấy phép MIT và yêu cầu Python 3.8+, nhưng không nêu số star, số lượt tải, phiên bản phát hành hay benchmark so sánh với các cách làm khác. Các nhận định về việc harness quan trọng không kém việc chọn model là quan điểm của tác giả; bài viết này không có dữ liệu độc lập để xác nhận. Thông tin được trình bày tính đến khi bài gốc đăng ngày 17/11/2026.
Kết
Cách diễn đạt đáng nhớ nhất trong bài gốc: model là động cơ, harness là khung xe và vô lăng; động cơ mạnh đến đâu mà thiếu vô lăng và phanh thì chỉ lao nhanh hơn về hướng sai. Nếu chỉ giữ lại một nguyên tắc, hãy giữ nguyên tắc đừng để agent tự tuyên bố xong — hãy để test làm việc đó.
Nguồn: Viblo
Nguồn tham khảo: Viblo – Nguyễn Anh
Bài viết liên quan

AI cho lập trình viên8 phút đọc
learn-claude-code: repo dạy tự xây agent harness từ 0
Repo Python của shareAI-lab dạy cách tự viết harness cho coding agent: tools, knowledge, observation, quyền hạn. Tính đến 15/11/2026, repo đạt 80.412 sao.

Công nghệ Việt Nam10 phút đọc
Thuần hóa Coding Agent: context engineering và guardrails
Bài viết trên Viblo trình bày cách dùng spec, tệp quy tắc .cursorrules/CLAUDE.md và vòng lặp test tự động để Coding Agent không phá codebase production.

Bảo mật9 phút đọc
Vapor Panda dùng ARTEX AI tấn công tự động hơn 200 tổ chức
CrowdStrike cho biết nhóm Vapor Panda dùng ARTEX AI điều phối nhiều agent tấn công song song hơn 200 tổ chức ở 14 quốc gia, xâm nhập thành công ít nhất 9.
Bình luận
Đang tải bình luận…