Settings.json Và Settings.local.json: Hai File Cấu Hình Claude Code Mà Team Nào Cũng Cần Biết
📁 Hai File, Hai Mục Đích
Claude Code lưu cấu hình trong hai file JSON nằm ở thư mục .claude/ của dự án. settings.json là file của cả team, commit vào git, chứa các rule chung mà ai trong team cũng phải tuân theo. settings.local.json là file cá nhân, được Claude Code tự động gitignore, chứa preferences riêng của từng developer như API key, model mặc định, hay permissions mở rộng.
Cách tách biệt này cực kỳ quan trọng. Team thống nhất policy bảo mật trong settings.json, còn mỗi dev giữ thói quen cá nhân không làm phiền commit history của người khác.
🏗️ Bốn Scope Xếp Chồng Theo Ưu Tiên
Claude Code merge setting từ bốn nguồn theo thứ tự ưu tiên từ cao xuống thấp: Managed policies (IT admin quản lý ở cấp hệ điều hành, cao nhất), Local project (.claude/settings.local.json), Shared project (.claude/settings.json), và User (~/.claude/settings.json, thấp nhất).
Khi có xung đột, scope cao hơn thắng. Với các setting kiểu object như permissions, Claude Code merge từng field chứ không ghi đè toàn bộ. Nghĩa là team rule vẫn còn hiệu lực kể cả khi bạn thêm rule cá nhân.
🔧 Tám Section Chính Trong Settings.json
File settings.json hỗ trợ các section sau: permissions (allow/deny/ask rules, defaultMode, additionalDirectories), hooks (tự động chạy script khi có event), model (chọn giữa claude-sonnet-4-5, opus, haiku), env (biến môi trường như ANTHROPIC_API_KEY, BASH_DEFAULT_TIMEOUT_MS), statusLine (thanh status tuỳ chỉnh ở terminal), outputStyle (cách Claude format câu trả lời), apiKeyHelper (script lấy API key động), và includeCoAuthoredBy (thêm Co-Authored-By vào git commit).
🎯 Wildcard Patterns Trong Permissions
Permissions hỗ trợ wildcard rất mạnh. Bash(npm run test:*) cho phép mọi lệnh npm test. Read(~/Documents/)** đọc mọi file trong Documents. WebFetch(domain:github.com) chỉ fetch từ github.com. Edit(src//*.ts)** chỉ edit TypeScript files trong src folder.
Một rule quan trọng, deny luôn thắng allow. Dù bạn có allow rộng cỡ nào, deny rule vẫn chặn được. Đây là cơ chế an toàn để team bảo vệ các file nhạy cảm.
💡 Ví Dụ Thực Tế Cho Dự Án
Trong settings.json của team, bạn commit: allow gồm Bash(git:), Bash(npm:), Read(./). Deny gồm Bash(rm -rf:*), Read(./.env), Edit(./secrets/). Như vậy ai pull repo về cũng có cùng rule bảo mật.
Trong settings.local.json cá nhân, bạn có thể thêm env ANTHROPIC_API_KEY riêng, chọn model opus cho task khó, bật thêm permission cho MCP tool bạn thích dùng. File này không bao giờ lộ ra git, nên bạn thoải mái để token và preferences riêng.
Hiểu rõ hai file này giúp team vừa an toàn vừa linh hoạt, mỗi dev có trải nghiệm cá nhân hoá mà không ảnh hưởng người khác.
