Harness Engineering: Xây "bộ khung" để AI Agent viết code đáng tin cậy
Nếu đã dùng Claude Code, Cursor, Codex hay Windsurf một thời gian, có lẽ bạn đã gặp những cảnh này:
- Agent sửa một tính năng nhưng làm vỡ ba bài test khác.
- Agent báo "Xong rồi!" trong khi app còn chưa chạy nổi.
- Sang phiên làm việc mới, agent quên sạch hôm qua đã làm gì và bắt đầu lại từ đầu.
- Bạn mất thời gian dọn dẹp nhiều hơn thời gian tự viết code.
Phản xạ đầu tiên thường là: "Chắc model chưa đủ giỏi". Nhưng trong phần lớn trường hợp, vấn đề không nằm ở model mà ở môi trường model đang làm việc. Đó là lý do Harness Engineering đang được OpenAI, Anthropic và cộng đồng nhắc đến ngày càng nhiều.
Trong bài này mình sẽ chia sẻ:
- Harness là gì, và vì sao nó quan trọng không kém việc chọn model.
- 5 hệ thống con của một harness hoàn chỉnh.
- Cách bắt đầu với chỉ 4 file, và cách dựng nhanh bằng Harness Kit — bộ công cụ mã nguồn mở mình phát triển.
1. Cùng một model, kết quả khác hẳn nhau
Anthropic có một thí nghiệm rất đáng suy ngẫm trong bài Harness design for long-running apps. Họ dùng cùng model Claude Opus 4.5, cùng một prompt: "Tạo một 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 (solo) | 20 phút | $9 | Giao diện trông ổn, nhưng game không chơi được: entity hiện lên màn hình mà không phản hồi input |
| Có harness đầy đủ | 6 giờ | $200 | Một game editor chơi được thật |
Chi phí cao hơn hơn 20 lần, nhưng một bên là sản phẩm hỏng, một bên là sản phẩm dùng được. Điểm mấu chốt: model không đổi, thứ thay đổi là harness bao quanh nó.
OpenAI cũng có một câu chuyện tương tự 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 một sản phẩm với 0 dòng code viết tay. Vai trò của kỹ sư dịch chuyển từ "tự viết code" sang "thiết kế môi trường để agent viết code đúng".
2. Harness là gì?
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.
Một công thức dễ nhớ:
LLM (động cơ) + Harness (khung xe & vô lăng) = AI Agent (chiếc xe tự lái)
Bản chất LLM là bộ sinh văn bản "một lượt": bạn hỏi, nó trả lời, rồi dừng. Tự nó không thể duyệt codebase, chạy test, thấy lỗi rồi sửa lại. Harness cho nó khả năng hành động (qua tool), quan sát kết quả, tự sửa sai và lặp lại cho tới khi đạt mục tiêu — trong một không gian an toàn.
Hãy tưởng tượng bạn đưa cây búa cho một robot thông minh trong phòng khách. Không có tường bảo vệ và chỉ dẫn rõ ràng, nó có thể đập vỡ tivi chỉ để đóng một cây đinh. Harness chính là "phòng lab an toàn" đó.
Thực ra Claude Code, Cursor, Codex hay Windsurf đều là harness. Nhưng đó mới là phần chung của tool; phần harness ở cấp dự án — quy tắc, trạng thái, tiêu chí "xong" — là việc của bạn.
Harness khác gì 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ần 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 |
3. 5 hệ thống con của một harness hoàn chỉnh
3.1. Instructions — Chỉ dẫn
Cho agent 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ồ. Cách tốt hơn là tiết lộ dần (progressive disclosure): AGENTS.md / CLAUDE.md đóng vai trò bản đồ, chi tiết nằm trong docs/ để agent đọc khi cần. Cho agent một tấm bản đồ, không phải một bộ bách khoa toàn thư.
Đi kèm là nguyên tắc kho mã 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 bạn đều vô hình với agent.
3.2. State — Trạng thái
Context window có hạn, và mỗi phiên agent bắt đầu 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.
3.3. Verification — Kiểm chứng
Agent rất hay tuyên bố hoàn thành quá sớm, vì sự tự tin ≠ 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".
3.4. 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: một tính năng tại một thời điểm, 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 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.
3.5. Session Lifecycle — Vòng đời phiên
Mỗi phiên cần khởi tạo bài bản ở đầu (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.
4. Vòng đời một phiên agent "có kỷ luật"
- Bắt đầu: đọc
AGENTS.md→ chạyinit.sh→ đọcprogress.md→ đọcfeature_list.json→ xemgit log. - Chọn: chọn 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.mdvàfeature_list.json→ ghi lại vấn đề còn tồn đọng → commit (chỉ khi an toàn) → để lại trạng thái sạch.
5. Bắt đầu với chỉ 4 file
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/
# AGENTS.md
You are a coding agent working on this repo.
## Rules
1. Always run ./init.sh before claiming a task is done
2. Only work on one feature at a time (the active one in feature_list.json)
3. Update progress.md at the end of every session
feature_list.json
{
"features": [
{ "id": "auth", "name": "User Auth", "status": "pending" },
{ "id": "dashboard", "name": "Dashboard", "status": "pending" }
]
}
#!/bin/bash
set -e
npm install
npm run lint
npm test
echo "Environment ready!"
# progress.md
## Session 2026-11-17
- Done: auth (tests pass)
- Working: dashboard
- Remaining: settings, API docs
Chỉ vậy thôi đã đủ thay đổi rõ rệt cách agent làm việc.
6. Dựng harness bằng một lệnh với Harness Kit
Tạo tay 4 file thì dễ, nhưng giữ chúng nhất quán qua nhiều dự án thì mệt. Đó là lý do mình làm Harness Kit — một governance layer cho mọi AI coding agent: chỉ dùng thư viện chuẩn Python 3.8+, không phụ thuộc thư viện ngoài, mã nguồn mở (MIT). Dùng được với Claude Code, Cursor, Codex, Windsurf, Antigravity — bất kỳ tool nào đọc file chỉ dẫn.
Cài đặt
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
Bạn có ngay 6 file:
| File | Mục đích |
|---|---|
AGENTS.md |
Quy tắc AI đọc khi bắt đầu mỗi phiên |
feature_list.json |
Tính năng, trạng thái, phụ thuộc |
progress.md |
AI ghi tiến độ sau mỗi phiên |
init.sh / init.ps1 |
Script xác minh (test, lint, build) |
session-handoff.md |
Ngữ cảnh bàn giao cho phiên sau |
hk.py |
CLI quản lý hàng đợi tính năng và chấm điểm harness |
Tool của bạn đọc CLAUDE.md thay vì AGENTS.md? Thêm cờ --agent-file CLAUDE.md:
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh -s -- --agent-file CLAUDE.md
Hai cách làm việc
Cách 1 — nói chuyện với agent bằng ngôn ngữ tự nhiên:
"Read AGENTS.md and implement the active feature in feature_list.json."
"We're done with F-003 — run init.sh, update progress.md, and move to the next feature."
Agent tự đọc AGENTS.md, nhận tính năng đang active và tuân theo Definition of Done. Không cần plugin hay extension.
Cách 2 — 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 đầy đủ
(Trên macOS/Linux, thay py bằng python3.)
Lệnh mình thích nhất là done: 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". Còn audit cho bạn một con số cụ thể để biết harness của dự án đang thiếu gì.
Muốn đi sâu hơn: chế độ --full
Thêm --full khi cài, Harness Kit bổ sung thư mục harness/ gồm 7 module Python — một runtime agent tối giản để bạn hiểu (và tuỳ biến) những gì diễn ra bên trong các tool như Claude Code:
- Vòng lặp có giới hạn: lấy context → LLM chọn tool → chạy tool → đưa kết quả về context → lặp lại; dừng khi xong hoặc chạm trần số vòng.
- Quản lý context: tự nén (compaction) các lượt cũ khi gần chạm ngưỡng, giữ nguyên system prompt và các lượt gần nhất.
- Lưu trạng thái bền bỉ: log JSONL append-only, ghi xuống đĩa ngay lập tức; tiến trình sập thì replay log để dựng lại ngữ cảnh.
- Lắp prompt thân thiện với cache: phần tĩnh đặt trước, phần động đặt sau để không phá prefix cache — tiết kiệm chi phí API và độ trễ.
- Tool registry & phân quyền: 3 cấp Read-only / Workspace Write / Full Access; phân loại lệnh shell lúc chạy (
catkhácrm), lệnh nguy hiểm phải hỏi người dùng. - Sub-agent: spawn → giới hạn tool → chỉ trả bản tóm tắt về agent cha, tránh phình context.
- Hook pre-tool / post-tool: chặn hoặc sửa tham số trước khi chạy; audit, log, telemetry sau khi chạy.
Vài "bẫy" khi tự thiết kế harness
- Đừng gắn nhãn an toàn tĩnh cho tool. Tool shell an toàn khi chạy
git diffnhưng không an toàn khi chạyrm -rf. Hãy phân loại theo tham số tại thời điểm chạy. - Vô hiệu hoá cache khi file thay đổi. Ghi file xong mà không xoá cache của đường dẫn đó, các tool khác sẽ đọc phải dữ liệu cũ.
- Giới hạn bộ nhớ âm thầm. Bộ nhớ thường có giới hạn dung lượng khi đọc; bản tóm tắt dài sẽ bị cắt mà không báo lỗi. Hãy lưu những con trỏ ngắn một dòng thay vì đoạn tóm tắt dài.
7. Học bài bản: Learn Harness Engineering
Nếu muốn hiểu tại sao đằng sau từng quy tắc, mình có làm trang học Learn Harness Engineering bằng tiếng Việt: 6 giai đoạn, 12 bài giảng, 6 dự án thực hành.
| Giai đoạn | Nội dung chính |
|---|---|
| 1. Nền tảng | Vì sao agent mạnh vẫn thất bại; harness thực sự là gì |
| 2. Tổ chức kho mã | Kho mã là nguồn chân lý; vì sao file hướng dẫn khổng lồ thất bại |
| 3. Đa phiên | Giữ tính liên tục qua nhiều phiên; khởi tạo là một giai đoạn riêng |
| 4. Phản hồi & phạm vi | Agent vượt phạm vi; danh sách tính năng là "nguyên thủy" của harness |
| 5. Kiểm chứng | Agent tuyên bố xong quá sớm; kiểm thử đầu–cuối thay đổi kết quả |
| 6. Sản xuất | Khả năng quan sát; mỗi phiên phải để lại trạng thái sạch |
Các dự án xoay quanh việc xây một ứng dụng Electron từ đầu: bắt đầu bằng so sánh "chỉ dùng prompt" với "ưu tiên quy tắc", và kết thúc bằng một harness hoàn chỉnh kèm nghiên cứu ablation. Lời giải của mỗi dự án trở thành bộ khởi đầu cho dự án tiếp theo — ứng dụng lớn dần, kỹ năng harness của bạn cũng vậy.
Trang học còn có sẵn mẫu AGENTS.md, CLAUDE.md, feature_list.json, init.sh và các checklist cho khởi tạo, xác minh, bàn giao để bạn copy dùng ngay.
Kết luận
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ì cũng chỉ lao nhanh hơn về hướng sai.
Nếu chỉ nhớ một điều từ bài này: đừng để agent tự tuyên bố "xong" — hãy để test làm việc đó. Bắt đầu bằng 4 file, hoặc một lệnh cài Harness Kit, rồi xem agent của bạn thay đổi thế nào ngay trong phiên tiếp theo.
Bạn đang dùng agent nào và hay gặp kiểu "tai nạn" gì nhất? Chia sẻ ở phần bình luận nhé!
Tài liệu tham khảo
All rights reserved