Bỏ qua điều hướng

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.

Administrator13 phút đọc
Harness Engineering: bộ khung giúp AI Agent viết code đáng tin hơn

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ạyThời gianChi phíKết quả
Agent chạy một mình20 phút9 USDGiao 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 USDGame 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êuCung cấp khối trừu tượng để dev tự lắpMột agent lắp sẵn, chạy được ngay
Lấy ai làm trung tâmCon người, người lắp rápChính agent
Có phải viết code để lắpCóKhông, chỉ cần đưa mục tiêu
Trừu tượng cốt lõiThư viện, SDK, class APIVò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:

  1. Tạo AGENTS.md với vài quy tắc ngắn, không cố viết thành bách khoa toàn thư.
  2. Tạo init.sh chạy lint và test của dự án.
  3. Tạo feature_list.json với danh sách tính năng và trạng thái.
  4. Tạo progress.md và yêu cầu agent cập nhật ở cuối mỗi phiên.
  5. 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

Chia sẻ:FacebookXTelegram

Bài viết liên quan

Bình luận

Đang tải bình luận…