Bài 6.218 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

Hook định dạng, kiểm lỗi, chạy test

PostToolUse kiểm từng file ngay sau khi sửa, Stop không cho Claude xong khi test còn đỏ, và vì sao cần cả hai.

Bài 1.2 dạy bạn ghi tiêu chí "xong khi npm test đạt". Bài 2.1 đưa lệnh test vào CLAUDE.md. Cả hai đều là lời nhờ. Bài này biến chúng thành việc luôn xảy ra: mỗi lần Claude sửa file .js, một hook kiểm cú pháp; mỗi lần Claude định nói "xong", một hook chạy test, và nếu test đỏ thì Claude chưa được dừng.

Hai thời điểm để kiểm tra

Có hai chỗ hợp để gắn việc kiểm tra tự động:

Thời điểm Sự kiện Hợp với
Ngay sau mỗi lần sửa file PostToolUse Việc nhanh, theo từng file: định dạng, kiểm cú pháp, lint
Trước khi Claude trả lời xong Stop Việc chậm hơn, cho cả dự án: chạy bộ test

Cái trước bắt lỗi sớm, ngay file vừa sửa. Cái sau là lưới an toàn: dù lỗi lọt qua đường nào, Claude cũng không được nói "xong" khi test còn đỏ. Như bạn sẽ thấy ngay sau đây, cần cả hai.

Kiểm cú pháp sau mỗi lần sửa

todo-api không cài thêm công cụ lint nào, nhưng Node có sẵn node --check để kiểm cú pháp một file mà không chạy nó. Tạo .claude/hooks/check-js.sh:

Terminal
#!/bin/bash
# PostToolUse: syntax-check every .js file Claude edits or writes
FILE=$(jq -r '.tool_input.file_path // empty')
[[ "$FILE" == *.js ]] || exit 0
if ! OUT=$(node --check "$FILE" 2>&1); then
  echo "Syntax error in $FILE:" >&2
  echo "$OUT" >&2
  exit 2
fi

Nhớ chmod +x .claude/hooks/check-js.sh. Script lấy đường dẫn file vừa sửa từ JSON đầu vào (tool_input.file_path), bỏ qua file không phải .js, và nếu cú pháp sai thì in lỗi ra stderr rồi thoát với mã 2.

Với PostToolUse, exit 2 không hoàn tác được gì: file đã sửa rồi. Thay vào đó, Claude Code đưa stderr cho Claude, và Claude biết ngay mình vừa viết hỏng. Khi thử, chúng tôi nhờ Claude dùng Edit chèn một dòng sai cú pháp vào src/app.js. Hook chạy ngay sau lần sửa, và Claude báo lại rằng hook đã phát hiện lỗi cú pháp.

Nếu dự án có Prettier, docs đưa sẵn mẫu tự định dạng theo cùng cách: matcher Edit|Write, rồi npx prettier --write --ignore-unknown "$f" với f là đường dẫn lấy từ jq.

Lỗ hổng: Claude không chỉ sửa bằng Edit

Lần thử đầu, chúng tôi chỉ nói "thêm đúng dòng này vào cuối src/app.js". Claude chọn cách nhanh nhất: một lệnh Bash printf … >> src/app.js. Hook khớp Edit|Write không chạy, vì Claude không hề dùng Edit hay Write. Dòng sai cú pháp lọt qua.

Docs nói rõ điều này: Claude có thể thay đổi file bằng lệnh shell. Có ba cách vá:

  • Thêm một hook Stop kiểm cả dự án mỗi lượt: lỗi lọt qua cách nào cũng bị bắt trước khi Claude xong. Đây là cách bài này dùng.
  • Khớp thêm Bash và cho script đọc git status --porcelain để biết file nào vừa đổi.
  • Dùng sự kiện FileChanged khi cần phản ứng mỗi lần một file cụ thể đổi trên đĩa, bất kể ai sửa.

Bài học chung: hook PostToolUse theo tên công cụ chỉ thấy đúng công cụ đó. Đừng tin nó là lớp kiểm tra duy nhất.

Chưa được xong khi test còn đỏ

Tạo .claude/hooks/tests-before-stop.sh:

Terminal
#!/bin/bash
# Stop: don't let Claude finish while npm test fails
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Claude was already sent back once; let it stop
fi
cd "$CLAUDE_PROJECT_DIR" || exit 0
[ -z "$(git status --porcelain -- src test)" ] && exit 0  # nothing changed in code
if ! OUT=$(npm test 2>&1); then
  echo "npm test fails. Fix it before you finish:" >&2
  echo "$OUT" | grep -E -A4 "✖|Error" | head -30 >&2
  exit 2
fi

Với Stop, exit 2 ngăn Claude dừng: Claude nhận stderr như lý do để làm tiếp. Ba chi tiết đáng chú ý:

  • stop_hook_active là true khi Claude đang làm tiếp vì chính hook này. Thoát sớm lúc đó để không chặn mãi một điều kiện có thể không bao giờ đạt. Claude Code còn có giới hạn riêng: sau 8 lần chặn liên tiếp mà Claude không gọi công cụ nào, nó bỏ qua lần chặn tiếp theo.
  • Bỏ qua khi không sửa code: Stop chạy sau mọi câu trả lời, kể cả khi bạn chỉ hỏi một câu. Dòng git status --porcelain tránh chạy test vô ích.
  • Gửi đúng dòng lỗi: bản đầu của chúng tôi dùng tail -25 và chỉ gửi được một đống stack trace, mất dòng SyntaxError. grep theo ✖ và Error gửi đúng thứ Claude cần.

Khi thử, sau lần chèn dòng sai bằng Edit, hook Stop chặn với lỗi SyntaxError ở đầu. Claude xóa dòng đó, tự chạy npm test thấy 5/5 đạt, rồi mới dừng.

Một chuyện thú vị: ở lần chèn bằng Bash, Claude không xóa dòng đó mà giải thích rằng xóa đi là làm ngược yêu cầu của bạn, rồi dừng ở lần thứ hai. Hook giữ đúng lời hứa của nó: Claude không thể nói "xong" mà không biết test đang đỏ. Còn quyết định tiếp theo vẫn thuộc về bạn.

Test chậm thì chạy nền

Bộ test của todo-api chạy dưới một giây. Bộ test thật có thể mất vài phút, và một hook đồng bộ bắt Claude chờ suốt thời gian đó. Thêm "async": true để hook chạy nền:

JSON
{ "type": "command", "command": "…/run-tests.sh", "async": true }

Claude làm tiếp ngay; khi script xong, phần additionalContext nó in ra được đưa cho Claude ở lượt sau. Cái giá: hook async không chặn được gì, vì việc nó định ngăn đã xảy ra rồi. Với claude -p, hook async còn đang chạy lúc phiên kết thúc sẽ bị hủy.

Cách chia hợp lý: kiểm nhanh (cú pháp, định dạng) là PostToolUse đồng bộ; bộ test dài là PostToolUse async để báo sớm; còn chốt chặn "không được xong khi đỏ" là Stop đồng bộ.

Bộ hook cho todo-api

Ghép lại trong .claude/settings.json:

JSON
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-js.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tests-before-stop.sh" }
        ]
      }
    ]
  }
}

Commit cả .claude/settings.json lẫn thư mục .claude/hooks/ để cả team có cùng lưới an toàn. Kiểm tra bằng /hooks, và thử từng script bằng JSON mẫu trước khi tin nó.

Với bộ này, issue #3 (bộ lọc ?done=) giao cho Claude sẽ khác hẳn: mọi file sửa đều được kiểm cú pháp, và Claude không thể báo xong khi test chưa đạt. Bài 6.3 làm điều ngược lại: thay vì kiểm sau, ta chặn trước những việc không bao giờ được xảy ra.

Luyện tập bài 6.2

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.