Claude không theo CLAUDE.md, hook không chạy? Cách gỡ rối cấu hình Claude Code
Tóm tắt
Phần lớn lỗi cấu hình Claude Code là file sai vị trí, sai cú pháp matcher hoặc bị file khác ghi đè. Gỡ rối theo ba bước: xem cái gì đã nạp, thử với --safe-mode hoặc cấu hình sạch, rồi đọc log --debug.
Bạn viết quy tắc trong CLAUDE.md mà Claude không theo. Thêm hook mà nó không chạy. Cài MCP server mà không thấy tool đâu. Phần lớn những lúc như vậy không phải lỗi Claude Code, mà là file không được nạp, được nạp từ chỗ khác bạn tưởng, hoặc bị một file khác ghi đè. Tài liệu chính thức có hẳn một quy trình gỡ rối cấu hình; đây là phiên bản rút gọn để dùng ngay.
Bước 1: xem cái gì thực sự đã nạp
| Lệnh | Cho biết |
|---|---|
/context | Mọi thứ đang chiếm context: system prompt, tool, MCP, memory file, skill, hội thoại |
/memory | Vị trí các file CLAUDE.md và auto memory |
/skills, /hooks, /mcp | Skill, hook, MCP server đang hoạt động |
/permissions | Rule allow/deny đang có hiệu lực |
/status | Nguồn settings đang dùng, có managed settings không |
/doctor | Kiểm tra tổng thể: cài đặt, settings lỗi, extension thừa, kèm đề xuất sửa |
Nếu /context cho thấy CLAUDE.md đã nạp mà Claude vẫn không theo, vấn đề thường là cách viết: quy tắc mơ hồ, hai file mâu thuẫn, hoặc file quá dài khiến từng quy tắc bị loãng.
Những lỗi cấu hình hay gặp nhất
| Triệu chứng | Nguyên nhân | Cách sửa |
|---|---|---|
| Hook không chạy | matcher là mảng JSON, hoặc viết thường "bash" | Một chuỗi, dùng |: "Edit|Write"; tên tool viết hoa |
| Hook không chạy | Đặt trong file hooks riêng | Đặt dưới khoá "hooks" trong settings.json |
| Permission/hook toàn cục bị bỏ qua | Ghi vào ~/.claude.json | Ghi vào ~/.claude/settings.json (hai file khác nhau) |
| Giá trị trong settings.json không có tác dụng | Bị settings.local.json ghi đè | Kiểm tra thứ tự ưu tiên local → project → user |
| Skill không hiện | Đặt .claude/skills/ten.md | Phải là thư mục: .claude/skills/ten/SKILL.md |
| MCP trong .mcp.json không nạp | File nằm trong .claude/, hoặc dùng khoá servers | Đặt ở gốc repo, khoá mcpServers |
| MCP server lỗi khi mở từ thư mục khác | Dùng đường dẫn tương đối | Dùng đường dẫn tuyệt đối |
| Subagent bỏ qua CLAUDE.md | Explore và Plan không nạp CLAUDE.md | Nhắc lại chỉ dẫn trong prompt giao việc |
Bước 2: thử với cấu hình sạch
claude --safe-mode # tắt CLAUDE.md, skill, plugin, hook, MCP, lệnh tuỳ biến
# Sạch hoàn toàn: thư mục cấu hình mới, bỏ cấu hình dự án
mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources userHết lỗi trong safe mode nghĩa là nguyên nhân nằm ở một trong các tuỳ biến của bạn; bật lại từng phần để khoanh vùng. Vẫn lỗi thì xem managed settings (/status) và biến môi trường.
Bước 3: xem log chi tiết
claude --debug: log ghi lại từng sự kiện hook, matcher nào được kiểm tra, exit code.claude --debug=mcp: xem stderr của MCP server trong~/.claude/debug/<session-id>.txt.
Lưu ý
- CLAUDE.md là hướng dẫn, không phải hàng rào: việc tuyệt đối không được xảy ra hãy dùng permission hoặc hook.
- Rule Bash khớp chuỗi lệnh, không khớp chương trình: deny
Bash(rm *)không chặn/bin/rm; cần hook hoặc sandbox.
Áp dụng thế nào?
- Dev: Tập thói quen chạy
/contextvà/hooksngay sau khi đổi cấu hình. - Tech Lead: Thêm bảng "lỗi hay gặp" ở trên vào wiki nội bộ; chạy
claude doctortrong onboarding. - PM: Khi ai đó báo "Claude không theo quy tắc", hỏi trước: quy tắc đó có xuất hiện trong
/contextkhông?
Nguồn & tham khảo
- Debug your configuration — Claude Code Docs