TL;DR: Claude Code đọc 3 lớp cấu hình mỗi phiên: file
CLAUDE.md(chỉ dẫn dự án), thư mục.claude/(settings, skills, agents, hooks, rules…) và filesettings.json(quyền + tự động hoá). Hiểu 3 lớp này là biết Claude được phép làm gì, đọc gì, và cư xử ra sao. Bài này là bản đồ tổng: mỗi phần là gì, đặt ở đâu, ưu tiên thế nào, và link xuống bài chuyên sâu cho từng mục.
Bạn mở một project mới, gõ claude, rồi lại phải nhắc lại từ đầu: dùng pnpm chứ không npm, đừng đụng nhánh main, test bằng lệnh nào. Phiên sau lại nhắc y hệt. Cảm giác như onboarding một nhân viên mất trí nhớ mỗi sáng.
Thứ chữa được việc đó nằm ở cấu hình của Claude Code, và phần lớn người dùng chưa bao giờ mở nó ra. Nó gồm một file ai cũng thấy (CLAUDE.md) và một thư mục ẩn hầu như không ai động vào: .claude/. Bài này đi qua toàn bộ: thư mục .claude/ chứa gì, settings.json cấu hình được gì, thứ tự ưu tiên khi nhiều file cùng khai báo một thứ, và quan trọng nhất, cách chặn Claude đọc nhầm file chứa mật khẩu.
Trong settings.json còn có khối sandbox để cho Claude chạy lệnh bash không cần bấm Accept: xem cách bật sandbox và cái nó không bảo vệ.
Mọi chi tiết kỹ thuật bên dưới mình đã đối chiếu tài liệu chính thức tại code.claude.com/docs (truy cập 29/06/2026), vì với sản phẩm của Anthropic, sai nguy nhất là sai trạng thái tính năng chứ không phải sai số liệu.
Thư mục .claude/ gồm những gì?
Có hai thư mục .claude/ cùng tên nhưng khác phạm vi (scope). Hiểu sai chỗ này là nguồn gốc của hầu hết câu hỏi “sao máy đồng nghiệp không thấy skill của tôi”.
.claude/trong project (cùng cấp.git/): chỉ áp dụng cho dự án đó. Commit lên git thì cả team dùng chung.~/.claude/trong home directory (thư mục user của bạn): cấu hình cá nhân, đi theo bạn vào mọi project, không bao giờ commit.
Quy tắc một câu: cái gì cả team cần thì để trong project, cái gì chỉ mình bạn cần thì để trong ~/.claude/.
Đây là bản đồ rút gọn của một project:
project/
├── CLAUDE.md # chỉ dẫn dự án (đọc mỗi phiên)
├── .mcp.json # MCP server chia sẻ cho team (commit)
├── .claude/
│ ├── settings.json # quyền + hooks + env (commit)
│ ├── settings.local.json # cấu hình cá nhân (gitignore)
│ ├── skills/ # skill tự tạo
│ ├── agents/ # sub-agent
│ ├── hooks/ # script chặn/chạy theo sự kiện
│ ├── rules/ # rule theo path
│ └── output-styles/ # đổi tone trả lời
└── ~/.claude/ # bản global của tất cả mục trên + .claude.json (MCP cá nhân)
Một điểm dễ bỏ qua: skill hay agent đặt trong .claude/ của project chỉ chạy được khi bạn mở Claude Code trong project đó. Rời thư mục là mất. Còn thứ đặt trong ~/.claude/ thì theo bạn khắp nơi. Nếu bạn dùng Git worktree, file cấu hình worktree (.worktreeinclude) cũng nằm ở gốc project.
settings.json cấu hình những gì?
settings.json là file trung tâm quyết định Claude được phép làm gì mà không cần hỏi, và phải hỏi bạn khi nào. Nó nằm ở .claude/settings.json (chia sẻ) và ~/.claude/settings.json (cá nhân).
Phần quan trọng nhất là permissions, với ba danh sách allow / deny / ask:
{
"permissions": {
"allow": ["Bash(npm run test *)", "Bash(git status)"],
"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
"ask": ["Bash(git push *)"]
}
}
Đọc nôm na: cho Claude chạy test và xem git status mà không hỏi; cấm tuyệt đối đọc file .env; còn git push thì phải xin phép. Mô hình này giống một người gác cổng cho từng thao tác.
Ngoài permissions, settings.json còn khai báo: khối hooks (script chạy trước/sau mỗi tool, sẽ nói kỹ ở phần bảo mật), env (biến môi trường tự inject), model (model mặc định), cùng vài mục như statusLine hay outputStyle.
Riêng statusLine (thanh trạng thái dưới đáy hiện model, % context, git) có bài hướng dẫn riêng: bật và tùy biến status line.
Bên cạnh đó bạn sẽ thấy settings.local.json. Nó cùng cấu trúc nhưng có một khác biệt quan trọng: đây là file riêng của bạn, không commit. Còn settings.json thì commit để chia sẻ. Vậy nên secret hay tuỳ chỉnh cá nhân để vào settings.local.json, đừng để vào settings.json.
Thứ tự ưu tiên settings hoạt động ra sao?
Khi cùng một thiết lập xuất hiện ở nhiều nơi, Claude Code áp theo thứ tự ưu tiên từ cao xuống thấp (theo code.claude.com/docs, truy cập 29/06/2026):
| Ưu tiên | Tầng | Vị trí |
|---|---|---|
| 1 (cao nhất) | Managed (tổ chức) | cấp hệ thống, IT cài, không override được |
| 2 | Command-line flags | chỉ cho phiên đó (vd cờ khi gõ claude) |
| 3 | Local | .claude/settings.local.json |
| 4 | Project | .claude/settings.json |
| 5 (thấp nhất) | User | ~/.claude/settings.json |
Hai điều thực tế hay làm người ta vấp:
- Local đè Project, không phải ngược lại. Cấu hình cá nhân của bạn trong
settings.local.jsonthắng cấu hình team trongsettings.json. Nhiều người nhớ nhầm thứ tự này. - Riêng
permissionsthì GỘP (merge), không đè. Đây là ngoại lệ quan trọng. Một ruledenyở tầng project và một ruledenyở tầng user sẽ cộng dồn, cả hai cùng hiệu lực, không cái nào xoá cái nào. Logic này rất hợp lý cho bảo mật: một lệnh cấm không thể bị một tầng thấp hơn vô hiệu.
Tầng Managed chỉ dành cho doanh nghiệp (IT ép policy toàn máy, dev không sửa được). Nếu bạn làm cá nhân hay team nhỏ, chỉ cần quan tâm Project, Local và User. Phần quyền sâu hơn (bypass, các permission mode) mình tách riêng ở bài permission modes của Claude Code.
Mỗi phần trong .claude/ đọc sâu ở đâu?
Pillar này cố tình giữ ngắn cho từng mục con, vì mỗi mục đã có một bài đào sâu riêng. Đây là bản đồ tra cứu nhanh:
| Mục trong .claude/ | Một câu | Đọc sâu |
|---|---|---|
CLAUDE.md | Chỉ dẫn dự án, đọc đầu mỗi phiên | CLAUDE.md là gì |
skills/ | Quy trình lặp lại đóng gói thành kỹ năng | Claude Code Skills |
agents/ | Sub-agent có context window + tool riêng | Sub-agents |
hooks/ | Script chặn/chạy theo sự kiện (deterministic) | Claude Code Hooks |
commands/ | Slash command (cách cũ, skill thay dần) | Slash commands |
output-styles/ | Đổi tone và văn phong câu trả lời | Output styles |
workflows/ | Dynamic workflow: JS điều phối nhiều agent | Dynamic Workflows |
| auto memory | Ghi chú Claude tự lưu xuyên phiên | Auto memory |
.mcp.json | Kết nối service ngoài qua MCP | MCP servers |
Một lưu ý nhỏ về commands/: theo tài liệu chính thức, skill là hướng đi mới, và nếu một skill trùng tên với một command thì skill thắng. Nếu bạn bắt đầu mới, dùng skill luôn cho gọn.
Còn về rules/: thư mục .claude/rules/ cho phép tách rule theo path. Mỗi file markdown khai báo paths: ở frontmatter sẽ chỉ nạp khi Claude đụng vào file khớp pattern, giúp đỡ tốn context. Đây là cách hay khi CLAUDE.md của bạn phình quá 200 dòng (con số này là khuyến nghị, không phải ngưỡng cắt cứng, và bản thân CLAUDE.md luôn được nạp đầy đủ).
Làm sao chặn Claude đọc nhầm file secret?
Đây là phần ít người để ý nhất nhưng đáng giá nhất. Claude Code đọc được file trên máy bạn, nghĩa là nó đọc được cả file .env chứa API key, mật khẩu database, access token. Mà những thứ đó thường gắn với tiền: một API key lộ ra là người khác gọi API bằng tiền của bạn.
Vấn đề là: khi Claude đọc file, nội dung đó rời khỏi máy bạn, đi lên server của nhà cung cấp model. Một khi secret đã rời máy thì bạn không lấy lại được. Cách duy nhất là xoá hoặc vô hiệu (rotate) nó.
Ví dụ kinh điển: API báo lỗi, bạn nhờ Claude “kiểm tra giúp file .env xem sao”. Claude đọc file đó, và toàn bộ key nằm trong prompt gửi đi. Lúc đó đã muộn.
Có hai lớp chặn, dùng cùng nhau là an toàn nhất:
permissions.denytrongsettings.json(xem ví dụ ở trên): chặn đọc.env,secrets/**, file*.pem. Đây là lớp khai báo, đơn giản, đủ cho phần lớn trường hợp.- PreToolUse hook: một script chạy trước khi Claude đọc/chạy lệnh, kiểm tra theo logic của bạn rồi cho phép hoặc chặn. Hook mạnh hơn vì nó là code thật (deterministic), chặn được cả khi Claude tìm đường vòng (ví dụ dùng một module Python để đọc file thay vì đọc trực tiếp).
Vì sao cần tới hook khi đã có permissions? Vì có một nguyên tắc nền: CLAUDE.md và mọi chỉ dẫn dạng văn bản chỉ là gợi ý ngữ cảnh, không phải luật cứng (theo code.claude.com/docs, truy cập 29/06/2026). Muốn chặn một hành động bất kể Claude nghĩ gì, bạn phải dùng hook. Cùng cơ chế đó, hook còn dùng để chặn lệnh nguy hiểm (xoá dữ liệu, đẩy lên server lạ), bảo vệ nhánh main khỏi auto-merge, hay format và lint code tự động để khỏi tốn token. Chi tiết cách viết và ví dụ ở bài Claude Code Hooks.
CLAUDE.md và AGENTS.md khác gì nhau?
Nếu repo của bạn từng dùng công cụ AI khác, có thể bạn đã có sẵn file AGENTS.md. Câu hỏi hay gặp gần đây: vậy phải viết lại sang CLAUDE.md à?
Câu trả lời từ tài liệu chính thức (truy cập 29/06/2026): Claude Code đọc CLAUDE.md, không đọc AGENTS.md. Nhưng bạn không cần chép tay hai bản. Cách gọn nhất là tạo CLAUDE.md rồi import file kia vào:
@AGENTS.md
## Claude Code
Dùng plan mode cho thay đổi trong src/billing/.
Claude sẽ nạp nội dung AGENTS.md ở đầu phiên, rồi đọc thêm phần riêng cho Claude bên dưới. Nếu không cần thêm gì riêng, một symlink cũng được (ln -s AGENTS.md CLAUDE.md); riêng Windows cần quyền admin hoặc Developer Mode nên cứ dùng cú pháp @AGENTS.md cho lành.
Tiện thể, khi bạn chạy /init trong repo đã có AGENTS.md, Claude đọc cả nó lẫn .cursorrules, .windsurfrules và gộp phần liên quan vào CLAUDE.md mới. Đây là điểm hay cho ai dùng nhiều công cụ AI cùng lúc trên một repo.
Cái gì nên commit, cái gì giữ riêng?
Đường ranh đơn giản: tên file có .local thì đừng commit. Cụ thể, thêm vào .gitignore:
CLAUDE.local.md
.claude/settings.local.json
Vậy là mỗi người trong team có cấu hình cá nhân riêng mà không đụng người khác. Còn lại, CLAUDE.md và .claude/settings.json thì commit để chia sẻ chuẩn chung. Một điểm dễ nhầm về MCP: file .mcp.json (trong project) là bản chia sẻ, commit được; còn cấu hình MCP cá nhân nằm trong ~/.claude.json thì không. Nếu đồng nghiệp pull về mà không thấy MCP server bạn cấu hình, khả năng cao bạn để nhầm vào file cá nhân.
Cấu hình tốt cũng là một cách tiết kiệm token cho Claude Code: rule theo path chỉ nạp khi cần, CLAUDE.md ngắn gọn, skill chỉ kích hoạt đúng lúc. Càng ít context thừa mỗi phiên, càng đỡ tốn.
/effort và ultracode: chỉnh độ sâu suy luận thế nào?
Ngoài cấu hình bằng file, Claude Code còn cho bạn chỉnh độ sâu suy luận (effort level) ngay trong phiên. Effort điều khiển adaptive reasoning: model tự quyết định có nên suy nghĩ và suy nghĩ bao nhiêu ở mỗi bước, tùy độ khó của việc. Effort thấp thì nhanh và rẻ cho việc đơn giản, effort cao thì suy luận sâu hơn cho việc phức tạp.
Gõ lệnh /effort để chọn mức. Các mức khả dụng trên Opus 4.8, Opus 4.7, Sonnet 5 và Fable 5:
| Mức | Khi nào dùng |
|---|---|
low | Việc ngắn, phạm vi hẹp, cần nhanh, không đòi hỏi thông minh |
medium | Việc cần tiết kiệm chi phí, chấp nhận đánh đổi một phần trí tuệ |
high | Cân bằng token và trí tuệ. Mặc định trên hầu hết model |
xhigh | Suy luận sâu hơn, tốn token hơn. Mặc định trên Opus 4.7 |
max | Suy luận sâu nhất, không giới hạn token |
low, medium, high, xhigh giữ nguyên qua các phiên. Riêng max chỉ áp cho phiên hiện tại, trừ khi đặt qua biến môi trường CLAUDE_CODE_EFFORT_LEVEL. Lưu ý theo model: Opus 4.6 và Sonnet 4.6 không có mức xhigh, nên đặt xhigh trên các model này sẽ tự lùi về high.
Menu /effort còn có ultracode. Đây là một setting chứ không phải mức effort: nó gửi xhigh cho model và cho Claude tự dựng dynamic workflows cho các việc lớn. Ultracode chỉ áp cho phiên hiện tại, bật qua /effort hoặc truyền "ultracode": true trong --settings hay Agent SDK. Nó không nằm trong effortLevel, cờ --effort hay CLAUDE_CODE_EFFORT_LEVEL.
Nguồn: Claude Code Docs, “Model configuration” (code.claude.com/docs/en/model-config, truy cập 01/07/2026).
Câu hỏi thường gặp
File cấu hình Claude Code nằm ở đâu?
Hai nơi: trong project (./CLAUDE.md, .claude/settings.json, .mcp.json) áp cho dự án đó và commit được; trong home directory (~/.claude/) là cấu hình cá nhân đi theo bạn vào mọi project. Cùng tên nhưng khác phạm vi.
settings.json và settings.local.json khác nhau thế nào?
Cùng cấu trúc. settings.json commit để chia sẻ với team; settings.local.json không commit, dành cho cấu hình cá nhân và secret. Khi cùng một thiết lập, settings.local.json (Local) ưu tiên cao hơn settings.json (Project). Riêng permissions thì hai file gộp lại chứ không đè.
.mcp.json khác .claude.json ở đâu?
.mcp.json nằm trong project, commit được, chia sẻ MCP server cho cả team. Cấu hình MCP cá nhân của bạn nằm trong ~/.claude.json (home directory), không commit, chỉ mình bạn thấy.
Làm sao chặn Claude Code đọc file .env?
Hai lớp: thêm "Read(./.env)" và "Read(./.env.*)" vào permissions.deny trong settings.json; và viết một PreToolUse hook để chặn cứng kể cả khi Claude tìm đường vòng. Vì chỉ dẫn dạng văn bản là gợi ý, còn hook mới là luật.
Managed settings là gì, ai cần?
Là tầng cấu hình cao nhất, do IT cài ở cấp hệ thống và dev không override được. Dùng cho doanh nghiệp cần ép policy bảo mật toàn tổ chức. Cá nhân và team nhỏ không cần quan tâm, chỉ tập trung vào Project, Local và User.
Kết luận
Cấu hình Claude Code gồm nhiều lớp, nhưng đừng để bị ngợp. Phần lớn người dùng chỉ cần ba thứ để bắt đầu tốt: một CLAUDE.md gọn ở gốc project, một khối permissions trong settings.json (tối thiểu là deny cho .env), và biết rằng muốn chặn cứng thì dùng hook chứ không dựa vào lời dặn trong CLAUDE.md.
Khi dự án lớn hơn, thêm rules/ theo path, skills/ cho quy trình lặp lại, và agents/ khi cần việc chạy song song. Bắt đầu đơn giản, mở rộng dần. Bản đồ ở phần 4 là nơi bạn quay lại mỗi khi cần đào sâu một mục cụ thể.
