CLAUDE.md Của Bạn Là File Hướng Dẫn. Nó Nên Là Nhật Ký Lỗi.

TL;DR - CLAUDE.md chỉ được tuân thủ khoảng 60-70%. AGENTS.md của Mitchell Hashimoto trong Ghostty không có dòng nào viết theo kiểu “nên làm gì”, mỗi dòng đều gắn với một lỗi thực tế. Dùng Decision Tree: hành động nguy hiểm → Hook, workflow lặp lại → Command, convention → CLAUDE.md. Nhảy đến decision tree →

📊 Bài viết này giúp bạn:

Một workflow failure-first để viết CLAUDE.md từ đầu

Decision tree phân loại lỗi vào đúng layer (CLAUDE.md vs Hook vs Command)

Ví dụ Before/After biến đổi CLAUDE.md áp dụng ngay tối nay

Checklist pruning giữ file dưới 60 dòng

Hai file CLAUDE.md. Cùng project. Hai triết lý khác nhau:

# ❌ Trước: CLAUDE.md viết theo kiểu hướng dẫn (phổ biến)
# 47 dòng quy tắc chung chung
- "Cẩn thận với production database."
- "Luôn viết test."
- "Dùng TypeScript strict mode."
- "Tuân thủ naming conventions."
# Claude đọc hết, cân nhắc giữa 200K tokens... tuân thủ ~65%.

# ✅ Sau: CLAUDE.md viết từ lỗi thực tế (phương pháp Hashimoto)
# 12 dòng, mỗi dòng gắn với một sự cố cụ thể
- "KHÔNG BAO GIỜ dùng git push --force. Dùng --force-with-lease."
  # Lỗi: 2026-03-12, force push ghi đè commits của teammate trên feature/auth
- "Chạy npm test trước MỌI git commit. Không ngoại lệ."
  # Lỗi: 2026-02-28, import lỗi push lên main, CI phát hiện sau 20 phút

File đầu có 47 dòng lời khuyên. File sau có 12 dòng “vết sẹo”. File nào agent thực sự nghe theo?

Không cần bàn cãi. File 12 dòng thắng tuyệt đối. Vì mỗi dòng đều có trọng lượng. Mỗi dòng tồn tại vì một lý do cụ thể mà model có thể đánh giá. File 47 dòng là danh sách mong muốn. File 12 dòng là một harness thực thụ.

Tại sao hầu hết CLAUDE.md đều thất bại?

Hầu hết CLAUDE.md thất bại vì developer viết nó giống bản mô tả công việc: tham vọng, toàn diện, và phình to. LLM không thực thi instruction như code thực thi function. Nó cân nhắc mỗi instruction trong toàn bộ context window. Càng nhiều dòng, mỗi dòng càng bị loãng.

Giả định sai lầm phổ biến: “Viết instruction rõ ràng thì Claude sẽ nghe theo.” Không phải vậy. Mỗi instruction cạnh tranh sự chú ý với mọi token khác trong context window. Thêm instruction, mỗi cái đều giảm giá trị.

Dữ liệu chứng minh điều này. Một nghiên cứu từ ETH Zurich (Gloaguen et al., 2026) test context files trên 138 GitHub issues thực tế: agentfiles do LLM tạo ra giảm tỷ lệ thành công 0.5-2%, đồng thời tăng chi phí inference 20-23%. Ngay cả file do developer viết cũng chỉ cải thiện ~4% trung bình. File trung bình có 641 từ, chia thành 9.7 sections.

Rất nhiều instruction cho 4% cải thiện.

Chỉ số	CLAUDE.md 200 dòng	CLAUDE.md 40 dòng
Số instruction	~200	~40
Tỷ lệ tuân thủ	~60-70%	~85-90%
Bảo trì	Cần review hàng tháng	Tự duy trì

Frontier LLM có thể tuân thủ khoảng 150-200 instruction một cách nhất quán (HumanLayer Blog, 2026). File CLAUDE.md 200 dòng đã vượt ngân sách này trước khi tính system prompt (khoảng 50 instruction nữa). Benchmark từ cộng đồng: tỷ lệ tuân thủ 60-70% cho file trên 200 dòng.

Hãy tưởng tượng như tab trình duyệt. Mở 200 tab thì không tìm được gì. Mở 12 tab, mỗi tab cho một task cụ thể, bạn biết chính xác mọi thứ ở đâu.

Key insight: Nghiên cứu ETH Zurich cho thấy agentfiles do LLM tạo ra giảm tỷ lệ thành công 0.5-2%, tăng chi phí inference 20-23%. Ngay cả file do developer viết cũng chỉ cải thiện ~4%. File trung bình có 641 từ trong 9.7 sections, phần lớn là noise (Gloaguen et al., 2026).

Phương pháp Mitchell Hashimoto cho AGENTS.md là gì?

Mitchell Hashimoto (người tạo ra Terraform, Vagrant, và Ghostty) coi AGENTS.md là nhật ký lỗi, không phải file hướng dẫn. Mỗi dòng trong AGENTS.md của Ghostty tồn tại vì agent đã mắc lỗi đó ít nhất một lần. Không dòng nào mang tính “nên làm”. Mỗi dòng là một vết sẹo từ sự cố thực tế.

Hashimoto viết: “Each line in that file is based on a bad agent behavior, and it almost completely resolved them all” (mitchellh.com, 2026).

Triết lý của ông rất đơn giản: mỗi khi agent mắc lỗi, hãy dành thời gian xây dựng giải pháp để agent không bao giờ lặp lại lỗi đó (HumanLayer Blog, 2026). Đây là harness engineering áp dụng cho Layer 1.

Sự thay đổi tư duy quan trọng:

Viết theo instruction	Viết theo failure
”Agent nên làm gì?"	"Agent đã phá gì?”
Chủ động, mang tính mong muốn	Phản ứng, dựa trên bằng chứng
Nhiều dòng, ít tín hiệu	Ít dòng, tín hiệu mạnh
Thêm trước khi có vấn đề	Thêm sau khi có vấn đề
Loãng dần theo thời gian	Mạnh hơn theo thời gian

Instruction là mong muốn. Constraint là bài học. LLM không cần thêm mong muốn. Chúng cần ít constraint hơn, sắc bén hơn, với context cụ thể về lý do mỗi constraint tồn tại.

Key insight: AGENTS.md của Mitchell Hashimoto trong Ghostty theo pattern failure-first: mỗi dòng gắn với một lỗi cụ thể trong quá khứ. “Each line in that file is based on a bad agent behavior, and it almost completely resolved them all” (mitchellh.com, 2026). Biến CLAUDE.md từ danh sách mong muốn thành hệ thống phòng ngừa lỗi.

Làm sao xây dựng CLAUDE.md từ lỗi thực tế thay vì tưởng tượng?

Bắt đầu với CLAUDE.md tối thiểu chỉ có project overview và tech stack. Chạy agent trên task thực. Khi nó gây lỗi, chuyển lỗi đó thành constraint. Sau đó dùng decision tree để route constraint vào đúng layer.

Bước 1: Bắt đầu tối giản

CLAUDE.md ban đầu chỉ cần 5-10 dòng:

# Project: Acme SaaS
TypeScript, Next.js 15, Drizzle ORM, deploy trên Vercel.

## Build
npm run build && npm test

Xong. Không rules. Không conventions. Không guidelines. Chỉ đủ context để agent hiểu nó đang làm việc với cái gì.

Bước 2: Chạy agent, quan sát lỗi

Dùng agent cho công việc thực tế. Đừng thêm rules trước. Khi agent mắc lỗi, ghi chép chính xác:

Gì: force-push lên main
Khi nào: 2026-03-12
Ảnh hưởng: ghi đè commits của teammate trên feature/auth

Bước 3: Chuyển lỗi thành constraint

Biến sự cố thành rule cụ thể, có thể kiểm chứng:

KHÔNG BAO GIỜ dùng `git push --force`. Dùng `--force-with-lease`.
# 2026-03-12: force push ghi đè commits của teammate trên feature/auth

Pattern luôn là: CONSTRAINT + LÝ DO + NGÀY XẢY RA LỖI.

Bước 4: Route bằng decision tree

Không phải constraint nào cũng thuộc về CLAUDE.md. Decision tree này là takeaway quan trọng nhất:

Agent mắc lỗi
    │
    ├── Hành động có nguy hiểm hoặc không thể hoàn tác?
    │   CÓ → Hook (PreToolUse block)
    │   Ví dụ: xóa file production, force push, sửa .env
    │   → Xem: "Which Claude Code Hook Do You Need?"
    │
    ├── Là workflow lặp đi lặp lại mà agent nên tự động hóa?
    │   CÓ → Command hoặc Skill (.claude/commands/)
    │   Ví dụ: chạy test sau refactor, update changelog
    │
    └── Là vấn đề style, convention, hoặc context?
        CÓ → CLAUDE.md constraint
        Ví dụ: naming conventions, test patterns, commit format

Nếu bạn chỉ nhớ một thứ từ bài viết này, hãy nhớ decision tree. Nó thay thế bản năng “có lỗi gì thì thêm dòng vào CLAUDE.md” bằng quyết định routing có cấu trúc.

Key insight: Decision Tree Failure-to-Constraint route lỗi agent vào đúng layer enforcement. Hành động không thể hoàn tác → Hook (100% enforcement). Workflow lặp lại → Command (automation). Chỉ vấn đề style và convention → CLAUDE.md (soft context). Tránh overload CLAUDE.md với rules cần enforcement mạnh hơn.

Phân loại lỗi agent vào đúng layer như thế nào?

Không phải lỗi nào cũng thuộc CLAUDE.md. Hành động nguy hiểm cần Hook cho enforcement cứng. Workflow lặp lại cần Command cho automation. Chỉ vấn đề style và convention mới thuộc CLAUDE.md. Đặt hành động nguy hiểm vào CLAUDE.md giống như dán biển “xin đừng ăn trộm” thay vì gắn khóa.

Loại A: Lỗi cấu trúc → Hook

Những thứ không thương lượng. Xóa file, sửa config nhạy cảm, force push, thao tác sai branch. Tỷ lệ tuân thủ CLAUDE.md là 60-70% cho file lớn. Với hành động không thể hoàn tác, bạn cần 100%.

Đọc chi tiết cách implement: Which Claude Code Hook Do You Need?

Loại B: Lỗi style và convention → CLAUDE.md

Variable naming, comment style, test patterns, git commit message format. Low-stakes nếu vi phạm đôi khi. Soft context của LLM xử lý tốt ở đây.

Viết dưới dạng failure-derived constraint:

- Dùng camelCase cho variables, PascalCase cho components.
  # 2026-03-20: agent dùng snake_case trong 3 React components, phá style
- Test files đặt trong __tests__/ cạnh source file, không phải top-level test/.
  # 2026-02-15: agent tạo test/api/users.test.ts, jest config bỏ qua

Loại C: Lỗi workflow → Commands/Skills

“Luôn chạy test sau refactor.” “Luôn update changelog sau API changes.” Đây là quy trình lặp lại. Đừng nhắc nhở agent. Hãy tự động hóa.

Đặt vào .claude/commands/ để chạy deterministic. Command chạy mọi lần. CLAUDE.md instruction chạy khi model nhớ.

Layer	Enforcement	Tỷ lệ tuân thủ	Ví dụ
Hook	Deterministic (shell script)	100%	Block `git push --force`
Command	Deterministic (thực thi)	100%	Chạy test sau refactor
CLAUDE.md	Probabilistic (LLM context)	60-90%	Dùng camelCase naming

Tìm hiểu thêm các layer phối hợp ra sao: The Think-Plan-Execute Pattern.

Nhận tips Claude Code hàng tuần - Một email mỗi tuần. Tips thực tế, không rác. Đăng ký AI Developer Weekly →

CLAUDE.md trước và sau khi áp dụng failure-first trông như thế nào?

CLAUDE.md theo failure-first ngắn hơn, cụ thể hơn, và có nguồn gốc cho mọi constraint. Thay vì “Cẩn thận với production database,” bạn viết chính xác lỗi gì, ngày nào, và cách phòng ngừa.

Trước: viết theo instruction (47 dòng)

# Project: Acme SaaS

## Rules
- Cẩn thận với production database.
- Luôn viết test.
- Dùng TypeScript strict mode.
- Tuân thủ naming conventions.
- Không dùng deprecated APIs.
- Giữ function dưới 50 dòng.
- Dùng ESLint và Prettier.
- Comment logic phức tạp.
- Không hardcode environment variables.
- Dùng tên biến có ý nghĩa.
# ... 37 dòng tương tự

Mỗi dòng đều hợp lý. Không dòng nào cụ thể. Agent đọc cả 47, nhớ khoảng 30, tuân thủ nhất quán khoảng 25.

Sau: viết theo failure (18 dòng)

# Project: Acme SaaS
TypeScript, Next.js 15, Drizzle ORM, Vercel.

## Build
npm run build && npm test

## Constraints (mỗi dòng từ một lỗi thực tế)

KHÔNG BAO GIỜ dùng `git push --force`. Dùng `--force-with-lease`.
# 2026-03-12: force push ghi đè commits teammate trên feature/auth

Chạy `npm test` trước MỌI git commit.
# 2026-02-28: import lỗi push lên main, CI phát hiện sau 20 phút

Schema migrations: luôn generate bằng `drizzle-kit generate`.
# 2026-03-05: migration viết tay thiếu NOT NULL, staging sập

API routes: validate input bằng zod schemas, không trust req.body.
# 2026-03-18: input không validate gây lỗi 500 trong 2 giờ

18 dòng. 4 constraints. Mỗi cái gắn với sự cố thực, có ngày tháng. Agent biết không chỉ tránh gì mà còn tại sao, khiến constraint “dính” hơn trong context.

Constraint force-push? Nó nên được nâng cấp lên Hook cho 100% enforcement. Nhưng ngay cả trong CLAUDE.md, failure context khiến nó được tuân thủ tốt hơn nhiều so với “cẩn thận với git.”

Thử ngay: Mở CLAUDE.md của bạn bây giờ. Với mỗi dòng, viết ra lỗi cụ thể khiến bạn thêm nó vào. Nếu không nhớ sự cố nào, xóa dòng đó. Rồi kiểm tra: constraint nào nên là Hook? Chuyển chúng sang .claude/settings.json.

Tôi đã làm bài tập này trên CLAUDE.md 90 dòng tháng trước. Giảm xuống còn 23 dòng. Tỷ lệ tuân thủ trên các rules còn lại tăng rõ rệt ngay session đầu tiên. Ít rules hơn, tuân thủ tốt hơn.

Key insight: Pattern failure-first dùng CONSTRAINT + LÝ DO + NGÀY LỖI cho mỗi dòng CLAUDE.md. Cung cấp context cụ thể cho LLM về lý do rule tồn tại, tăng khả năng ghi nhớ. Thực tế, pruning file 90 dòng xuống 23 dòng cho thấy tỷ lệ tuân thủ tăng rõ rệt ngay session đầu.

Giữ CLAUDE.md gọn gàng lâu dài như thế nào?

Prune hàng tháng. Constraint nào không kích hoạt trong 3 tháng, cân nhắc xóa. Constraint nào đã lên Hook, xóa khỏi CLAUDE.md. CLAUDE.md production của HumanLayer dưới 60 dòng. Phình to là kẻ thù số một.

Đây là checklist pruning tôi chạy hàng tháng:

Với mỗi constraint trong CLAUDE.md, hỏi:

1. Agent có trigger constraint này trong 3 tháng qua không?
   KHÔNG → ứng viên để xóa

2. Constraint này đã lên Hook chưa?
   RỒI → xóa khỏi CLAUDE.md (đã enforce, không cần suggest)

3. Đây có phải workflow có thể thành Command không?
   CÓ → chuyển sang .claude/commands/, xóa khỏi CLAUDE.md

4. Tôi có thể nêu tên lỗi cụ thể đằng sau dòng này không?
   KHÔNG → xóa (nó mang tính mong muốn, không dựa trên bằng chứng)

5. Agent đã làm đúng mà không cần instruction này chưa?
   RỒI → xóa (đang lãng phí instruction budget)

Bẫy phình to rất thực tế. Trong team, mọi developer đều thêm dòng. Không ai xóa. Ba tháng sau, file 300 dòng và bạn quay lại vạch xuất phát.

Chạy pruning session mỗi tháng. Hỏi Claude: “Constraint nào trong số này bạn gặp tháng này?” Những cái không bao giờ gặp là ứng viên để xóa.

Constraint nào chứng minh quan trọng qua nhiều sự cố nên được nâng cấp. Chuyển lên Hook nơi enforcement là deterministic. Rồi xóa khỏi CLAUDE.md. Constraint đã có Hook enforce thì không cần sống trong CLAUDE.md nữa (Hook sẽ block hành động bất kể).

Key insight: CLAUDE.md production của HumanLayer dưới 60 dòng (HumanLayer Blog, 2026). Pruning hàng tháng giữ file gọn: xóa constraint không trigger trong 3 tháng, nâng cấp rules quan trọng lên Hook, xóa dòng nào không có lỗi gốc. Mục tiêu: 30-60 dòng failure-derived constraints.

Xây dựng .claude/ setup đúng cách. Nhận .claude/ Template Repo đầu tiên khi ra mắt. Tham gia danh sách chờ →

FAQ

CLAUDE.md và AGENTS.md khác nhau thế nào?

CLAUDE.md là file instruction cấp project của Claude Code, tự động load khi bắt đầu session. AGENTS.md là tiêu chuẩn mở đang phát triển được OpenAI Codex, Amp, Google Jules, và Cursor hỗ trợ, phục vụ cùng mục đích nhưng không phụ thuộc vào agent cụ thể. Cả hai đều là repository-level context files. Nếu dùng Claude Code, viết CLAUDE.md. Nếu muốn tương thích đa agent, thêm AGENTS.md. Phương pháp failure-first áp dụng cho cả hai.

Nên bắt đầu CLAUDE.md từ đầu hay dùng template?

Bắt đầu từ đầu với chỉ 3 thứ: tên project, tech stack, build commands. Rồi xây dựng qua failure-first workflow: chạy agent, quan sát lỗi, thêm constraint từng cái một. Template khuyến khích tư duy instruction-first, chính là vấn đề bài viết này giải quyết. Nếu bắt buộc dùng template, chỉ dùng cho phần project overview, không bao giờ cho constraints.

Agent có thể bỏ qua constraint trong CLAUDE.md không?

Có. CLAUDE.md là “soft” context. LLM cân nhắc nó với context khác nhưng có thể bỏ qua. Tỷ lệ tuân thủ 60-70% với file lớn, cao hơn với file gọn. Với constraint phải tuân thủ 100% (hành động nguy hiểm, security rules), dùng Hooks. Hooks chạy bằng shell scripts và chặn hành động vật lý. Model không thể bypass.

CLAUDE.md nên có bao nhiêu dòng?

Càng ít càng tốt. CLAUDE.md production của HumanLayer dưới 60 dòng. Nghiên cứu cho thấy LLM tuân thủ ~150-200 instruction nhất quán, nhưng ngân sách này chia sẻ với system prompt (~50 instruction). Nhắm 30-60 dòng failure-derived constraints cộng project overview tối giản. Nếu file vượt 100 dòng, audit bằng failure-first test: bạn có nêu được sự cố cụ thể đằng sau mỗi dòng không?

Đọc Tiếp

Harness Engineering: Hệ thống quanh AI quan trọng hơn chính AI - Framework 5 layer đặt CLAUDE.md vào đúng ngữ cảnh. Layer 1 là memory. Bài này đi sâu vào cách xây Layer 1 đúng cách.
Chọn Hook nào cho Claude Code? Hướng dẫn quyết định - Khi decision tree đưa bạn đến Hooks (lỗi loại A), guide này chỉ cách chọn loại hook và implement.
Hơn cả CLAUDE.md: 5 Layer mà AI Agent Harness đang thiếu - Hướng dẫn setup từng layer. Khi CLAUDE.md đã gọn gàng và failure-driven, xây tiếp 4 layer còn lại.