Cách thiết lập CLAUDE.md năm 2026: Mẫu và 6 quy tắc

Tài liệu về vibe coding: công cụ, nghiên cứu tình huống, lỗi thường gặp. Ailoot Guides.

Vì sao bạn cần CLAUDE.md, và vì sao Claude quên dự án nếu không có tệp này?#

Bạn mở Claude Code vào thứ Ba và giải thích: “Tôi đang làm việc trên dự án này, đây là các công cụ, đừng làm việc này.” Mọi thứ hoạt động.

Đến thứ Năm, cuộc trò chuyện đó đã kết thúc, nên bạn lặp lại mọi thứ. Thứ Bảy lại lặp lại; thứ Hai lại thêm một lần nữa.

Đó là cách làm việc với tác nhân không có CLAUDE.md: mỗi cửa sổ mới là một thực tập sinh bắt đầu từ trang giấy trắng, người mà bạn phải nói đi nói lại cùng một điều. Trước đây, tôi mất 5-10 phút gõ phần hướng dẫn mở đầu này cho mỗi phiên. Các lời nhắc ngày càng dài vì tôi phải tự mang theo toàn bộ ngữ cảnh. Kết quả vẫn chung chung: tác nhân không biết đối tượng, bài toán kinh tế hay nguyên tắc của tôi.

Với CLAUDE.md được duy trì thường xuyên, bạn không còn phải mở đầu phiên. Tất cả quy tắc từng phải nhắc lại trong mỗi cuộc trò chuyện đều nằm trong một tệp và tự động xuất hiện khi bắt đầu mỗi phiên. Lời nhắc trở nên ngắn gọn: “làm X”, thay vì “tôi đang làm dự án Y, công cụ là Z, đừng làm A hoặc B, và nhớ cả C nữa.”

Sau đó, các lỗi lặp đi lặp lại biến mất.

Mỗi lỗi của tác nhân là lý do để thêm một dòng vào CLAUDE.md. Sau một tháng, bạn có một “hiến chương dự án” luôn được cập nhật, và Claude không còn mắc lại những cái bẫy quen thuộc.

Còn một lớp thứ ba: tác nhân không còn viết trong chân không. Thông qua CLAUDE.md, tôi hướng Claude đến các thư mục có ngữ cảnh: nơi tìm thông tin về đối tượng, giá cả và thương hiệu. Không có định tuyến này, tác nhân viết “giải pháp chất lượng cao” mà không biết bài toán kinh tế của tôi, nên kết quả trừu tượng, rập khuôn và “giống hệt mọi người khác.”

CLAUDE.md là gì và Claude đọc các tệp theo thứ tự nào?#

Anthropic mô tả CLAUDE.md như sau trong tài liệu chính thức:

Bốn nơi Claude Code tìm CLAUDE.md, theo thứ tự ưu tiên tăng dần:

Cả bốn tệp được tải vào ngữ cảnh cùng lúc. Nếu các quy tắc xung đột, Anthropic nói rõ trong tài liệu rằng chưa biết quy tắc nào sẽ được ưu tiên; Claude có thể tùy ý chọn một quy tắc. Vì vậy, đơn giản hơn là giữ mọi thứ quan trọng trong CLAUDE.md của dự án và tránh tạo bản trùng lặp.

Có một chi tiết kỹ thuật hầu như không ai viết về, nhưng nó giải thích nhiều hành vi kỳ lạ.

Nói cách khác, CLAUDE.md không phải “system prompt” theo nghĩa chặt chẽ. Đây là tin nhắn người dùng đầu tiên Claude nhìn thấy. Vì vậy, các quy tắc trong đó là khuyến nghị mạnh, không phải luật. Nếu quy tắc cần cưỡng chế, dùng hook đã thử cho sự kiện nó phủ, và quyền hoặc cách ly môi trường cho ranh giới truy cập rộng hơn. Hook chạy tự động không làm kiểm tra của nó đầy đủ. Tôi sẽ giải thích ranh giới giữa hooks và CLAUDE.md ở phần dưới.

Viết CLAUDE.md tối giản trong 5 phút như thế nào (mẫu dùng ngay)?#

Dưới đây là mẫu tôi đã thử nghiệm trong hàng chục dự án của mình. Tệp dài khoảng 80-120 dòng, phù hợp khuyến nghị nhắm dưới 200 dòng của Anthropic. Mẫu này giúp tác nhân đưa ra kết quả hợp lý nhất.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Để Claude tự động điền mẫu này cho dự án của bạn, hãy gửi lời nhắc sau. Claude sẽ đọc ngữ cảnh và điền các trường trong ngoặc vuông:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Nhắm giữ CLAUDE.md dưới 200 dòng. Nếu dài hơn, xem trùng lặp và chuyển quy trình chi tiết sang tệp liên kết. Giữ quy tắc lập kế hoạch, nhìn lại và kho cốt yếu, rồi thử trên việc đại diện.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Nếu bạn chưa có thư mục about-me/ và business/ thì cũng không sao. Claude sẽ hỏi thêm để làm rõ và tạo CLAUDE.md tối giản dựa trên thông tin hiện có. Bạn có thể tạo các thư mục đó sau, khi đã biết cần đưa gì vào.

6 quy tắc nào biến CLAUDE.md thành tài liệu luôn được cập nhật?#

Quy tắc 1. Giữ tệp dưới 200 dòng

Anthropic nói ngắn gọn trong tài liệu chính thức:

CLAUDE.md dài tự làm giảm hiệu quả theo hai cách. Thứ nhất, nó tiêu tốn token. Tệp chỉ dẫn 800 dòng được tải vào mọi cửa sổ và dùng hết vài nghìn token trong ngân sách của bạn ở mỗi phiên. Với gói Pro có giới hạn hằng ngày, điều đó làm giảm đáng kể số phiên khả dụng. Thứ hai, mô hình bắt đầu phớt lờ các quy tắc.

Tài liệu khuyên nhắm dưới 200 dòng để giảm ngữ cảnh và cải thiện tuân thủ, không xác lập mốc hỏng đột ngột ở dòng 201. Xem độ liên quan, mâu thuẫn, số token đã nạp và kết quả việc thật trước quyết định chuyển phần nào ra.

Quy tắc 2. Kết thúc mỗi phiên bằng phần nhìn lại

Trong CLAUDE.md, hãy viết: “Cuối mỗi phiên, ghi lại những gì bạn đã làm và học được vào retrospectives/YYYY-MM-DD_*.md.” Sau khi thêm dòng này, Claude sẽ tự kết thúc mỗi phiên bằng phần nhìn lại; bạn không cần yêu cầu.

Vì sao nên nhìn lại:

• Hai tuần sau, bạn có thể mở một bản nhìn lại cũ và nhớ vì sao mình chọn hướng đi đó.
• Khi quay lại dự án sau một tháng, bạn có sẵn bản đồ các quyết định gần đây.
• Nếu làm việc theo nhóm, cộng sự có thể đọc bản nhìn lại và hiểu trạng thái hiện tại trong 2 phút mà không cần gọi điện.

Quy tắc 3. Commit sau mỗi nhiệm vụ hoàn thành

CLAUDE.md của tôi ghi: “Sau mỗi nhiệm vụ hoàn thành, tạo một git commit với thông điệp có ý nghĩa.” Claude sẽ tự chia công việc thành các commit nguyên tử.

Điều này mang lại hai lợi ích. Thứ nhất, nếu có sự cố, bạn có thể hoàn tác một thao tác thay vì “mọi thứ tôi làm hôm nay”. Thứ hai, lịch sử commit trở thành nhật ký công việc cho thấy điều gì đã thay đổi và theo thứ tự nào.

Quy tắc 4. Luôn tham khảo thư mục business/

Với mọi nhiệm vụ liên quan đến khách hàng, sản phẩm hoặc nội dung, trước tiên tác nhân nên mở business/INDEX.md và tệp liên quan được chỉ ra ở đó. CLAUDE.md của tôi ghi rõ: “Khi làm việc với UI hoặc nội dung, trước tiên hãy kiểm tra business/audience/avatar.md và business/assets/brand-guidelines.md.”

Không có quy tắc này, Claude viết nội dung theo “phong cách chung của một trang web chất lượng”. Có quy tắc, nội dung sẽ mang phong cách của bạn, dành cho khách hàng của bạn và tránh các từ bị cấm.

Quy tắc 5. Thêm quy tắc sau mỗi lỗi của tác nhân

Đây là quy tắc chính giúp CLAUDE.md luôn được cập nhật.

Ví dụ từ CLAUDE.md của tôi được thêm sau những lỗi cụ thể:

• “Không bao giờ commit tệp WIP của người khác bằng git add . - hãy đưa từng tệp vào staging theo tên.”
• “Trước khi push lên main, hãy kiểm tra git log origin/main..main --oneline - nếu kết quả không trống, đừng push.”
• “Đừng tự bịa giá trị - lấy chúng từ .env hoặc mã nguồn. Đặc biệt là URL, tên người dùng và token.”

Mỗi dòng là dấu vết của một sự cố cụ thể. Có lần, tác nhân commit nhánh dang dở của cộng sự. Có lần, tôi đưa cả các commit chưa push của người khác vào. Có lần, tác nhân bịa ra một URL không tồn tại. Mỗi lỗi trở thành một quy tắc, và vết thương do chính mình gây ra sẽ không lặp lại.

Quy tắc 6. Đặt quy tắc bảo mật trong .claude/settings.json, không phải CLAUDE.md

Trong CLAUDE.md, bạn có thể ghi “đừng đụng vào .env”, nhưng đó chỉ là yêu cầu; Claude có thể vi phạm vì CLAUDE.md được tải như tin nhắn người dùng, không phải luật. Với bảo mật thiết yếu, hãy dùng .claude/settings.json, nơi bạn có thể chặn nghiêm ngặt một số lệnh.

Danh sách chặn tôi thêm vào mọi dự án mới:

• rm -rf (xóa đệ quy mọi tệp).
• Đọc toàn bộ .env (Read .env).
• export và curl trong cùng một lệnh (một kiểu có thể làm rò rỉ bí mật ra bên ngoài).
• git push --force khi chưa được phê duyệt rõ ràng.

Tìm các hướng dẫn khác tại Ailoot.

CLAUDE.md trong một doanh nghiệp đang hoạt động được cấu trúc ra sao (phân tích tệp 280 dòng)?#

Hầu hết ví dụ CLAUDE.md trên mạng là mẫu kỹ thuật cho lập trình viên: “Dùng TypeScript,” “Đừng viết test dài hơn 50 dòng.” Với một doanh nhân, dạng CLAUDE.md này vô ích - nó không đề cập đến khía cạnh kinh doanh.

Dưới đây là cấu trúc CLAUDE.md mà tôi đang dùng. Tôi đã bỏ các quy tắc và đường dẫn cụ thể vì chúng phản ánh hoạt động nội bộ của tôi. Nhưng cấu trúc và logic của các mục có thể áp dụng cho mọi dự án: đưa hoàn cảnh của bạn vào là có một tệp dùng được.

1. Mô tả ngắn về dự án (15 dòng). Chúng ta làm gì, đối tượng là ai, cung cấp sản phẩm nào. Không phải phần tóm tắt từ trang tiếp thị, mà là phần tóm tắt cho tác nhân để nó hiểu “chúng ta đang hướng đến đâu.”

2. Về tôi (10 dòng). Con trỏ đến thư mục about-me/ - hình ảnh số về cách tôi suy nghĩ. Giọng điệu, giá trị, nguyên tắc, từ ngữ bị cấm. Khi Claude viết nội dung “với tư cách tôi”, nó đọc thư mục này trước để khớp giọng văn.

3. Cấu trúc repository (20 dòng). Cây thư mục có chú thích: mã nguồn ở đâu, ngữ cảnh kinh doanh ở đâu, kế hoạch và phần nhìn lại ở đâu. Không có bản đồ này, Claude phải mò tìm tệp mỗi lần.

4. Bảng “tìm thông tin ở đâu” (25 dòng). Định tuyến từ “câu hỏi → tệp”. Ví dụ, với một công ty bất động sản, có thể ghi “cần điều khoản thế chấp → business/products/mortgage.md” hoặc “cần giọng điệu bài đăng → business/assets/voice.md.” Thay bằng các tệp của riêng bạn. Bảng này là trọng tâm của CLAUDE.md. Không có nó, tác nhân sẽ đoán tệp nào chứa câu trả lời. Có nó, tác nhân đi thẳng đến nguồn.

5. Nguyên tắc cốt lõi của dự án (40 dòng, 10-15 mục). Mục này tích lũy từ từ và tốn nhiều công sức nhất. Mỗi mục là dấu vết của một lỗi cụ thể. Ví dụ, quy tắc cho cửa hàng trực tuyến có thể là “không bao giờ ghi cứng giá và thời gian giao hàng,” “đừng xuất bản sản phẩm nếu chưa có lệnh rõ ràng,” và “kiểm tra phong cách theo bảng thuật ngữ thương hiệu trước khi đăng danh sách sản phẩm.” Mục này là “hiến chương dự án.”

6. Lập kế hoạch vận hành (20 dòng). Bảng kích hoạt ánh xạ “câu nói của người dùng → hành động”. Ví dụ: “Khi tôi nói ‘lên kế hoạch tuần’, mở ops/monthly.md và tạo tệp của tuần.” Điều này biến Claude thành trợ lý vận hành hiểu ngữ cảnh các lệnh.

7. Công cụ (5 dòng). Công nghệ. Ngắn gọn, không dài dòng.

8. Xuất bản (15 dòng). Quy trình từng bước để đưa thay đổi lên production: chạy lệnh nào, theo thứ tự nào và cần kiểm tra gì. Trước đây tôi phải giải thích mỗi lần. Giờ Claude đã biết.

9-12. Bảo mật (35 dòng). Bốn tiểu mục riêng: quy tắc làm việc với .env, quyền truy cập cơ sở dữ liệu production, lệnh an toàn cho bản demo (ghi màn hình, phát trực tiếp, ảnh chụp màn hình để tránh vô tình lộ token) và quy tắc luân chuyển bí mật.

13. Thư mục plans/ (10 dòng). Tiêu chuẩn kế hoạch: tên tệp, cấu trúc giai đoạn và nội dung cần có trong phần tóm tắt.

14. Thư mục retrospectives/ (5 dòng). Tiêu chuẩn nhìn lại: mẫu, tên tệp và nội dung cần có.

15. Dữ liệu cơ sở dữ liệu trực tiếp (15 dòng). Quy tắc đánh dấu “dữ liệu mới”: khi tệp yêu cầu số liệu phải cập nhật, tác nhân lấy chúng từ nguồn thay vì dùng dữ liệu cũ. Điều này loại bỏ nguy cơ Claude dùng số liệu của ngày hôm qua.

16. Ngôn ngữ (3 dòng). “Luôn trả lời bằng ngôn ngữ người dùng ưa thích. Chỉ dùng dấu gạch nối, không dùng em dash.”

Tổng khoảng 280 dòng, vượt mục tiêu gọn nhưng không làm tệp vô hiệu. Trong ví dụ này nó còn hữu ích; giữ hay không nên dựa mức ngữ cảnh đo được và kiểm tra việc đại diện. Bảng không tự rẻ token hơn văn xuôi.

Lệnh /init làm gì và vì sao chưa đủ?#

Anthropic mô tả lệnh này trong tài liệu như sau:

/init làm tốt những việc sau:

• Nhận diện công cụ từ package.json, Cargo.toml và pyproject.toml.
• Liệt kê lệnh build và test.
• Phát hiện quy ước từ các tệp hiện có (.eslintrc, .prettierrc).
• Nhận ra quy tắc Cursor hiện có (.cursorrules, .cursor/rules/) và quy tắc Copilot, rồi đưa các phần liên quan vào. Nó phát hiện AGENTS.md ở chế độ CLAUDE_CODE_NEW_INIT=1.

/init không làm được những việc sau:

• Không biết khách hàng của bạn là ai.
• Không đưa các từ bị cấm cho nội dung vào tệp.
• Không thêm quy tắc về lỗi của tác nhân (vì chưa có lỗi nào xảy ra).
• Không tạo bảng “tìm thông tin ở đâu” cho cấu trúc kinh doanh của bạn.

Vì vậy, quy trình phù hợp là:

1. Chạy /init trong Claude Code

   Bạn sẽ có CLAUDE.md khởi đầu dài 30-50 dòng với công cụ và lệnh. Đây là nền tảng kỹ thuật.

2. Thêm mẫu trong bài viết này lên trên

   Dùng mục “CLAUDE.md tối giản trong 5 phút”. Thêm các mục định tuyến, đường dẫn và nguyên tắc.

3. Điền các trường trong ngoặc vuông

   Gửi Claude lời nhắc “đọc dự án của tôi và điền mẫu”. Nếu chưa có thư mục business/ và about-me/, Claude sẽ hỏi thêm để làm rõ.

4. Kiểm tra sức chịu đựng

   Bảo Claude: “Đọc CLAUDE.md của tôi và tìm 10 điểm mơ hồ có thể khiến bạn, với tư cách tác nhân, hiểu sai.” Bạn sẽ nhận được danh sách điều chỉnh.

5. Sau đó, hãy cùng sống với tệp này

   Thêm một dòng sau mỗi lỗi của tác nhân. Sau một tháng, bạn sẽ có CLAUDE.md sống động, được điều chỉnh cho doanh nghiệp của mình.

Lời nhắc cho bước thứ tư:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md, AGENTS.md và MEMORY.md: năm 2026, ai đọc tệp nào?#

Câu hỏi chính khiến người mới bối rối là: Claude Code có đọc AGENTS.md không? Trước tháng 9 năm 2026, câu trả lời là “không”: tài liệu Anthropic khuyên tạo CLAUDE.md để nhập AGENTS.md. Kể từ phiên bản 2.1.277 (phát hành ngày 18 tháng 9 năm 2026), Claude Code tự đọc AGENTS.md, nhưng chỉ khi không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md trong thư mục làm việc hoặc thư mục cấp trên.

Nếu dự án có CLAUDE.md, theo mặc định Claude Code chỉ đọc tệp đó và bỏ qua AGENTS.md. Bạn có thể thay đổi tại /config, trong Project instructions: chẳng hạn, tùy chọn claude-md-and-agents-md khiến Claude đọc cả hai tệp. Một cách khác dùng được ở mọi phiên bản là thêm dòng nhập tệp vào CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

Cú pháp @filename nhập một tệp khác. Claude đọc tệp đó và tải vào ngữ cảnh cùng với CLAUDE.md. Tệp không bị đọc hai lần do thao tác nhập, kể cả khi Claude Code có thể tự đọc AGENTS.md.

Khi nào bạn cần AGENTS.md. Nếu làm việc song song với Claude Code và Codex CLI, Cursor hoặc Copilot, hãy tạo AGENTS.md làm nguồn sự thật duy nhất, thêm @AGENTS.md vào CLAUDE.md và đặt các quy tắc riêng cho Claude lên trên. Nếu không có quy tắc riêng như vậy, bạn không cần tạo CLAUDE.md: kể từ phiên bản 2.1.277, Claude Code tự đọc AGENTS.md. Nếu chỉ dùng Claude Code, bạn không cần AGENTS.md; chỉ cần một CLAUDE.md. Để xem từng bước mọi tùy chọn, hãy đọc hướng dẫn sử dụng AGENTS.md và CLAUDE.md trong cùng một dự án.

MEMORY.md là gì? Kể từ một bản cập nhật gần đây, Claude Code tự động ghi chú về bạn tại ~/.claude/projects/<project-name>/memory/MEMORY.md. Những ghi chú này gồm thói quen trò chuyện (“người dùng thích câu trả lời ngắn”), cụm từ thường gặp (“cấm emoji trong mã”) và quan sát về hành vi (“dùng macOS, sử dụng zsh”).

Đây là một hệ thống bộ nhớ riêng, không phải CLAUDE.md. Bạn không tự viết; Claude tạo ra dựa trên các cuộc trò chuyện. Nếu MEMORY.md có điều cần trở thành quy tắc, hãy chuyển nó sang CLAUDE.md. Nếu có nội dung không cần thiết hoặc sai, bạn có thể tự xóa; đây là tệp văn bản.

CLAUDE.md dài bao nhiêu là hữu ích, và nên xem lại tệp dài thế nào?#

Trong mỗi cửa sổ Claude Code, nhiều lớp được tải vào ngữ cảnh: system prompt của Anthropic (ước tính hàng chục nghìn token), CLAUDE.md của bạn, các tệp được nhập bằng @, MEMORY.md, lịch sử trò chuyện hiện tại và nội dung các tệp Claude mở. Tất cả phải vừa trong ngữ cảnh của mô hình (200K token cho Sonnet, 1M cho Opus).

CLAUDE.md càng lớn thì càng ít chỗ cho công việc hiện tại. Tệp 1,000 dòng có khoảng 8,000 token và được tải lại trong mỗi phiên. Với gói Pro (theo trải nghiệm của tôi, khoảng 10-12 lời nhắc “nặng” mỗi ngày), điều đó làm giảm năng lực của bạn một phần tư.

Chi phí chỉ là một mối lo. Tuân thủ có thể giảm khi hướng dẫn dài, không liên quan hoặc xung đột; không có số chỉ dẫn được theo đáng tin cậy phổ quát. Thử vài việc đại diện dùng quy tắc cốt yếu, ghi lỗi rồi so sau sửa có trọng tâm.

Vậy đây là quy tắc kinh nghiệm về kích thước:

• 80-120 dòng - khoảng khởi đầu tiện cho bản đồ dự án gọn, không bảo đảm điểm tuân thủ.
• 150-200 dòng - lời nhắc xem độ liên quan và chuyển quy trình chi tiết sang tệp liên kết.
• 200-300 dòng - xem token, trùng lặp và kết quả việc; ví dụ doanh nghiệp 280 dòng trên vẫn có thể tốt.
• 400+ dòng - lý do mạnh để xem có trọng tâm, chưa chứng minh vô dụng. Giữ giới hạn cốt yếu; chuyển chi tiết sau khi kiểm liên kết và quy tắc còn chạy.

Riêng số dòng không xác lập thành công hay thất bại. Sau sửa, lặp cùng việc đại diện và xác minh quy tắc quan trọng thay vì gán tỷ lệ tuân thủ bịa.

Anthropic đưa ra một phép thử trực tiếp trong tài liệu:

Áp dụng điều này cho từng dòng. Nếu câu trả lời là “nó vẫn làm đúng”, hãy xóa dòng đó. CLAUDE.md không phải nơi chứa tài liệu, lịch sử quyết định hay triết lý. Nó chỉ dành cho các quy tắc giúp tác nhân tránh mắc lỗi.

7 lỗi nào khiến CLAUDE.md trở nên vô dụng?#

Lỗi 1. “Hãy là một kỹ sư giỏi”

Đây là lỗi phổ biến nhất. Mọi người viết những mong muốn chung chung trong CLAUDE.md: “viết mã sạch”, “dùng các phương pháp hay nhất”, “suy nghĩ như kỹ sư cấp cao.”

Những từ này chẳng có ý nghĩa gì. Claude vốn đã viết “mã sạch” theo nghĩa chung. Các dòng này chiếm ngữ cảnh nhưng không ảnh hưởng đến quyết định nào.

Thay “viết mã sạch” bằng “thụt lề 2 dấu cách”, “không dùng any trong TypeScript” hoặc “hàm không được dài quá 30 dòng”. Cụ thể và có thể kiểm chứng.

Lỗi 2. Lặp lại điều Claude đã biết

Mô tả các quy ước ngôn ngữ tiêu chuẩn (“trong JavaScript, hàm là công dân hạng nhất”, “TypeScript có kiểu tĩnh”). Giải thích cách npm, git hoặc docker hoạt động.

Claude đã học tất cả những điều này trong quá trình huấn luyện. Lặp lại trong CLAUDE.md không thêm giá trị gì; nó chỉ chiếm chỗ trong ngữ cảnh.

Lỗi 3. Hướng dẫn dài từng bước trong CLAUDE.md

Các hướng dẫn dài về “cách deploy dự án”, “cách viết database migration” hoặc “cách thiết lập component mới”. Có hàng chục dòng từng bước.

Đây không phải nơi chứa hướng dẫn từng bước dài. Tệp này dành cho các quy tắc một dòng. Đặt hướng dẫn dài trong skills/ (cơ chế riêng của Claude Code được tải khi cần) hoặc trong docs/. Trong CLAUDE.md, hãy dùng liên kết một dòng: “Khi tạo migration mới, mở docs/migrations.md.”

Lỗi 4. Quy tắc đã được trình phân tích mã tự động kiểm tra

“Dùng dấu chấm phẩy”, “không để import chưa sử dụng”, “không dùng var”. ESLint, Prettier và Biome phát hiện tất cả những điều này - chúng là linter (công cụ kiểm tra mã tự động).

Linter hoạt động xác định: chạy, tìm lỗi rồi sửa. Quy tắc CLAUDE.md mang tính xác suất; tác nhân có thể quên. Không cần lặp lại - cấu hình linter dễ hơn.

Lỗi 5. Để bí mật trong CLAUDE.md

Tôi từng thấy mật khẩu tài khoản thử nghiệm, token API sandbox và liên kết đến bảng quản trị cần xác thực. Tất cả nằm trong tệp được commit vào git và tải vào ngữ cảnh mô hình của Anthropic.

Tuyệt đối không. Bí mật phải nằm trong .env, và tệp này được đưa vào .gitignore. Tối đa, CLAUDE.md nên ghi: “Đừng đọc toàn bộ .env; dùng grep cho một biến cụ thể.”

Lỗi 6. Tệp chứa đủ thứ dài hơn 500 dòng mà sáu tháng chưa được dọn

CLAUDE.md dài ra, lặp lại một nửa docs/, tự mâu thuẫn ở vài chỗ và không ai nhớ trong đó có gì. Tác nhân bắt đầu phớt lờ phần lớn nội dung. Nhóm phàn nàn rằng “Claude không làm theo chỉ dẫn” rồi thêm nhiều quy tắc hơn, khiến tình hình tệ hơn.

Dấu hiệu CLAUDE.md bị bỏ bê: hơn 300 dòng, quy tắc lặp lại ở nhiều mục, liên kết cũ đến tệp không còn tồn tại và ghi chú “lịch sử” như “năm 2024 chúng ta quyết định làm theo cách này, sau đó đổi ý.”

Cách khắc phục: hai tuần một lần, yêu cầu Claude xem lại bằng phép thử của Anthropic: “Nếu xóa dòng này, tác nhân có mắc lỗi không?” Xóa mọi thứ có câu trả lời là “không”.

Lỗi 7. Tạo CLAUDE.md rồi quên mất

Đây là mặt đối lập của lỗi trước. Tệp được soạn một lần cách đây hai tháng và chưa được động đến kể từ đó. Trong lúc ấy, công cụ đã thay đổi, thư mục mới được thêm và các lỗi mới của tác nhân xuất hiện. CLAUDE.md không biết những điều này vì không ai cập nhật nó.

Dấu hiệu dễ nhận ra: bạn lặp lại cùng một chỉ dẫn trong mọi phiên. “Đừng làm X,” “đừng chạm vào Y,” “nhớ Z.” Nếu đã nhắc lại hơn hai lần, quy tắc đó thuộc về CLAUDE.md, không phải trong đầu bạn.

Làm cho CLAUDE.md tự học bằng quy tắc “cập nhật cuối phiên” như thế nào?#

CLAUDE.md của tôi có một mục ngắn:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Sau khi thêm mục này vào CLAUDE.md, Claude bắt đầu hỏi vào cuối mỗi phiên: “Có điều gì mới đáng ghi lại không?” Nếu có, nó đề xuất bản nháp quy tắc, tôi làm rõ rồi tạo tệp.

Sau hai tháng làm theo cách này, tôi có hơn hai chục tệp trong about-me/feedback/ - các quy tắc rút ra từ những lỗi cụ thể. Mỗi tệp là một trang theo định dạng Quy tắc → Lý do → Cách áp dụng. Thư mục trở thành “bộ nhớ thứ hai” ghi lại sở thích và điều cấm kỵ riêng của tôi.

Mỗi lỗi không tái diễn vì nó trở thành quy tắc, và các quy tắc tích lũy, củng cố lẫn nhau. Sau sáu tháng, Claude hiểu dự án của tôi tốt hơn cả những gì tôi nhớ sau khi nghỉ một tháng.

Thêm quy tắc pháp lý, tiếp thị và vận hành vào CLAUDE.md như thế nào?#

Với hầu hết nhóm, CLAUDE.md là tài liệu thuần kỹ thuật: công cụ, lệnh build, quy ước viết mã. Những điều này hữu ích, nhưng chỉ chiếm một phần ba giá trị.

Khi doanh nhân duy trì CLAUDE.md, nên thêm các mục kinh doanh. Ba mục quan trọng nhất:

Quy tắc pháp lý (cho thị trường có quy định)

Nếu bạn xuất bản nội dung trong ngành được quản lý (tài chính, y tế, quảng cáo thuốc, sản phẩm trẻ em), từ ngữ bị cấm có ý nghĩa pháp lý và cần được ghi thành quy tắc rõ ràng trong CLAUDE.md. Không nên để trong đầu ai đó hay trong ảnh chụp màn hình của biên tập viên - hãy để trong tệp mà tác nhân thấy ở mọi phiên.

Ví dụ cho dự án fintech không có giấy phép ngân hàng:

Ghi chú biên tập: Nội dung dưới đây cho thấy định dạng của một quy tắc nội bộ dành cho một dự án cụ thể. Đây không phải sự cho phép chung để dùng các thuật ngữ được liệt kê: việc một tuyên bố có được chấp nhận hay không phụ thuộc vào luật áp dụng và tình trạng của công ty.

🚨 QUAN TRỌNG - cấm cách diễn đạt về tài chính. Trong tài liệu hướng đến khách hàng, không dùng: “tiền gửi”, “lợi nhuận được đảm bảo” hoặc “sản phẩm đầu tư”. Hãy dùng: “tài khoản tiết kiệm”, “lợi nhuận dự kiến” và “sản phẩm lãi suất biến đổi”. Lý do là các yêu cầu pháp lý áp dụng cho quảng cáo dịch vụ tài chính của dự án này.

Khối này trong CLAUDE.md làm một việc đơn giản: mỗi khi bạn yêu cầu Claude viết nội dung cho khách hàng, tác nhân sẽ đối chiếu nội dung với các điều cấm này. Không có quy tắc, từ bị cấm xuất hiện trong mỗi chiến dịch thứ ba. Có quy tắc, bạn sẽ quên mất chúng từng tồn tại.

Cách tiếp cận tương tự áp dụng cho:

• Dự án y tế (không tuyên bố điều gì đó “điều trị” hoặc “chữa khỏi”).
• Quảng cáo thuốc (không nói “hiệu quả nhất”; phải có cảnh báo).
• Bất kỳ ngành được quản lý nào có quy định quảng cáo riêng.

Phong cách tiếp thị và định dạng nội dung

Nếu bạn thường xuyên xuất bản nội dung (mạng xã hội, bản tin, trang web), hãy ghi lại định dạng trong một đoạn văn ở CLAUDE.md. Đây là ví dụ mà một influencer hoặc công ty quản lý kênh nhắn tin có thể viết:

Khi viết bài đăng cho kênh, hãy tham khảo style/posts.md. Dùng các dấu định dạng mà kênh cho phép và tránh ký tự đặc biệt “nguy hiểm”. Kết thúc bằng CTA có UTM tag theo quy ước này: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Trước đây Claude viết bài theo “phong cách chung của một trang web tiếp thị”. Giờ đây nó làm theo định dạng của bạn, dùng UTM của bạn và không để lộ rằng nội dung do AI viết.

Thói quen vận hành

Bảng kích hoạt. Khi bạn nói một cụm từ cụ thể, tác nhân biết cần mở tệp nào và thực hiện hành động gì. Đây là ví dụ cho một nhóm lập kế hoạch theo tuần:

“Lên kế hoạch tuần” → mở ops/monthly.md, tạo YYYY-WNN.md trong cùng thư mục và chuyển các nhiệm vụ từ ops/backlog.md sang những ngày phù hợp. “Danh sách công việc tồn đọng có gì?” → đọc ops/backlog.md và hiển thị dưới dạng danh sách. “Kết thúc tuần” → điền mục “Tóm tắt tuần” trong tệp của tuần hiện tại.

Với những bảng như vậy, Claude chuyển từ “trợ lý viết mã” thành “người vận hành” hiểu thói quen kinh doanh của bạn. Mỗi thứ Hai, tôi nói “lên kế hoạch tuần nhé”, Claude mở đúng tệp, đọc mục tiêu tháng và đề xuất cách chia nhỏ công việc.

Kiểm tra CLAUDE.md bằng danh sách 12 điểm trong 5 phút như thế nào?#

1. Kích thước. Tệp có gọn, dùng khoảng 200 dòng làm mục tiêu xem lại thay vì ngưỡng đạt/trượt không?
2. Tên. Tên có chính xác là CLAUDE.md với chữ in hoa, không phải claude.md không?
3. Vị trí. Tệp nằm ở thư mục gốc dự án hoặc ./.claude/CLAUDE.md không?
4. Mô tả dự án. 5 dòng đầu có nói rõ dự án là gì và dành cho ai không?
5. Công cụ. Công nghệ có được liệt kê rõ ràng, không dài dòng không?
6. Cấu trúc. Có sơ đồ repository kèm giải thích không?
7. Định tuyến. Có bảng “câu hỏi → tệp” chỉ nơi tìm câu trả lời không?
8. Nguyên tắc. Có mục quy tắc bắt đầu bằng “không bao giờ” và “luôn luôn” không?
9. Cụ thể. Mỗi quy tắc có thể kiểm chứng không? (“Dùng 2 dấu cách”, không phải “viết thật hay.”)
10. Tự cập nhật. Có quy tắc “kiểm tra điều gì cần bổ sung khi kết thúc phiên” không?
11. Nhìn lại. Có quy tắc “ghi bản tóm tắt phiên vào retrospectives/” không?
12. Bảo mật. Các điều cấm thiết yếu (.env, rm -rf) cũng có trong .claude/settings.json không?

Nếu có hơn năm câu trả lời “không”, hãy mở Claude và gửi lời nhắc sau:

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

Đủ gọn cho tác vụ; xem lại quanh 200 dòng, không coi là trần cứng

Project description in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

Sau CLAUDE.md nên dùng Plan Mode, Skills hay sub-agents?#

CLAUDE.md là nền tảng. Khi nó hoạt động tốt, bạn có thể thêm ba cơ chế Claude Code bổ trợ cho nhau.

Plan Mode. Chế độ trong đó Claude lập kế hoạch thay đổi trước, chờ bạn phê duyệt rồi mới bắt đầu làm. Kích hoạt bằng Shift+Tab hoặc lệnh /plan. Chế độ này xử lý vấn đề nhức nhối nhất của vibe coding: “Tôi yêu cầu Claude sửa một thứ, nó viết lại nửa dự án.” Điều đó sẽ không xảy ra trong Plan Mode - bạn xem kế hoạch trước khi tác nhân chạm vào bất kỳ tệp nào.

Skills. Các tệp .md riêng trong thư mục .claude/skills/ chứa kiến thức cho một loại nhiệm vụ cụ thể. Ví dụ, skill “cách viết database migration” chứa quy trình cụ thể, mẫu và ví dụ. Kiến thức đó không nằm trong CLAUDE.md vì quá dài. Nhưng khi Claude gặp nhiệm vụ như “viết migration”, nó tải skill liên quan và làm theo.

Sub-agents. Khi một nhiệm vụ cần nhiều ngữ cảnh (ví dụ, xem xét một tính năng lớn), Claude có thể khởi chạy một sub-agent riêng với ngữ cảnh sạch của nó. Sub-agent thực hiện công việc rồi trả kết quả mà không làm lộn xộn ngữ cảnh cuộc trò chuyện chính.

Cả ba cơ chế đều dùng CLAUDE.md làm điểm bắt đầu: chúng đọc tệp khi bắt đầu công việc để hiểu ngữ cảnh dự án. Đó là lý do các tính năng này cũng hoạt động kém nếu không có CLAUDE.md được duy trì thường xuyên. Bắt đầu từ nền tảng rồi mới thêm các lớp bên trên.

Bước tiếp theo. Tạo tệp CLAUDE.md ở thư mục gốc dự án, sao chép mẫu ở đầu bài viết và điền các trường trong ngoặc vuông bằng lời nhắc hỗ trợ. Sau đó tiếp tục dùng tệp: biến mỗi lỗi của tác nhân thành một dòng mới. Sau hai hoặc ba tuần, CLAUDE.md không còn là “tài liệu chúng ta viết rồi quên” mà trở thành thứ Claude thực sự tham khảo trong mỗi phiên.

Nếu muốn xây dựng một khuôn khổ hoàn chỉnh quanh CLAUDE.md - thư mục business/ cho Second Brain, thư mục about-me/ làm hình ảnh số về bạn, các skill cơ bản và Plan Mode được cấu hình - hãy dùng các bước và ví dụ trong bài viết này. Ailoot Guides.

Tiếp tục với Ailoot.