Harness engineering: ba cấp độ làm coding agent tốt hơn

1. Harness bạn được giao không phải là harness duy nhất

Leon mở đầu bằng một nhận định: phần lớn mọi người, và cả các công ty, đều nghĩ rằng coding harness mà mình được giao là cái duy nhất mình có. Bạn cài Claude Code, Codex hoặc OpenCode, cấu hình model, thêm vài memory file, có thể thêm vài hook, vài tool, rồi nghĩ thế là xong. Nhưng thực tế, đó mới chỉ là cấp 1 của harness engineering, và phần lớn những người đang build bằng AI không bao giờ vượt qua được cấp này.

Harness engineering là chủ đề Leon thực sự đam mê. Anh đã làm việc với rất nhiều cá nhân và team để chỉ cho họ cách dùng coding harness hiệu quả, và thậm chí tự build harness của riêng họ. Theo anh, nếu bạn muốn theo nghề AI engineer, hoặc muốn làm việc với khách hàng thật, bạn cần hiểu ba cấp độ của harness engineering, và đó chính là nội dung của video này. Anh hứa người xem sẽ thấy rất vui, rồi đi thẳng vào nội dung.

Ngay sau đó có một đoạn ngắn Leon giới thiệu cộng đồng trả phí Agentic Labs của anh: các lớp học về dùng coding agent, buổi deep dive mỗi thứ Năm (một buổi đã bàn về harness engineering suốt một tiếng rưỡi, xem lại được trong lớp), một series mới dạy đi từ con số không tới thành thạo với coding agent, và một chương trình giảm giá gói năm.

2. Agent là gì: model cộng với harness

Nếu đã dùng AI một thời gian, chắc bạn đã nghe chữ agent tới phát ngán. Nhưng chính xác thì agent là gì? Leon định nghĩa: agent thực ra là model, tức large language model (LLM) của bạn, cộng với harness.

Model là những cái tên như Opus, Fable, GPT-6. Đó là các model thật sự, về cơ bản là bộ não của cả hệ thống. Còn harness là môi trường mà LLM đó hoạt động bên trong.

3. Harness cấp rules, tools, checks và hooks

Leon liệt kê từng thứ mà harness làm cho agent:

• Rules. Harness là thứ phân phát các luật mà agent phải tuân theo.
• Tools. Harness gán các tool mà agent được phép dùng, chẳng hạn khả năng ghi file, tìm file, tìm trên web, mở browser, vân vân.
• Checks. Harness cũng bắt buộc chạy các bước kiểm tra, như chạy test suite, lint, type check. Theo Leon, chắc bạn đã thấy những thứ này rồi.
• Hooks. Harness có thể mở ra các hook. Đây là những sự kiện xảy ra trong suốt vòng đời của agent mà ta có thể móc vào để chạy thêm việc của mình.

Ví dụ về hook: ngay lúc ta gửi một prompt cho agent, ta muốn chạy trước một script riêng để kiểm tra prompt đó có chứa thông tin nhạy cảm không, và che (mask) những thông tin đó đi trước khi chúng tới được agent thật.

Hook dùng được cho rất nhiều việc khác nhau. Leon kể Claude mới đây ra mắt tính năng mods, cho phép bạn tuỳ biến trải nghiệm Claude Code của mình (trên màn hình là trang "Customize Claude Code with mods", ghi rằng bạn có thể đổi cách Claude Code hoạt động và trông ra sao chỉ với vài dòng TypeScript). Nhưng bên dưới, theo Leon, mods về cơ bản cũng đang dùng hook.

4. Memory file, sandbox và công thức agent = model + harness

Harness còn cho agent quyền truy cập vào các memory file. Đó là file AGENTS.md của bạn, file DESIGN.md, SOUL.md, hoặc thậm chí các file nằm trong thư mục docs.

Harness cũng có thể quyết định cách đặt agent vào sandbox. Ví dụ, agent chỉ được làm việc bên trong một workspace rất cụ thể, hoặc chỉ được phép tạo worktree mới và feature branch mới, và không bao giờ được đụng vào branch main.

Tới đây, Leon hy vọng người xem đã bắt đầu hiểu: harness là thứ trao năng lực cho agent, đồng thời định nghĩa môi trường và các luật mà agent được phép làm việc bên trong. Nói thật đơn giản, agent là model cộng với harness. Harness mở ra các chỉ dẫn (instructions), các tool, các check và memory mà agent được dùng.

Tất nhiên, danh sách này có thể mở rộng thêm các năng lực khác như sub-agent và workflow, nhưng tất cả những thứ đó cũng đều do harness mở ra.

5. Ba cấp độ, cấp 1: cấu hình harness có sẵn

Khi đã có cái nhìn tổng quan về harness và agent, Leon chuyển sang phần cốt lõi của video: ba cấp độ của harness engineering.

Cấp đầu tiên là configuration. Leon nói đây là nơi phần lớn người xem video đang đứng: bạn dùng một coding harness do nhà cung cấp model hoặc một bên thứ ba build sẵn. Ví dụ, nếu bạn đang dùng Claude Code, bạn đang ở cấp này. Việc bạn làm là cấu hình harness để nó chạy theo cách bạn muốn. Nếu muốn agent tuân theo những luật rất cụ thể, bạn cập nhật file AGENTS.md để đưa cho agent những hướng dẫn đó.

Leon mở ra một ví dụ thực tế. Trong hầu hết project, bạn đặt luật vào file AGENTS.md, gọi là một memory file. Nghĩa là mọi luật ta muốn agent tuân theo mỗi khi mở session mới đều có thể dồn vào file này, và lần tới mở một session Claude mới, agent sẽ làm theo các luật đó. Trên màn hình là AGENTS.md của một project game kinh dị "cozy horror" chạy trên browser, có tiêu đề, mô tả game và mục "Sources of truth (read before changing anything)".

6. AGENTS.md: open standard và có thể tách nhỏ

Chuyện này không chỉ áp dụng cho Claude. File AGENTS.md thực ra là một open standard (trang agents.md mô tả nó là một định dạng mở để hướng dẫn coding agent). Theo Leon, coding harness nào đáng dùng cũng sẽ tôn trọng file AGENTS.md.

Nguyên tắc cơ bản với file này: nếu agent bắt đầu làm điều gì đó trong chat mà bạn thật sự không thích, hãy thêm một luật vào file bảo agent đừng bao giờ làm vậy nữa, hoặc đưa hướng dẫn về cách nó nên cư xử từ nay về sau. Trên màn hình là một khung AGENTS.md mẫu với mục "## Rules" và một dòng "Use TypeScript strict mode."

File này cũng có tính composable, nghĩa là bạn không phải nhét mọi thứ vào cùng một file markdown, vì nó sẽ dài quá mức. Thay vào đó, bạn tách các luật ra và lưu thành những file riêng. Một quy ước phổ biến là tạo thư mục docs rồi chia markdown thành những file nhỏ hơn, sắp xếp rất có cấu trúc trong thư mục đó. Sau đó, trong file AGENTS.md chính, bạn đặt một mục lục (index) trỏ tới tất cả những file nhỏ trong docs. Mỗi file trong đó chẳng qua là một file markdown nhỏ hơn, với những chỉ dẫn rất cụ thể cho đúng một phần của app.

Trong project game của Leon, AGENTS.md có một bảng "File / What it is" liệt kê từng file: docs/GAME_DESIGN.md chứa câu chuyện, nhân vật, cơ chế, beat sheet, các cú hù và thoại; docs/SCRIPT.md là toàn bộ kịch bản thoại; docs/TECH_PLAN.md là stack, kiến trúc và các cổng chất lượng; docs/LEVEL_LAYOUT.md là toạ độ và tên các điểm neo dùng chung; docs/BACKLOG.md ghi mọi phát hiện từ các lần playtest.

7. Handoff document khi sắp chạm giới hạn context window

Một mẹo khác Leon chia sẻ về memory file: nếu session bắt đầu dài quá và bạn sắp chạm giới hạn context window, bạn chỉ cần bảo agent lưu lại tiến độ hiện tại và những việc còn phải làm vào các file riêng.

Bản thân Leon đã phải nhờ agent tạo một handoff document như vậy, để anh có thể mở một session hoàn toàn mới với một agent mới và chỉ cần đưa cho agent đó file handoff. Trên màn hình là file docs/HANDOFF.md của project game, tiêu đề "LAST CALL: Session handoff", câu đầu ghi rằng đây là file phải đọc đầu tiên trong mọi session mới hoặc sau khi nén context, và nó là một file trỏ (pointer file) dẫn sang các tài liệu chi tiết.

Nhờ toàn bộ ngữ cảnh có sẵn trong các tài liệu đó, agent mới biết chính xác những gì đã xảy ra tới giờ, project nói về cái gì, và phải tiếp tục ra sao.

Tất nhiên, bạn còn có thể cấu hình harness theo nhiều cách khác nữa, chẳng hạn thêm hook vào harness. Đó là phần demo tiếp theo.

8. Demo hook: stop hook bắt agent ghi changelog

Leon chuyển sang VS Code, nơi anh dựng sẵn một demo rất đơn giản. Trong app này, mỗi khi có thay đổi, agent phải ghi một mục vào changelog. File CHANGELOG.md trên màn hình có tiêu đề "# Changelog", mục "## Unreleased" và một dòng ghi đã thêm một app todo chạy trên browser (index.html, style.css, app.js) có thể thêm, sửa, xoá và lọc todo, lưu vào localStorage.

Leon nói anh không có file AGENTS.md nào trong project này. Lý tưởng thì nên có một file bảo agent cập nhật changelog, nhưng anh cũng có thể ép hành vi đó bằng hook.

Hầu hết các harness đều cho phép bạn móc vào một số sự kiện nhất định. Ví dụ, khi ta gửi prompt, ta có thể chen vào, lấy prompt đó, xử lý gì đó rồi mới chuyển cho agent. Có rất nhiều hook. Một hook rất có giá trị là stop hook: mỗi khi agent làm xong việc, ta có thể kích hoạt stop hook và làm gì đó với cuộc hội thoại.

Trong file .claude/settings.json trên màn hình, mục "hooks" có một khoá "Stop" chứa một hook kiểu "command" chạy bằng bash một script verify.sh trong thư mục tutorial của anh, với "timeout": 30 và "statusMessage": "Running verify.sh...". Phía dưới file còn có một mục "permissions" với danh sách "deny".

Script này kiểm tra xem changelog đã được cập nhật chưa. Nếu chưa, nó sẽ nói với Claude rằng: này, bạn phải quay lại và thêm một mục vào changelog, nhờ vậy hành vi đó được ép buộc. Bạn có thể làm y hệt để kiểm tra xem PR đã được tạo chưa, hoặc test suite đã được chạy chưa.

Leon nhấn mạnh: có rất nhiều thứ bạn có thể ép buộc như một phần của harness. Theo cách này, bạn không phải trông chờ agent tự nhớ làm một việc gì đó. Tài liệu chính thức về hook của Claude Code có mô tả sự kiện Stop cùng các sự kiện khác: code.claude.com/docs/en/hooks.

9. Cấp 2: tự build harness, một kỹ năng đang được săn

Dĩ nhiên, cấu hình harness mới chỉ là cấp 1. Cấp 2 là nơi ta build custom harness. Leon bảo người xem hãy tin anh: tự build harness đang là thứ có nhu cầu rất cao lúc này. Một số tổ chức cần khả năng kiểm soát những gì developer được phép làm, như áp các policy, cho agent quyền dùng những tool rất cụ thể, hoặc giới hạn hẳn một số năng lực. Anh đã làm việc với nhiều thương hiệu và đã thấy cả tá custom harness ngoài kia.

Vậy tại sao lại muốn tự build harness thay vì dùng những cái có sẵn? Có khó không? Người không có kinh nghiệm kỹ thuật có làm được không? Câu trả lời đầu tiên của Leon: ai cũng build được harness. Anh có một khoá học miễn phí trong cộng đồng miễn phí của mình dạy cách build coding harness, và anh nói rất thích thú khi thấy kết quả mọi người làm ra.

10. Cùng một model, harness tốt hơn, kết quả khác hẳn

Leon đã thấy vài ví dụ rất hay, trong đó chỉ thay harness thôi mà cùng một model đã cho ra kết quả tốt hơn.

Ví dụ đầu tiên là LangChain, từng làm một thí nghiệm: họ lấy GPT 5.2, đúng model đó, cùng prompt đó, và đạt kết quả tốt hơn nhờ dùng công cụ deep agent CLI của họ, tức coding agent harness riêng của họ. Theo lời Leon, họ đẩy được kết quả từ khoảng 53% lên khoảng 66%. Bài viết của LangChain trên màn hình có tiêu đề "Improving Deep Agents with harness engineering", phần tóm tắt ghi coding agent của họ đi từ Top 30 lên Top 5 trên Terminal Bench 2.0 và họ chỉ thay đổi harness.

Ví dụ thứ hai là một bài đăng rất nổi trên X của Can Bölük (Leon xin lỗi trước nếu anh đọc sai tên). Người này đạt được kết quả rất tốt, một lần nữa, chỉ bằng cách đổi harness. Tiêu đề bài viết trên màn hình ghi "The Harness Is the Bottleneck" và "I improved 15 LLMs at coding in one afternoon. Only the harness changed." Như chính tác giả viết, coding harness mới là nút thắt cổ chai. Theo lời Leon, anh ấy đẩy Grok Code Fast 1 từ chỉ 6.7% lên gần 70%, đơn giản bằng cách thay đổi cách các tool bên dưới hoạt động.

11. Vì sao các harness phổ biến không hợp với model chạy local

Đây là mảng Leon có rất nhiều kinh nghiệm. Ai theo dõi kênh anh một thời gian sẽ biết anh hay làm video về open-weight model, tức các model chạy trên phần cứng của chính bạn. Anh đã chạy những model này trong OpenCode, trong Claude Code và đủ loại harness khác, và anh cũng đã làm video về Pi agent SDK. Tuy nhiên, không harness nào trong số đó được tối ưu cho model chạy local.

Để tiết kiệm thời gian của người xem, Leon không đi lại mọi chi tiết, bạn có thể xem video riêng của anh về Smol Coder. Tóm lại điều xảy ra là thế này: hãy nhớ harness là thứ chèn vào system prompt, các memory file, và mở ra các tool. Những harness kia chèn quá nhiều context cho các model nhỏ.

Thông thường, model local có context window rất nhỏ, nhất là trên phần cứng phổ thông. Nếu toàn bộ context window chỉ khoảng 32.000 hoặc 64.000 token, bạn không thể để Claude Code chèn vào 30.000 token chỉ toàn là thứ của harness.

Vì vậy Leon quyết định tạo harness Smol Coder, gỡ bỏ mọi thứ mà một open-weight model sẽ không bao giờ cần. Open-weight model chạy trên phần cứng của bạn sẽ không bao giờ cần chạy những thứ như MCP tool hay sub-agent. Nó chỉ nên có một bộ tool giới hạn, và system prompt phải thật nhỏ, chỉ được tối ưu cho một chức năng cụ thể.

12. Demo Smol Coder: 1.400 token thay vì hơn 30.000

Leon cho xem nhanh Smol Coder trông như thế nào. Nó chỉ là một CLI tool bình thường, và tất nhiên cũng có bản chạy trên web. Trang giới thiệu smolcoder.dev ghi "A smol coding agent for the models already running on your machine": nếu bạn có Ollama hoặc LM Studio thì chỉ cách hai lệnh là có một AI pair programmer đọc code, sửa file, chạy test và khởi động dev server, không cần API key, không cần file config, không cần cloud. Ví dụ trên trang cho thấy một model qwen3 chạy qua Ollama nhận yêu cầu "Add a dark mode toggle to the settings page", đọc file Settings.tsx, sửa nó, chạy npm test với 12 test đạt.

Theo Leon, công cụ này giúp kéo vào bất kỳ model nào bạn muốn thật dễ dàng. Nó tự động phát hiện các model từ LM Studio và cả Ollama. Trong terminal, anh gõ lệnh /models và một danh sách chọn model hiện ra, gồm các model đang có trên máy qua Ollama và một lựa chọn tìm model trên máy khác trong mạng.

Nếu bạn từng thử dùng open-weight model với Pi agent SDK, OpenCode hay thậm chí Claude Code, sẽ có rất nhiều thứ phải cấu hình từ đầu. Còn harness này, vì là đồ tự làm và anh muốn làm gì cũng được, nên phát hiện model trên phần cứng của bạn dễ tới mức buồn cười, và nó được tối ưu thật sự cho model đó.

Để so sánh, Leon chạy Claude ngay lúc đó và mở phần context: trước khi anh gửi một tin nhắn nào cho Claude, nó đã chiếm hơn 30 nghìn token trong context window của anh. Vì vậy chạy một open-weight model trong harness đó đơn giản là không thực tế.

13. Tổ chức cần harness riêng để giữ trải nghiệm nhất quán

Leon cũng đã thấy nhiều ví dụ các tổ chức cần custom harness để kiểm soát trải nghiệm của developer trông ra sao. Ví dụ, họ không nhất thiết muốn bị khoá chặt vào chỉ một mình Claude. Họ có thể muốn cho developer dùng các nhà cung cấp khác, như OpenAI. Nhưng các tool và trải nghiệm chung thì phải nhất quán.

Nếu bạn tự build harness, chuyện này rất dễ. Bạn đổi provider, đổi model, và tất cả được kiểm soát bên trong custom harness đó. Bạn có thể áp các policy của tổ chức. Bạn kiểm soát được những tool nào được phép gán, có những quyền quản trị nào. Nói chung, với custom harness bạn làm được những thứ rất hay.

14. Cấp 3: orchestration harness và AutoForge

Khi đã học được cách build custom harness của riêng mình, theo Leon, rất đáng để bước lên tiếp và nhìn tới việc build orchestration harness. Trong một orchestration harness, bạn thực sự quản lý nhiều coding harness cùng lúc.

Bạn có thể có một harness phục vụ các job chạy dài, và mỗi job được thực thi bởi một coding agent hoặc harness cụ thể. AutoForge là một ví dụ của long-running harness. Bạn lên kế hoạch mọi feature bạn muốn, chúng được đưa vào một kiểu bảng to-do, rồi agent sẽ chạy, triển khai từng thay đổi một. Có thể có tới hàng trăm feature, và agent có thể mất không chỉ vài giờ hay vài ngày mà thậm chí vài tuần để làm hết. Nhưng điều quan trọng là bạn không phải ngồi đó trông chừng agent: nó tự làm hết việc này và tự test ở chế độ autopilot.

README của AutoForge mô tả nó là một coding agent tự hành chạy dài, dùng Claude Agent SDK để build trọn ứng dụng qua nhiều session với mô hình hai agent (initializer và coding agent); README hiện cũng ghi rằng repo không còn được bảo trì tích cực.

15. Software factory: một bầy agent chờ việc

Một ví dụ khác của orchestration harness là software factory. Leon nói phần này nhìn thì không thú vị lắm, và anh sẽ cho xem một ví dụ rất vui ngay sau đó. Nhưng về cơ bản, software factory là nơi bạn có một agent swarm. Bạn có thể có 10 hay 20 coding agent ngồi chờ ở chế độ nền. Những agent này có thể là một hỗn hợp: agent Codex, agent Claude Code, thậm chí coding harness tự build của bạn. Chúng chỉ ngồi chờ việc.

Việc software factory làm là: mỗi khi bạn cần thay đổi bất kỳ project nào, nó sẽ giao task đó cho một trong các coding agent đang rảnh. Nếu tất cả agent trong swarm đều bận, software factory sẽ tự xử lý: nó chờ tới khi có một agent rảnh rồi mới giao task tiếp theo. Leon có một video riêng về cách build software factory, anh sẽ để link trong phần mô tả.

Ở slide trước đó, Leon cũng cho thấy dạng đơn giản nhất của điều phối: một Orchestrator với "3 jobs running", lấy việc từ một job queue (auth-flow, billing, search, dark-mode) và phân cho ba harness khác nhau là Claude Code, Codex và Smol Coder.

16. cubefarm: bầy coding agent trong văn phòng 3D

Cuối cùng, Leon nói chẳng ai bảo agent harness thì phải nhàm chán. Anh cho xem coding agent swarm của mình được thể hiện trong không gian 3D, tức project cubefarm. Màn hình chào ghi "Cognaitiv AI" với nút "Enter the office", rồi mở ra một văn phòng hoạt hình với các bàn làm việc, màn hình và những nhân vật nhỏ ngồi gõ.

Những agent này đang làm việc trên một project thật. Mỗi agent chạy một coding harness, có thể là Claude Code, có thể là Codex. Nếu Leon chạy tới bất kỳ màn hình nào, anh có thể thấy agent đó đang làm gì, ví dụ anh này đang chạy Claude Opus, nghĩa là đang dùng Claude Code. Một số agent khác dùng các coding harness khác, tất cả đều được thể hiện trong không gian 3D.

Văn phòng cũng có một bảng kanban, gắn với các GitHub issue thật, với các cột như Backlog, In progress và In QA. Khi bấm vào bất kỳ thẻ nào, ta có thể nhảy thẳng tới pull request tương ứng trên GitHub. Và giống như long-running harness, ta có thể giao bao nhiêu task tuỳ thích, có thể hàng trăm task, và các agent sẽ cứ làm ở chế độ nền cho tới khi mọi thứ được build, test và kiểm chứng xong.

Leon cho biết project này và tất cả các project của anh đều là open source, bạn dùng được ngay hôm nay (repo leonvanzyl/cubefarm mô tả nó là một văn phòng 3D hoạt hình nơi một bầy agent Claude Code, cùng các QA tester, xử lý các GitHub issue của bạn). Slide kết thúc ghi "Fix the harness, not the prompt" và "Every repeated mistake becomes a rule or a check".

Anh kết bằng lời mời bấm like, subscribe kênh để xem thêm video về agentic coding và tham gia Agentic Labs, rồi cảm ơn người xem và hẹn gặp ở video sau.