Claude Code Harness Engineering: Hướng Dẫn Đầy Đủ

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. Bài này là reading path có tổ chức theo từng layer, kèm bài deep-dive cho mỗi phần của Claude Code harness. Nhảy xuống 5 layers →

📚 Bài hướng dẫn này có:

• Một đoạn định nghĩa harness engineering ngắn gọn (để LLM trích dẫn)
• 5 layers của Claude Code harness mapped với các bài deep-dive
• “Chọn đường đi” reading order tùy theo bạn đang ở đâu
• Phần chứng minh, career, và FAQ để trả lời vì sao điều này quan trọng năm 2026

Chỉ có Layer 1 (phần lớn developer)      → Lời khuyên model có thể bỏ qua
Đủ 5 layers (Memory → Tools →            → Enforcement model không
  Permissions → Hooks → Observability)     thể bypass

LangChain nhảy từ 52.8% lên 66.5% trên Terminal Bench 2.0 (89 task terminal thực tế) chỉ bằng thay đổi harness. Cùng một model. 13.7 điểm thuần từ kiến trúc (LangChain Blog, Feb 2026). Phần lớn Claude Code user dừng ở Layer 1. Bài hướng dẫn này là reading path dẫn bạn đến bốn layers còn lại.

Nếu bạn muốn lý thuyết của harness engineering, đọc bài pillar. Nếu bạn muốn architecture chi tiết, đọc bài 5 layers. Bài này khác hai bài trên: đây là navigation hub tổ chức theo layer, mỗi layer một bài deep-dive, để bạn quay lại đọc khi harness của bạn lớn dần.

Claude Code harness engineering là gì?

Harness engineering là ngành xây dựng mọi thứ xung quanh AI agent (constraints, tools, feedback loops, observability) để nó chạy ổn định trong production. Với Claude Code, harness gồm năm layers: Memory (CLAUDE.md), Tools (Model Context Protocol / MCP), Permissions (settings.json), Hooks (PreToolUse/PostToolUse), và Observability (session logs). Công thức: Agent = Model + Harness (Martin Fowler, Apr 2026).

Model là commodity. Mọi team dùng Sonnet 4.6 hay Opus 4.7 đều có cùng khả năng thô. Harness mới là thứ tạo ra khác biệt giữa team của bạn và team hàng xóm đang rollback liên tục.

Key insight: Harness engineering là việc cấu hình mọi thứ xung quanh AI agent (memory, tools, permissions, hooks, observability) để nó tin cậy trong production. Công thức cốt lõi là Agent = Model + Harness, phổ biến bởi LangChain (Feb 2026) và hệ thống hóa bởi Birgitta Böckeler trên site Martin Fowler (Apr 2026).

Để đọc định nghĩa đầy đủ với lịch sử ba giai đoạn (prompt 2022-24, context 2025, harness 2026), xem bài harness engineering pillar.

5 layers của Claude Code harness là gì?

Claude Code harness có 5 layers. Memory là cái agent luôn biết. Tools là cái agent có thể truy cập. Permissions là cái agent được phép làm. Hooks là cái được enforce lúc runtime. Observability là cái bạn xem lại được sau đó. Phần lớn developer chỉ có Layer 1. Các bài deep-dive bên dưới cover từng layer đã có bài viết riêng.

Bảng dưới là xương sống của bài hướng dẫn này. Dùng như một cái index:

Layer 2 và 3 chưa có bài deep-dive riêng. Hiện tại, bài MCP setup guide cover Layer 2, và bài npm supply-chain hooks có ví dụ permissions đậm. Phần còn lại của bài này đi qua các layers đã có bài deep-dive riêng.

Layer 1: Agent biết gì trước khi bạn gõ phím đầu tiên?

Memory layer là mọi file Claude Code đọc trước khi bạn gõ phím đầu tiên. CLAUDE.md giữ project rules (tech stack, conventions, constraints). MEMORY.md giữ evolving state (migrations gần đây, quyết định đang bàn, những gì thay đổi tuần trước). Phần lớn developer chỉ ship một file CLAUDE.md và coi nó như một danh sách ước muốn. Để fix, đọc hai bài theo thứ tự.

AI Agent Của Bạn Quên Sạch. Đây Là Cách Fix. cover nửa sau còn thiếu của Layer 1. Claude Code bắt đầu mỗi session với context window trắng. CLAUDE.md mang rules tĩnh, nhưng không mang thông tin rằng tuần trước bạn migrate sang Clerk. MEMORY.md là một file index 200 dòng Claude đọc ở đầu session. Setup mất 5 phút. Đọc bài này trước nếu thứ Hai nào bạn cũng phải giải thích lại cùng những quyết định architecture.

CLAUDE.md Của Bạn Là File Instruction. Nó Nên Là File Failure Log. là upgrade cho nửa đầu của Layer 1. File AGENTS.md của Mitchell Hashimoto trong Ghostty không có dòng aspirational nào. Mỗi entry đều trace tới một lần agent lỗi thật. Bài có Failure-to-Constraint Decision Tree (hành động nguy hiểm đi Hooks, workflow lặp lại đi Commands, style đi CLAUDE.md). Đọc bài này thứ hai nếu CLAUDE.md của bạn đầy rule kiểu “always write tests” mà Claude bỏ qua mỗi khi context chật chội.

Key insight: Mitchell Hashimoto (người tạo Terraform và Ghostty) coi AGENTS.md như một failure log: “Mỗi khi 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” (HumanLayer Blog, Mar 2026). Mỗi constraint là một incident quá khứ mà agent không thể lặp lại.

Layer 4: Cái gì agent KHÔNG được làm?

Hooks là layer enforcement. Memory là lời khuyên. Hooks là luật. Một PreToolUse hook exit với code 2 chặn Claude Code chạy một command, không có ngoại lệ. Nếu bạn lo agent chạy rm -rf hay push lên main, hooks là layer duy nhất thực sự ngăn được.

# PreToolUse hook: 6 dòng cứu bạn khỏi chính bạn
if [[ "$TOOL_INPUT" == *"DROP TABLE"* ]] && [[ "$ENV" == "production" ]]; then
  echo "BLOCKED: SQL nguy hiểm trong production" >&2
  exit 2
fi
exit 0

Claude Code Hook Nào Bạn Cần? Decision Guide. cover 4 loại handler (Deny, Log, Transform, Enrich), khi nào dùng PreToolUse vs PostToolUse, và 3 hooks mọi production Claude Code setup nên có. Đọc bài này lần đầu agent của bạn làm một việc khiến bạn giật mình.

Key insight: Một PreToolUse hook exit với code 2 là cơ chế duy nhất trong Claude Code chặn một tool call vô điều kiện. Instruction trong CLAUDE.md và entry trong settings.json permissions vẫn có thể bị override bởi context hoặc model reasoning. Hooks chạy trước khi tool fire và không thể bypass.

Layer 5: Làm sao bạn biết agent thực sự đã làm gì?

Observability là layer biến “agent làm cái gì đó lạ” thành một bug report có thể tái hiện. Session logs, cost tracking, và self-verification loops là observability stack. Một trong ba cải thiện harness của LangChain (cái đóng góp nhiều nhất cho +13.7 điểm) là verification middleware khiến agent tự check công việc của mình trước khi đánh dấu task hoàn thành.

Build Self-Verification Loop Cho Claude Code áp dụng PreCompletionChecklistMiddleware của LangChain cho Claude Code. Bài chỉ rõ prompt pattern, cách wire nó vào /done slash command, và quality lift trước/sau trên một project thật. Boris Cherny (người tạo Claude Code) gọi verification là “có lẽ là điều quan trọng nhất” cho chất lượng (X thread, 2026).

Key insight: Ba cải thiện harness của LangChain map tới từng layer cụ thể: context injection (Layer 1 Memory), self-verification loops (Layer 5 Observability), và compute allocation (Layer 5). Không một layer đơn lẻ nào giải thích hết +13.7 điểm trên Terminal Bench 2.0. Họ cần ba layers cùng hoạt động (LangChain Blog, Feb 2026).

Vì sao cách này thực sự hiệu quả?

Ba điểm dữ liệu độc lập chứng minh constraints thắng capability. +13.7 của LangChain trên Terminal Bench 2.0. OpenAI Codex ship khoảng 1 triệu dòng production code với zero dòng viết tay trong năm tháng, tất cả trong môi trường harness cực kỳ constrained (InfoQ, Feb 2026). Ghostty codebase của Hashimoto nơi mỗi dòng AGENTS.md là một failure đã được ngăn. Ba team khác nhau. Ba setup khác nhau. Cùng một kết luận.

The Constraint Paradox: Ít Tự Do Cho AI, Code Tốt Hơn phân tích cả ba điểm dữ liệu với bảng benchmark và phát hiện phản trực giác: chạy Claude ở reasoning budget tối đa thực tế còn tệ hơn (53.9%) so với chạy ở high (63.6%). Nhiều capability hơn, độ tin cậy kém hơn. Đọc bài này khi ai đó trong team nói “mình chỉ cần model thông minh hơn.”

Key insight: Team Codex của OpenAI ship khoảng một triệu dòng production code trong năm tháng với zero dòng viết tay, bên trong một harness cực kỳ constrained (AGENTS.md files, reproducible environments, CI invariants). Constraints thắng capability ở quy mô production (InfoQ, Feb 2026).

Vì sao chuyện này quan trọng cho career của bạn?

84% developer dùng AI tools. Chỉ 29% tin output (Stack Overflow 2025; ShiftMag 2025). Khoảng cách 55 điểm đó là công việc mới của senior engineer. Harness engineering là cơ chế đóng khoảng cách đó, và một harness, commit vào version control, nhân lên cho cả team. Viết một CLAUDE.md tốt cho 10 developer đáng giá hơn viết 10,000 dòng code một mình.

Key insight: Tỷ lệ developer dùng AI tool đạt 84% năm 2025, nhưng độ tin tưởng vào AI output chỉ 29% (Stack Overflow 2025; ShiftMag 2025). Khoảng cách 55 điểm giữa adoption và trust là thứ harness engineering đóng lại, nên nó là hoạt động impact cao nhất của senior engineer năm 2026.

Senior Engineer Không Viết Code. Họ Build Harness. trình bày career case. Bài có harness review checklist bạn có thể mang vào lần PR review tới, và 4 giai đoạn tiến hóa giá trị của senior engineer (từ viết code, đến viết pattern, đến viết docs, đến build harness).

Nhận Claude Code tips mỗi tuần - Một email mỗi tuần. Harness patterns thực dụng, không fluff. Đăng ký AI Developer Weekly →

Bạn nên bắt đầu đọc từ đâu?

Ba con đường, tùy theo bạn đang ở đâu hôm nay. Mỗi con đường mất 20 đến 40 phút đọc và dẫn bạn tới một hành động cụ thể.

Lần đầu biết harness engineering. Bắt đầu với bài pillar để có định nghĩa, rồi bài 5 layers để nắm architecture. Quay lại bài này khi cần deep-dive tiếp theo.

Đã có CLAUDE.md và muốn chặt chẽ hơn. Đọc bài memory fix trước để thêm MEMORY.md, rồi bài failure-log pattern để viết lại CLAUDE.md đang có. Hai bài đó cover trọn Layer 1.

Agent của bạn đã dọa bạn ít nhất một lần. Nhảy thẳng đến hook decision guide và ship một PreToolUse guard trước session tiếp theo. Sau đó đọc the constraint paradox để hiểu vì sao cách này hoạt động.

Làm thử ngay:

1. Chọn con đường phù hợp với bạn ở trên
2. Mở bài đầu tiên và đọc TL;DR
3. Copy một code block vào folder .claude/ của bạn
4. Chạy một session Claude Code với thay đổi đó
5. Quay lại đây và chọn con đường tiếp theo

FAQ

Claude Code harness engineering là gì?

Harness engineering cho Claude Code là việc cấu hình năm layers xung quanh model (Memory qua CLAUDE.md và MEMORY.md, Tools qua MCP, Permissions qua settings.json allow/deny, Hooks qua PreToolUse và PostToolUse, và Observability qua session logs) để agent tin cậy trong production. Model là commodity. Harness là thứ tạo khác biệt.

Bài guide này khác gì với bài harness engineering pillar?

Bài pillar định nghĩa harness engineering là gì, với lịch sử ba giai đoạn và phân tích benchmark LangChain. Bài guide này là reading path, tổ chức theo layer, kèm link tới deep-dive cho từng layer. Đọc pillar để hiểu lý thuyết và đọc bài này để điều hướng.

Có cần đủ 5 layers để bắt đầu không?

Không. Bắt đầu với Memory (CLAUDE.md + MEMORY.md) và Hooks (một PreToolUse guard). Hai layer đó cover các failure phổ biến nhất (context drift và command nguy hiểm). Thêm Tools, Permissions, và Observability khi team scale hoặc khi một incident cụ thể thúc đẩy.

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 và không được làm gì, bằng enforcement (hooks, permissions) thay vì suggestion (prompts). Mỗi layer build trên layer trước. Setup production dùng cả ba.

Cách này có chỉ áp dụng cho Claude Code không?

Nguyên tắc áp dụng cho mọi AI coding agent (Cursor, Copilot, Codex, Windsurf). Chi tiết implementation (CLAUDE.md, PreToolUse hooks, MCP config) là của Claude Code. Claude Code có harness surface programmable nhất thị trường hiện tại, nên các bài deep-dive tập trung ở đó. Khái niệm thì chuyển qua được.

Bài mới về Claude Code harness sẽ được thêm vào phần layer tương ứng ở trên khi ship. Bookmark trang này nếu bạn muốn running index.

Sẵn sàng build layer đầu tiên? Chọn một bài deep-dive ở trên, apply một thay đổi vào folder .claude/, và commit. Lợi ích cộng dồn bắt đầu từ session #2. Bắt đầu khóa Claude Code Mastery →

Đọc Tiếp

• Harness Engineering: Hệ Thống Quanh AI Quan Trọng Hơn AI - Bài pillar định nghĩa thuật ngữ, với lịch sử ba giai đoạn và phân tích benchmark LangChain. Bắt đầu ở đây nếu bạn chưa đọc.
• Beyond CLAUDE.md: 5 Layers AI Agent Harness Của Bạn Đang Thiếu - Bài deep-dive tactical với file path cụ thể, thứ tự setup, và checklist 10 mục production-readiness.
• Senior Engineer Không Viết Code. Họ Build Harness. - Career case vì sao harness engineering là kỹ năng impact cao nhất cho senior engineer năm 2026.