Thực hành tốt CLAUDE.md: 9 quy tắc để Claude không còn phớt lờ bạn (2026)

Best Practices cho CLAUDE.md: 9 Quy Tắc Khiến Claude Không Còn Phớt Lờ Bạn (2026)

Hầu hết các bài viết về best practices cho CLAUDE.md đều đưa cho bạn một mẫu có sẵn rồi coi như xong, nhưng cái file bạn viết tuần trước có lẽ đã bị bỏ qua từ lâu mà bạn chẳng hiểu vì sao. Cách khắc phục hiếm khi là "thêm nhiều quy tắc hơn." Thường thì ngược lại mới đúng. Chúng tôi đã triển khai Claude Code trên mọi dự án khách hàng gần đây, và 9 quy tắc dưới đây mới thực sự tạo ra khác biệt: hệ thống phân cấp phản ánh đúng cách Claude nạp file, một ngân sách chỉ thị không thể phá vỡ, quyết định về AGENTS.md, và sáu lý do Claude âm thầm bỏ rơi file của bạn giữa chừng phiên làm việc.

Những điểm cần nhớ

• CLAUDE.md là bộ nhớ dự án được nạp vào ngữ cảnh của Claude Code, hãy giữ nó dưới 200 dòng, nếu không các quy tắc sẽ bắt đầu bị rơi rớt.
• Các tệp được nạp theo thứ tự từ trên xuống: toàn cục, thư mục gốc dự án, thư mục con (nạp chậm), và CLAUDE.local.md (cá nhân, được gitignore).
• Hãy dùng AGENTS.md nếu bạn cũng sử dụng Cursor hoặc Copilot; tạo symlink từ CLAUDE.md đến AGENTS.md để nhắm đến cả hai.
• Nếu Claude bỏ qua tệp của bạn, thì 90% là do độ dài, sự mơ hồ, hoặc thiếu "lý do".

CLAUDE.md Thực Sự Làm Gì (Và Tại Sao Nó Quan Trọng)

Tóm lại: CLAUDE.md là một tệp markdown mà Claude Code đọc như bộ nhớ dự án khi bắt đầu mỗi phiên làm việc. Nó không phải là system prompt, hook hay skill, mà là ngữ cảnh mang tính tham vấn, giúp định hướng Claude theo các quy ước của nhóm bạn. Hãy coi nó ít giống tài liệu hơn và giống một tệp cấu hình mà người lập trình cặp AI của bạn thực sự đọc.

Rất nhiều nhóm viết CLAUDE.md như thể đó là một tệp README. Đó là sai lầm đầu tiên. README giải thích dự án cho con người, những người có thể đọc lướt và bỏ qua. Còn CLAUDE.md được Claude Code tiếp nhận trọn vẹn khi bắt đầu phiên, mỗi dòng đều tiêu tốn token và ảnh hưởng đến mức độ tuân thủ. Nó gần với một tệp cấu hình hoặc một bộ test fixture hơn là tài liệu.

Đây cũng không phải là cách duy nhất để điều hướng Claude. Hook thực thi các hành động tất định (định dạng code, chặn commit). Skill đóng gói các quy trình làm việc có thể tái sử dụng. CLAUDE.md nằm ở khoảng giữa, đóng vai trò ngữ cảnh tham vấn — Claude đánh giá nó, đôi khi ghi đè lên nó, và chắc chắn sẽ quên mất một phần nếu bạn viết quá nhiều. Sự phân biệt đó là nền tảng cho mọi thứ bên dưới, và đó là lý do CLAUDE.md chỉ là một công cụ trong thực hành rộng lớn hơn của kỹ thuật ngữ cảnh, chứ không phải một viên đạn bạc.

Quy tắc #1: Hãy coi nó như code, không phải tài liệu. Đưa nó vào version control. Review nó trong các PR. Cắt tỉa nó theo cách bạn refactor một module đang phình to. Theo hướng dẫn về CLAUDE.md của Anthropic, tệp này được nạp với cùng mức ưu tiên như bất kỳ chỉ thị hệ thống nào, điều đó có nghĩa là một quy tắc lỗi thời từ sáu tháng trước vẫn đang âm thầm định hình mọi phản hồi ngày nay.

Cách CLAUDE.md được tải: Hệ thống phân cấp 4 tầng

Tóm lại: Claude Code tải CLAUDE.md từ bốn tầng: toàn cục (~/.claude/CLAUDE.md), thư mục gốc dự án, CLAUDE.local.md cho các ghi đè cá nhân, và các tệp thư mục con chỉ tải lười khi Claude đọc các tệp bên trong thư mục đó. Các thư mục con cùng cấp không bao giờ nhìn thấy CLAUDE.md của nhau, giúp cho bộ nhớ claude code được giới hạn phạm vi chặt chẽ.

Hệ thống phân cấp này là phần bị hiểu nhầm nhiều nhất của CLAUDE.md, và cũng là nơi mà không có kết quả nào trong top 5 SERP đi sâu phân tích. Đây là những gì thực sự diễn ra bên dưới:

Có hai thuật ngữ đáng để làm rõ: tải lười và cách ly cùng cấp.

Tải lười có nghĩa là CLAUDE.md của thư mục con sẽ không đi vào ngữ cảnh của Claude cho đến khi Claude thực sự mở một tệp bên trong thư mục đó. Nếu bạn yêu cầu "sửa lỗi đăng nhập" và Claude chỉ chạm đến backend/, thì frontend/CLAUDE.md của bạn sẽ không bao giờ được tải. Điều này tốt, nó giữ cho cửa sổ ngữ cảnh sạch sẽ, nhưng nó lại gây khó cho các đội ngũ đặt những quy tắc quan trọng trong các thư mục con với kỳ vọng chúng sẽ luôn được áp dụng.

Cách ly cùng cấp là hệ quả tất yếu: frontend/CLAUDE.md và backend/CLAUDE.md không bao giờ tải lẫn nhau. Chúng chỉ chia sẻ những gì có trong thư mục gốc dự án. Vì vậy, nếu các quy tắc frontend của bạn mâu thuẫn với các quy tắc backend, điều đó hoàn toàn ổn. Nếu chúng cần chia sẻ một quy ước chung, hãy đẩy nó lên tệp ở thư mục gốc.

CLAUDE.local.md là lối thoát hiểm. Nó được tải nhưng không được commit, hoàn hảo cho những ghi đè kiểu "tôi thích pnpm nhưng cả đội đã chuẩn hóa trên npm". Vấn đề là: nó không tự động được gitignore. Bạn phải tự thêm nó vào. Quên điều đó và bạn sẽ commit các quy tắc cá nhân của mình vào repo của cả đội. Quy tắc #4: Đặt hướng dẫn vào đúng nơi Claude thực sự đọc chúng. Các quy tắc về style cho component React nên nằm trong frontend/CLAUDE.md, chứ không phải ở thư mục gốc. Các quy tắc về migration cơ sở dữ liệu nên nằm trong backend/. Tài liệu Anthropic Memory (cập nhật tháng 11 năm 2025) xác nhận điều này, hành vi lazy-load là có chủ đích và đóng vai trò then chốt.

Những gì nên đưa vào CLAUDE.md (Và những gì nên bỏ qua)

Tóm lại: Bên trong CLAUDE.md nên chứa bất cứ điều gì mà Claude không thể suy luận được từ code của bạn: các lệnh build, quy ước đặt tên, những anti-pattern mà team bạn từng phải trả giá, và lý do đằng sau mỗi quy tắc. Nên loại bỏ bất cứ thứ gì đã có trong README, bất cứ thứ gì trong package.json, và bất kỳ quy tắc nào thay đổi hàng tuần. Các hướng dẫn claude code cần phải cụ thể và có thể kiểm thử được.

Dưới đây là một CLAUDE.md tối giản nhưng thực sự phát huy tác dụng:

# Dự án: techsy-app
## Lệnh
- Build: `pnpm build` (Turbopack — các cờ Webpack không có tác dụng)
- Test: `pnpm test --run` (chúng tôi dùng Vitest, không phải Jest)
- Lint: `pnpm lint` (CI sẽ fail nếu có cảnh báo, chứ không chỉ lỗi)
## Quy ước
- Mặc định dùng server components. Chỉ thêm `'use client'` khi thực sự cần thiết.
  Lý do: quý trước chúng ta đã bị LCP 8 giây do dùng quá nhiều client components.
- Chỉ truy cập database qua các helper trong `lib/db/` — không bao giờ viết SQL thô trong các route.
  Lý do: các chính sách bảo mật cấp dòng (row-level security) được đặt trong các helper đó.
- Các test được đặt cạnh file được test dưới dạng `*.test.ts`.
## Những điều không nên
- Không thêm dependency mới mà chưa mở bình luận PR trước.
- Không dùng `any` — hãy dùng `unknown` và thu hẹp kiểu.
## Tìm ở đâu
- Schema: `db/schema.ts`
- Luồng xác thực: `lib/auth/README.md`

Now compare that to the anti-pattern version most teams ship:

# Quy tắc dự án

- Viết mã nguồn sạch, dễ bảo trì.
- Tuân thủ các phương pháp tốt nhất.
- Sử dụng TypeScript đúng cách.
- Đảm bảo các bài kiểm tra đều đạt.
- Nhất quán với các mẫu hiện có.
- Ghi tài liệu cho các logic phức tạp.

Tệp thứ hai không sai. Nó chỉ vô dụng. Claude vốn đã muốn viết mã sạch. "Hãy nhất quán" không cho Claude biết phải nhất quán với mẫu nào. Các ví dụ công khai của kỹ sư Boris Cherny tại Anthropic nghiêng hẳn về phong cách đầu tiên: những lệnh cụ thể, công cụ được đặt tên rõ ràng, và lý do đằng sau các quyết định mà chỉ nhìn mã nguồn thì không thể nhận ra.

Quy tắc #2: Hãy cụ thể, đừng viển vông. "Viết mã sạch" là lời hô hào viển vông. "Mặc định dùng server components; chỉ thêm 'use client' khi thực sự cần thiết" thì có thể kiểm chứng được. Cùng một nguyên tắc ấy cũng là nền tảng của kỹ thuật viết prompt tốt: các chỉ dẫn cụ thể, có thể kiểm chứng luôn thắng những mong muốn mơ hồ, dù chúng nằm trong một prompt hay trong tệp CLAUDE.md.

Quy tắc #3: Giải thích lý do mỗi quy tắc lại quan trọng. Phần "lý do" không phải câu chữ thừa thãi, mà là cách Claude đưa ra quyết định trong các trường hợp ngoại lệ. Một quy tắc có kèm lý do ("chúng ta từng bị LCP lên tới 8 giây do lạm dụng client-side") có thể suy rộng ra các tình huống tương tự. Một quy tắc không có lý do sẽ bị bỏ qua ngay khi bối cảnh thay đổi. Mô hình này cũng được ghi nhận trong hướng dẫn CLAUDE.md của Builder.io.

Tại Sao Claude Bỏ Qua File CLAUDE.md Của Bạn? Ngân Sách Chỉ Thị

Tóm lại: Claude không hề cố tình chống đối — nó đơn giản là hết "sự chú ý". Vượt khoảng 80 dòng, bạn sẽ thấy các quy tắc bắt đầu bị bỏ sót; vượt 200 dòng, những khối lớn bị bỏ qua hoàn toàn; vượt 500 từ quy tắc dày đặc, mức độ tuân thủ sụp đổ. Giải pháp là ngân sách chỉ thị. Hãy coi mỗi dòng là một chi phí đánh đổi lấy bộ nhớ claude code và mức độ tuân thủ từng quy tắc.

Nghiên cứu gần đây xác nhận điều mà người dùng production liên tục phát hiện ra: khả năng tuân thủ chỉ thị suy giảm phi tuyến tính theo số lượng quy tắc. Bài báo arxiv 2507.11538 về năng lực tuân thủ chỉ thị cho thấy mức độ tuân thủ trên mỗi quy tắc giảm dần khi bạn chồng thêm quy tắc mới, và phân tích của HumanLayer về CLAUDE.md trong môi trường production cũng phản ánh cùng phát hiện đó.

Nói cách khác: mỗi quy tắc bạn thêm vào khiến mọi quy tắc khác giảm nhẹ xác suất được tuân thủ. Vậy nên một file CLAUDE.md 400 dòng không hiệu quả gấp 4 lần file 100 dòng. Nó thường kém hiệu quả hơn, vì những quy tắc bạn thực sự quan tâm bị pha loãng bởi những thứ bạn viết vào một buổi thứ Sáu ba tháng trước rồi không bao giờ xóa.

Trong các file CLAUDE.md của chúng tôi, mọi thứ sau dòng 150 bắt đầu mất mức tuân thủ rõ rệt. Đến dòng 250, chúng tôi đã thấy Claude bỏ qua toàn bộ các phần. Nên chúng tôi đặt giới hạn.

wc -l CLAUDE.md

Đó là toàn bộ công cụ. Hãy chạy nó. Nếu bạn vượt 200, bạn đã vượt ngân sách. Quy tắc cứng mà chúng tôi áp dụng cho khách hàng:

Hãy coi CLAUDE.md như ngân sách 200 dòng. Mỗi dòng đều tốn chi phí tuân thủ. Hãy chi tiêu ở nơi quan trọng.

Quy tắc #1 được nhấn mạnh lại: Giữ cho ngắn gọn. Dưới 200 dòng. Dưới 500 từ quy tắc dày đặc. Nếu bạn thấy mình muốn thêm các quy tắc tự động hóa ("luôn chạy prettier sau khi chỉnh sửa"), những thứ đó có lẽ nên nằm trong Claude Code hooks thì hơn — hooks mang tính tất định và không tiêu tốn token ngân sách chỉ thị.

Nên dùng CLAUDE.md, AGENTS.md, .cursorrules hay copilot-instructions?

Tóm lại: Nếu bạn chỉ dùng Claude Code, CLAUDE.md là đủ. Nếu bạn dùng từ hai CLI agent trở lên (Codex, Cursor, Copilot, Sourcegraph), hãy chuyển sang AGENTS.md và tạo symlink từ CLAUDE.md trỏ đến AGENTS.md. AGENTS.md ra đời vào cuối năm 2025 như một chuẩn liên công cụ, hầu hết các agent hiện đại đều fallback về nó, nên chỉ cần một file duy nhất là đủ cho mọi hệ sinh thái.

Đây chính là câu hỏi số 0 mà top 5 kết quả tìm kiếm thực sự trả lời. Đây là ma trận:

Thủ thuật nhắm đến hai mục tiêu chỉ cần một dòng:

ln -s AGENTS.md CLAUDE.md

Xong. Giờ thì Claude Code, Codex và bất kỳ công cụ nào nhận diện AGENTS.md đều đọc cùng một file. Cập nhật một lần, mọi agent đều nhận được. Đặc tả AGENTS.md là mở và tối giản một cách có chủ đích, nó chỉ là markdown với các phần theo quy ước.

Có hai điểm rắc rối trong thực tế. Thứ nhất: nếu nhóm của bạn có một người dùng Cursor thành thạo, .cursorrules của Cursor tiếp cận theo hướng khác, một file duy nhất, không có phân cấp, định dạng cứng nhắc hơn. Một số nhóm giữ cả hai: AGENTS.md cho các quy tắc dùng chung, .cursorrules cho những đặc thù riêng của Cursor. Thứ hai: .github/copilot-instructions.md của Copilot không fallback về AGENTS.md, nên những nhóm dùng Copilot nhiều sẽ cần một file riêng.

Nếu bạn đang chọn một bộ agent từ đầu, bài phân tích Claude Code vs Cursor vs Copilot của chúng tôi bao quát các đánh đổi ở cấp độ sử dụng. Phiên bản ngắn gọn: hệ thống phân cấp của Claude Code mạnh nhất cho monorepo, UX của Cursor thắng thế khi làm việc đơn lẻ, còn khả năng tích hợp IDE của Copilot vẫn mượt mà nhất cho việc áp dụng dần dần.

Quy tắc #9: Dùng AGENTS.md nếu bạn chạy nhiều hơn một CLI agent. Đừng duy trì hai file nói cùng một nội dung. Hãy chọn file mà phần lớn bộ công cụ của bạn đọc, rồi symlink những file còn lại.

CLAUDE.md vs Hooks vs Skills: Tam giác quyết định

Tóm lại: CLAUDE.md = ngữ cảnh mang tính khuyến nghị. Hooks = hành động có tính xác định. Skills = các năng lực được đóng gói. Chọn sai công cụ và bạn sẽ đốt ngân sách hướng dẫn vào thứ mà một hook lẽ ra phải xử lý, hoặc viết một quy tắc trong CLAUDE.md cho thứ mà chỉ skill mới đáp ứng được. Tam giác này là cách rẻ nhất để giữ CLAUDE.md tinh gọn.

Ba công cụ, ba nhiệm vụ. Sai lầm mà chúng tôi thấy thường xuyên nhất: đặt "luôn chạy prettier sau khi chỉnh sửa" vào CLAUDE.md. Claude đọc nó. Claude đôi khi chạy prettier. Bạn thấy bực mình. Cách khắc phục là chuyển dòng đó ra khỏi CLAUDE.md và đưa vào một hook, bởi vì hook kích hoạt một cách xác định vào mọi lúc, không có khoảng trống nào cho sự du di mang tính khuyến nghị.

Nếu một quy tắc phải luôn kích hoạt, nó thuộc về hook. Nếu đó là một tùy chọn phong cách mà Claude có thể đánh giá dựa trên ngữ cảnh, nó thuộc về CLAUDE.md. Nếu đó là một quy trình nhiều bước với các tài nguyên được đóng gói (template, script, prompt), nó thuộc về skill.

Quy tắc số 8: Chọn đúng giữa CLAUDE.md, hooks và skills; đặt một hook vào CLAUDE.md là sự lãng phí ngân sách hướng dẫn phổ biến nhất. Cấu hình các hành động có tính xác định bằng Claude Code hooks và đóng gói các quy trình có thể tái sử dụng thành Claude skills. CLAUDE.md của bạn sẽ ngắn hơn, các rào chắn của bạn sẽ vững chắc hơn, và Claude sẽ ngừng "quên" những quy tắc quan trọng.

Các mẫu Monorepo: CLAUDE.md lồng nhau, @imports và .claude/rules/

Tóm lại: Trong một monorepo, hãy giữ CLAUDE.md gốc thật nhỏ gọn, chỉ chứa các con trỏ và quy ước dùng chung. Đẩy các chi tiết cụ thể vào apps/*/CLAUDE.md để mỗi cây con có quy tắc riêng theo phạm vi. Sử dụng @imports để chia sẻ các tệp quy tắc dạng mô-đun thông qua .claude/rules/. Đây chính là tiết lộ dần dần — Claude chỉ kéo từng phần khi thực sự liên quan.

Cây CLAUDE.md điển hình trong một monorepo:

.
├── CLAUDE.md                        # 30 lines — points to subdirs and shared rules
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-specific rules
│   └── api/
│       └── CLAUDE.md                # Fastify-specific rules
└── packages/
    └── shared/
        └── CLAUDE.md                # Library author rules

Cú pháp @import cho phép tệp gốc kéo vào các đoạn quy tắc dùng chung mà không cần viết lại chúng:

# CLAUDE.md gốc

Đây là một Turborepo. Xem CLAUDE.md trong các thư mục con để biết quy tắc riêng cho từng ứng dụng.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md
## Các lệnh cấp cao nhất
- `pnpm dev` chạy tất cả các ứng dụng song song
- `pnpm test` chạy tập lệnh kiểm thử của mọi workspace

Đây chính là progressive disclosure (bộc lộ dần thông tin) trong thực tế. Tệp ở gốc chỉ là một con trỏ dài 30 dòng. Mỗi tệp CLAUDE.md ở thư mục con bổ sung 50–80 dòng quy tắc tập trung. Các tệp trong .claude/rules/ chứa các khối quy ước mà nhiều thư mục con có thể kéo vào. Không có gì bị trùng lặp, không có gì bị bỏ sót, và không một tệp nào vượt quá ngân sách chỉ thị.

Quy tắc tải lười (lazy-loading) ở phần trước còn trở nên quan trọng hơn ở đây: khi Claude làm việc với apps/web/Button.tsx, nó chỉ nhìn thấy tệp ở gốc cùng với apps/web/CLAUDE.md và các tệp quy tắc được @import. Nó không nhìn thấy apps/api/CLAUDE.md. Đó chính là toàn bộ mục đích — các quy ước của backend không làm ô nhiễm ngữ cảnh của frontend, và cửa sổ ngữ cảnh của bạn vẫn luôn ở trạng thái dùng được.

Quy tắc #6: Dùng @import để giữ tệp ở gốc dưới 200 dòng. Cẩm nang Các thực hành tốt nhất dành cho Claude Code của Anthropic coi đây là mẫu hình monorepo chuẩn. Các subagent cũng kế thừa ngữ cảnh CLAUDE.md của cha — điều này đáng để biết nếu bạn đang lồng ghép các quy trình làm việc; hãy xem kỹ thuật ngữ cảnh để hiểu cách điều đó tương tác với thiết kế subagent.

6 Lý Do Claude Bỏ Qua Tệp Của Bạn (Và Cách Khắc Phục Cho Từng Trường Hợp)

Tóm lại: Khi Claude bỏ qua CLAUDE.md, gần như luôn là do một trong sáu nguyên nhân: tệp quá dài, cách diễn đạt mơ hồ, thiếu "lý do", nén ngữ cảnh, tệp cha xung đột, hoặc sai tên tệp. Mỗi nguyên nhân đều có cách khắc phục trong 60 giây. Hãy kiểm tra trong một phiên mới sau mỗi thay đổi, đó là Quy tắc số 7.

1. Tệp quá dài (>200 dòng / >500 từ)

Chạy wc -l CLAUDE.md. Nếu vượt quá 200, hãy cắt bỏ mạnh tay. Chuyển các quy tắc tự động hóa sang hooks. Chuyển các quy trình làm việc sang skills. Tách các phần dùng chung vào .claude/rules/ và nạp chúng bằng @import. Lý do phổ biến nhất khiến Claude "không còn tuân theo" các quy tắc của bạn là tệp đã trở nên quá dài theo thời gian và mức độ tuân thủ âm thầm sụp đổ.

2. Cách diễn đạt mơ hồ ("hãy viết code sạch")

Hãy thay thế mọi quy tắc mang tính kỳ vọng bằng một quy tắc cụ thể, có thể kiểm chứng được. "Hãy nhất quán" là điều vô hình đối với Claude. Còn "Mặc định sử dụng server component; chỉ thêm 'use client' cho các form hoặc UI tương tác" lại là điều mà Claude thực sự có thể áp dụng được.

3. Thiếu lý do "tại sao"

Các quy tắc mà không có lý do thì không thể áp dụng linh hoạt. Claude không thể tự suy luận khi nào nên duỗi cong quy tắc vì nó không biết quy tắc đó đang bảo vệ khỏi điều gì. Mọi quy tắc không hiển nhiên đều có một dòng giải thích: "chúng tôi dùng unknown chứ không dùng any vì quý trước đã có ba lần crash runtime do response từ API được gán kiểu là any."

4. Context compaction đã loại bỏ nó

Các phiên làm việc dài sẽ kích hoạt cơ chế nén ngữ cảnh, Claude tóm tắt phần ngữ cảnh trước đó để vừa với cửa sổ, và nội dung CLAUDE.md đôi khi bị tóm tắt đến mức không còn lại gì. Cách khắc phục: dùng /clear sau những lần tiêu tốn nhiều ngữ cảnh, hoặc khởi động lại toàn bộ phiên. Đây chính xác là vấn đề mà GitHub Issue #17530 liên tục ghi nhận.

5. Xung đột giữa các tệp CLAUDE.md cha

Tệp toàn cục ghi "dùng 4 khoảng trắng." Tệp ở thư mục gốc dự án ghi "dùng 2 khoảng trắng." Tệp ở thư mục con không ghi gì cả. Claude sẽ chọn một trong số đó, và đôi khi chọn sai. Hãy kiểm tra ~/.claude/CLAUDE.md và thư mục gốc dự án để tìm các mâu thuẫn. Quy tắc nào cụ thể hơn sẽ được ưu tiên, nhưng chỉ khi bạn nêu rõ điều đó một cách tường minh.

6. Sai vị trí tệp hoặc sai chữ hoa/thường của tên tệp

Claude.md và CLAUDE.md là hai tệp khác nhau trên Linux và macOS. claude.md và CLAUDE.md cũng vậy. Hãy xác nhận đường dẫn chính xác là ./CLAUDE.md (viết hoa toàn bộ) và xác nhận rằng Claude Code được khởi chạy từ thư mục chứa tệp này. GitHub Issue #668 chứa đầy các trường hợp tệp tồn tại nhưng Claude không thể nhìn thấy do vấn đề về đường dẫn.

Quy tắc #7: Thử nghiệm trong một phiên mới. Sau bất kỳ thay đổi nào đối với CLAUDE.md, hãy mở một phiên mới và yêu cầu Claude "tóm tắt các quy tắc trong CLAUDE.md." Nếu bản tóm tắt thiếu mất điều gì đó, thì tệp đó đang không phát huy tác dụng.

CLAUDE.md đầu tiên của bạn trong 10 phút: Khởi đầu với 5 bước

Tóm lại: Chạy /init để tạo bản nháp, cắt gọn còn 6–10 quy tắc thực sự có kèm lý do, thêm 3 lệnh mà Claude cần biết, thêm 2 anti-pattern mà nhóm của bạn từng gặp, sau đó kiểm tra trong một phiên mới bằng cách yêu cầu Claude tóm tắt tệp này. Tổng thời gian: khoảng 10 phút. Công thức 5 bước này là những gì chúng tôi áp dụng vào ngày đầu tiên của mọi repo mới.

1. Chạy /init để tạo bản nháp. Lệnh /init của Claude Code quét repo của bạn và viết một CLAUDE.md khởi đầu. Đừng dùng nguyên những gì nó viết. Kết quả của /init chỉ là điểm khởi đầu, không phải tệp hoàn chỉnh, và nói thẳng là phần lớn những gì nó tạo ra đều có thể bỏ đi.

2. Cắt gọn còn 6–10 dòng quy tắc thực sự có kèm lý do. Xóa mọi thứ chung chung. Xóa mọi thứ đã có trong README. Chỉ giữ lại những quy tắc mà Claude không thể tự suy ra từ chính mã nguồn.

3. Thêm 3 lệnh mà Claude cần biết. Build, test, lint. Ghi rõ lệnh chính xác và mọi cờ (flag) không hiển nhiên. Nếu bạn dùng Vitest chứ không phải Jest, hãy nói rõ.

4. Thêm 2 anti-pattern mà nhóm này từng gặp. Những thứ có thật. "Đừng dùng any vì chúng tôi đã gặp ba lần crash runtime" luôn tốt hơn "hãy dùng TypeScript cho đúng".

5. Mở một phiên mới và kiểm chứng. Yêu cầu Claude "tóm tắt các quy tắc trong CLAUDE.md." Nếu nó bỏ sót điều gì, nghĩa là tệp quá dài, quá mơ hồ, hoặc thiếu một "lý do." Hãy sửa và lặp lại.

Quy tắc #5: Đừng chỉ tự động tạo từ /init. /init là điểm khởi đầu, không phải tệp hoàn chỉnh. 8 phút bạn bỏ ra để cắt gọn nó mới chính là nơi tạo ra giá trị.

Câu hỏi thường gặp

Tệp CLAUDE.md là gì?

Tệp CLAUDE.md là một tệp markdown mà Claude Code đọc như bộ nhớ dự án khi bắt đầu mỗi phiên làm việc. Nó cho Claude biết các quy ước, lệnh và những mẫu cần tránh để Claude không phải đoán. Nó hoạt động ở bốn cấp độ: toàn cục, thư mục gốc dự án, thư mục con (tải lười) và tệp CLAUDE.local.md cá nhân mà bạn giữ ngoài git (gitignored).

Tệp CLAUDE.md nên dài bao nhiêu?

Dưới 200 dòng và dưới 500 từ cho các quy tắc súc tích. Vượt qua những ngưỡng đó, khả năng tuân thủ chỉ dẫn của Claude sẽ giảm sút, mỗi quy tắc bạn thêm vào sẽ khiến mọi quy tắc khác giảm đi một chút khả năng được tuân thủ. Hãy coi đó như một ngân sách cố định. Nếu bạn cần nhiều hơn, hãy chia thành các tệp CLAUDE.md ở thư mục con và sử dụng @import cho các phần dùng chung.

Tôi nên đặt CLAUDE.md ở đâu?

Tệp chính đặt ở thư mục gốc của dự án (./CLAUDE.md) và được commit. Hãy thêm các tệp CLAUDE.md ở thư mục con cho các quy tắc riêng của từng ứng dụng trong monorepo. Đặt các tùy chọn liên dự án vào ~/.claude/CLAUDE.md. Dùng CLAUDE.local.md cho các ghi đè cá nhân mà bạn không muốn commit, nhưng nhớ tự thêm nó vào gitignore.

Tại sao Claude lại bỏ qua file CLAUDE.md của tôi?

90% các trường hợp là do một trong ba nguyên nhân: file quá dài (hơn 200 dòng), các quy tắc quá mơ hồ ("hãy viết code sạch"), hoặc các quy tắc thiếu phần "lý do" để Claude có thể dựa vào đó mà áp dụng. Hãy chạy wc -l CLAUDE.md, sau đó rà soát xem các quy tắc đã đủ cụ thể chưa. Kiểm thử các thay đổi trong một phiên làm việc mới bằng cách yêu cầu Claude tóm tắt file đó.

Nên dùng CLAUDE.md hay AGENTS.md?

Nếu nhóm của bạn chỉ dùng Claude Code, hãy giữ nguyên CLAUDE.md. Nếu bạn dùng từ hai CLI agent trở lên (Codex, Cursor, Sourcegraph), hãy chuyển sang AGENTS.md và tạo symlink từ CLAUDE.md trỏ đến nó: ln -s AGENTS.md CLAUDE.md. Hầu hết các CLI agent hiện đại đều hỗ trợ fallback về AGENTS.md, nên chỉ cần một file là đủ cho mọi công cụ.

Tôi có nên chạy /init để tạo CLAUDE.md không?

Có, nếu coi đó là bản nháp. Không, nếu coi đó là file hoàn chỉnh. /init quét repo của bạn và tạo ra một bản khởi đầu, nhưng nó dài dòng và chung chung. Cả Anthropic và HumanLayer đều khuyên nên cắt gọt mạnh tay sau khi chạy /init. 8 phút bạn dành để lược bỏ và thêm các dòng giải thích "tại sao" mới là lúc file thực sự trở nên hữu ích.

Tệp CLAUDE.md hoạt động như thế nào trong monorepo?

Tệp CLAUDE.md ở thư mục gốc nên giữ thật gọn, chỉ chứa các con trỏ và quy tắc dùng chung. Mỗi ứng dụng có tệp apps/*/CLAUDE.md riêng với các quy ước được khoanh vùng. Các tệp ở thư mục con chỉ được tải khi Claude đọc tệp bên trong cây thư mục đó, nên các ứng dụng anh em vẫn hoàn toàn tách biệt. Dùng @import .claude/rules/style.md để chia sẻ các mảnh quy tắc theo mô-đun mà không phải sao chép lặp lại giữa các ứng dụng.

Sự khác biệt giữa CLAUDE.md, hooks và skills là gì?

CLAUDE.md là ngữ cảnh mang tính tham khảo, Claude sẽ đọc và thường làm theo. Hooks là các hành động tất định, luôn được thực thi (định dạng, chặn commit). Skills là các bộ khả năng được đóng gói cho quy trình làm việc có thể tái sử dụng kèm theo tài nguyên. Hãy dùng CLAUDE.md cho hướng dẫn về phong cách, hooks cho các quy tắc bắt buộc, và skills cho những công việc nhiều bước mà bạn sẽ lặp lại ở nhiều dự án.

Cách Techsy tiếp cận vấn đề này

Tại Techsy, mọi dự án Claude Code mà chúng tôi bàn giao đều có một tệp CLAUDE.md dưới 150 dòng và một symlink AGENTS.md. Chúng tôi coi tệp này như mã nguồn, quản lý phiên bản, xem xét các thay đổi trong PR, và kiểm thử lại trong các phiên làm việc mới trước khi hợp nhất. Bạn cần hỗ trợ tích hợp AI agent vào quy trình phát triển của mình? Nhận tư vấn miễn phí.