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.rules/ — tách hướng dẫn theo module và theo đường dẫn
Khi các chỉ dẫn về kiến trúc, bảo mật hoặc testing bắt đầu phình to, bạn module hóa chúng vào thư mục .claude/rules/. Thay vì một tệp 500 dòng, bạn có testing.md, api-design.md, hay security.md. Mỗi file giữ một mối quan tâm riêng và dễ cập nhật độc lập.
Sức mạnh thực sự của rules nằm ở path-scoped rules thông qua YAML frontmatter. Cơ chế này cho phép Claude chỉ nạp hướng dẫn khi đang làm việc với các file cụ thể. Ví dụ, một rule về tối ưu SQL chỉ nên nạp khi bạn sửa file trong thư mục database. Điều này giữ cho context window luôn sạch và tiết kiệm token. Ví dụ một rule chuyên biệt cho Entity Framework Core:
---
paths:
- "src/Infrastructure/Persistence/**/*"
- "**/*DbContext*.cs"
---
### Database Persistence Rules
- Không dùng 'Include' nếu không có lý do rõ ràng; ưu tiên Projections.
- Mọi migration phải có phương thức Down() tương ứng.
- Không inject DBContext trực tiếp vào Controllers.
- Dùng AsNoTracking() cho các truy vấn chỉ đọc.Hệ thống glob pattern hỗ trợ kiểm soát phạm vi linh hoạt:
| Glob pattern | Phạm vi áp dụng |
|---|---|
**/*.cs | Tất cả file C# trong dự án. |
src/API/**/*.{ts,js} | Các file TypeScript/JS trong thư mục API. |
**/*DbContext*.cs | Mọi file có chứa từ khóa DbContext trong tên. |
!tests/**/* | Loại trừ toàn bộ thư mục tests. |
commands/ — slash command lặp lại theo yêu cầu
Thư mục .claude/commands/ cho phép định nghĩa các lệnh gạch chéo tùy chỉnh. Tên file Markdown chính là tên lệnh — ví dụ review.md tạo ra lệnh /project:review. Đây là cách hiệu quả để đóng gói các prompt phức tạp mà bạn dùng thường xuyên; nếu cần một điểm khởi đầu, bộ cheatsheet lệnh Claude Code liệt kê các lệnh có sẵn.
Điểm kỹ thuật đáng chú ý nhất là cú pháp !backtick: nó cho phép chèn đầu ra của lệnh shell trực tiếp vào prompt trước khi mô hình xử lý. Điều này biến các lệnh tĩnh thành workflow động, giúp AI "nhìn" thấy trạng thái thực tế của hệ thống. Ví dụ file pr-check.md:
description: Kiểm tra sơ bộ các thay đổi trước khi tạo PR.
## Git Status Summary
!git status -s
## Detailed Diff against Main
!git diff main...HEAD
Hãy phân tích các thay đổi trên. Tập trung vào:
1. Các đoạn code debug chưa xóa (console.log, print).
2. Các lỗ hổng bảo mật tiềm tàng (hardcoded secrets).
3. Tuân thủ quy ước đặt tên trong CLAUDE.md.Một lưu ý về thứ tự ưu tiên: hệ thống command đang dần được hợp nhất vào skill. Nếu bạn có cả /project:deploy dạng command lẫn một skill tên deploy, Claude Code sẽ ưu tiên thực thi skill. Cách làm tốt hiện nay là chuyển dần các command phức tạp sang skill để tận dụng khả năng auto-invocation.
skills/ — chuyên môn tự kích hoạt và tiết kiệm token
Skill là đỉnh cao của việc tối ưu hiệu suất trong Claude Code. Khác với MCP (Model Context Protocol) server luôn chiếm một lượng token lớn cố định, skill dùng cơ chế Progressive Disclosure (tiết lộ lũy tiến): lúc khởi động, Claude chỉ đọc tên và mô tả của skill; toàn bộ phần chỉ dẫn chi tiết chỉ được nạp khi AI thực sự quyết định dùng kỹ năng đó.
Con số minh họa rất rõ: một MCP server cho Playwright có thể tốn khoảng 14.300 token nạp ngay khi khởi động, trong khi một skill Playwright tương đương chỉ tốn khoảng 200 token ban đầu. Đây là chênh lệch quyết định giữa một context window ngộp thở và một context window còn chỗ cho công việc thật. Vì thế, bạn nên viết phần description thật súc tích và cụ thể để skill được nhận diện đúng lúc. Cấu trúc một SKILL.md:
---
name: playwright-expert
description: Dùng khi cần viết hoặc debug UI tests bằng Playwright. Không dùng cho API tests.
allowed-tools:
- Bash
- Read
- Write
---
### Playwright Expert Workflow
1. Luôn kiểm tra playwright.config.ts để xác định BASE_URL.
2. Dùng Page Object Model (POM) trong thư mục tests/pages/.
3. Nếu test lỗi, chạy 'npx playwright show-report' để xem dấu vết.Điểm mấu chốt: skill giúp bạn đóng gói chuyên môn một lần và dùng lại mãi, mà gần như không tốn token khi chưa cần đến. Đó là lý do skill đang dần thay thế cả command lẫn một số MCP server nhẹ.
agents/ — subagent chuyên biệt, chạy cách ly
Với các tác vụ nặng về đọc file như "rà soát toàn bộ dependency" hay "phân tích log 100 MB", làm trực tiếp trong hội thoại chính sẽ phá hủy context window. Subagent giải quyết vấn đề này bằng cách chạy trong một context window riêng biệt hoàn toàn: nó nhận lệnh, thực hiện hàng trăm bước trung gian (đọc, grep, tìm kiếm), rồi chỉ trả về một bản tóm tắt súc tích cho agent chính.
Bạn cấu hình mỗi agent qua YAML frontmatter: chọn model (ví dụ dùng Haiku để tiết kiệm cho các task rà soát diện rộng), giới hạn tools (ví dụ chỉ Read/Grep/Glob cho một reviewer chỉ-đọc), và bật isolation: worktree để agent làm việc trên một bản sao repository (git worktree). Tính cách ly này rất an toàn: agent có thể chuyển sang branch khác hoặc xóa file để thử nghiệm mà không đụng đến thư mục làm việc của bạn. Ví dụ security-auditor.md:
---
name: security-expert
description: Chuyên gia rà soát lỗ hổng bảo mật.
model: haiku
tools:
- Read
- Grep
- Glob
isolation: worktree
memory: project
---
Bạn là chuyên gia bảo mật. Hãy rà soát các thay đổi trong branch hiện tại
và tìm các lỗi logic, SQL injection hoặc rò rỉ thông tin nhạy cảm.Subagent cũng là cách tốt nhất để thực hiện "adversarial review" — để một AI khác đánh giá kết quả của AI đầu tiên trong một môi trường sạch, không bị ảnh hưởng bởi quá trình suy luận trước đó.
settings.json và hooks — phân quyền và thực thi tất định
Nếu các file Markdown là "lời khuyên", thì settings.json và hooks là "luật pháp". AI có thể quên hướng dẫn trong prompt, nhưng hooks thì luôn được thực thi một cách tất định.
Phân quyền quản lý theo mô hình ba tầng: Deny (chặn), Ask (hỏi), Allow (cho phép), đánh giá theo đúng thứ tự đó và luật khớp đầu tiên sẽ thắng. Cú pháp specifier cho phép kiểm soát chi tiết: Read(.env*) chặn tuyệt đối việc đọc các file bí mật, còn Bash(dotnet test *) cho phép tự động chạy lệnh test.
Về hooks — các script chạy tự động tại các sự kiện lifecycle — có ba điểm cần nhớ. Thứ nhất, exit code 1 là lỗi nhưng không chặn: Claude nhận thông báo nhưng vẫn có thể tuyên bố hoàn thành. Thứ hai, exit code 2 chặn tuyệt đối: Claude buộc phải dừng và tự sửa dựa trên stderr cho đến khi script trả về 0. Thứ ba, hooks chạy với toàn quyền người dùng và không nằm trong sandbox, nên cần cực kỳ cẩn trọng. Ví dụ cấu hình linter tự động và một quality gate:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "dotnet format $EDITED_FILE" }]
}
],
"Stop": [{ "type": "command", "command": "dotnet test --no-build || exit 2" }]
}
}Trong ví dụ trên, Stop hook đảm bảo Claude không bao giờ kết thúc nhiệm vụ nếu bộ unit test chưa pass — một sự đảm bảo mà một dòng chỉ dẫn trong CLAUDE.md không bao giờ đạt được.
Tách cấu hình nhóm khỏi cấu hình cá nhân
Để giữ repository sạch sẽ, Claude Code hỗ trợ các file local: settings.local.json và CLAUDE.local.md. Chúng được tự động thêm vào .gitignore khi khởi tạo. Nguyên tắc đơn giản: nếu một cấu hình giúp cả team làm việc nhất quán, nó thuộc về dự án; nếu nó chỉ phản ánh thói quen của một người, nó thuộc về file local hoặc thư mục toàn cục.
Kỹ sư thường dùng các file local để lưu quyền hạn đặc thù trên máy, hoặc đặt model mặc định riêng (ví dụ dùng Haiku để tiết kiệm thay vì Sonnet). Điểm quan trọng là các lựa chọn này không rò rỉ vào bộ cấu hình chung mà cả team phải tin tưởng.
Còn một lớp nữa: auto-memory. Claude Code ghi lại các quan sát về dự án vào ~/.claude/projects/<project>/memory/, với tệp trung tâm là MEMORY.md. Về mặt kỹ thuật, chỉ khoảng 200 dòng đầu của tệp này được nạp vào context khi khởi động — nếu bạn để bộ nhớ tự động phình to, những thông tin quan trọng nhất có thể bị đẩy xuống dưới và không bao giờ được đọc. Hãy dùng lệnh /memory để dọn dẹp định kỳ; nếu muốn hiểu vì sao đôi khi nên xóa hẳn bộ nhớ tự động của Claude Code, đó là một quyết định vận hành đáng cân nhắc.
Lộ trình thiết lập — và cách tái cấu trúc file có sẵn
Hãy coi thư mục .claude như Hạ tầng dưới dạng Code (Infrastructure as Code): đừng cố xây mọi thứ trong một ngày. Một lộ trình thực tế gồm ba giai đoạn. Giai đoạn 1 (khởi tạo): dùng /init để tạo CLAUDE.md cơ bản và thiết lập các lệnh build/test chính xác. Giai đoạn 2 (module hóa): khi CLAUDE.md chạm ngưỡng 200 dòng, bắt đầu chuyển các quy tắc đặc thù sang .claude/rules/ kèm path-scoping. Giai đoạn 3 (automation): đóng gói các workflow lặp lại thành skills và thiết lập hooks cho các gate kiểm tra tự động.
Nếu bạn đang ôm một CLAUDE.md dài 500 dòng, cách di chuyển gọn nhất là: giữ lại khoảng 50 dòng mô tả kiến trúc cốt lõi và các lệnh hay dùng; chuyển hướng dẫn code style sang rules/general-style.md; chuyển quy tắc API sang rules/api.md kèm paths: ["src/api/**/*"]; và chuyển các checklist deploy vào skills/deploy/SKILL.md. Kết quả không phải là một thư mục hoành tráng hơn, mà là một AI phản hồi nhanh và chính xác hơn — vì mỗi file giờ đây đều có một mục đích rõ ràng.
Tài liệu tham khảo
- How to Structure the .claude Folder for Maximum Efficiency — Youssef Hosni
- The .claude Folder: Anatomy of a Cognitive System — Nuno Roberto
- Explore the .claude directory — Claude Code Docs
- Anatomy of the .claude/ folder — Akshay Pachaar
- Best practices for Claude Code — Claude Code Docs
- Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents — Anthropic
- Anatomy of the .claude Folder — Every File Explained (2026) — Mukesh Murugan
- Claude Code Skills in 2026: The Complete Guide — Totalum