Cách cấu hình Claude Code Hooks giúp tự động định dạng và kiểm thử code

Claude Code hooks là cơ chế chạy một lệnh bất kỳ khi một sự kiện nhất định xảy ra, chẳng hạn khi Claude vừa chỉnh sửa file thành công. Nhờ hook, bạn có thể tự động định dạng file hoặc chạy test mà không phải nhắc Claude làm những việc đó mỗi lần. Bạn có thể tìm hiểu thêm về tính năng này trong tài liệu hooks của Anthropic.

Trong bài hướng dẫn này, Quantrimang.com sẽ giúp bạn:

• Xây dựng một máy tính phí vận chuyển nhỏ.
• Tự động định dạng file cài đặt sau mỗi lần ghi.
• Chạy năm bài kiểm tra sau các lần chỉnh sửa được chọn.
• Cố ý gây ra một lỗi, xem bài test nào phát hiện, rồi sửa lại code.

Ví dụ này theo dõi hai công cụ Edit và Write của Claude trên ba file được chỉ định. Lệnh shell và thao tác sửa tay trong trình soạn thảo nằm ngoài phạm vi kiểm tra. Nếu bước kiểm tra sau chỉnh sửa thất bại, thay đổi đã lưu vẫn được giữ nguyên, vì PostToolUse chỉ chạy sau khi công cụ đã thực hiện thành công.

1. Claude Code hooks là gì?

Một hook nối một sự kiện với một hành động. Trong bài này, sự kiện là “Claude vừa chỉnh sửa file thành công”, còn hành động là một script cục bộ có nhiệm vụ định dạng file cài đặt, chạy test và báo kết quả.

Chúng ta dùng sự kiện PostToolUse, chạy sau khi một lần gọi công cụ thành công. Nếu cần kiểm tra trước khi công cụ chạy, hãy dùng PreToolUse. Tài liệu tham chiếu hooks của Anthropic mô tả đầy đủ các sự kiện và giới hạn của chúng.

Quy tắc thực hành rất đơn giản: phí vận chuyển là 5 USD nếu tổng đơn hàng dưới 50 USD, và 0 USD nếu từ 50 USD trở lên. Chỉ cần đổi một phép so sánh là quy tắc này bị phá vỡ, trong khi code vẫn dễ đọc và vẫn chạy được. Đây chính là loại lỗi lý tưởng để thực hành kiểm thử.

2. Bạn cần chuẩn bị gì?

• Bản cài đặt Claude Code mới trong terminal
• Một trình soạn thảo văn bản
• js 22.17.0 trở lên

Ví dụ này dùng trình chạy test có sẵn của Node, nên bạn không cần cài thêm gói nào. Các file đã được khắc phục trong bộ kit chuẩn bị sẵn được xác minh với Node.js 24.11.1 trên macOS 26.6. Script hỗ trợ dùng sự kiện test:summary có cấu trúc, được ghi trong tài liệu test runner của Node 22.17.0.

Kiểm tra công cụ trong terminal:

claude --version

node --version

Hãy dùng tài khoản Claude Code và cài đặt quyền như bình thường. Các file hook cục bộ không gọi mô hình hay mạng và không yêu cầu thêm gói thuê bao AI nào. Tuy nhiên, việc nhờ Claude tạo, sửa hoặc khắc phục file vẫn tiêu tốn hạn mức Claude Code của bạn.

Lưu ý an toàn quan trọng:

• Hãy bắt đầu trong một thư mục thực hành trống.
• Đọc kỹ code của hook và test trước khi bật. Hook dạng lệnh chạy với toàn quyền người dùng của bạn, và test thực thi code của dự án trên máy.
• Không đặt file khách hàng thật, mật khẩu hay quyền triển khai vào bài thực hành.
• Trong phiên tương tác, Claude Code giữ lại các hook trong file settings cho đến khi bạn chấp nhận workspace trust. Hãy xem lại.claude/settings.json và cả hai file hook trước, rồi chỉ tin cậy thư mục thực hành dùng một lần này.

3. Các lỗi thường gặp khi dùng hooks

Mẹo ghi nhật ký riêng tư: để xem chính xác Claude Code đã chạy những gì, hãy bắt đầu phiên thực hành bằng:

claude --debug-file hook-debug.log

Kiểm tra file log sau khi chỉnh sửa. Hãy giữ file này ở chế độ riêng tư vì log có thể chứa đường dẫn cục bộ và chi tiết công việc. Cờ này được ghi trong tài liệu CLI.

Nếu bạn dùng máy của tổ chức, họ có thể giới hạn hook nào được chạy. Hãy tuân theo chính sách đó thay vì thay đổi quyền toàn cục để ép ví dụ này chạy. Tài liệu settings giải thích về managed settings và thứ tự ưu tiên.

4. Hooks, permissions, Skills và mods khác nhau thế nào?

Anthropic ghi nhận permissions, Skills và mods là các tính năng riêng, có một số điểm giao nhau. Hãy chọn thiết lập nhỏ nhất đủ cho nhiệm vụ.

Bài hướng dẫn về Claude Code mods của chúng tôi giới thiệu một câu hỏi duyệt tùy chỉnh trước các lần sửa được chọn. Bài này thêm bước kiểm tra sau khi sửa, để bạn học và thử từng phần độc lập. Ngoài ra, hướng dẫn Claude Code Insights giúp bạn nhận ra các vấn đề lặp lại trong phiên lập trình. Khi nó chỉ ra một bước kiểm tra thường quên, bạn có thể dùng quy trình hook này để thử một cải tiến.

5. Các bước thực hiện Claude Hook Code

Bước 1: Tạo dự án với kết quả đúng đã biết

Tạo thư mục claude-hooks-practice, mở bằng trình soạn thảo, mở terminal trong thư mục đó và khởi động Claude Code:

claude

Thành viên Pro có thể mở dự án chuẩn bị sẵn thay thế. Hook của dự án này chưa hoạt động cho đến khi bạn thêm cài đặt ở Bước 2. Hãy đọc README đi kèm trước khi dùng.

Xem lại ba file. File cài đặt cần chứa:

json

{ " freeShippingAt ": 50, " standardFee ": 5 }

Chạy test trong terminal trước khi thêm hook:

node --test shipping.test.cjs

Cả năm test phải đạt. Nếu có test lỗi, hãy sửa dự án ban đầu trước và kiểm tra kết quả kỳ vọng vẫn khớp với quy tắc vận chuyển đã nêu.

Bước 2: Thêm hook cho dự án, bắt đầu bằng định dạng

Nhờ Claude tạo hai file hook dưới đây (thành viên Pro đã có sẵn cả hai và chỉ cần xem lại):

Tạo hai file thực hành cục bộ: .claude/hooks/after-edit.cjs và .claude/hooks/run-shipping-tests.cjs. Chỉ dùng thư viện có sẵn của Node.js. Tạo file nhưng chưa bật.

Trong after-edit.cjs, đọc sự kiện hook dạng JSON từ đầu vào chuẩn. Chỉ xử lý PostToolUse cho hai công cụ Edit và Write. Đọc tool_input.file_path và yêu cầu đường dẫn tuyệt đối. Lấy thư mục chứa hook làm gốc dự án. Chỉ xử lý ba file shipping.json, shipping.cjs, shipping.test.cjs, bỏ qua các đường dẫn khác. Từ chối file thiếu, liên kết tượng trưng (symlink), liên kết cứng (hard link) và file lớn hơn 64 KB. Không quét thư mục khác.

Khi shipping.json thay đổi, phân tích và ghi lại cùng giá trị với thụt lề hai khoảng trắng và dòng mới ở cuối. Không đụng đến định dạng JavaScript. Nếu JSON không hợp lệ, báo lỗi mà không thay thế nội dung.

Hỗ trợ --format-only để bỏ qua toàn bộ test. Nếu không có tham số này, định dạng xong thì chạy helper cố định run-shipping-tests.cjs bằng process.execPath, không dùng shell, giới hạn 10 giây và giới hạn đầu ra.

Trong run-shipping-tests.cjs, dùng node:test run() chỉ cho shipping.test.cjs, đặt isolation là none và concurrency là false. Đọc các sự kiện test:fail và test:summary và in một kết quả JSON có cấu trúc. Không phân tích TAP dạng văn bản và không tìm lệnh test khác. Yêu cầu ít nhất năm test, không có test lỗi, bỏ qua, hủy hay todo.

Khi thành công, in ra JSON hook hợp lệ kèm systemMessage báo số test đạt. Khi thất bại, ghi lỗi có giới hạn và chi tiết cấu trúc ra stderr và thoát với mã 2, nói rõ chỉnh sửa đã được lưu. Không bao giờ hoàn tác chỉnh sửa, làm yếu test, tự duyệt công cụ, cài gói hay gọi mạng.

Hiển thị cả hai file và giải thích chúng đọc, thay đổi và thực thi những gì. Không sửa file settings cho đến khi tôi đồng ý.

Cấu trúc thư mục kết quả sẽ như sau:

claude-hooks-practice/

shipping.json

shipping.cjs

shipping.test.cjs

.claude/

hooks/

after-edit.cjs

run-shipping-tests.cjs

Chỉ phê duyệt hai file sau khi đã đọc kỹ. Sau đó tạo .claude/settings.json trong thư mục thực hành với cấu hình:

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "^(Edit|Write)$",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": [
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.cjs",
              "--format-only"
            ],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Đây là file settings cấp dự án. Với dự án có sẵn, hãy gộp mục mới vào cài đặt hiện tại, giữ nguyên các hook và quyền khác. Tài liệu settings giải thích sự khác nhau giữa settings cấp dự án, cục bộ, người dùng và managed.

Giải thích cấu hình:

• matcher chỉ chọn hai công cụ Edit và Write, sau đó script thu hẹp xuống ba file thực hành.
• Tham số cuối --format-only khởi động script ở chế độ chỉ định dạng.
• Dùng args tách riêng sẽ gọi lệnh không qua shell và để Claude Code thay đường dẫn dự án thành một tham số duy nhất, đúng như phần cấu hình hook dạng lệnh trong tài liệu.

Claude Code tự tải lại hầu hết thay đổi hook trong phiên đang chạy. Nhập /hooks và tìm mục PostToolUse của dự án. Nếu không thấy, dùng /status để tìm lỗi settings trước khi khởi động lại.

Bước 3: Kiểm chứng việc định dạng chạy sau khi ghi file

Hãy yêu cầu Claude:

Dùng công cụ Write để lưu shipping.json với đúng nội dung JSON một dòng này: {"freeShippingAt":50,"standardFee":5}. Giữ nguyên helper và test. Không tự chạy trình định dạng. Dừng lại sau khi ghi để tôi kiểm tra hook đã đổi gì.

Tự mở file đã lưu. File phải có bố cục nhiều dòng, thụt lề hai khoảng trắng như ở Bước 1, với hai con số không đổi.

Script mẫu trả về systemMessage thành công như sau:

[after-edit] Formatted shipping.json. Tests are off.

Claude Code hiển thị systemMessage như một cảnh báo hướng tới người dùng. Đây không phải bản ghi test hay lời xác nhận gửi cho Claude, nên hãy kiểm tra cả file đã lưu chứ đừng chỉ tin vào thông báo. Bộ định dạng này chỉ xử lý file JSON cài đặt, không định dạng các file JavaScript.

Trong lần kiểm thử gốc với Claude Code 2.1.293, một lệnh Write thật đã kích hoạt hook chỉ định dạng này, lưu hai giá trị với thụt lề hai khoảng trắng và không làm đổi mã băm của file test.

Với dự án lớn hơn, bạn có thể dùng trình định dạng như Prettier cho nhiều ngôn ngữ. Hãy dùng phiên bản đã được xem xét, cài cục bộ và giới hạn các file nó được chạm vào. Chỉ mở rộng sau khi ví dụ nhỏ này chạy tốt. Hướng dẫn cài đặt của Prettier giải thích cách ghim nó thành phụ thuộc của dự án.

Bước 4: Thêm bước chạy test vào cùng hook

Trong danh sách tham số của hook, chỉ xóa --format-only. Giữ nguyên đường dẫn script và các cài đặt khác:

json

"args" : [ "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.cjs" ]

Dòng này chỉ là một phần cấu hình, không phải file settings hoàn chỉnh. Thành viên Pro cũng có sẵn ví dụ đầy đủ gồm định dạng và test trong thư mục thiết lập.

Kiểm tra lại /hooks, rồi lặp lại yêu cầu ghi JSON một dòng ở Bước 3. Claude Code sẽ hiển thị thông báo:

[after-edit] PASS: 5 tests passed.

Vì sao gộp định dạng và test vào một script? Các hook handler khớp cùng lúc sẽ chạy song song, nên đặt hai handler riêng cho định dạng và test cạnh nhau không đảm bảo việc định dạng xong trước. Gộp vào một script cho phép định dạng trước, test sau.

Script của chúng ta chờ các bài test nhỏ này. Với ứng dụng thật, hãy chọn một bước kiểm tra nhanh cho mỗi lần sửa và chạy các bài test dài hơn ở thời điểm rà soát phù hợp. Tránh chạy toàn bộ bộ test chậm cho mọi thay đổi nhỏ.

Bước 5: Cố ý gây lỗi và đọc thông báo thất bại

Hãy yêu cầu Claude:

Dùng công cụ Edit để chỉ đổi phép so sánh >= thành > trong shipping.cjs. Đây là lỗi cố ý để thử nghiệm cục bộ. Giữ nguyên cài đặt vận chuyển và cả năm bài test. Để hook chạy, báo kết quả của nó, rồi dừng lại trước khi sửa gì. Không đổi công cụ, không tắt hook và không sửa test cho qua.

Phiên bản lỗi vẫn cho kết quả đúng với đơn dưới 50 USD và đơn trên 50 USD. Nhưng đơn đúng 50 USD giờ bị tính phí 5 USD. Bài test cho đúng giá trị này sẽ thất bại.

Trong lần kiểm tra khi đăng nhập Claude Code 2.1.293, một lệnh Edit thật đã kích hoạt hook và tạo ra thông báo lỗi:

[after-edit] Tests failed: 4 passed, 1 failed, 0 skipped, 0 todo, 0 cancelled.
- orders at $50 ship free: Expected values to be strictly equal: 5 !== 0; expected: 0; actual: 5
The tool's edit has already saved. Review the failure before continuing.

Hook trả mã thoát 2, phép so sánh lỗi vẫn được lưu và mã băm của file test ban đầu không đổi. PostToolUse gửi phản hồi lỗi này đến Claude sau kết quả công cụ. Cách hiển thị tương tác có thể khác tùy phiên bản, vì vậy hãy kiểm tra cả code đã lưu lẫn kết quả hook.

Vì sao lỗi vẫn còn đó? Vì PostToolUse không thể hoàn tác một công cụ đã chạy xong. Hãy giữ nguyên các bài test. Nếu đổi kết quả kỳ vọng thành 5 USD, bạn chỉ đang che giấu vấn đề.

Bước 6: Sửa code và xác minh kết quả

Gửi yêu cầu:

Khôi phục phép so sánh >= trong shipping.cjs bằng công cụ Edit. Giữ nguyên shipping.json và các bài test gốc. Để hook chạy và báo kết quả. Không commit, không triển khai và không đổi file khác.

Hook phải báo lại năm test đạt. Hãy kiểm tra rằng phép so sánh đã bao gồm dấu bằng, rồi chạy test độc lập:

node --test shipping.test.cjs

Kiểm tra cả file test và file cài đặt: chúng phải vẫn giữ chính sách vận chuyển và kết quả kỳ vọng ban đầu.

Bảng tổng kiểm toàn bộ bài thực hành:

Gói đã khắc phục lỗi của tác giả vượt qua toàn bộ 33 bài kiểm tra tích hợp cục bộ trên macOS 26.6 với Node.js 24.11.1, cùng năm bài test vận chuyển và bản demo lỗi rồi sửa được cô lập. Các kiểm tra này bao phủ định dạng, lỗi cố ý và việc sửa, test bị bỏ qua, đầu vào sai định dạng, đường dẫn không liên quan, bí danh đường dẫn, file liên kết và các trường hợp cục bộ khác.

33 kiểm tra đó gửi JSON sự kiện hook giả lập tới các script thật. Ngoài ra, tác giả đã xác minh mục dự án trong /hooks và chạy các lệnh Write và Edit thật với Claude Code 2.1.293 trên macOS cùng Node.js 24.11.1. Định dạng hoạt động, lỗi ngưỡng cố ý bị bắt, và việc khôi phục >= đưa năm test về trạng thái đạt mà không đổi các test gốc. Một lần chạy test độc lập ở terminal cũng đạt cả năm.

Bước 7: Tắt hook

Chỉ xóa mục lệnh này khỏi danh sách PostToolUse của dự án. Giữ nguyên các mục khác và cài đặt quyền. Claude Code sẽ tải lại thay đổi trong phiên đang chạy. Hãy kiểm tra /hooks để chắc mục đã biến mất. Chỉ khởi động lại khi trạng thái đã tải không cập nhật, sau khi bạn đã loại trừ lỗi settings.

Yêu cầu ghi lại JSON một dòng mà không nhờ Claude định dạng. Nếu không có trình định dạng nào khác đang hoạt động, file phải giữ nguyên một dòng. Bạn vẫn có thể tự chạy test vận chuyển.

Tác giả đã kiểm tra bằng phiên Claude Code mới: /hooks không còn hook dự án nào, lần Write kế tiếp không tạo sự kiện hook nào và JSON đã lưu vẫn nằm trên một dòng. Một lần Write file notes.txt không liên quan cũng bị script đã bật bỏ qua.

Đừng tắt toàn bộ hooks chỉ để gỡ một ví dụ hướng dẫn. Các hook khác có thể là những bước kiểm tra mà nhóm của bạn đang dựa vào.

6. Các công cụ AI lập trình khác để tham khảo

Nếu bạn muốn đối chiếu quy trình tự động hóa kiểm thử với các trợ lý khác đang phổ biến tại Việt Nam, hãy xem:

• GitHub Copilot: gợi ý code ngay trong VS Code, JetBrains, rất quen thuộc với lập trình viên Việt.
• Cursor: trình soạn thảo tích hợp AI, mạnh về sửa code theo ngữ cảnh toàn dự án.
• ChatGPT (OpenAI): hỗ trợ giải thích lỗi, viết test mẫu và tạo script nhỏ.
• Gemini (Google): tiện khi làm việc với hệ sinh thái Google và có công cụ cho nhà phát triển qua Gemini API.
• Windsurf, Cline: các lựa chọn khác cho lập trình có AI hỗ trợ.

Dù dùng công cụ nào, nguyên tắc chung vẫn giữ nguyên: tự động hóa bước kiểm tra, giữ nguyên bài test và luôn tự đọc lại code do AI viết.

7. Câu hỏi thường gặp

Claude Code hooks là gì?

• Là cơ chế chạy một lệnh khi một sự kiện chọn trước xảy ra, ví dụ sau khi Claude chỉnh sửa file thành công. Bạn dùng nó để tự động định dạng, chạy test hoặc báo cáo mà không phải nhắc Claude nhiều lần.

PostToolUse khác PreToolUse thế nào?

• PostToolUse chạy sau khi công cụ thành công, còn PreToolUse chạy trước khi công cụ thực hiện. Muốn chặn hoặc kiểm tra trước thì dùng PreToolUse.

Test thất bại có làm Claude tự hoàn tác thay đổi không?

• Không. Với PostToolUse, chỉnh sửa đã được lưu và vẫn giữ nguyên. Hook chỉ gửi phản hồi lỗi để bạn và Claude xử lý.

Hook có an toàn không?

• Hook dạng lệnh chạy với toàn quyền người dùng của bạn. Hãy đọc kỹ code trước khi bật, chỉ tin cậy thư mục thực hành và không để dữ liệu nhạy cảm trong bài thử.

Vì sao nên gộp định dạng và test trong một script?

• Vì các handler khớp cùng lúc chạy song song, nên hai handler riêng không đảm bảo định dạng hoàn tất trước khi test chạy.

Có nên chạy toàn bộ bộ test sau mỗi lần sửa không?

• Không nên với bộ test chậm. Hãy chọn kiểm tra nhanh cho mỗi lần sửa và chạy test dài ở các điểm rà soát hợp lý.

8. Kết luận

Claude Code hooks giúp biến các bước kiểm tra lặp đi lặp lại thành quy trình tự động, từ định dạng file đến chạy test ngay sau mỗi lần Claude chỉnh sửa. Qua bài thực hành máy tính phí vận chuyển, bạn đã thấy cả vòng: cấu hình hook, kiểm chứng định dạng, thêm test, gây lỗi có chủ đích, đọc thông báo thất bại rồi sửa lại mà không làm yếu bài test.

Đơn giản nhất là bạn hãy nhớ ba nguyên tắc: đọc kỹ code hook trước khi bật, giữ test nguyên vẹn khi sửa lỗi và chọn bước kiểm tra nhỏ, nhanh cho mỗi lần chỉnh sửa. Hooks chỉ làm cho một bước kiểm tra nhỏ trở nên lặp lại được. Việc chọn test hữu ích, rà soát thay đổi và quyết định khi nào ứng dụng sẵn sàng cho người dùng vẫn là trách nhiệm của bạn. Nếu muốn đi xa hơn với toàn bộ quy trình phát triển có AI hỗ trợ, bạn có thể tìm hiểu các khóa như Intro to Vibe Coding của Nate Grahek, bao quát lập kế hoạch, công cụ lập trình AI, gỡ lỗi, triển khai và rủi ro về xác thực, thanh toán và khóa API.