Cách cấu hình Claude Code với CLAUDE.md: Hướng dẫn đầy đủ

Bạn clone một repository, khởi động Claude Code, và nó phớt lờ mọi quy ước mà team bạn đã thống nhất. Không tuân theo chuẩn đặt tên. Không theo mẫu test nào. Xử lý lỗi sai lung tung. Đồng nghiệp bạn thề rằng nó chạy hoàn hảo trên máy của họ.

Thủ phạm gần như luôn là một thứ: cấu hình đặt sai chỗ. Claude Code đọc file CLAUDE.md từ ba tầng khác nhau, và việc nhầm lẫn giữa các tầng này là lỗi cấu hình sai phổ biến nhất mà người dùng gặp phải. Bài thi khai thác điểm này rất mạnh.

Hệ thống phân cấp CLAUDE.md ba tầng

Ba tầng. Mỗi tầng có phạm vi khác nhau.

Tầng User nằm trong thư mục home của bạn. Không được quản lý bởi version control. Một thành viên mới clone repository và họ không bao giờ thấy nó. Khoảng trống đó gây ra nhiều phiên debug hơn bất kỳ ai muốn thừa nhận.

Tầng Project nằm ngay trong repository, hoặc ở .claude/CLAUDE.md hoặc dưới dạng CLAUDE.md ở gốc repo. Cả hai đều hoạt động. Cả hai đều đi cùng git. Clone repo là bạn có ngay các hướng dẫn — không cần thiết lập gì thêm.

File tầng Directory chỉ có phạm vi trong chính thư mục của nó, không hơn. Đặt một file /packages/api/CLAUDE.md chứa đầy quy ước REST vào package API, các rule đó sẽ kích hoạt khi bạn làm việc ở đó. Chuyển sang các component frontend cách đó hai thư mục? Biến mất. Vô hình.

Cái bẫy "thành viên mới của team"

Bạn sẽ gặp dạng câu hỏi này trên gần như mọi đề thi thử. Lập trình viên A đã ở trong team nhiều tháng — Claude Code tuân theo mọi quy ước hoàn hảo. Lập trình viên B gia nhập, clone repo, và kết quả đầu ra lộn xộn hết cả lên.

Lập trình viên A lưu quy ước trong ~/.claude/CLAUDE.md (tầng User) thay vì .claude/CLAUDE.md (tầng Project). Đó luôn là đáp án đúng. Chuyển hướng dẫn sang tầng Project và vấn đề biến mất. Trong bài thi, "thành viên mới của team" cộng với "hành vi không nhất quán" chính là dấu hiệu để bạn kiểm tra phạm vi cấu hình.

Tổ chức module hóa với import đường dẫn @

Qua vài chục dòng, một file CLAUDE.md duy nhất trở thành cơn đau đầu trong bảo trì. Cú pháp import @ chia nhỏ nó ra — và không hề có từ khóa @import, chỉ là @ theo sau bởi một đường dẫn nằm trên dòng riêng của nó:

markdownCopy

# .claude/CLAUDE.md
 
Coding standards:
 
@./standards/naming-conventions.md
@./standards/error-handling.md
@./standards/testing-requirements.md

Mỗi package chỉ import những gì áp dụng cho nó. Package API nhận quy ước API. Package frontend nhận quy ước component. Không trùng lặp, không lệch pha giữa các file nguồn.

Một cái bẫy đáng lưu ý: import nạp ngay lập tức (eagerly). Khi Claude nạp CLAUDE.md của bạn, mọi file được import đều được chèn thẳng vào ngay lúc đó, y như thể bạn đã dán nội dung vào file chính. Chia một file CLAUDE.md 500 dòng thành năm import 100 dòng giúp file nguồn dễ bảo trì hơn, nhưng context được nạp vẫn có kích thước như cũ. Nếu mục tiêu của bạn là thu nhỏ context cho mỗi phiên làm việc, bạn cần rules theo đường dẫn trong .claude/rules/ (phần tiếp theo), không phải import.

Rules theo đường dẫn trong .claude/rules/

Cả CLAUDE.md ở gốc lẫn file tầng Directory đều không xử lý tốt một tình huống: quy ước gắn với một loại file cụ thể nhưng rải rác khắp hàng chục thư mục. File test nằm cạnh file nguồn là ví dụ kinh điển — và thực sự là một nỗi đau nếu không có tính năng này.

Thư mục .claude/rules/ giải quyết vấn đề này bằng các file rule theo chủ đề với YAML frontmatter để xác định phạm vi đường dẫn:

yamlCopy

# .claude/rules/testing.md
---
paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
---
# Test Conventions
 
- Use describe/it blocks with descriptive sentence-style names
- Each test must cover at least one happy path and one error case
- Use factory functions for test data, not inline literals
- Mock external services at the module boundary

Sửa một file khớp với **/*.test.ts và các rule này tự động nạp. Sửa một React component thì chúng không can thiệp gì. Một file, áp dụng cho mọi thư mục test trong codebase.

Tại sao không nhét quy ước test thẳng vào CLAUDE.md ở gốc? Vì file đó nạp cho mọi phiên làm việc bất kể bạn đang làm gì. Các rule Terraform của bạn ngốn token trong khi bạn đang viết component React. Rules theo đường dẫn chỉ kích hoạt khi liên quan — tốt hơn cho ngân sách token, tốt hơn cho tỷ lệ tín hiệu trên nhiễu.

Khi nào dùng cách tiếp cận nào

Hook: tự động hóa hành vi xung quanh lệnh gọi tool

Hook là các lệnh shell được kích hoạt để phản ứng lại các sự kiện của Claude Code. Chúng nằm trong settings.json — không phải CLAUDE.md, điều này khiến nhiều người nhầm lẫn — và kích hoạt tại các điểm cụ thể trong vòng đời:

• PreToolUse — chạy trước khi một tool thực thi. Cổng xác thực, ghi log, chặn các thao tác nguy hiểm.
• PostToolUse — chạy sau khi một tool thực thi. Lint, format, thông báo.
• Notification — kích hoạt khi Claude Code phát thông báo. Cảnh báo Slack, ping desktop, tùy theo workflow của bạn.

jsonCopy

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Tool about to execute: Bash'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Trường matcher nhắm đến các tool cụ thể theo tên. Bỏ trống nó và hook sẽ kích hoạt trên mọi lệnh gọi tool — có lẽ không phải điều bạn muốn. Cùng nguyên tắc như thực thi theo lập trình: kiểm soát tất định mà mô hình không thể lách qua bằng lời nói.

Cấu hình MCP server

MCP server (Model Context Protocol) cho phép Claude Code truy cập các tool và nguồn dữ liệu bên ngoài. Cấu hình đặt trong .claude/settings.json ở tầng project hoặc ~/.claude/settings.json ở tầng user:

jsonCopy

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"],
      "env": {}
    },
    "database": {
      "command": "node",
      "args": ["./mcp-servers/database-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/app"
      }
    }
  }
}

Logic phân tầng giống hệt mọi thứ khác. Tầng project (.claude/settings.json) đi cùng repo. Tầng user (~/.claude/settings.json) chỉ mang tính cá nhân. Cấu hình một MCP server ở tầng project và ai clone repo cũng có quyền truy cập nó mà không cần làm gì thêm.

Để hiểu đầy đủ MCP hoạt động ra sao bên dưới, xem bài MCP Server được giải thích.

Quyền hạn và mô hình tin cậy

Claude Code chạy dưới một hệ thống phân quyền cân bằng giữa khả năng và an toàn. Thiết lập allowedTools trong settings.json phê duyệt trước các tool cụ thể để bạn bỏ qua prompt xin phê duyệt:

jsonCopy

{
  "allowedTools": [
    "Read",
    "Glob",
    "Grep",
    "Write",
    "Edit"
  ]
}

Bất cứ thứ gì không nằm trong danh sách đó đòi hỏi phê duyệt rõ ràng cho mỗi lần dùng. Đây là ranh giới bảo mật, không phải một nút bấm tiện lợi. Một workflow phân tích chỉ đọc không có lý do gì cần quyền Write hay Bash, và bài thi muốn bạn hiểu rõ sự khác biệt đó.

Chẩn đoán vấn đề cấu hình

Lệnh /memory hiển thị những file cấu hình nào đang được nạp trong phiên làm việc hiện tại của bạn. Nó không nạp bất cứ thứ gì. Đọc lại câu đó lần nữa — thuần túy mang tính chẩn đoán.

Khi Claude Code hành xử khác nhau giữa các thành viên team, /memory là nơi bạn bắt đầu. Nó cho thấy liệu các file CLAUDE.md, rules, và settings mà bạn kỳ vọng có thực sự đang hoạt động hay đang âm thầm biến mất.

Cây cấu hình dự án hoàn chỉnh

Một dự án được cấu hình tốt trông giống như thế này:

.claude/ ├── CLAUDE.md # Chuẩn chung toàn dự án ├── settings.json # Hook, MCP server, quyền hạn ├── rules/ │ ├── testing.md # Quy ước test theo đường dẫn │ ├── api-conventions.md # Quy ước API theo đường dẫn │ └── terraform.md # Rule hạ tầng theo đường dẫn ├── skills/ │ └── review/ │ └── SKILL.md # Workflow review code theo yêu cầu └── standards/ ├── naming-conventions.md # được import qua @./standards/naming-conventions.md trong CLAUDE.md └── error-handling.md # được import qua @./standards/error-handling.md trong CLAUDE.md

Cấu hình dùng chung đều được quản lý qua version control. Tùy chọn cá nhân nằm trong ~/.claude/. Clone repo, có ngay bộ thiết lập đầy đủ — không cần kiến thức truyền miệng nào.

Những gì bài thi kiểm tra

Domain 2 (Cấu hình & Workflow của Claude Code) chiếm 20% trọng số bài thi. Các câu hỏi về cấu hình theo những khuôn mẫu có thể đoán trước, và một khi bạn biết các bẫy đó, bạn sẽ không còn mắc lại nữa:

Bài thi ưu tiên kiểm tra sự hiểu biết về ranh giới phạm vi. Câu hỏi mô tả cấu hình không đến được đúng người? Truy ngược xem nó nằm ở tầng nào. Câu hỏi về lãng phí token? Rules theo đường dẫn gần như chắc chắn là đáp án họ muốn.

Để có toàn bộ chương trình học Domain 2, hãy bắt đầu với Hệ thống phân cấp và phạm vi CLAUDE.md và làm qua từng nội dung nhiệm vụ. Thi thử có các tình huống về cấu hình được xây dựng từ chính những mẫu này.