Settings System trong Claude Code: Phân biệt Global, Project và Local

Định nghĩa

Settings System trong Claude Code là hệ thống phân tầng (three-tier) gồm Global (phạm vi user), Project (phạm vi repository), và Local (phạm vi session). Hệ thống này giúp bạn tách biệt rõ ràng: sở thích cá nhân, quy tắc chung của team, và thiết lập nhạy cảm chỉ dùng một lần — đảm bảo Claude luôn load đúng context khi bạn chuyển từ dự án cá nhân sang dự án công ty, hoặc từ code thử nghiệm sang production.

Giải thích chi tiết

Global Settings: "Bản ngã" của bạn trên mọi dự án

Global settings sống trong thư mục ~/.claude/ (macOS/Linux) hoặc %USERPROFILE%\.claude\ (Windows). Đây là nơi định nghĩa "con người" của bạn — những thứ không đổi dù bạn làm việc ở đâu:

• Phong cách lập trình cá nhân: Thích indent 2 spaces hay 4 spaces, dùng single quote hay double quote, giới hạn dòng bao nhiêu ký tự
• API keys cá nhân: Claude API key, token dịch vụ bạn dùng xuyên suốt như OpenAI, Gemini
• Memory cá nhân: File ~/.claude/CLAUDE.md mô tả background ("Tôi là full-stack dev ưu tiên React và Node, không thích Java legacy")
• Custom skills cá nhân: Các skill định nghĩa trong ~/.claude/skills/ dùng cho mọi repo, ví dụ skill viết commit message theo chuẩn Conventional Commits

Global settings giống như "default personality" — được load đầu tiên mỗi khi session bắt đầu, tạo nên baseline cho mọi tương tác.

Project Settings: "Luật chơi" chung của team

Khi Claude phát hiện bạn đang trong một git repository, nó tự động load thêm settings từ thư mục .claude/ ở root của repo. Đây là nơi định nghĩa quy chuẩn team:

• CLAUDE.md dự án: Quy tắc kiến trúc (ví dụ: "Luôn dùng Repository Pattern", "Không được phép dùng any trong TypeScript"), thông tin về tech stack (Next.js 14, Prisma, PostgreSQL), và link đến tài liệu nội bộ
• MCP servers: File .mcp.json hoặc .claude/mcp.json định nghĩa kết nối đến database staging, API nội bộ, hay tools đặc thù (ví dụ: MCP server kết nối hệ thống VietQR của công ty)
• Custom commands: Các slash commands trong .claude/commands/ như /deploy-staging hay /run-e2e mà cả team dùng chung để đồng nhất workflow
• Permission modes mặc định: Có thể bắt buộc dự án này luôn dùng plan mode cho production code, trong khi dự án side-project dùng auto mode

Project settings được git-tracked (nếu bạn add vào repo), nên chúng đồng bộ với toàn team. Khi member mới clone repo về, họ tự động inherit toàn bộ setup — không cần onboarding dài dòng.

Local Settings: "Bộ nhớ ngắn hạn" cho dữ liệu nhạy cảm

Local scope không lưu file — nó chỉ tồn tại trong session hiện tại và biến mất khi bạn gõ exit. Đây là "working memory" tạm thời cho những thứ không thể để lộ:

• Environment variables nhạy cảm: API keys của khách hàng ngân hàng, connection string production database chứa password, tokens truy cập hệ thống thanh toán VietQR live mà bạn không muốn lưu vào file (tránh leak lên GitHub)
• Context tạm thời: Thông tin về task one-time (ví dụ: "Trong session này, tôi đang debug issue #1234 liên quan đến lỗi thanh toán Momo, hãy tập trung vào file payment-gateway.ts")
• Override đặc biệt: Tạm thời override một setting Project/Global cho một task cụ thể mà không ảnh hưởng đến các lần dùng sau (ví dụ: đang demo cho sếp, bật dontAsk cho mượt rồi tắt ngay sau)

Local scope hoạt động như "chế độ riêng tư" (incognito mode) — hoàn hảo cho những thao tác nhạy cảm hoặc thử nghiệm mà bạn không muốn để lại dấu vết trên disk.

Cơ chế kế thừa: Quy tắc vàng Local > Project > Global

Khi cùng một setting được định nghĩa ở nhiều nơi, độ ưu tiên là:

Local thắng > Project thắng > Global

Cơ chế này tạo ra sự linh hoạt tối đa:

1. Global đặt default an toàn (ví dụ: permission mode là acceptEdits để luôn hỏi trước khi sửa file)
2. Project override cho dự án cụ thể (ví dụ: dự án nội bộ tin cậy dùng auto mode cho nhanh)
3. Local ghi đè tạm thời cho tình huống đặc biệt (ví dụ: đang sửa chữa nóng production, cần quyền dontAsk nhưng chỉ trong 30 phút này)

Ví dụ thực tế

Lập trình viên freelance với 2 client khác biệt

Anh Minh làm freelance cho ví điện tử Momo (fintech) và một sàn TMĐT như Tiki (e-commerce):

• Global (~/.claude/CLAUDE.md): "Tôi thích dùng VS Code keybindings, theme tối, luôn viết comment bằng tiếng Anh, và ưu tiên giải pháp đơn giản hơn clever code"
• Project Momo (.claude/CLAUDE.md): "Tech stack: Java Spring Boot, PostgreSQL. Coding convention: camelCase, 4 spaces indentation. Luôn dùng plan mode vì code liên quan đến tiền bạc. MCP server kết nối vào database staging qua VPN nội bộ"
• Project Tiki (.claude/CLAUDE.md): "Tech stack: Next.js, Prisma, Tailwind. Coding convention: snake_case cho database fields. Dùng auto mode cho nhanh. MCP server kết nối Vercel và Stripe test environment"

Khi Minh chuyển từ thư mục Momo sang Tiki, Claude tự động "thay đổi tính cách": từ conservative Java dev chú trọng security sang nhanh nhẹn JavaScript dev chú trọng UX, không cần Minh nhắc lại preferences.

Kỹ sư dữ liệu phân tích production data ngân hàng

Chị Lan cần phân tích dữ liệu giao dịch thực của một ngân hàng lớn như Techcombank:

• Local settings: Export DATABASE_URL trỏ đến production read-replica (connection string chứa password mạnh) ngay trong terminal session
• Tại sao không Global: Vì chị không muốn password production nằm trong ~/.claude/ - sợ sau này copy nhầm lên máy cá nhân hoặc sync lên iCloud
• Tại sao không Project: Vì .claude/ được git-tracked, đưa secrets vào đây là nguy cơ leak lên GitHub public repo hoặc lộ trong PR
• Kết quả: Sau khi phân tích xong và export báo cáo, chị gõ exit, mọi trace của connection string biến mất hoàn toàn khỏi RAM, không để lại file log hay history nào

Standardization cho team 10 người tại startup

Lead dev Khánh muốn cả team dùng Claude Code đồng nhất tại công ty logistics nội địa:

• Project settings: Khánh tạo .claude/CLAUDE.md với quy tắc: "Stack: React + TypeScript + Zod. Rule: Không bao giờ dùng as any. Luôn viết test cho utils. Khi thấy bug, dùng /debug command trước khi sửa"
• MCP config: File .mcp.json pre-configure sẵn MCP server cho GitHub Enterprise, Jira nội bộ, và Slack channel #dev-alerts
• Custom commands: .claude/commands/pr-ready.md định nghĩa checklist trước khi tạo PR (chạy lint, test, update changelog, kiểm tra VietQR test credentials đã được mock chưa)
• Triển khai: Cả team clone repo về, tự động inherit toàn bộ setup. New member chỉ cần chạy claude là đã có đầy đủ context và tools, giảm thời gian onboarding từ 3 ngày xuống 30 phút.

Ứng dụng theo đối tượng

Solo Developer (Lập trình viên cá nhân)

Dùng Global cho "con người" của bạn (sở thích, phong cách code), và Project cho từng repo khác nhau. Ví dụ: repo Python phân tích data cho Shopee có conventions khác hẳn repo React frontend cho blog cá nhân, nhưng cả hai đều inherit theme và keybindings từ Global.

Team Lead và Enterprise

Project settings trở thành "bible" cho team. Thông qua .claude/, bạn có thể:

• Enforce coding standards (Claude sẽ tự động suggest đúng convention khi review code)
• Pre-configure MCP servers cho mọi member (không cần hướng dẫn setup từng người cách kết nối database nội bộ)
• Tạo custom slash commands cho workflow nội bộ (ví dụ: /release-patch với đầy đủ bước kiểm thử và đồng bộ Jira)

Freelancer với nhiều client

Tách biệt hoàn toàn giệt Global, Project và Local để tránh lẫn lộn. Client A (ngân hàng) yêu cầu strict security rules và dùng AWS; Client B (startup giáo dục) dùng Firebase và cần move nhanh. Settings không bao giờ lẫn lộn vì mỗi project folder có .claude/ riêng biệt, và secrets của client A không bao giờ lộ ra khi làm việc cho client B nhờ Local scope.

Sinh viên và Người mới học code

Global settings giúp bạn tạo "training wheels" — ví dụ: set permission mode là plan để Claude luôn giải thích trước khi sửa code, giúp bạn học từng bước logic sửa lỗi. Project settings cho từng assignment (bài tập React, bài tập Python) giúp bạn tập trung vào yêu cầu cụ thể mà không bị nhiễu bởi context các môn khác.

So sánh các phạm vi Settings

So sánh với IDE truyền thống

Nếu bạn quen VS Code:

• VS Code User Settings ≈ Claude Global (preferences cá nhân dùng mọi nơi)
• VS Code Workspace Settings ≈ Claude Project (theo dự án cụ thể)

Điểm khác biệt then chốt của Claude Code là layer Local — VS Code không có khái niệm tương đương cho ephemeral settings. Điều này cho phép Claude xử lý sensitive operations an toàn hơn so với việc lưu secrets vào .vscode/settings.json có nguy cơ bị commit nhầm.

Bài viết liên quan

Cùng cụm (Core Concepts)

• Vòng lặp Agent: Claude Code hoạt động thế nào? — Hiểu cách Claude sử dụng settings trong agent loop để đọc file và chạy lệnh
• Hệ thống Tools và Permission — Settings quyết định tools nào được phép dùng và permission mode nào được áp dụng
• Context Window 200K token — Settings ảnh hưởng đến cách context được quản lý trong giới hạn token
• CLAUDE.md: Hướng dẫn viết project instructions — File quan trọng nhất trong Project settings, nơi định nghĩa "luật chơi" dự án
• 6 chế độ Permission — Cách settings điều khiển hành vi permission của Claude từ auto đến plan

Đọc tiếp

• Workflow hàng ngày với Slash Commands — Áp dụng Global và Project settings vào thực chiến hàng ngày với /plan, /commit, /debug
• Memory System và CLAUDE.md nâng cao — Kỹ thuật tối ưu file CLAUDE.md trong Project settings để Claude nhớ sâu hơn
• Enterprise Setup và Managed Settings — Quản lý settings ở quy mô tổ chức lớn với SSO, SCIM và shared team configuration