Hooks in Claude Code

• Hooks trong Claude Code là các lệnh có tính xác định, đảm bảo chạy mọi lúc tại các điểm cụ thể trong vòng đời của Claude Code, khác với các lời nhắc không đảm bảo thực thi.
• Chúng được sử dụng để thực thi các quy tắc không thể thương lượng như tự động định dạng, ghi nhật ký tuân thủ, chặn các thao tác nguy hiểm, hoặc gửi thông báo.
• Được cấu hình ở cấp độ dự án trong settings.json và có thể kiểm soát phiên bản, Hooks giúp duy trì tính nhất quán hành vi và tiêu chuẩn trên toàn bộ nhóm phát triển.

• Cấu hình Hooks trong tệp settings.json của dự án để đảm bảo thực thi các lệnh một cách có tính xác định trong Claude Code.
• Sử dụng Hooks sự kiện Post tool use với matcher là edit hoặc multi-edit để tự động định dạng mã nguồn (ví dụ: chạy Prettier cho TypeScript, go format cho Go) sau khi tệp được chỉnh sửa.
• Triển khai Hooks sự kiện Pre-tool use để chặn các thao tác nguy hiểm: thoát với mã lỗi 2 để ngăn chặn hành động và cung cấp phản hồi cho Claude, trong khi mã thoát 0 cho phép tiếp tục.
• Tận dụng các loại sự kiện khác như User prompt submit, Notification, và Stop để thực hiện các hành động tùy chỉnh trước khi xử lý lời nhắc, gửi cảnh báo, hoặc sau khi Claude hoàn thành phản hồi.
• Đảm bảo toàn bộ nhóm của bạn có cùng các Hook bằng cách kiểm tra tệp settings.json chứa cấu hình Hook vào kho lưu trữ của dự án.
• Sử dụng biến môi trường CLAUDE_PROJECT_DIR trong tập lệnh Hook của bạn để tham chiếu đến các script được lưu trữ trong dự án, đảm bảo chúng hoạt động độc lập với thư mục làm việc hiện tại của Claude.
• Đối với các tác vụ quan trọng phải xảy ra mọi lúc và không được thất bại (ví dụ: ghi nhật ký tuân thủ, chặn lệnh nguy hiểm), hãy ưu tiên cấu hình chúng dưới dạng Hook thay vì dựa vào lời nhắc.

• Hooks — Móc
• deterministic — có tính xác định
• tool call — lời gọi công cụ
• matcher — bộ khớp
• event — sự kiện
• auto-formatting — tự động định dạng
• exit code — mã thoát
• project-level — cấp độ dự án

Giới thiệu về Hooks trong Claude Code

Hooks cho phép bạn chạy các lệnh tại những điểm khác nhau trong vòng đời của Claude Code. Sự khác biệt chính giữa hook và tất cả những gì chúng tôi đã đề cập là hook có tính xác định (deterministic). Chúng luôn chạy. Nói cách khác, bạn có thể yêu cầu Claude trong tệp claude.md của mình chạy Prettier sau mỗi lần chỉnh sửa tệp, và hầu hết thời gian nó sẽ làm như vậy. Nhưng đôi khi nó sẽ không thực hiện; nó không hoàn hảo. Tuy nhiên, một hook sẽ đảm bảo điều đó xảy ra mọi lúc, không có ngoại lệ.

Các Trường hợp Sử dụng Phổ biến

Các trường hợp sử dụng phổ biến có thể bao gồm tự động định dạng (auto-formatting) sau khi chỉnh sửa tệp, ghi nhật ký tất cả các lệnh đã thực thi để tuân thủ, chặn các thao tác nguy hiểm như sửa đổi tệp sản xuất, và gửi thông báo (notifications) cho bạn khi Claude hoàn thành một tác vụ.

Cấu hình và Các loại Sự kiện

Hook được cấu hình trong tệp settings.json của bạn. Bạn chọn một sự kiện, tùy chọn đặt một bộ khớp (matcher) cho những công cụ nào nó áp dụng, và cung cấp một lệnh để chạy.

• User prompt submit (Gửi lời nhắc người dùng) chạy khi bạn gửi một lời nhắc trước khi Claude xử lý nó.
• Pre-tool use (Trước khi sử dụng công cụ) chạy trước một lời gọi công cụ.
• Post tool use (Sau khi sử dụng công cụ) chạy sau khi một lời gọi công cụ hoàn thành.
• Notification (Thông báo) chạy khi Claude gửi một thông báo.
• Và stop (dừng) chạy khi Claude hoàn thành phản hồi.

Ví dụ: Tự động Định dạng sau Chỉnh sửa

Hook phổ biến nhất là tự động định dạng sau khi chỉnh sửa (auto-formatting after edit). Bạn thiết lập một hook Post tool use với bộ khớp là edit hoặc multi-edit. Như vậy, nó sẽ kích hoạt bất cứ khi nào Claude sửa đổi một tệp. Lệnh sẽ kiểm tra phần mở rộng của tệp và chạy bộ định dạng (formatter) thích hợp. Ví dụ, Prettier cho TypeScript, go format cho Go, ruff cho Python, hoặc bất kỳ công cụ nào dự án của bạn sử dụng.

Chặn Các Thao tác Nguy hiểm

Các hook Pre-tool use có thể chặn các lời gọi công cụ trước khi chúng được thực thi. Hook của bạn nhận tên công cụ và đầu vào dưới dạng JSON trên stdin. Nếu nó thoát với mã lỗi 2, hành động sẽ bị chặn và thông báo lỗi stderr sẽ được chuyển ngược lại cho Claude để phản hồi. Như vậy, Claude biết tại sao nó bị chặn và có thể điều chỉnh. Mã thoát 0 (Exit code 0) có nghĩa là tiếp tục. Mã thoát 2 (Exit code 2) có nghĩa là chặn. Đây là cách bạn thực thi các quy tắc cứng rắn (hard rules). Ví dụ: chặn ghi vào thư mục cấu hình môi trường sản xuất (production config directory), chặn các lệnh Bash chứa rm -rf, chặn các commit — bất cứ điều gì mà Nhóm của bạn cần được đảm bảo, chứ không chỉ được đề xuất.

Cấu hình Cấp độ Dự án và Thực tiễn tốt nhất

Hook được cấu hình trong tệp settings.json là cấp dự án (project-level) và có thể được kiểm tra vào kho lưu trữ (repo) của bạn. Điều này có nghĩa là toàn bộ Nhóm của bạn sẽ tự động có cùng các hook. Sử dụng biến môi trường CLAUDE_PROJECT_DIR trong tập hợp lệnh của bạn để tham chiếu các script được lưu trữ trong dự án của bạn, để chúng hoạt động bất kể thư mục làm việc hiện tại (current working directory) của Claude là gì.

Kết luận

Hook cung cấp cho bạn khả năng kiểm soát có tính xác định (deterministic control) đối với hành vi của Claude Code. Sử dụng Post tool use để tự động định dạng và ghi nhật ký (logging). Sử dụng Pre-tool use để chặn các thao tác nguy hiểm. Cấu hình chúng trong thư mục /hooks hoặc trong settings.json và kiểm tra chúng vào kho lưu trữ của bạn để Nhóm của bạn cũng nhận được chúng. Nếu điều gì đó cần xảy ra mọi lúc mà không thất bại, đừng đặt nó vào một lời nhắc; hãy đặt nó vào một hook.