CLAUDE.md Là Gì? Cách Viết File Chỉ Dẫn Cho Claude Code (2026)

73% team kỹ thuật dùng AI coding tools hàng ngày, tăng từ 41% năm 2025 (Pragmatic Engineer Survey, 2026). Nhưng bao nhiêu người thực sự config để AI hiểu đúng project, quy tắc, và workflow của mình?

Nếu bạn đang dùng Claude Code là gì, câu trả lời nằm ở hai thứ: file CLAUDE.md và thư mục .claude/. Hai thứ này cùng nhau tạo nên toàn bộ hệ thống cấu hình của Claude Code, từ project instructions đến permissions, từ auto memory đến custom skills.

Bài này là hướng dẫn đầy đủ nhất về cả hai. Mình sẽ đi qua từng phần: CLAUDE.md là gì, thư mục .claude/ có gì, cấu hình settings.json ra sao, và cách kết hợp để làm việc hiệu quả nhất.

CLAUDE.md is a markdown file that Claude Code automatically reads at the start of every session, containing project instructions, coding conventions, and workflow rules. The .claude/ directory extends this with settings, path-specific rules, custom commands, and skills.

CLAUDE.md Là Gì?

CLAUDE.md là file markdown đặt ở root project, được Claude Code tự động đọc mỗi khi bạn bắt đầu phiên làm việc. Claude Code đang có hơn 110.000 GitHub stars (GitHub, 2026), và file chỉ dẫn này là cách bạn “dạy” nó hiểu codebase của mình mà không cần giải thích lại mỗi phiên.

Nghĩ đơn giản thế này: CLAUDE.md giống như bản mô tả công việc cho nhân viên mới. Tech stack, conventions, lệnh build, những điều cần tránh. Tất cả chỉ cần viết một lần, Claude Code sẽ nhớ mãi.

Vị trí và cách hoạt động

Bạn đặt file CLAUDE.md ở thư mục root của project, cùng cấp với .git/ hoặc package.json. Mỗi khi chạy claude trong terminal, file này được đọc tự động. Không cần cấu hình thêm, không cần plugin.

Ngoài vị trí mặc định, bạn còn có thể đặt ở .claude/CLAUDE.md nếu muốn tách biệt khỏi root. Cả hai vị trí đều được Claude Code nhận diện. Chỉ cần chọn một cách nhất quán.

So sánh với các AI coding tools khác

CLAUDE.md không phải khái niệm hoàn toàn mới. Các tools khác cũng có cơ chế tương tự, nhưng Claude Code hỗ trợ multi-level hierarchy và path-specific rules, hai thứ các tool khác chưa có.

Cấu Trúc Thư Mục .claude/ Đầy Đủ Cho Dev

CLAUDE.md chỉ là một phần của thư mục .claude/. Thư mục này còn chứa settings.json (quyền + hooks), cùng skills/, agents/, hooks/, rules/, output-styles/, workflows/ và .mcp.json ở gốc project. Mỗi thứ có phạm vi project (commit cho team) và global (~/.claude/, cá nhân) riêng.

Bài này tập trung vào CLAUDE.md. Toàn bộ cấu trúc .claude/, ý nghĩa từng phần và bản đồ trỏ xuống bài chuyên sâu nằm ở bài hub: cấu hình Claude Code và thư mục .claude.

settings.json: Cấu Hình Quyền & Tự Động Hóa

File .claude/settings.json quyết định Claude được phép làm gì mà không cần hỏi. Quan trọng nhất là khối permissions với ba danh sách allow / deny / ask (ví dụ deny đọc .env). Ngoài ra còn hooks, env, model; bản cá nhân không commit để ở settings.local.json.

Phần đào sâu settings.json nằm ở bài cấu hình Claude Code; cách chặn cứng bằng quyền và các permission mode xem permission modes của Claude Code.

Thứ Tự Ưu Tiên Settings Hoạt Động Thế Nào?

Claude Code áp dụng settings theo thứ tự ưu tiên từ cao xuống thấp qua 5 tầng. Tầng ưu tiên cao hơn sẽ override tầng thấp hơn (riêng permissions thì gộp). Theo tài liệu chính thức, cơ chế này cho phép tổ chức đặt policy bắt buộc ở tầng cao nhất mà developer không thể override.

Managed Policy dùng khi nào?

Managed Policy là scope dành cho enterprise và tổ chức. IT admin cài đặt ở cấp hệ thống, developer không thể override. Dùng khi bạn cần enforce security rules bắt buộc, ví dụ: “không bao giờ được phép đọc file *.pem” hoặc “không được push thẳng lên production branch.”

Với cá nhân và team nhỏ, bạn có thể bỏ qua scope này. Tập trung vào Project Shared (.claude/settings.json) và User Global (~/.claude/settings.json).

Thứ tự load CLAUDE.md

Tương tự settings, CLAUDE.md cũng có thứ tự load riêng. Claude Code đọc từ trên xuống dưới, nội dung đọc sau có thể override nội dung đọc trước:

1. Managed Policy CLAUDE.md (toàn tổ chức, bắt buộc)
2. CLAUDE.md từ các thư mục cha (đi từ thư mục hiện tại lên root)
3. Project root CLAUDE.md hoặc .claude/CLAUDE.md
4. CLAUDE.local.md (personal, gitignored)
5. ~/.claude/CLAUDE.md (user global)
6. Subdirectory CLAUDE.md (load on-demand khi Claude đọc file trong thư mục đó)

Cách Viết CLAUDE.md Hiệu Quả?

Một CLAUDE.md tốt gồm 5 phần chính, giữ dưới 200 dòng theo khuyến nghị của tài liệu chính thức Anthropic. Theo blog kỹ thuật của Anthropic, các team viết file chỉ dẫn rõ ràng thấy Claude Code thực hiện đúng yêu cầu từ lần đầu, giảm rõ rệt số vòng chỉnh sửa.

Năm phần cần có:

• Project overview: 2-3 câu mô tả project là gì, mục tiêu chính.
• Tech stack và architecture: Liệt kê công nghệ, kiến trúc tổng thể.
• Commands: Lệnh build, test, lint, deploy. Claude Code sẽ dùng chính xác những lệnh này.
• Code conventions: Naming, file structure, import order, error handling.
• Gotchas: Những lỗi thường gặp, giới hạn kỹ thuật, điều cần tránh.

Template thực tế – Next.js project

# Project Overview
E-commerce platform. Next.js 14 + App Router. Vietnamese market.

## Tech Stack
- Next.js 14 (App Router, Server Components by default)
- TypeScript strict
- Tailwind CSS + shadcn/ui
- Supabase (auth + database)
- Vercel (deployment)

## Commands
```
npm run dev          # Dev server port 3000
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Vitest
npm run db:migrate   # Supabase migrations
```

## Code Conventions
- Named exports only (no default exports)
- File naming: kebab-case
- Server Components by default; "use client" only when needed
- Error handling: Result pattern, never throw in lib/

## Gotchas
- Supabase RLS enabled, test với anon key
- Always use next/image, never raw <img>
- Vietnamese text: Unicode NFC normalization required

@import – Tách file khi cần

Khi file vượt quá 200 dòng, tách thành nhiều file và import chúng bằng cú pháp @path/to/file. Claude Code sẽ expand file được import vào context. Hỗ trợ tối đa 4 hops (import trong import trong import…) và đường dẫn khá tính từ file đang import.

# Project Overview
E-commerce platform. Next.js 14. Vietnamese market.

@docs/coding-standards.md
@docs/api-conventions.md
@docs/deployment-guide.md

Kỹ thuật này giúp giữ file chính ngắn gọn. Đặt nội dung theo chủ đề vào các file riêng, dễ maintain hơn khi cần cập nhật. Mình dùng cách này cho dự án ongboit.com, tách directives thành nhiều file .md nhỏ.

Best practices mình đúc kết được

Sau hàng trăm giờ dùng CLAUDE.md, mình nhận ra: phần Gotchas mang lại giá trị cao nhất. Đây là những lỗi bạn đã gặp và không muốn Claude lặp lại. Viết cụ thể: “Không dùng npm install --legacy-peer-deps vì lý do X” tốt hơn nhiều so với “Cẩn thận với npm install.”

Một rule quan trọng khác: HTML comments trong CLAUDE.md bị strip trước khi inject vào context. Bạn có thể dùng comments để note cho người đọc file mà không làm “bẩn” context của Claude.

Template CLAUDE.md mẫu (copy về dùng ngay)

Đây là CLAUDE.md thực tế mình dùng cho project ongboit.com. Không phải template lý thuyết, đây là file đang chạy production hàng ngày. Copy về, chỉnh lại Architecture và Commands cho project của bạn.

# CLAUDE.md

> You are the **orchestration layer**: intelligent glue between
> human intent (directives) and deterministic execution (scripts).

## Architecture

directives/*.md   → SOPs: the "what"
You (Claude)      → Parse intent, plan, call tools: the "how"
execution/*.py    → Deterministic scripts: the "do"

## Project Structure

project/
├── directives/          # SOPs in Markdown
├── execution/           # Deterministic scripts
│   ├── data/
│   ├── integrations/
│   └── utils/
├── mcp_servers/         # MCP server implementations
├── tests/
├── .tmp/                # Intermediate files (gitignored)
└── CLAUDE.md

## Commands

python -m pytest tests/              # Run all tests
python execution/main.py             # Run main entry point

## Decision Flow

1. Directive exists? → Follow it.
2. No directive? → Ask before creating one.
3. Existing tool? → Use it.
4. No tool? → Create minimal new tool.
5. Error? → Diagnose, fix, test, update directive.

## Key Principles

- Check for tools first before writing new code
- Self-anneal when things break
- Update directives as you learn
- Fail fast, recover gracefully
- Simple beats clever

## Human-in-the-Loop

Require approval: financial, data deletion, external comms
Auto-approve: read-only, internal tools, formatting

.claude/rules/ Dùng Khi Nào?

Thư mục .claude/rules/ cho phép tạo rules theo path pattern, chỉ load khi Claude làm việc với file phù hợp. Đây là cách hiệu quả nhất để quản lý rules trong project lớn, vì Claude không phải load mọi rules mọi lúc. Rules không có path sẽ load vô điều kiện khi khởi động.

Cú pháp YAML frontmatter

Mỗi file trong .claude/rules/ là một markdown file với YAML frontmatter ở đầu. Frontmatter định nghĩa rule áp dụng cho paths nào. Claude Code đọc frontmatter và chỉ inject rule vào context khi bạn đang làm việc với file phù hợp.

---
description: Rules cho React components
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

- Functional components only, no class components
- Props interface phải được export
- Mỗi component file cần có .test.tsx tương ứng
- Dùng Tailwind CSS, không inline styles
- Không import trực tiếp từ node_modules, dùng aliased paths

---
description: Rules cho test files
paths:
  - "tests/**/*"
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

- Dùng describe/it pattern
- Mỗi test file test một module duy nhất
- Mock external dependencies, không call API thật
- Coverage tối thiểu 80% cho code mới

Rules không có paths

Nếu bạn không khai báo paths trong frontmatter, rule đó được load mọi lúc khi Claude Code khởi động. Dùng cho các quy tắc chung như “luôn dùng tiếng Việt trong comments” hoặc “không bao giờ commit credentials.”

Symlinks để chia sẻ rules

Một tính năng ít được biết đến: .claude/rules/ hỗ trợ symlinks. Nếu bạn có monorepo với nhiều packages, bạn có thể tạo rules ở một chỗ và symlink vào các packages khác. Giúp DRY hoàn toàn cho rules management. Đây là cách mình muốn thử khi mở rộng dự án ongboit.com.

Loại Trừ Files Khỏi Context Thế Nào?

Claude Code không có file .claudeignore riêng. Thay vào đó, có 3 cơ chế loại trừ files khỏi context để tiết kiệm token:

1. .gitignore (mặc định)

Claude Code tự động respect .gitignore khi dùng @ file picker. Setting respectGitignore mặc định là true. Các files như node_modules/, .env, dist/ tự động bị loại khỏi autocomplete.

2. permissions.deny trong settings.json

Đây là cách mạnh nhất để block Claude Code truy cập files nhạy cảm. Không chỉ ẩn khỏi picker mà còn deny read/write hoàn toàn:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./*.pem)",
      "Bash(rm -rf *)"
    ]
  }
}

3. claudeMdExcludes

Dùng khi bạn muốn Claude Code bỏ qua CLAUDE.md files từ thư mục khác (phổ biến trong monorepo):

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "**/legacy/.claude/rules/**"
  ]
}

Custom Commands Và Skills: Vị Trí Lưu Trữ Chuẩn

Skill là hướng đi mới (đặt ở .claude/skills/ hoặc ~/.claude/skills/); commands (.claude/commands/) là cách cũ, và nếu skill trùng tên command thì skill thắng. Nếu bắt đầu mới, dùng skill.

Đọc sâu: Claude Code Skills, cách tự tạo skill cho workflow, và slash commands.

Auto Memory Hoạt Động Thế Nào?

Auto memory là ghi chú Claude tự lưu xuyên phiên ở ~/.claude/projects/<project>/memory/; 200 dòng đầu (hoặc 25KB) của MEMORY.md được nạp mỗi phiên, topic file nạp khi cần. Bật mặc định, tắt qua /memory hoặc autoMemoryEnabled:false.

Chi tiết đầy đủ về auto memory ở bài auto memory của Claude Code.

Lệnh /init Và /memory Làm Gì?

Hai lệnh này là điểm khởi đầu quan trọng nhất khi setup Claude Code cho project mới. /init phân tích codebase và tạo CLAUDE.md tự động. /memory cho phép bạn duyệt và quản lý auto memory. Theo Builder.io, /init là cách nhanh nhất để bắt đầu với dự án đã có sẵn code.

Dùng /init như thế nào?

1. 1 Mở terminal trong thư mục root của project.
2. 2 Chạy claude để khởi động Claude Code.
3. 3 Gõ /init và nhấn Enter.
4. 4 Claude phân tích package.json, pyproject.toml, Dockerfile, cấu trúc thư mục, rồi tạo CLAUDE.md.
5. 5 Review file được tạo, bổ sung phần Gotchas và team conventions.

Những gì /init không tự biết

/init tạo file cơ bản khá tốt. Nó nhận diện tech stack và cấu trúc thư mục rất nhanh. Nhưng có một số thứ nó không thể biết, bạn phải bổ sung thủ công:

• Naming conventions riêng của team
• Gotchas và lỗi đã gặp trong quá khứ
• Architecture decisions và lý do đằng sau
• Workflow riêng (“luôn tạo PR, không push thẳng main”)
• Thông tin business domain cụ thể

Mình thường dùng /init như điểm khởi đầu, rồi bổ sung thêm 30-50% nội dung từ kinh nghiệm thực tế. Phần Gotchas thường bị bỏ qua nhưng lại có giá trị cao nhất.

/memory – Duyệt và chỉnh sửa auto memory

Lệnh /memory mở giao diện để bạn xem toàn bộ notes trong auto memory của project hiện tại. Bạn có thể xem, chỉnh sửa, hoặc xóa từng note. Nếu Claude đã nhớ thứ gì đó sai, đây là nơi để sửa.

Đọc thêm về các slash commands quan trọng khác và cách kết hợp chúng trong workflow hàng ngày.

Câu Hỏi Thường Gặp

Gợi ý: Bộ nguyên tắc hành vi trong một CLAUDE.md tốt (nghĩ trước khi code, giữ tối giản, sửa đúng phạm vi, chạy tới khi đạt mục tiêu) lấy cảm hứng từ repo andrej-karpathy-skills của Andrej Karpathy. Đọc repo này để hiểu vì sao nên viết CLAUDE.md theo hướng đó.

Kết Luận

Hệ thống cấu hình của Claude Code gồm nhiều lớp, mỗi lớp phục vụ một mục đích khác nhau. Nhưng đừng để bị overwhelm. Hầu hết developer chỉ cần ba thứ để bắt đầu tốt:

1. CLAUDE.md ở root project: 5 phần chính, dưới 200 dòng, viết cụ thể bằng imperative. Dùng /init để tạo bản đầu, customize phần Gotchas sau.
2. .claude/settings.json: Tối thiểu cần cấu hình section permissions để Claude Code biết được phép làm gì và không được làm gì.
3. Auto memory bật mặc định: Để nó chạy, dùng /memory định kỳ để dọn dẹp notes cũ.

Khi project lớn hơn, thêm .claude/rules/ cho path-specific rules, và .claude/skills/ cho workflow automation. Nhưng bắt đầu đơn giản, rồi mở rộng dần khi thấy cần.

Nếu bạn chưa biết Claude Code là gì, đọc bài giới thiệu trước. Nếu bạn đã dùng Claude Code và muốn tiết kiệm token, xem bài về tối ưu token Claude Code. Còn nếu bạn muốn xây dựng workflow automation phức tạp hơn, roadmap Claude Code sẽ chỉ ra hướng tiếp theo.