Harness engineering là gì: biến AI agent thành công cụ làm việc thực sự

Harness engineering nói đơn giản

Harness engineering là ngành kỹ thuật về cách xây dựng quanh một mô hình ngôn ngữ một môi trường để nó thực hiện công việc thật một cách đáng tin cậy. Từ harness có nghĩa là «dây cương»: mô hình rất mạnh, nhưng tự nó không biết phải đi đâu, dùng công cụ gì và khi nào thì dừng lại. Harness định hướng sức mạnh đó.

Cách diễn đạt ngắn nhất là như sau:

Agent = Mô hình + Harness

Mô hình là các trọng số, khả năng suy luận và viết văn bản hoặc mã. Harness là tất cả phần còn lại: hướng dẫn hệ thống và các tệp như CLAUDE.md hoặc AGENTS.md, bộ công cụ (shell, chỉnh sửa tệp, máy chủ MCP), sandbox nơi agent chạy lệnh, các tệp trạng thái giữa các phiên, bài kiểm thử, linter và hook báo lỗi cho agent. Nếu bỏ harness đi, chỉ còn lại một khung chat chỉ biết trả lời bằng văn bản.

Vì sao agent lúc «giỏi như senior», lúc «non như junior»

Quen thuộc không? Trong một repository, agent làm việc như lập trình viên giàu kinh nghiệm, còn trong repository khác thì lạc hướng, quên quyết định hôm qua và báo cáo «xong» cho một tính năng không chạy. Phản ứng đầu tiên là đổi sang mô hình mới hơn. Thường thì cách này không giúp gì, vì mô hình vẫn là một. Khác biệt nằm ở môi trường.

Từ đó xuất hiện sự thay đổi tư duy đầu tiên của harness engineering: agent không hỏng, hỏng là thứ xung quanh nó. Agent không thể chạy kiểm thử nếu không có quyền truy cập. Nó sẽ không nhớ điều đã thử nếu điều đó không được ghi lại ở đâu cả. Nó không biết tính năng bị lỗi nếu không có kiểm tra nào báo cho nó. Đây không phải là «tính cách» của mô hình mà là lỗi thiết kế, và có thể sửa một cách có hệ thống.

Các triệu chứng điển hình của harness yếu

• Mỗi phiên mới bắt đầu bằng việc sửa môi trường: sai phụ thuộc, cơ sở dữ liệu không khởi động, thiếu biến môi trường.
• Agent lặp lại những giải pháp đã bị loại bỏ, vì không nhớ phiên trước.
• Quy tắc được viết sẵn trong hướng dẫn nhưng agent vẫn bỏ qua.
• «Kiểm thử đều xanh», nhưng tính năng vẫn lỗi vì kiểm thử kiểm tra sai thứ.
• Agent nhận ba việc cùng lúc và không hoàn thành việc nào.

Harness gồm những gì: năm hệ thống con

Lỗi thường gặp là coi harness chỉ là một tệp prompt. Trên thực tế, đó là năm cơ chế, và mỗi cơ chế hỏng theo cách riêng.

Hướng dẫn

Hướng dẫn trả lời câu hỏi «agent có tìm thấy quy tắc cần thiết không». Tệp đầu vào tốt là một bản đồ, không phải sách giáo khoa: một mục lục ngắn gồm các lệnh kiểm tra và ràng buộc cứng, còn chi tiết nằm trong các tài liệu riêng mà agent mở khi cần. Hướng dẫn tốt đặt ra các bất biến («mọi truy vấn SQL đều dùng tham số hoá»), chứ không ra lệnh cách cài đặt từng dòng.

Công cụ

Agent chỉ có thể kiểm tra những gì nó có quyền truy cập. Nếu nó không chạy được linter, thì quy tắc «chạy linter trước khi commit» cũng vô tác dụng. Công cụ được cung cấp qua các khả năng tích hợp sẵn của agent (đọc và sửa tệp, chạy lệnh) và qua MCP, giao thức cho phép agent truy cập cơ sở dữ liệu, trình duyệt, hệ thống quản lý công việc.

Môi trường

Môi trường là nơi agent chạy lệnh. Nó phải khởi động bằng một lệnh, giống nhau ở mọi phiên, và giới hạn thiệt hại khi xảy ra lỗi: sandbox không có quyền truy cập production, nhánh hoặc bản sao làm việc riêng, khả năng đưa mọi thứ về trạng thái ban đầu trong một phút.

Trạng thái

Mô hình không có bộ nhớ giữa các phiên: mọi thứ không được ghi vào repository đều biến mất cùng với cửa sổ ngữ cảnh. Vì vậy mục tiêu, những việc đã làm, các quyết định, ngõ cụt và bước tiếp theo phải nằm trong tệp. Cách kiểm tra đơn giản: mở một phiên mới, nói với agent «tiếp tục đi» và xem nó bắt đầu làm việc hay hỏi xem phải làm gì.

Phản hồi

Vòng phản hồi là hệ thống con quan trọng nhất. Không có nó, agent là thẩm phán duy nhất của chính mình và sẽ tự tin cho rằng nhiệm vụ đã xong. Kiểm thử, kiểm tra kiểu, linter, hook chạy sau mỗi lần sửa, kịch bản E2E trong trình duyệt: tất cả đều trả về cho agent tín hiệu đỏ khi lỗi vẫn còn rẻ để sửa.

Harness là một vòng khép kín, không phải một danh sách

Năm hệ thống con hoạt động như một vòng khép kín. Mô hình nhận hướng dẫn, thông qua công cụ hành động trong môi trường, thực hiện thay đổi trong repository, và kiểm chứng sẽ kiểm tra kết quả. Phản hồi đỏ quay lại mô hình để sửa, phản hồi xanh được ghi vào trạng thái. Trạng thái lại cập nhật hướng dẫn cho phiên tiếp theo.

hướng dẫn → mô hình → công cụ → môi trường → thay đổi
                ↑                              ↓
                └──── đỏ ── kiểm chứng ────────┘
                                     ↓ xanh
                                 trạng thái → (phiên tiếp theo)

Bỏ đi bất kỳ mũi tên nào thì vòng sẽ hở đúng ở chỗ đó. Không có kiểm chứng, agent không biết mình sai. Không có trạng thái, phiên tiếp theo sẽ bắt đầu bằng việc lần lại dấu vết thay vì làm việc. Vì vậy, đầu tư vào một hệ thống con không bù được lỗ hổng ở hệ thống khác: một tệp AGENTS.md dài năm trang không thay thế được bài kiểm thử còn thiếu.

Harness engineering khác gì prompt engineering và context engineering

Các khái niệm này nằm lồng vào nhau, không phải cạnh tranh với nhau.

Prompt engineering là một phần của hệ thống con hướng dẫn. Context engineering bao gồm hướng dẫn và trạng thái: agent nhìn thấy gì ở mỗi thời điểm. Harness engineering bổ sung những thứ không thể nhét vừa cửa sổ ngữ cảnh: quyền truy cập, sandbox, kiểm thử, hook, quy trình làm việc. Một prompt viết rất tốt cũng không giúp được gì nếu agent thực sự không thể chạy kiểm thử.

Vì sao cần harness: toán học của các tác vụ dài

Có vẻ như một mô hình làm đúng 95% các bước thì gần như hoàn hảo. Nhưng tác vụ của agent gồm nhiều bước, và lỗi tích luỹ dần. Nếu các bước độc lập, xác suất đi qua tất cả mà không sai là tích của các xác suất:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Đến bước thứ mười, chỉ khoảng 60% lần chạy không mắc lỗi nào, còn đến bước thứ năm mươi thì ít hơn một trên mười. Nâng mô hình lên 97% thì tốn kém và không nằm trong tầm tay bạn. Nhưng bắt lỗi ngay tại bước nó xảy ra và trả lại cho agent thì đó chính là nhiệm vụ của harness. Vòng phản hồi biến chuỗi «lỗi kéo theo lỗi tiếp theo» thành chuỗi các bước ngắn có thể sửa được.

Ví dụ: cùng một agent ở hai repository

Nhiệm vụ: thêm chiết khấu theo mã khuyến mãi vào backend thanh toán trên FastAPI.

Không có harness

Agent đọc vài tệp, viết hàm tính chiết khấu và một unit test kiểm tra hàm đó một cách độc lập. Test xanh, agent viết «xong». Nó không biết rằng việc tính tổng cuối cùng được thực hiện ở một module khác và không thể dựng cơ sở dữ liệu hay chạy trọn vẹn kịch bản đặt hàng. Một ngày sau người ta phát hiện chiết khấu trong giỏ hàng không được áp dụng.

Có harness

Ở thư mục gốc có AGENTS.md dài vài chục dòng: cách khởi động môi trường, những lệnh kiểm chứng bắt buộc, nơi mô tả kiến trúc thanh toán. Môi trường khởi động bằng docker compose up -d. Trong repository có tệp kế hoạch với tiêu chí hoàn thành: «kịch bản E2E đặt hàng với mã khuyến mãi chạy thành công». Sau mỗi lần sửa, một hook chạy linter và kiểm tra kiểu, và trước khi kết thúc agent phải chạy kiểm thử E2E.

# AGENTS.md (đoạn trích)
## Kiểm chứng — bắt buộc trước khi nói «xong»
make lint        # ruff + mypy
make test        # pytest, unit và integration
make e2e         # kịch bản đặt hàng

## MUST
- Tiền được tính bằng xu (int), tuyệt đối không dùng float
- Mọi truy vấn SQL đều phải tham số hoá
- Không sửa các migration đã áp dụng lên production

Mô hình vẫn như cũ. Nhưng bây giờ agent tìm được module tính tổng tiền thông qua bản đồ dự án, kiểm thử E2E thất bại ngay lần chạy đầu tiên, agent thấy chiết khấu chưa đến được giỏ hàng, sửa lại và chỉ báo cáo sau khi lần chạy xanh. Sự khác biệt về kết quả hoàn toàn là nhờ harness.

Bắt đầu từ đâu

1. Mô tả cách agent kiểm tra công việc của chính nó: một đến ba lệnh mà nó bắt buộc phải chạy. Phản hồi mang lại hiệu quả lớn nhất, nên hãy bắt đầu từ đó.
2. Làm cho môi trường có thể tái lập: khởi động bằng một lệnh, và có cách để quay lại nhanh chóng.
3. Tạo tệp trạng thái: mục tiêu, những việc đã làm, quyết định và ngõ cụt, bước tiếp theo.
4. Rút gọn hướng dẫn thành bản đồ: lệnh kiểm chứng, ràng buộc cứng, liên kết đến tài liệu chi tiết.
5. Ghi nhật ký thất bại của agent: với mỗi sự cố, ghi lại hệ thống con nào đã cho phép nó xảy ra. Nhật ký sẽ cho biết cần sửa gì tiếp theo.

Một cách thực tế là chấm từng hệ thống con trong năm hệ thống theo thang điểm từ 1 đến 5, dành nửa giờ cho hệ thống yếu nhất và chạy cùng một bộ năm nhiệm vụ điển hình trước và sau khi sửa. Nhờ vậy, việc cải thiện harness trở nên đo được, không phải chỉ dựa vào cảm giác.

Tóm lại

Harness engineering là công việc không nhắm vào mô hình, mà vào mọi thứ bao quanh nó: hướng dẫn, công cụ, môi trường, trạng thái và các vòng phản hồi. Độ tin cậy của agent do mắt xích yếu nhất trong vòng này quyết định, vì vậy đổi mô hình hiếm khi chữa được sự bất ổn, còn thêm một bài kiểm thử hay một tệp kế hoạch thì thường lại có tác dụng. Cả năm hệ thống con và cách lắp ráp harness được trình bày chi tiết qua thực hành trong khoá học harness engineering.