CLAUDE.md: Tối ưu hóa ngữ cảnh (context) cho Claude Code

Thay vì phải tái định nghĩa môi trường trong mỗi phiên làm việc, file Markdown này cung cấp một "bộ nhớ vĩnh viễn" (persistent memory) nằm tại gốc dự án. Claude Code tự động nạp các chỉ dẫn này ngay sau system prompt để hiểu cấu trúc, quy tắc và phong cách lập trình của bạn mà không cần giải thích lại.

Vấn đề cốt lõi của các mô hình ngôn ngữ lớn (LLM) hiện nay là tính vô trạng thái (stateless) — chúng không học thêm từ các phiên hội thoại trừ khi thông tin được nạp trực tiếp vào cửa sổ ngữ cảnh (context window). CLAUDE.md giải quyết bài toán "mất trí nhớ" này, biến Claude từ một trợ lý mới tuyển dụng thành một cộng sự cấp cao am hiểu hệ thống chỉ trong vài mili giây khởi chạy.

Tại sao các dự án chuyên nghiệp cần CLAUDE.md?

Trong quy trình làm việc thực tế, một kỹ sư thường mất kha khá thời gian mỗi sáng để tái thiết lập ngữ cảnh cho AI. CLAUDE.md triệt tiêu khoản phí này bằng cách đóng vai tài liệu tóm tắt (briefing document) cho một đồng nghiệp đang bị mất trí nhớ tạm thời.

Lợi ích về mặt kỹ thuật bao gồm:

• Tối ưu token: không lãng phí token để nhắc lại các lệnh build/test cơ bản.
• Nhất quán kiến trúc: ngăn AI tự ý dùng npm khi dự án chạy pnpm, hoặc dùng default exports khi quy chuẩn là named exports.
• Giảm sai sót hệ thống: cung cấp các rào chắn (guardrail) về bảo mật và tuân thủ (compliance) ngay từ đầu phiên làm việc.

Cơ chế xếp chồng (stacking) và thứ tự ưu tiên

Claude Code nạp các file chỉ dẫn theo thứ tự từ gốc hệ thống tệp (filesystem root) xuống thư mục làm việc hiện hành. Dữ liệu được nối tiếp (concatenated) thay vì ghi đè hoàn toàn:

1. Managed Policy: chính sách doanh nghiệp (ví dụ /etc/claude-code/CLAUDE.md). Không thể bị loại trừ bởi người dùng.
2. User Instructions: cấu hình cá nhân cho mọi dự án (~/.claude/CLAUDE.md).
3. Project Instructions: file tại gốc dự án (./CLAUDE.md hoặc ./.claude/CLAUDE.md). Thường được commit lên Git.
4. Local Instructions: ghi chú cá nhân, sandbox URL (./CLAUDE.local.md). Nên đưa vào .gitignore.

Lưu ý cho monorepo: trong các dự án lớn, bạn có thể dùng cấu hình claudeMdExcludes trong .claude/settings.local.json để loại bỏ các file CLAUDE.md không liên quan từ những team khác, tránh làm loãng ngữ cảnh.

Khởi tạo và cấu trúc nội dung chuẩn

Dùng lệnh /init (hoặc đặt CLAUDE_CODE_NEW_INIT=1) để Claude quét codebase và tự động đề xuất file mẫu. Sau khi khởi tạo, hãy lược bỏ các thông tin hiển nhiên (như "đây là dự án JS") để dành "không gian suy nghĩ" (thinking room) cho AI.

Một file CLAUDE.md hiệu quả cần tập trung vào bốn trụ cột:

• Project Context: mô tả súc tích mục đích dự án (1–2 dòng).
• Commands: các chuỗi lệnh chính xác (build, test, lint, deploy). Claude sẽ dùng các lệnh này một cách nguyên bản.
• Code Style: quy tắc cụ thể (ví dụ 2-space indentation, functional components).
• Architecture Decisions: cách tổ chức file, các pattern chính (ví dụ Repository pattern, Clean Architecture).

Ví dụ CLAUDE.md cho dự án Next.js

# Project Context
 
Next.js 15 app sử dụng App Router và Tailwind CSS.
 
# Commands
 
- Build: `pnpm run build`
- Test: `pnpm test`
- Lint: `pnpm run lint -- --fix`
 
# Code Style
 
- Sử dụng 2-space indentation.
- Ưu tiên `named exports` thay vì `default exports`.
- Sử dụng Server Actions thay cho API routes khi có thể.
 
# Architecture
 
- API routes nằm trong `app/api/`.
- Component dùng Tailwind để styling.
 
@./docs/testing-standards.md

Nguyên tắc viết chỉ dẫn: càng ít càng tốt

System prompt của Claude Code đã chiếm khoảng 50 chỉ dẫn. Với giới hạn an toàn 150–200 chỉ dẫn, bạn chỉ còn khoảng 100–150 "slot" cho CLAUDE.md. Khi vượt ngưỡng này, AI sẽ gặp hiện tượng suy giảm đồng loạt (Uniform Decay) — chất lượng tuân thủ cả quy tắc cũ lẫn mới đều giảm sút đồng loạt.

4 dòng quy tắc hành vi của Karpathy

Bốn nguyên tắc của Karpathy là nền tảng giúp AI quản lý sự mơ hồ và tăng độ chính xác:

1. Don't assume: không giả định. Nêu bật các đánh đổi (trade-off) và hỏi lại khi không rõ.
2. Minimum code: viết code tối giản. Không viết code dự phòng hay trừu tượng hóa sớm.
3. Surgical changes: thay đổi chính xác. Chỉ chạm vào những gì cần thiết để giữ diff sạch.
4. Define success criteria: xác định tiêu chí thành công. Đây là đòn bẩy để AI tự lặp lại cho đến khi xác minh đạt mục tiêu.

Kỹ thuật nâng cao: imports và quy tắc theo đường dẫn (path-specific rules)

Khi dự án lớn dần, nhồi mọi quy tắc vào một file CLAUDE.md duy nhất sẽ khiến file phình to, chiếm chỗ cửa sổ ngữ cảnh và làm loãng sự chú ý của AI — đúng vấn đề đã nói ở phần "càng ít càng tốt" bên trên. Cách xử lý là tiết lộ dần dần (progressive disclosure): tách nội dung ra nhiều file nhỏ và chỉ nạp phần cần thiết, thay vì đưa tất cả vào cùng lúc. Có hai kỹ thuật chính, và nên giữ file chính dưới 300 dòng:

• @Imports — tách file chính thành các module nhỏ. Thay vì viết mọi thứ trong một file, bạn đưa từng nhóm quy tắc ra một file riêng rồi "gọi" nó vào file chính bằng cú pháp @path/to/file, nhờ vậy file chính luôn ngắn gọn và dễ bảo trì. Hệ thống còn hỗ trợ nạp đệ quy (recursive imports) — file được gọi vào lại có thể gọi tiếp file khác — lên tới bốn cấp. Ví dụ: @./docs/api-conventions.md.
• Path-scoped Rules — quy tắc chỉ bật khi đúng chỗ. Bạn tạo các file trong thư mục .claude/rules/ với YAML frontmatter khai báo paths; các quy tắc đó chỉ kích hoạt khi Claude làm việc với file khớp đường dẫn đã khai báo. Nhờ vậy, quy tắc dành riêng cho API không chiếm chỗ trong ngữ cảnh khi bạn đang sửa phần giao diện, và ngược lại.

Ví dụ một file path-scoped rule chỉ áp dụng cho các file API trong src/api/:

---
paths: ["src/api/**/*.ts"]
---
 
# API Rules
 
- Luôn dùng Zod để validate input.

Tóm lại, cả hai kỹ thuật cùng phục vụ một mục tiêu: để AI chỉ thấy đúng thông tin cần cho việc đang làm, giữ cửa sổ ngữ cảnh sạch và tập trung.

Xử lý khi Claude bỏ qua CLAUDE.md

Về mặt kỹ thuật, CLAUDE.md được chèn vào dưới dạng một tin nhắn người dùng (user message) ngay sau system prompt. Anthropic chèn thêm thẻ <system_reminder> thông báo rằng các chỉ dẫn này "có thể hoặc không liên quan", dẫn đến việc AI đôi khi bỏ qua chúng.

Giải pháp khắc phục:

1. Thẻ điều kiện (conditional tag): đặt chỉ dẫn vào giữa một cặp thẻ mở và đóng có kèm điều kiện. Ví dụ, để một quy tắc chỉ áp dụng khi đang viết test, bạn viết trong CLAUDE.md như sau:

   markdown

   <important if="writing tests">
   Luôn dùng React Testing Library, không dùng Enzyme.
   </important>

   Phần if="writing tests" cho Claude biết quy tắc nằm giữa hai thẻ chỉ thực sự quan trọng khi bạn đang viết test — nhờ đó nó nổi bật đúng lúc cần, thay vì bị coi là "có thể không liên quan" như mặc định. Đây là cách gửi tín hiệu mạnh và đúng thời điểm hơn so với một dòng quy tắc thông thường.

2. Dùng /memory: chạy lệnh này để kiểm tra file đã được nạp thành công vào phiên làm việc hay chưa.

3. Tránh xung đột: kiểm tra xem các quy tắc ở cấp User có đang mâu thuẫn với cấp Project hay không.

So sánh CLAUDE.md, Auto memory và AGENTS.md

Đừng nhầm lẫn giữa chỉ dẫn do người viết với mẫu hành vi do máy tự học.

Lời khuyên: dùng AGENTS.md cho các quy chuẩn chung của team để tương thích với những công cụ khác (Cursor, Copilot). Trong CLAUDE.md, hãy dùng @AGENTS.md để kế thừa rồi thêm các tính năng riêng của Claude Code như custom skills.

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

Có nên commit CLAUDE.md lên Git không? Nên. Đây là cách tốt nhất để đồng bộ quy trình làm việc với AI cho cả team. Chỉ loại trừ CLAUDE.local.md.

Tại sao file quá dài lại gây hại? Nó chiếm dụng cửa sổ ngữ cảnh và làm giảm không gian suy nghĩ, khiến Claude dễ mắc lỗi logic và giảm khả năng sáng tạo do bị bó buộc bởi quá nhiều luật.

Làm sao để AI tự cập nhật CLAUDE.md? Cuối phiên làm việc, hãy ra lệnh: "Tóm tắt các bài học quan trọng và cập nhật vào CLAUDE.md". AI sẽ tự đề xuất các thay đổi dựa trên hội thoại.

Tài liệu tham khảo

• The 4 Lines Every CLAUDE.md Needs — Level Up Coding
• Claude Code for Everything: The Best Personal Assistant Remembers Everything About You — Hannah Stulberg
• How Claude Remembers Your Project — Claude Code Docs
• Writing a Good CLAUDE.md — HumanLayer
• Stop Claude From Ignoring Your CLAUDE.md — HumanLayer
• How to Use CLAUDE.md in Claude Code in 5 Minutes — YouTube
• CLAUDE.md in Claude Code (Walkthrough) — YouTube
• The Complete Guide to AI Agent Memory Files: CLAUDE.md, AGENTS.md, and Beyond — Data Science Collective