Thiết lập Claude Code trước khi code: 9 bước để AI làm đúng việc, đúng chỗ

Cài Claude Code xong, phần lớn anh em gõ ngay câu lệnh đầu tiên. Sau đó thường rơi vào một trong hai cảnh: Claude hỏi xin phép ở mọi lệnh git status, hoặc được bật chế độ bỏ qua quyền rồi tự chạy những lệnh không ai duyệt. Cả hai đều đến từ việc chưa thiết lập gì.

Điều mình rút ra sau hơn một tháng rưỡi dựng lại chính trang này cùng Claude Code: khoảng mười lăm phút thiết lập ban đầu quyết định chất lượng làm việc nhiều hơn mọi mẹo viết prompt. Bài này đi qua chín bước theo thứ tự nên làm. Năm bước đầu quyết định Claude được làm gì và tin vào đâu: file cấu hình, chế độ quyền, luật allow/deny, CLAUDE.md và coding convention. Bốn bước sau là tắt dòng Co-Authored-By, dùng hook để ép quy tắc, cấu hình VS Code và giữ phiên làm việc gọn.

Nội dung viết theo tài liệu chính thức của Anthropic tại code.claude.com/docs (bản cập nhật ngày 17/10/2026, Claude Code v2.1.301). Tên khoá cài đặt thay đổi theo phiên bản, nên anh em kiểm tra phiên bản của mình bằng claude --version trước khi chép cấu hình.

Biết file cấu hình nào thắng trước khi sửa bất cứ thứ gì

Claude Code đọc cấu hình từ nhiều file cùng lúc rồi gộp lại. Theo tài liệu Settings, thứ tự ưu tiên từ cao xuống thấp là: cấu hình quản lý của tổ chức (managed), tham số dòng lệnh, .claude/settings.local.json, .claude/settings.json và cuối cùng là ~/.claude/settings.json.

File	Phạm vi	Commit vào git?
~/.claude/settings.json	Cá nhân, mọi dự án	Không (nằm ngoài repo)
.claude/settings.json	Cả nhóm, một dự án	Có
.claude/settings.local.json	Cá nhân, một dự án	Không
Managed settings	Toàn tổ chức, do admin đặt	Không

Cách chia việc hợp lý: thói quen cá nhân (model, ngôn ngữ trả lời, chế độ quyền) để ở file người dùng; luật chung của dự án (lệnh được chạy, file cấm đọc) để ở .claude/settings.json và commit cho cả nhóm dùng chung. Khi bấm "Yes, and don't ask again" ở một hộp xin quyền, Claude Code ghi luật đó vào .claude/settings.local.json, nên file này sẽ dày lên dần theo thời gian.

Điểm đáng chú ý là hai chế độ auto và bypassPermissions đặt trong file của dự án sẽ bị bỏ qua. Lý do dễ hiểu: nếu không chặn, một repo lạ chỉ cần commit sẵn một dòng cấu hình là Claude tự chạy mọi lệnh ngay khi anh em mở dự án. Muốn dùng hai chế độ này thì đặt ở ~/.claude/settings.json.

Thêm dòng $schema ở đầu mỗi file để VS Code gợi ý tên khoá và báo lỗi gõ sai:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Chế độ quyền quyết định Claude được tự làm đến đâu

Chế độ quyền (permission mode) là công tắc tổng: nó quyết định hành động nào Claude được làm ngay, hành động nào phải chờ anh em bấm đồng ý. Tài liệu Permission modes liệt kê sáu chế độ:

Chế độ	Chạy không cần hỏi	Hợp khi
plan	Chỉ đọc và khám phá; không sửa file cho tới khi duyệt kế hoạch	Việc lớn, đụng nhiều file, chưa rõ cách làm
default (Manual)	Chỉ thao tác đọc	Mới làm quen, hoặc repo có thứ nhạy cảm
acceptEdits	Sửa file và lệnh file cơ bản (mkdir, mv, cp, rm…) trong thư mục dự án	Đã tin kế hoạch, muốn Claude sửa liền mạch
auto	Mọi thứ, có một model phân loại chạy nền duyệt từng hành động	Làm hằng ngày khi tài khoản hỗ trợ
bypassPermissions	Mọi thứ, trừ những gì luật deny chặn	Chỉ trong container hoặc máy ảo cô lập
dontAsk	Chỉ những gì đã có trong danh sách allow; còn lại tự từ chối	Chạy trong CI, không có người ngồi duyệt

Có ba cách đổi chế độ:

• Trong phiên: bấm Shift+Tab để xoay vòng Manual → Accept edits → Plan → Bypass (nếu được bật) → Auto (nếu tài khoản có). dontAsk không nằm trong vòng xoay này.
• Khi khởi động: claude --permission-mode plan.
• Mặc định lâu dài: khoá permissions.defaultMode trong file settings.

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Chế độ auto nghe như lời giải hoàn hảo, nhưng tài liệu của Anthropic ghi rõ nó "không bảo đảm an toàn". Bộ phân loại chặn những hành động vượt quá yêu cầu như curl | bash, force push hay deploy production, nhưng vẫn là một model đoán ý định. Chế độ này cần model đời mới (Opus 4.6, Sonnet 4.6 trở lên trên API của Anthropic) và từ v2.1.283 là chế độ khởi đầu mặc định của phiên tương tác.

bypassPermissions (tương đương cờ --dangerously-skip-permissions) đáng dè chừng hơn cả: luật allow không còn tác dụng, chỉ luật deny còn hiệu lực, và các thư mục .git, .claude cũng không được bảo vệ. Tổ chức muốn cấm hẳn thì đặt "disableBypassPermissionsMode": "disable" trong mục permissions của managed settings.

Cá nhân mình thấy cách an toàn và đỡ phiền nhất là: dùng plan cho việc lớn, acceptEdits hoặc auto cho việc thường ngày, cộng với danh sách allow/deny ở bước tiếp theo. Bypass chỉ dành cho máy ảo dùng xong là xoá.

Viết danh sách lệnh allow, ask, deny như viết luật tường lửa

Chế độ quyền là công tắc tổng, còn luật quyền (permission rules) là danh sách chi tiết cho từng lệnh. Có ba nhóm: allow chạy luôn, ask luôn hỏi, deny cấm hẳn. Theo tài liệu Permissions, Claude Code xét theo thứ tự deny → ask → allow, luật khớp đầu tiên thắng, và độ cụ thể của luật không làm đổi thứ tự này.

Dưới đây là cấu hình mẫu cho một dự án .NET đang chạy production, đặt ở .claude/settings.json. Danh sách deny lấy từ bảng "Không được làm" trong quy tắc AI của chính blog này: không push, không SSH tới server, không chạy migration, không đọc file bí mật.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(dotnet build *)",
      "Bash(dotnet run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git clean *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(ssh *)",
      "Bash(rsync *)",
      "Bash(dotnet ef *)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./src/**/appsettings.Production.json)"
    ]
  }
}

Một số quy tắc cú pháp cần nhớ:

• Dấu sao sau khoảng trắng: Bash(ls *) khớp ls -la nhưng không khớp lsof. Dạng cũ Bash(ls:*) vẫn chạy, nhưng chỉ khi dấu sao nằm cuối.
• Lệnh ghép được tách ra xét riêng: với &&, ||, ;, |, mỗi lệnh con phải khớp luật. git status && git push vẫn bị chặn ở vế sau.
• Đường dẫn file theo cú pháp gitignore: ./path tính từ thư mục hiện tại, /path tính từ gốc dự án (không phải đường dẫn tuyệt đối), //path mới là tuyệt đối, ~/path tính từ thư mục người dùng.
• Không có .claudeignore: tài liệu ghi rõ file này không có tác dụng. Muốn giấu file thì dùng luật Read trong deny; cấm đọc cũng cấm luôn sửa và ghi file đó.
• Công cụ khác: WebFetch(domain:docs.microsoft.com) cho trang web, mcp__github__* cho công cụ MCP.

Nhưng thực tế, luật Bash chỉ so khớp chuỗi lệnh. Tài liệu đưa ví dụ Bash(git push *) không chặn được git -C . push, và Bash(curl *) không chặn được sh -c 'curl …'. Nói gọn lại, deny là hàng rào chống nhầm lẫn, không phải ranh giới bảo mật. Thứ thật sự không được xảy ra thì cần thêm hook (bước 7) hoặc sandbox.

Gõ /permissions trong phiên để xem toàn bộ luật đang áp dụng và mỗi luật đến từ file nào. Đây là cách nhanh nhất để biết vì sao một lệnh cứ bị hỏi mãi.

CLAUDE.md là nơi chỉ cho AI đâu là nguồn sự thật

Mỗi phiên Claude Code bắt đầu với bộ nhớ trống về dự án. Thứ duy nhất nó tự đọc khi khởi động là các file CLAUDE.md, nên đây là nơi đặt những gì AI cần biết trước khi động vào code. Theo tài liệu Memory, file này có ở nhiều cấp:

• ~/.claude/CLAUDE.md: thói quen cá nhân, áp dụng cho mọi dự án.
• ./CLAUDE.md hoặc ./.claude/CLAUDE.md: quy tắc của dự án, commit cho cả nhóm.
• ./CLAUDE.local.md: ghi chú riêng trong dự án, nhớ thêm vào .gitignore.
• CLAUDE.md trong thư mục con: chỉ nạp khi Claude làm việc với file trong thư mục đó.

Lỗi hay gặp nhất khi làm việc với AI không phải code sai cú pháp, mà là AI tự suy ra một hành vi rồi viết code theo suy luận đó. Cách chặn là viết hẳn ra thứ tự ưu tiên nguồn thông tin và việc phải làm khi các nguồn mâu thuẫn:

# CLAUDE.md

## Nguồn sự thật (theo thứ tự ưu tiên)
1. Tài liệu thiết kế trong `docs/design/`: kiến trúc, database, các quyết định (ADR).
2. Đặc tả yêu cầu trong `docs/srs/`.
3. Code hiện có.

- Tài liệu và code mâu thuẫn: dừng lại, báo cả hai chỗ, không tự chọn bên nào.
- Không tìm thấy thông tin trong ba nguồn trên: hỏi lại, không suy diễn.
- Khi khẳng định một hành vi: ghi rõ đã kiểm ở file nào, điều gì là suy luận.
- Một chỗ trông "sai chuẩn" thường có lý do: tra `docs/design/decisions.md` trước khi đề xuất sửa.

## Quy tắc làm việc
@docs/conventions/ai-rules.md

Dòng @docs/conventions/ai-rules.md là cú pháp import: Claude Code nạp nội dung file đó vào cùng lúc với CLAUDE.md. Đường dẫn tính từ file đang import, lồng tối đa bốn cấp. Nhờ vậy CLAUDE.md chỉ cần ngắn gọn, phần chi tiết tách ra file riêng để người cũng đọc được. Tài liệu khuyên mỗi file CLAUDE.md nên dưới 200 dòng; repo của blog này dùng đúng cách đó, CLAUDE.md 22 dòng import một file quy tắc 102 dòng.

Không muốn viết từ đầu thì gõ /init để Claude đọc repo và sinh bản nháp, sau đó sửa lại bằng tay. Lệnh /memory mở nhanh các file này để chỉnh. Ngoài ra Claude Code còn có bộ nhớ tự động (auto memory), lưu ở ~/.claude/projects/<dự án>/memory/, bật mặc định; thứ gì cả nhóm cần biết thì vẫn nên nằm trong CLAUDE.md của repo.

Coding convention phải là quy tắc kiểm được, không phải khẩu hiệu

Câu "hãy viết code sạch, theo best practice" gần như không có tác dụng, vì model vốn đã cố làm vậy, và "best practice" của nó chưa chắc là của dự án anh em. Thứ AI cần là những quyết định riêng của dự án mà nó không thể tự đoán: dùng thư viện nào, cấm pattern nào, xong việc phải chạy lệnh gì.

Claude Code hỗ trợ thư mục .claude/rules/: mỗi file .md là một nhóm quy tắc, và phần đầu file (frontmatter) paths giới hạn quy tắc chỉ nạp khi Claude làm việc với file khớp mẫu. Nhờ vậy quy ước C# không chiếm chỗ trong ngữ cảnh khi Claude đang sửa CSS.

---
paths:
  - "src/**/*.cs"
  - "src/**/*.razor"
---
# Quy ước C#

- Truy cập DB qua `IDbContextFactory<BlogDbContext>`, không inject `BlogDbContext`.
  Vì sao: component Blazor sống lâu, DbContext không an toàn khi dùng song song.
- SQL thô chỉ qua `ExecuteSqlAsync($"…{param}…")`; không ghép chuỗi vào `ExecuteSqlRaw`.
  Vì sao: chống SQL injection.
- Không thêm package NuGet khi chưa được đồng ý.
- Xong việc: `dotnet build` 0 error, không thêm warning mới. Build lỗi thì báo kèm output.

Ba nguyên tắc khi viết bộ convention cho AI:

1. Mỗi quy tắc kiểm được bằng mắt hoặc bằng lệnh. "Hàm ngắn gọn" không kiểm được; "hàm không quá 40 dòng" thì kiểm được.
2. Ghi lý do ngay dưới quy tắc. Có lý do, Claude xử lý đúng các trường hợp quy tắc không nói tới.
3. Thứ gì máy kiểm được thì giao cho máy. Định dạng, thụt lề, thứ tự import để cho .editorconfig, formatter và linter; file quy tắc dành cho những quyết định mà công cụ không biết.

Nếu dự án đã có tài liệu convention cho người đọc, đừng chép lại vào .claude/rules/. Chỉ cần import nó từ CLAUDE.md để người và AI đọc chung một nguồn, sửa một chỗ là cả hai cùng cập nhật.

Tắt dòng Co-Authored-By nếu không muốn commit ghi tên AI

Mặc định, mỗi commit Claude Code tạo ra có thêm dòng Co-Authored-By: <tên model> <noreply@anthropic.com>, và mô tả pull request có dòng "🤖 Generated with Claude Code". GitHub đọc dòng Co-Authored-By và hiện Claude như một đồng tác giả của commit.

Có công ty muốn giữ dòng này để minh bạch, cũng có dự án khách hàng không cho phép. Cấu hình nằm ở khoá attribution, theo Settings reference:

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

• commit: nội dung dòng thêm vào cuối commit; chuỗi rỗng là tắt.
• pr: dòng thêm vào mô tả pull request; chuỗi rỗng là tắt.
• "attribution": false: tắt toàn bộ một lần, cần v2.1.281 trở lên.

Khoá cũ includeCoAuthoredBy đã bị đánh dấu ngừng dùng từ v2.0.62; Claude Code chỉ còn đọc nó khi không có khoá attribution. Anh em nào chép cấu hình từ bài viết cũ nên đổi sang khoá mới. Muốn tắt cho mọi dự án thì đặt ở ~/.claude/settings.json; nếu là quy định của nhóm thì đặt ở .claude/settings.json để mọi người cùng áp dụng.

Nhân tiện, nên ghi thêm vào CLAUDE.md hai điều mà settings không quản: commit chỉ khi được yêu cầu, và commit message viết theo quy ước nào (ngôn ngữ, tiền tố, độ dài dòng đầu).

Hook biến quy tắc "nên làm" thành "bắt buộc làm"

Mọi thứ viết trong CLAUDE.md và .claude/rules/ đều là chỉ dẫn cho model, và trong một phiên dài model có thể bỏ sót. Hook là lệnh shell do chính Claude Code chạy ở những thời điểm cố định, không phụ thuộc vào việc model có nhớ hay không. Theo tài liệu Hooks, hai thời điểm dùng nhiều nhất là PreToolUse (trước khi chạy công cụ, chặn được) và PostToolUse (sau khi chạy xong).

Ví dụ thứ nhất: tự chạy formatter mỗi khi Claude sửa hoặc tạo file, để code luôn đúng định dạng mà không cần nhắc.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Ví dụ thứ hai: chặn sửa những file không được đụng. Hook nhận thông tin công cụ qua stdin dạng JSON; script thoát với mã 2 thì hành động bị chặn, nội dung ghi ra stderr được gửi lại cho Claude để nó biết vì sao.

#!/usr/bin/env bash
# .claude/hooks/protect-files.sh
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.env|*/secrets/*|*/appsettings.Production.json)
    echo "Không được sửa $file: file chứa bí mật, sửa tay trên server." >&2
    exit 2 ;;
esac
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

Hai ví dụ trên cần có jq trong PATH; trên Windows, Git Bash không cài sẵn công cụ này. Quyết định chặn của hook có hiệu lực cao hơn luật allow, nên đây là chỗ đặt những ranh giới thật sự quan trọng. Gõ /hooks để xem hook nào đang bật.

VS Code dùng chung cấu hình với CLI, nhưng có vài khoá riêng

Extension Claude Code cài từ Marketplace (tìm "Claude Code", cần VS Code 1.94.0 trở lên), đăng nhập bằng tài khoản Claude. Một điểm hay bị nhầm: cài extension không đưa lệnh claude vào PATH, muốn dùng trong terminal thì cài thêm bản CLI.

Các khoá đáng chỉnh trong settings.json của VS Code, theo tài liệu VS Code:

Khoá	Mặc định	Tác dụng
claudeCode.preferredLocation	—	panel hoặc sidebar: mở Claude ở khung nào
claudeCode.initialPermissionMode	—	Chế độ khi mở hội thoại mới: default, plan, acceptEdits, bypassPermissions
claudeCode.allowDangerouslySkipPermissions	false	Có hiện lựa chọn Bypass hay không
claudeCode.respectGitIgnore	true	Bỏ file trong .gitignore khỏi tìm kiếm
claudeCode.attachOpenFile	true	Tự đính kèm file đang mở vào ngữ cảnh
claudeCode.environmentVariables	[]	Biến môi trường cho phiên Claude
claudeCode.useTerminal	false	Chạy giao diện dòng lệnh thay cho khung đồ hoạ

Lưu ý: initialPermissionMode không nhận giá trị auto. Muốn dùng Auto thì để trống khoá này và chọn ở nút chế độ dưới ô nhập. Extension cũng không đọc chế độ khởi đầu từ .claude/settings.json của dự án.

Ba thao tác dùng nhiều nhất:

• Ctrl+Esc (macOS: Cmd+Esc): chuyển qua lại giữa editor và khung Claude.
• Alt+K (macOS: Option+K): chèn tham chiếu tới đoạn code đang chọn, kèm số dòng, vào câu lệnh.
• Ở chế độ Manual, mỗi thay đổi hiện dạng diff hai cột để chấp nhận hoặc từ chối từng chỗ; ở chế độ Plan, kế hoạch mở thành file Markdown để anh em ghi chú ngay trên đó.

Anh em nào dùng CLI trong terminal của VS Code thì chạy thêm /terminal-setup một lần để Shift+Enter xuống dòng được thay vì gửi luôn câu lệnh.

Giữ phiên làm việc gọn để Claude không lạc giữa chừng

Phần cuối là những cài đặt nhỏ nhưng dùng hằng ngày. Một file ~/.claude/settings.json cá nhân có thể trông như sau:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "opus",
  "effortLevel": "high",
  "language": "Vietnamese",
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 60,
  "attribution": { "commit": "", "pr": "" },
  "permissions": { "defaultMode": "acceptEdits" }
}

• model, effortLevel: model và mức suy nghĩ mặc định (low, medium, high, xhigh). Đổi nhanh trong phiên bằng /model và /effort.
• language: ngôn ngữ Claude dùng để trả lời, đỡ phải nhắc "trả lời bằng tiếng Việt" ở mỗi phiên.
• autoUpdatesChannel: stable nhận bản ổn định, latest nhận bản mới nhất. Máy làm dự án thật nên dùng stable.
• cleanupPeriodDays: số ngày giữ lịch sử phiên và checkpoint, mặc định 30.
• statusLine: dòng trạng thái dưới ô nhập, hiện model, nhánh git, mức dùng ngữ cảnh. Gõ /statusline để Claude tự cấu hình.

Trong phiên, bốn lệnh giúp ngữ cảnh không phình quá mức:

• /context: xem ngữ cảnh đang bị chiếm bởi những gì (CLAUDE.md, file đã đọc, lịch sử hội thoại).
• /compact: tóm tắt hội thoại để giải phóng chỗ, có thể kèm chỉ dẫn giữ lại điều gì.
• /clear: xoá hội thoại khi chuyển sang việc khác hẳn. Rẻ và sạch hơn để phiên cũ kéo dài.
• Esc Esc hoặc /rewind: quay về checkpoint trước đó, khôi phục code, hội thoại hoặc cả hai.

Đáng tiếc là checkpoint không theo dõi thay đổi do lệnh Bash tạo ra (rm, mv, cp) và thay đổi anh em sửa tay ngoài Claude. Theo tài liệu Checkpointing, đây không phải thứ thay thế git, nên vẫn cần commit thường xuyên.

Khi đã quen: skill, subagent, MCP

Tính năng	Đặt ở đâu	Dùng khi
Skill	.claude/skills/<tên>/SKILL.md	Một quy trình lặp lại: review, viết tài liệu, chuẩn bị release
Subagent	.claude/agents/<tên>.md	Việc cần ngữ cảnh riêng, như tìm kiếm rộng trong repo lớn
MCP	.mcp.json hoặc claude mcp add	Kết nối công cụ ngoài: GitHub, Jira, cơ sở dữ liệu

Ba thứ này đều nằm trong thư mục .claude/ hoặc gốc repo, commit được để cả nhóm dùng chung. Chưa cần ngay ở ngày đầu; thêm khi thấy mình lặp lại một kiểu yêu cầu từ lần thứ ba trở đi.

Checklist mười lăm phút cho dự án mới

Nói gọn lại, thiết lập ban đầu là việc chia vai: settings quyết định Claude được làm gì, CLAUDE.md quyết định Claude tin vào đâu, còn hook giữ những ranh giới không được vượt qua. Làm một lần, commit vào repo, cả nhóm cùng hưởng.

Anh em đang để Claude Code ở chế độ quyền nào khi làm dự án thật, và đã có lệnh nào nằm trong danh sách deny của mình?