Xa Hơn CLAUDE.md: 5 Layer Harness Mà Agent AI Của Bạn Đang Thiếu

TL;DR — Claude Code harness có 5 layers: Memory, Tools, Permissions, Hooks, Observability. Hầu hết developer chỉ có Layer 1. Setup theo thứ tự 1, 4, 2, 3, 5: thêm guardrails trước khi thêm capabilities. Nhảy tới thứ tự setup →

📊 Bài viết này bao gồm:

• 5 layers riêng biệt với đường dẫn file Claude Code cụ thể
• Thứ tự setup phi tuyến tính (1→4→2→3→5) kèm lý do
• Checklist 10 mục đánh giá production-readiness
• Code template cho permissions và observability

Hai setup. Cùng một project. Kết quả khác nhau:

# Chỉ Layer 1 (đa số dev đang ở đây)
CLAUDE.md: "Không bao giờ xóa production database tables."
→ LLM cân nhắc dòng này trong 200K tokens context. Có thể bỏ qua.

# Đủ 5 layers (production-ready)
CLAUDE.md   → agent biết rule
Hook        → chặn "DROP TABLE" trước khi chạy (exit 2)
Permission  → từ chối write access vào /prod/
MCP         → không config database tool trong production
Logs        → alert khi phát hiện destructive pattern

Nếu bạn xóa CLAUDE.md ngay bây giờ, agent của bạn có còn hoạt động đúng không?

Với hầu hết developer, câu trả lời là không. Toàn bộ harness nằm trong một file markdown mà LLM coi như gợi ý, không phải luật. Đó chỉ là Layer 1 trong tổng số 5.

Tôi đã giới thiệu harness engineering trong bài pillar. Bài đó giải thích tại sao hệ thống xung quanh agent quan trọng hơn bản thân model. Bài này là bản đồ triển khai. Năm layers, mỗi cái có đường dẫn file thực tế, và thứ tự setup mà hầu hết mọi người làm ngược.

Tại sao cần 5 layers?

Vì mỗi layer giải quyết một loại lỗi khác nhau, và không layer nào bao phủ được cả năm. Memory giải quyết quên. Tools giải quyết thiếu khả năng. Permissions giải quyết vượt quyền. Hooks giải quyết enforcement. Observability giải quyết mù thông tin. Bỏ qua một layer là để ngỏ một lớp lỗi.

LangChain đã chứng minh: +13.7 điểm benchmark chỉ bằng thay đổi harness, cùng model (phân tích đầy đủ trong bài pillar). Ba cải tiến của họ map trực tiếp vào mô hình này: context injection (Layer 1), self-verification loops (Layer 4), và compute allocation (Layer 4/5).

Đây là bản đồ đầy đủ:

Hầu hết developer đang ở Layer 1. Một số có Layer 2. Production cần cả năm.

Thêm compute không bù được cho việc thiếu layers. Reasoning budget tối đa của LangChain thực tế còn tệ hơn setting tối ưu, vì timeout từ over-thinking giết performance (LangChain Blog, Feb 2026). Kiến trúc thắng compute.

Key insight: Ba cải tiến harness của LangChain map vào các layer cụ thể: context injection cải thiện Layer 1 (Memory), self-verification loops cải thiện Layer 4 (Hooks), compute allocation cải thiện Layer 5 (Observability). Không layer nào đơn lẻ giải thích toàn bộ +13.7 điểm. Cần cả ba (LangChain Blog, Feb 2026).

Layer 1: Agent của bạn luôn biết gì? (Memory)

Layer 1 là kiến thức bền vững: mọi thứ agent đọc trước khi viết dòng code đầu tiên. Trong Claude Code, ba file tạo nên memory layer: CLAUDE.md cho project rules, MEMORY.md cho cross-session learnings, và .claude/commands/ cho reusable workflows. Đây là nền tảng để các layer khác xây dựng lên.

CLAUDE.md là file quan trọng nhất. Nó chứa tech stack, naming conventions, testing requirements, và architectural constraints. Claude Code tự động đọc file này khi bắt đầu session. Đọc thêm chi tiết tại Tại Sao CLAUDE.md Là File Quan Trọng Nhất.

MEMORY.md theo dõi những gì agent học qua các sessions: quyết định gần đây, trạng thái migration, công việc đang làm. Nếu CLAUDE.md là hiến pháp thì MEMORY.md là nhật ký thay đổi.

.claude/commands/ lưu slash commands như /review hoặc /deploy cho các workflow lặp đi lặp lại. Mỗi file là một markdown chứa prompt template.

Một CLAUDE.md tối giản nhưng đủ dùng:

## Tech Stack
- TypeScript, Next.js 15, Prisma, PostgreSQL on Supabase

## Conventions
- Dùng server actions cho mutations, không dùng API routes
- Tests: Vitest unit, Playwright E2E. Tối thiểu 80% coverage
- Commits: conventional commits (feat:, fix:, chore:)

## Constraints
- Không sửa file .env trực tiếp
- Không chạy migrations nếu chưa được phê duyệt
- Tất cả API responses dùng Result<T> wrapper type

Bẫy: CLAUDE.md phình to

Nhiều instructions hơn không có nghĩa compliance tốt hơn. Nghiên cứu của ETH Zurich cho thấy context files do LLM tạo ra thực tế giảm task success ~3% và tăng inference costs hơn 20% (MarkTechPost, Feb 2026). HumanLayer giữ CLAUDE.md dưới 60 dòng vì lý do này.

Nguyên tắc thực tế: nếu một instruction chỉ áp dụng cho ít hơn nửa số sessions, nó không thuộc CLAUDE.md. Chuyển nó sang .claude/commands/ hoặc hook.

Key insight: Layer 1 đơn lẻ giới hạn cải thiện ở khoảng 4%, kể cả với instructions viết hoàn hảo (nghiên cứu ETH Zurich, Feb 2026). Đó là lý do mô hình 5 layers tồn tại. CLAUDE.md xử lý agent cần biết gì. Layers 2-5 xử lý agent làm được gì, được phép gì, không phá được gì, và bạn thấy được gì.

Layer 2: Agent của bạn làm được gì? (Tools)

Layer 2 mở rộng khả năng tương tác của agent ra ngoài filesystem. Claude Code có sẵn các built-in tools (Read, Write, Edit, Bash, Grep, Glob). MCP servers thêm capabilities bên ngoài: GitHub quản lý PR, Brave Search tra cứu docs, Playwright tự động hóa browser, databases, và nhiều hơn nữa.

Khái niệm đơn giản: không có Layer 2, agent chỉ sống trong project directory. Với Layer 2, agent có thể check GitHub PR, query staging database, và tìm trên Stack Overflow, tất cả mà bạn không cần copy-paste giữa các tab trình duyệt.

Tôi đã viết chi tiết về 5 MCP servers hàng đầu cho dev hàng ngày trong hướng dẫn setup MCP. Thay vì lặp lại danh sách đó, câu hỏi quan trọng của Layer 2 là: nên thêm bao nhiêu tools?

Bẫy: quá tải tools

Mỗi MCP server bạn thêm vào là thêm một quyết định mà agent phải cân nhắc ở mỗi lượt. HumanLayer đã học bài học này. Họ dùng Linear MCP server suốt mấy tháng rồi nhận ra chỉ dùng một phần nhỏ tools. Họ thay bằng một CLI wrapper nhẹ hơn, cho responses gọn hơn. Ít tools, tập trung hơn.

Nguyên tắc: chỉ thêm tools mà agent dùng trong hầu hết sessions. Tool nào tháng mới dùng một lần thì tự dùng tay.

Key insight: HumanLayer phát hiện quá nhiều MCP tools gây agent confusion. Họ thay Linear MCP server đầy đủ bằng CLI wrapper nhỏ. Mỗi tool bạn thêm vào là một quyết định mà agent phải cân nhắc ở mỗi lượt (HumanLayer Blog, 2026).

Layer 3: Agent của bạn được phép làm gì? (Permissions)

Layer 3 kiểm soát tools, commands, và file paths nào Claude Code được dùng mà không cần hỏi bạn. Nó nằm trong settings.json, có hai cấp: project (.claude/settings.json, commit vào git) và user (~/.claude/settings.json, cá nhân). Project settings áp dụng cho cả team. Xem tổng quan hệ thống components tại Claude Code Components Explained.

Pattern quan trọng: allowlist hơn denylist. Bắt đầu restrictive, rồi mở dần. Một denylist cố chặn mọi command nguy hiểm sẽ luôn thiếu edge cases. Một allowlist chỉ cho phép operations biết trước là an toàn thì mặc định kín.

Template production-ready:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Grep",
      "Glob",
      "Bash(npm run test*)",
      "Bash(npm run lint*)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "mcp__github__get_pull_request",
      "mcp__github__list_pull_requests"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git push -f*)",
      "Bash(*DROP TABLE*)",
      "Bash(*DROP DATABASE*)"
    ]
  }
}

MCP tool permissions theo pattern mcp__servername__toolname. Dùng mcp__github__* để allow tất cả tools từ một server, hoặc liệt kê cụ thể từng tool.

Hai điều cần nhớ:

1. Commit project settings vào git. Cả team được cùng guardrails khi clone. Không có “máy tôi chạy được” cho permissions.
2. Permissions chặn nhưng cho phép override. Action bị denied sẽ prompt user cho phép. Nếu muốn chặn tuyệt đối, bạn cần Layer 4 (Hooks), chặn execution hoàn toàn.

Key insight: Claude Code permissions chặn actions nhưng cho phép user override. Action bị denied sẽ prompt xác nhận. Để enforcement tuyệt đối không thể bypass, cần Layer 4 (Hooks) với exit code 2, chặn execution trước khi permission check chạy (Claude Code docs).

Layer 4: Agent của bạn không thể phá vỡ gì? (Hooks)

Layer 4 là deterministic enforcement. Khác với CLAUDE.md (gợi ý mà model cân nhắc trong context), khác với permissions (cổng mà user có thể override), hooks chạy shell scripts ở các lifecycle points không thể bypass. PreToolUse hook trả exit code 2 sẽ chặn action trước khi nó xảy ra. Không override. Không “bạn có chắc?” prompt.

Claude Code hooks có hai events quan trọng nhất: PreToolUse (chạy trước tool, có thể chặn) và PostToolUse (chạy sau tool, có thể log, lint, hoặc inject feedback). Xem framework quyết định đầy đủ cho tất cả 21 events và 4 handler types trong Hook Decision Guide.

Hooks chia thành ba loại:

Guardrails chặn actions nguy hiểm. Force pushes, rm -rf trên project root, DROP TABLE trong production. Đây là PreToolUse command hooks chạy dưới 5ms.

Quality gates enforce standards sau changes. Auto-lint khi save file, type check sau edits, validate test coverage. Đây là PostToolUse hooks.

Context injection thêm thông tin project-specific vào tool calls. Inject environment variables, append docs liên quan, hoặc tag actions với metadata. Đây là PreToolUse hooks sửa input thay vì chặn.

Guardrail đơn giản từ phần mở đầu:

#!/bin/bash
# PreToolUse hook: chặn destructive SQL
COMMAND=$(jq -r '.tool_input.command // empty' < /dev/stdin)
if echo "$COMMAND" | grep -qiE 'DROP\s+(TABLE|DATABASE)'; then
  echo "BLOCKED: destructive SQL command" >&2
  exit 2
fi
exit 0

Boris Cherny, người tạo Claude Code, coi verification là yếu tố quan trọng nhất cho chất lượng agent. Hooks chính là verification layer đó, tích hợp trực tiếp vào lifecycle của agent. Mỗi PreToolUse check và PostToolUse log chạy tự động, không phụ thuộc vào quyết định của model (ngữ cảnh đầy đủ trong bài pillar).

Bẫy: hooks chậm

Mỗi hook chạy synchronously trong agent loop. Hook gọi external API sẽ block toàn bộ session cho đến khi trả về. Giữ command hooks dưới 100ms. Nếu cần external validation, dùng http handler type, chạy asynchronously.

Xem thêm hook patterns tại Claude Code Hooks guide và bài supply chain security hooks.

Key insight: Hooks là verification layer mà Boris Cherny coi là yếu tố quan trọng nhất cho chất lượng Claude Code. PreToolUse checks ngăn actions sai trước khi chạy. PostToolUse hooks verify kết quả sau. Cả hai chạy deterministically ngoài chuỗi reasoning của model (bài pillar).

Muốn folder .claude/ hoàn chỉnh, pre-configured với đủ 5 layers? Đăng ký waitlist. Bạn sẽ là người đầu tiên nhận template repo khi nó sẵn sàng. Đăng ký .claude/ Template Waitlist →

Layer 5: Bạn có biết agent đang làm gì? (Observability)

Layer 5 trả lời ba câu hỏi: agent đã làm gì, tốn bao nhiêu, và có gì bất thường? Không có observability, bạn bay mù. Phát hiện vấn đề khi hóa đơn đến hoặc production lỗi. Cả hai đều không phải feedback loop tốt.

Agent observability có ba trụ cột:

Decision logging. PostToolUse hook ghi JSON cho mỗi tool call: tool nào, input gì, output gì, timestamp, session ID. Đây là audit trail.

#!/bin/bash
# PostToolUse hook: log mỗi tool call dạng JSON
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
SESSION=${CLAUDE_SESSION_ID:-"unknown"}

echo "$INPUT" | jq -c \
  --arg ts "$TIMESTAMP" \
  --arg sid "$SESSION" \
  '{timestamp: $ts, session: $sid, tool: .tool_name,
    input: .tool_input, duration_ms: .duration_ms}' \
  >> .claude/logs/tool-calls.jsonl

exit 0

Cost tracking. Monitor chi phí theo session và task. Task bình thường tốn $2-3 mà bỗng tốn $47 là tín hiệu bất thường. Thường là infinite loop, context explosion, hoặc agent đi sai hướng. Xem chi tiết tại Cách Tôi Giảm 60% Hóa Đơn Claude Code.

Anomaly detection. Cost spikes, sessions dài bất thường, tool failures lặp lại. Bắt đầu đơn giản: review .claude/logs/ sau mỗi session. Nâng cấp lên automated alerts khi patterns rõ ràng.

Bài học của HumanLayer áp dụng ở đây: khi chạy full test suite sau mỗi change, 4,000 dòng passing tests tràn ngập context window và agent mất dấu task thực sự. Giờ họ nuốt output thành công, chỉ hiện failures. Nguyên tắc tương tự cho observability: log mọi thứ, nhưng chỉ alert anomalies.

Đây là layer mới nhất và ít mature nhất. Hầu hết teams bắt đầu với cost logging rồi thêm decision recording sau. Như vậy là ổn. Có observability nào cũng tốt hơn không có.

Key insight: HumanLayer phát hiện chạy full test suite sau mỗi change làm tràn context với 4,000 dòng passing tests, agent mất dấu task. Họ chuyển sang chỉ hiện failures. Nguyên tắc tương tự cho observability: log mọi thứ, alert chỉ anomalies (HumanLayer Blog, 2026).

Làm sao setup Claude Code harness hoàn chỉnh?

Đây là file tree đầy đủ cho production-ready Claude Code harness bao phủ cả 5 layers. Mỗi file map tới một layer cụ thể:

project-root/
├── CLAUDE.md                      # Layer 1: Memory (project rules)
├── MEMORY.md                      # Layer 1: Memory (cross-session state)
├── .claude/
│   ├── settings.json              # Layer 3: Permissions + Layer 4: Hooks
│   ├── settings.local.json        # Layer 3: Personal overrides (gitignored)
│   ├── commands/                  # Layer 1: Memory (reusable workflows)
│   │   ├── review.md
│   │   └── deploy.md
│   └── logs/                      # Layer 5: Observability output
│       └── tool-calls.jsonl
│
# Layer 2: MCP servers → config trong settings.json block "mcpServers"
# Layer 4: Hooks → config trong settings.json block "hooks"
# Layer 5: Logging hook → ghi vào .claude/logs/

Thứ tự setup khuyến nghị

Đừng setup 1, 2, 3, 4, 5. Setup 1, 4, 2, 3, 5.

Logic: thêm guardrails trước capabilities. Hầu hết mọi người làm ngược. Họ cài 5 MCP servers, cho agent access production database, rồi thắc mắc tại sao nó chạy destructive query. Layer 4 (Hooks) phải có trước Layer 2 (Tools) cho agent thêm tầm với.

Harness của bạn đã production-ready chưa?

Tự chấm điểm:

• CLAUDE.md dưới 60 dòng với project-specific rules
• MEMORY.md theo dõi cross-session learnings
• Ít nhất 2 custom commands trong .claude/commands/
• PreToolUse hook chặn destructive commands
• PostToolUse hook cho quality gates (lint, test)
• MCP servers cho top 3 tools hàng ngày
• settings.json có explicit allowlist (không chỉ defaults)
• Project-level settings.json đã commit vào git
• PostToolUse logging hook ghi JSON
• Cost alerting khi sessions vượt ngưỡng

8-10: production-ready. Bạn đang làm harness engineering. 4-7: nền tảng tốt. Ưu tiên hooks (Layer 4) tiếp theo. 1-3: bạn thuộc đa số. Bắt đầu theo thứ tự setup ở trên.

Xem framework khái niệm tại Harness Engineering: Hệ Thống Quanh AI Quan Trọng Hơn AI.

Thử ngay: Chọn mục chưa check thấp nhất trong checklist. Implement trước session Claude Code tiếp theo. Nếu chưa có gì, bắt đầu với CLAUDE.md (10 phút). Nếu đã có CLAUDE.md, thêm PreToolUse guardrail hook (15 phút, copy-paste từ Layer 4 ở trên).

Đang xây harness từng layer? Nhận tips Claude Code hàng tuần với config thực tế, không lý thuyết suông. Đăng ký AI Developer Weekly →

FAQ

Nên bắt đầu từ layer nào trong Claude Code harness?

Bắt đầu Layer 1 (Memory/CLAUDE.md), rồi nhảy sang Layer 4 (Hooks) để có safety guardrails trước khi mở rộng capabilities. Thứ tự khuyến nghị: 1→4→2→3→5. Thêm guardrails trước capabilities. Nghe ngược đời nhưng ngăn được lỗi phổ biến nhất: cho agent tools mạnh trước khi có enforcement.

Harness có làm chậm Claude Code không?

Không. Command hooks thêm dưới 5ms mỗi tool call. Permissions được evaluate trong memory, không có network call. Chỉ MCP servers cần lưu ý vì mỗi server thêm một connection. Chỉ cài những gì dùng hàng ngày và overhead không đáng kể. LangChain phát hiện thêm compute (xhigh reasoning) thực tế còn tệ hơn harness optimization (LangChain Blog, Feb 2026).

Hooks nào quan trọng nhất nên implement trước?

Ba hooks bao phủ 80% nhu cầu safety: (1) PreToolUse command hook chặn destructive bash commands như rm -rf, git push --force, DROP TABLE; (2) PostToolUse hook auto-lint files đã sửa; (3) PostToolUse hook log mỗi tool call dạng JSON. Xem framework quyết định đầy đủ cho tất cả 21 events và 4 handler types tại Hook Decision Guide.

Nên cài bao nhiêu MCP servers cho Claude Code?

Bắt đầu với 2-3 phù hợp workflow hàng ngày. HumanLayer phát hiện quá nhiều tools gây agent confusion. Agent tốn tokens quyết định dùng tool nào thay vì làm việc. GitHub, search tool, và một domain-specific server đủ cho hầu hết teams. Setup chi tiết tại MCP setup guide.

Đọc Tiếp

• Harness Engineering: Hệ Thống Quanh AI Quan Trọng Hơn AI. Bài pillar định nghĩa harness engineering, với LangChain benchmark data và self-assessment checklist.
• Which Claude Code Hook Do You Need? A Decision Guide. Deep-dive Layer 4: 4 handler types, 21 events, decision tree, và 3 hooks nên implement trước.
• Tại Sao CLAUDE.md Là File Quan Trọng Nhất. Deep-dive Layer 1: cách viết instructions mà Claude thực sự follow, kèm 5-section template.