Harness Engineering: Hệ Thống Quanh AI Quan Trọng Hơn AI

TL;DR — Harness engineering là mọi thứ xung quanh AI agent ngoại trừ model: memory, tools, permissions, hooks, observability. LangChain tăng 13.7 điểm benchmark chỉ bằng thay đổi harness (52.8% lên 66.5%, cùng model). Hầu hết developer chỉ có Layer 1 (CLAUDE.md). Production cần đủ 5.

Hai dòng config. Cùng một AI model. Độ tin cậy khác nhau hoàn toàn:

# Cách CLAUDE.md (có thể bị bỏ qua)
"Không bao giờ xóa production database tables."
# Claude đọc dòng này, cân nhắc nó trong 200K tokens context, và có thể bỏ qua.

# Cách Hook (luôn được enforce)
# PreToolUse hook: command chứa "DROP TABLE" + env=production → exit 2 → BLOCKED.

Cái đầu tiên là lời khuyên. Cái thứ hai là enforcement.

Một cái nằm trong file markdown, cạnh tranh với hàng nghìn tokens khác để giành sự chú ý của model. Cái còn lại là shell script chạy trước mọi command, không thể bypass. Khoảng cách giữa hai cách tiếp cận này là thứ mà hầu hết team chưa nhận ra tồn tại.

Khoảng cách đó giờ đã có tên: harness engineering.

Harness engineering là gì? (Và tại sao prompt engineering không đủ)

Harness engineering là ngành xây dựng constraints, tools, feedback loops, và observability xung quanh AI agent để nó hoạt động ổn định trong production. Công thức được LangChain phổ biến và Birgitta Böckeler trên site của Martin Fowler hệ thống hóa: Agent = Model + Harness. Model là commodity. Harness mới là lợi thế cạnh tranh.

Mitchell Hashimoto, người tạo ra Terraform và Ghostty, định nghĩa ý tưởng cốt lõi: mỗi lần agent mắc lỗi, bạn engineer một giải pháp để agent không bao giờ mắc lỗi đó nữa. Trong repo Ghostty, mỗi dòng trong file AGENTS.md tương ứng với một lần agent lỗi trong quá khứ, giờ đã được ngăn chặn (HumanLayer Blog, Mar 2026).

Ngành đã trải qua ba giai đoạn:

Prompt engineering quyết định agent cố gắng làm gì. Context engineering quyết định agent biết gì. Harness engineering quyết định agent được phép và không được phép làm gì.

Key insight: Harness engineering là ngành xây dựng constraints, tools, feedback loops, và observability xung quanh AI agents. Công thức: Agent = Model + Harness. Thuật ngữ xuất hiện đầu 2026, được hệ thống hóa bởi Birgitta Böckeler trên site Martin Fowler (Apr 2026), OpenAI, và LangChain. AGENTS.md pattern của Mitchell Hashimoto trong Ghostty trở thành ví dụ được trích dẫn nhiều nhất.

LangChain tăng 13.7 điểm benchmark mà không đổi model. Bằng cách nào?

Bằng cách cải thiện ba thành phần harness, LangChain nhảy từ 52.8% lên 66.5% trên Terminal Bench 2.0 (benchmark gồm 89 task thực tế trong terminal), giữ nguyên model gpt-5.2-codex. Từ Top 30 lên Top 5. Không fine-tune. Không đổi model. Chỉ thay đổi harness (LangChain Blog, Feb 2026).

Ba thay đổi cụ thể:

1. Context injection. LocalContextMiddleware của LangChain map toàn bộ environment trước và inject trực tiếp vào context. Trước đó, agent lãng phí nhiều bước chỉ để hiểu môi trường xung quanh.

2. Self-verification loops. Sau mỗi action, agent tự verify output dựa trên tiêu chí cụ thể của task trước khi sang bước tiếp theo. Không chỉ “chạy test.” Agent kiểm tra xem output có đúng với yêu cầu thực sự của task không.

3. Compute allocation. Phần này phản trực giác: chạy ở reasoning budget tối đa (xhigh) chỉ đạt 53.9%, trong khi setting high đạt 63.6%. Compute nhiều hơn gây timeout, làm giảm performance tổng thể. Harness cần quản lý agent suy nghĩ bao nhiêu, chứ không chỉ suy nghĩ về cái gì.

Nếu bạn đang đánh giá AI coding tools bằng cách so sánh model benchmarks, bạn đang đo sai biến số.

Key insight: LangChain cải thiện coding agent từ 52.8% lên 66.5% trên Terminal Bench 2.0 (+13.7 phần trăm), chỉ thay đổi harness và giữ nguyên gpt-5.2-codex. Chạy ở reasoning budget tối đa thực tế còn tệ hơn (53.9%) do timeout (LangChain Blog, Feb 2026).

5 layers của một AI agent harness là gì?

Một harness production-ready có năm layers: Memory, Tools, Permissions, Hooks, và Observability. Từ những gì tôi thấy trong cộng đồng Claude Code, hầu hết developer có Layer 1 và có thể một phần Layer 2. Còn lại ba layers đang bỏ phí.

Bản đồ đầy đủ cho Claude Code:

Nghĩ về nó như CI/CD pipeline. Bạn build hạ tầng đó một lần, cả team được lợi trên mỗi lần push. Harness cho AI agent sessions cũng hoạt động theo cách tương tự.

OpenAI đã chứng minh điều này ở quy mô lớn. Team Codex của họ ship khoảng một triệu dòng production code, không có dòng nào do con người viết, trong năm tháng. Harness của họ bao gồm AGENTS.md files, reproducible dev environments, và mechanical invariants trong CI. Throughput nhanh gấp khoảng 10 lần so với team thuần con người (InfoQ, Feb 2026).

Mỗi layer xứng đáng có bài deep-dive riêng. Xem chi tiết implementation tại 5 Layers của Claude Code Harness Production-Ready.

Key insight: Team Codex của OpenAI ship khoảng một triệu dòng production code, không có dòng nào viết tay, trong năm tháng, sử dụng harness gồm AGENTS.md files, reproducible environments, và CI invariants. Throughput: 3.5 merged PRs mỗi engineer mỗi ngày (InfoQ, Feb 2026).

Harness của bạn đang ở đâu?

Hầu hết developer có một file CLAUDE.md và có thể vài MCP servers. Đó là Layer 1 và một phần Layer 2 trong tổng số năm. Chạy checklist này để biết bạn đang ở đâu.

Trả lời có hoặc không:

Điểm của bạn:

• 1/5: Bạn thuộc đa số. Hầu hết developer dừng ở CLAUDE.md.
• 2-3/5: Trên trung bình. Bạn đã bắt đầu xây hạ tầng thật sự.
• 4-5/5: Production-ready. Bạn đang làm harness engineering dù có biết tên gọi hay không.

Hãy thành thật với câu 4. Nếu câu trả lời là không, agent của bạn vẫn có thể rm -rf project directory. CLAUDE.md nói “đừng làm thế.” Hook thì thật sự ngăn chặn được.

Tại sao điều này quan trọng: nghiên cứu từ ETH Zurich (Feb 2026) test context files trên 138 task thực tế từ 12 Python repositories. Human-written context files chỉ cải thiện agent success khoảng 4%. LLM-generated ones thực tế giảm success ~3% và tăng inference cost hơn 20% (MarkTechPost, Feb 2026). Instructions thôi không đủ. Bạn cần enforcement layers.

HumanLayer giữ CLAUDE.md của họ dưới 60 dòng (HumanLayer Blog, Mar 2026). Ít instruction hơn, nhiều hooks hơn. Đó là hướng đi.

Key insight: Nghiên cứu ETH Zurich test context files trên 138 task thực tế từ 12 Python repos. Human-written context files chỉ cải thiện agent success ~4%, trong khi LLM-generated files giảm success ~3% và tăng inference cost hơn 20% (MarkTechPost, Feb 2026).

Nhận tips Claude Code hàng tuần — Mỗi tuần một tip thực tế. Không spam, không fluff. Đăng ký AI Developer Weekly →

Bắt đầu xây harness ngay hôm nay bằng cách nào?

Không cần đủ 5 layers ngay lập tức. Bắt đầu với ba thay đổi có impact cao nhất, tổng cộng dưới 30 phút. Mỗi thay đổi cover một layer khác nhau.

Quick Win 1: Tạo MEMORY.md (5 phút)

MEMORY.md là lightweight index trỏ đến nơi kiến thức sống trong project. Khác với CLAUDE.md (giữ static rules), MEMORY.md theo dõi trạng thái đang thay đổi: quyết định gần đây, thay đổi architecture, work đang làm dở.

Mỗi entry dưới 150 ký tự:

- [Auth](src/lib/auth/) — Clerk, không phải NextAuth. Migrate tháng 3/2026.
- [DB](prisma/schema.prisma) — PostgreSQL trên Supabase. Query qua Prisma.
- [Deploy](docs/deploy.md) — Vercel preview cho PRs, production trên main.
- [Testing](vitest.config.ts) — Vitest unit, Playwright E2E. Min 80% coverage.
- [API](src/app/api/) — Server Actions ưu tiên hơn API routes cho mutations.

Quick Win 2: Thêm một PreToolUse guardrail hook (15 phút)

Hook này chặn Claude Code edit các file nhạy cảm. Copy-paste ready:

#!/bin/bash
# Chặn edit .env, credentials, và CI config

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

SENSITIVE=('.env' 'credentials' '.github/workflows' 'secrets')

for pattern in "${SENSITIVE[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "BLOCKED: Không thể edit file nhạy cảm: $FILE_PATH" >&2
    exit 2
  fi
done

exit 0

Register trong .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-sensitive-files.sh"
          }
        ]
      }
    ]
  }
}

Xem thêm guardrail patterns tại Claude Code Hooks guide và 17 Hook Events deep-dive.

Quick Win 3: Bật cost awareness (10 phút)

Track chi phí mỗi session để phát hiện anomalies sớm. Boris Cherny, người tạo ra Claude Code, gọi verification là “có lẽ thứ quan trọng nhất” cho chất lượng: “Cho Claude cách verify work của nó. Nếu Claude có feedback loop đó, nó sẽ tăng chất lượng kết quả cuối cùng lên 2-3 lần” (X thread, 2026).

Cost tracking là observability layer cho bạn biết khi nào session đang đốt tokens mà không tiến triển. Bắt đầu đơn giản: review ~/.claude/projects/ sau mỗi session để kiểm tra Claude đã làm gì và tốn bao nhiêu. Xem chi tiết tại Cách tôi giảm 60% hóa đơn Claude Code.

Key insight: Boris Cherny, người tạo ra Claude Code, gọi verification là “có lẽ thứ quan trọng nhất” cho chất lượng: “Cho Claude cách verify work của nó. Nếu Claude có feedback loop đó, nó sẽ tăng chất lượng kết quả cuối cùng lên 2-3 lần” (X thread, 2026).

Thử ngay: Chọn một quick win ở trên và implement trước session Claude Code tiếp theo. Quick Win 2 là copy-paste ready, mất 3 phút.

FAQ

Harness engineering là gì?

Harness engineering là ngành xây dựng constraints, tools, feedback loops, và observability xung quanh AI agents để chúng hoạt động ổn định trong production. Công thức: Agent = Model + Harness. Thuật ngữ xuất hiện đầu 2026, hệ thống hóa bởi Birgitta Böckeler trên site Martin Fowler, OpenAI, và LangChain.

Harness engineering khác prompt engineering thế nào?

Prompt engineering quyết định agent cố gắng làm gì. Context engineering quyết định agent biết gì. Harness engineering quyết định agent được phép và không được phép làm gì. Chúng không thay thế nhau mà là các layers chồng lên nhau. Production workflow dùng cả ba, nhưng harness engineering cho đảm bảo mạnh nhất vì dùng enforcement (hooks, permissions) thay vì gợi ý (prompts, context).

Có cần harness engineering cho Claude Code không?

Có. Claude Code bản thân nó là một harness mà Anthropic build quanh model của họ. Nhưng đó là inner harness. Bạn cần outer harness phù hợp với project: CLAUDE.md cho conventions, hooks cho guardrails, MCP servers cho tools, permissions cho safety boundaries, và observability cho cost control.

Harness engineering chỉ dùng cho Claude Code thôi à?

Không. Nguyên tắc áp dụng cho mọi AI coding agent: Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline. Claude Code có harness surface lập trình được nhiều nhất (17 hook events, MCP protocol, skills system), nên ví dụ ở đây dùng nó. Các khái niệm chuyển sang tools khác trực tiếp.

Đọc tiếp

• Chọn Hook Nào Cho Claude Code? Hướng Dẫn Quyết Định — 4 loại handler, decision tree, và 3 hooks nên implement trước (Layer 4 deep-dive)
• 5 Layers Của Claude Code Harness Production-Ready — Hướng dẫn implementation đầy đủ cho cả 5 layers với file templates
• Harness Paradox: Càng Constrain AI Nhiều, Output Càng Tốt — Tại sao giới hạn agent lại khiến nó đáng tin hơn