Thư mục .claude không chỉ đơn thuần là nơi chứa cấu hình; nó đóng vai trò là kiến trúc nhận thức (cognitive architecture) của Claude Code trong một dự án. Trong môi trường kỹ thuật hệ thống, việc thiết lập thư mục này chính là cách bạn định nghĩa "hệ điều hành" mà AI sẽ chạy trên đó. Thay vì dựa vào suy luận ngẫu nhiên của mô hình ngôn ngữ lớn (LLM), cấu hình .claude giúp bạn đặt ra các quy tắc cứng, quy trình tự động và các chuyên gia chuyên biệt để giảm sai sót và tối ưu context window — tài nguyên quan trọng và đắt đỏ nhất trong AI-assisted development.
Hệ thống điều khiển này quản lý năm phân hệ cốt lõi: hướng dẫn qua CLAUDE.md và rules; quy trình với skills và commands; chuyên gia qua agents; phân quyền trong settings.json; và bộ nhớ cục bộ. Tối ưu các thành phần này giúp Claude Code hoạt động ổn định trong repo lớn, tránh "ảo tưởng" về kiến trúc, và đặc biệt là tiết kiệm token bằng cách chỉ nạp đúng thứ cần thiết tại đúng thời điểm.
Hai thư mục .claude: cấp dự án và cấp toàn cục
Trong một dự án thực tế, cấu hình Claude Code phân tầng rõ rệt giữa phần dùng chung cho team và sở thích cá nhân. Thư mục .claude tại gốc repository là nơi chứa "luật chơi" của dự án. Khi được commit lên Git, mọi thành viên trong team kế thừa cùng một bộ chỉ dẫn, quy tắc an ninh và các automation script. Điều này đảm bảo tính nhất quán: AI của mọi kỹ sư đều hiểu cùng một kiến trúc và tuân thủ cùng một quy trình build/test.
Ngược lại, thư mục toàn cục tại ~/.claude/ (Linux/macOS) hoặc %USERPROFILE%\.claude (Windows) lưu các tùy chỉnh cá nhân và lịch sử phiên làm việc cùng bộ nhớ tự động (auto-memory). Đây là nơi bạn đặt các sở thích riêng hoặc các skill mang tính cá nhân hóa cao. Khi hai thư mục cùng tồn tại, Claude Code hợp nhất chúng theo một thứ tự ưu tiên nghiêm ngặt:
| Thứ tự ưu tiên | Nguồn cấu hình | Vị trí / Đặc điểm |
|---|---|---|
| 1 (Cao nhất) | Managed policy | Do quản trị viên/IT triển khai (qua MDM), không thể bị ghi đè. |
| 2 | CLI arguments | Các cờ dòng lệnh (ví dụ --permission-mode auto). |
| 3 | Local overrides | .claude/settings.local.json (ghi đè quyền hạn trên máy cục bộ). |
| 4 | Project settings | .claude/settings.json tại gốc dự án (chia sẻ qua Git). |
| 5 (Thấp nhất) | User settings | ~/.claude/settings.json (cấu hình cá nhân toàn cục). |
Cấu hình Managed Policy quan trọng với các doanh nghiệp lớn: nó cho phép áp các tiêu chuẩn an ninh và tuân thủ trên mọi repository mà kỹ sư không thể tự ý thay đổi. Nhờ đó, một quy tắc như "không bao giờ đọc file .env" luôn được thực thi ở mức hệ thống.
CLAUDE.md — tệp nền tảng, giữ dưới 200 dòng
File CLAUDE.md là điểm chạm đầu tiên của AI với dự án. Nội dung của nó được nạp trực tiếp vào system prompt ngay khi phiên bắt đầu. Sai lầm phổ biến nhất là biến file này thành một bãi rác chứa tài liệu dài dòng. Về mặt kỹ thuật, bạn nên giữ file này dưới 200 dòng; khi vượt ngưỡng đó, sự chú ý của AI bị phân tán và nó bắt đầu bỏ sót các chỉ dẫn quan trọng ở đầu hoặc cuối file.
Một đặc tính đáng chú ý của CLAUDE.md là khả năng sống sót qua compaction. Trong các phiên dài, Claude Code tự động nén (compact) lịch sử hội thoại để giải phóng bộ nhớ. Các chỉ dẫn bạn nói bằng lời có thể bị mất, nhưng CLAUDE.md được đọc lại từ đĩa, đảm bảo sự nhất quán.
Với monorepo, việc duy trì một file CLAUDE.md duy nhất là không khả thi. Claude Code xử lý bằng cách duyệt ngược cây thư mục: bạn đặt các file CLAUDE.md nhỏ hơn trong các thư mục con để định nghĩa quy tắc đặc thù cho từng module, và Claude chỉ nạp chúng khi làm việc trong thư mục đó. Dưới đây là một ví dụ CLAUDE.md gọn cho dự án .NET:
# Project: Financial Clearing System (.NET 10)
## Tech Stack
- ASP.NET Core Web API, Entity Framework Core, SQL Server
- MediatR (CQRS), FluentValidation, xUnit
## Structure
- src/Domain/: Logic nghiệp vụ và entities
- src/Application/: Use cases và MediatR handlers
- src/Infrastructure/: DBContext, tích hợp ngoài
- src/API/: Controllers và middleware
## Commands
- Build: dotnet build
- Test: dotnet test --filter Category=Unit
- Database: dotnet ef database update --project src/Infrastructure
## Conventions
- Dùng file-scoped namespaces.
- MediatR Handlers phải là internal và sealed.
- Dùng Result<T> pattern cho mọi service response.