settings.json: cấu hình Claude Code cho đúng dự án

Trả lời nhanh: Cấu hình chia làm ba tầng theo thứ tự ưu tiên tăng dần: cấu hình cá nhân của bạn áp cho mọi dự án, cấu hình chung của dự án nằm trong repo và cả đội dùng, và cấu hình riêng của bạn cho dự án đó không đưa vào Git. Nguyên tắc phân chia giống mọi thứ khác trong công cụ này: cái gì làm sai gây hậu quả thì để trong repo, cái gì là sở thích thì để riêng. Bốn nhóm đáng chỉnh nhất là quyền, hook, biến môi trường và máy chủ MCP.

Phần lớn người dùng chưa từng mở file cấu hình và vẫn làm việc bình thường. Nhưng khi bạn bắt đầu làm việc theo đội, hoặc muốn agent chạy tự động mà không hỏi từng bước, thì đây là chỗ phải nắm. Bài này chỉ nói những khóa thực sự đáng chỉnh.

Ba tầng và thứ tự ưu tiên

Cấu hình được ghép lại từ ba nguồn, nguồn gần dự án hơn sẽ thắng khi có khóa trùng:

• Cấu hình cá nhân trong thư mục nhà. Áp cho mọi dự án. Đặt ở đây những thứ theo bạn đi khắp nơi.
• Cấu hình dự án trong thư mục .claude của repo, commit vào Git. Đây là nơi đặt ràng buộc chung mà cả đội phải theo.
• Cấu hình riêng cho dự án, cùng thư mục nhưng thêm hậu tố báo là bản cục bộ, và phải nằm trong danh sách loại trừ của Git.

Ranh giới thực dụng: quyền và hook thì để trong repo vì chúng là hàng rào an toàn cho cả đội; máy chủ MCP gắn với tài khoản cá nhân thì để riêng; sở thích trình bày thì để trong cấu hình cá nhân vì áp lên người khác chỉ gây khó chịu.

Quyền, nhóm quan trọng nhất

{  "permissions": {    "allow": [      "Bash(npm run test:*)",      "Bash(npm run lint)",      "Bash(git status)",      "Bash(git diff:*)"    ],    "deny": [      "Bash(rm -rf:*)",      "Bash(git push:*)"    ]  }}

Danh sách cho phép giúp agent chạy những lệnh quen thuộc mà không phải hỏi bạn từng lần, thứ làm gián đoạn nhịp làm việc nhiều nhất. Danh sách cấm chặn những thứ không bao giờ nên xảy ra.

Sai lầm hay gặp là nới quyền cho tiện, ví dụ cho phép mọi lệnh hệ thống. Làm vậy thì bạn mất luôn lớp bảo vệ mà chẳng được gì thêm ngoài đỡ vài lần bấm. Cách đúng là liệt kê đúng nhóm lệnh bạn thật sự dùng hằng ngày và thêm dần khi gặp lệnh mới.

Quyền và hook bổ sung nhau: quyền cắt bề mặt theo loại lệnh, hook lọc theo nội dung thật của lệnh, như phân tích ở bài về hooks.

Biến môi trường và máy chủ MCP

Biến môi trường trong cấu hình dự án giúp agent chạy lệnh trong đúng ngữ cảnh, ví dụ trỏ vào database của môi trường phát triển:

{  "env": {    "NODE_ENV": "development",    "DATABASE_URL": "postgres://localhost:5432/du_an_dev"  }}

Quy tắc bắt buộc: chỉ đặt giá trị không nhạy cảm. File này nằm trong Git. Chuỗi kết nối tới database thật, khóa API, mật khẩu đều phải để ở nơi quản lý bí mật và nạp bằng cơ chế khác.

Khai báo máy chủ MCP cũng nằm trong tầng cấu hình, và cùng nguyên tắc: máy chủ phục vụ cả đội thì để trong repo, máy chủ gắn với tài khoản riêng của bạn thì để ở bản cục bộ. Cách chọn máy chủ nào đáng cắm nằm ở bài chọn MCP server.

Cấu hình cho máy chủ chạy tự động

Khi agent chạy trên máy chủ không có bạn ngồi cạnh, cấu hình phải khác so với lúc làm việc tương tác:

• Danh sách cho phép phải đủ rộng cho toàn bộ luồng việc, vì không có ai để bấm đồng ý. Nhưng phải liệt kê cụ thể, không mở toang.
• Danh sách cấm phải chặt hơn, đặc biệt với các lệnh đẩy code, thay đổi database và xóa file.
• Nên có hook ghi nhật ký mọi thao tác thay đổi, để sáng hôm sau bạn xem lại được nó đã làm gì.

Cách dựng môi trường chạy tự động nằm ở bài chạy Claude Code trên VPS. Một lời khuyên bổ sung: cho agent chạy trong một bản sao của repo trên nhánh riêng, đừng cho nó chạy thẳng trên thư mục làm việc chính của bạn.

Cách gỡ khi cấu hình không có tác dụng

Ba nguyên nhân theo thứ tự hay gặp:

Đặt sai tầng. Bạn sửa cấu hình cá nhân nhưng cấu hình dự án đang ghi đè khóa đó. Nhớ quy tắc gần dự án hơn thì thắng.

Cú pháp JSON hỏng. Thừa một dấu phẩy ở cuối là cả file bị bỏ qua, thường không có thông báo rõ ràng. Chạy một công cụ kiểm tra JSON là biết ngay.

Mẫu khớp lệnh viết sai. Danh sách quyền dùng mẫu khớp, nên viết thiếu phần đại diện là mẫu không bắt đúng lệnh bạn nghĩ. Cách thử: chạy đúng lệnh đó và xem agent có phải hỏi bạn không.

Nguyên tắc cuối: giữ cấu hình ngắn. Mỗi khóa bạn thêm là một thứ phải nhớ và một chỗ có thể gây bất ngờ cho đồng nghiệp. Cùng tinh thần với việc giữ file quy ước ngắn trong bài về memory.

Ba tầng cấu hình và thứ tự ưu tiên

Nguyên tắc phân loại: quy tắc chung của đội thì vào tầng hai và có duyệt; thói quen cá nhân và đường dẫn riêng trên máy bạn thì vào tầng ba và không đưa lên kho.

Ba nhóm thao tác và mức cho phép

# Ba nhom thao tac va cach nen dat: # 1. Doc file, tim kiem: cho phep, khong hoi# 2. Sua file trong thu muc du an: cho phep, nhung xem lai truoc khi ghep# 3. Chay lenh he thong: HOI moi lan, hoac chan han voi lenh nguy hiem # Nam nhom lenh nen chan cung:#   - xoa de quy o duong dan goc#   - ghi de vao thiet bi o dia#   - day thang len nhanh chinh hoac ep ghi de lich su#   - ket noi va chay lenh tren may chu that#   - tai tep tu internet roi chay thang # Kiem cau hinh dang co tac dung khong:# neu khong, kiem thu tu uu tien ba tang o tren

Khai rõ quyền cho môi trường không người trực

• Khác hẳn cấu hình trên máy cá nhân. Trên máy chủ không có ai bấm đồng ý, nên phải khai rõ cái gì được phép và cái gì bị chặn.
• Không cấp quyền chạy lệnh tùy ý. Chỉ cho chạy đúng tập lệnh cần thiết.
• Không để khóa đăng nhập máy chủ thật trên máy chạy tự động, trừ khi khóa đó bị giới hạn chỉ chạy được một tập lệnh.
• Ghi nhật ký mọi lệnh đã chạy, giữ ít nhất 30 ngày.

Khi cấu hình không có tác dụng

1. Kiểm bạn đang sửa đúng tầng nào; tầng cục bộ ghi đè tầng dự án.
2. Kiểm cú pháp tệp có hợp lệ không; một dấu phẩy thừa là cả tệp bị bỏ qua.
3. Khởi động lại phiên làm việc, vì một số cấu hình chỉ đọc lúc khởi động.
4. Kiểm đường dẫn tệp có đúng chỗ công cụ tìm không.