Quản lý cấu hình - CLAUDE.md, settings.json, ghim model, phiên bản prompt, plugin

Một ứng dụng dùng Claude có nhiều thứ "không phải code" nhưng quyết định hành vi y như code: file chỉ dẫn, file settings, tên model, nội dung prompt, phiên bản plugin. Khi chúng nằm rải rác trong biến môi trường, script cài đặt và trí nhớ của từng người, sự cố production sẽ rất khó lần lại.

Bài này giúp bạn trả lời: mỗi loại cấu hình đặt ở đâu, ghim thế nào, và thay đổi qua quy trình nào?

Ví dụ xuyên suốt: đội phần mềm của công ty vận tải container

Một công ty vận tải container có 4 repo dùng Claude Code hằng ngày và một ứng dụng dùng Claude API để đọc vận đơn, chạy ở ba môi trường: dev, staging, production. Hiện trạng:

• Quy ước code chung của công ty được chép tay vào CLAUDE.md của cả 4 repo, và đã bắt đầu lệch nhau.
• Model và prompt của ứng dụng đọc vận đơn nằm lẫn trong biến môi trường, giá trị viết thẳng trong code và một script cài đặt không ai ghi tài liệu.
• Tuần trước, một plugin tự cập nhật lên bản mới làm hỏng một skill, và không ai biết bản cũ là bản nào.

CLAUDE.md theo tầng

Claude Code đọc CLAUDE.md từ nhiều tầng và cộng dồn chúng:

Các file ở thư mục cha được nạp khi mở phiên; file trong thư mục con nạp khi Claude làm việc ở đó. Ngoài ra:

• Luật chỉ áp dụng cho một phần code thì đặt trong .claude/rules/, có thể giới hạn theo đường dẫn file.
• CLAUDE.md có thể nhập file khác bằng @duong/dan/file.
• Repo đã có AGENTS.md cho công cụ khác: nếu không có CLAUDE.md, Claude Code đọc AGENTS.md.
• Docs khuyên mỗi file dưới 200 dòng; file dài tốn context và Claude làm theo kém hơn.

Trong ví dụ, quy ước chung đưa lên một tầng rộng (managed policy do IT triển khai cho máy của cả đội), còn CLAUDE.md của từng repo chỉ giữ phần riêng của repo đó.

settings.json: tầng nào thắng, file nào commit

Khi cùng một khoá có ở nhiều nơi, Claude Code lấy giá trị ở tầng cao nhất, theo thứ tự: managed settings, tham số dòng lệnh, .claude/settings.local.json (riêng bạn trong dự án), .claude/settings.json (cả đội), ~/.claude/settings.json (riêng bạn, mọi dự án).

Docs khuyên commit .claude/settings.json để ai clone repo cũng có cùng quyền, hook và plugin; còn .claude/settings.local.json thì không commit (Claude Code tự loại nó khỏi git khi tạo file). Như vậy thay đổi cấu hình và thay đổi code đi chung một pull request, được review cùng nhau, và checkout một commit cũ là có đúng cặp code và cấu hình của thời điểm đó.

Ghim model

Trên Claude API, mỗi model ID là một bản ghim cố định: model bên dưới không đổi trong suốt vòng đời của ID đó. Từ thế hệ 4.6, ID không còn ngày (claude-sonnet-5-5) và bản thân nó đã là bản ghim. Với model cũ hơn, ID có ngày (claude-sonnet-4-5-20250929), còn dạng ngắn (claude-sonnet-4-5) là alias trỏ tới bản mới nhất của dòng đó; cam kết "không đổi" chỉ áp cho ID, không áp cho alias.

Claude Code có alias riêng: sonnet, opus, fable… luôn trỏ tới bản được khuyên dùng và đổi theo thời gian. Muốn ghim thì dùng tên đầy đủ (claude-opus-5-5) hoặc biến môi trường như ANTHROPIC_DEFAULT_OPUS_MODEL.

Trong ví dụ, ứng dụng đọc vận đơn ghi model ID đầy đủ cho từng môi trường trong file cấu hình: staging có thể thử model mới trước, production chỉ đổi khi regression test đạt.

Prompt là cấu hình, phải có phiên bản

Prompt quyết định hành vi ứng dụng y như code. Quy tắc cơ bản: một nguồn duy nhất cho prompt, lưu trong version control cùng code, và mọi thay đổi prompt phải qua code review.

Có một cách khác khi dùng Claude Managed Agents: prompt nằm ở phía server. Mỗi lần cập nhật agent tạo ra một phiên bản mới không sửa được; session chọn phiên bản bằng số. Cookbook của Anthropic chỉ ra chỗ hở: không có bước duyệt nào cho thao tác cập nhật, và ai gọi bằng ID trần sẽ nhận ngay bản mới nhất. Cách đưa bước review trở lại: production luôn ghim một số phiên bản cụ thể, và con số đó nằm trong cấu hình có review. Tạo phiên bản mới thì dễ; đưa nó lên production (sửa con số ghim) mới phải qua review. Lùi lại chỉ là ghim về số cũ.

Plugin phụ thuộc: ghim phiên bản

Docs về plugin dependencies nói: một phụ thuộc không có ràng buộc phiên bản sẽ theo bản mới nhất của marketplace mỗi lần người dùng cập nhật. Nếu bản mới đổi tên một tool MCP mà plugin của bạn gọi, plugin hỏng với mọi người vừa cập nhật. Đó đúng là chuyện đã xảy ra trong ví dụ.

Khai báo phụ thuộc trong .claude-plugin/plugin.json với một dải phiên bản theo semantic versioning:

{
  "name": "doc-van-don",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "kho-ma-cang", "version": "~2.1.0" }
  ]
}

~2.1.0 nhận các bản vá 2.1.x nhưng không lên 2.2; ^2.0 nhận mọi bản 2.x; =2.1.0 ghim đúng một bản. Muốn lên bản mới thì thử trước rồi mới nới dải phiên bản. Người duy trì plugin được phụ thuộc phải gắn tag cho các bản phát hành để dải phiên bản phân giải được.

1. Chỉ dẫn cho Claude Code?CLAUDE.md đúng tầng, commit bản project
2. Quyền, hook, plugin cho cả đội?.claude/settings.json, commit; ngoại lệ riêng vào settings.local.json
3. Model của ứng dụng?Model ID đầy đủ, ghi theo từng môi trường
4. Prompt?Một nguồn, version control, review bắt buộc, ghim phiên bản trên production
5. Còn lạiPlugin phụ thuộc: khai dải phiên bản hoặc ghim đúng bản