Guard rails: lớp phanh giữa model và hành động

Một task nhỏ, nhiều quyền quá rộng

Bạn giao cho agent một việc nhỏ: sửa validation trong một module. Nó muốn chắc hơn nên quét thêm vài thư mục, mở file config nhạy cảm, rồi tiện tay gom luôn vài cleanup không liên quan vào cùng một PR.

Nhìn qua thì mọi thứ vẫn ổn. Test vẫn pass. Nhưng context đã lẫn file rác, secret có thể đã đi vào transcript (toàn bộ bản ghi hội thoại giữa bạn và agent), còn review thì bị loãng vì phần cần sửa và phần "tiện tay" nằm chung một PR.

Guard rail là gì trong agentic coding

Guard rail là lớp đứng giữa agent và hành động: việc rủi ro thì chặn, việc đáng nghi thì cảnh báo. Nó giống lan can ở mép cầu thang: không làm bạn đi giỏi hơn, nhưng giảm khả năng một cú bước hụt thành tai nạn. Khác với lời dặn trong prompt, tức prompt instruction, guard rail chạy ở tầng điều phối tool, không phụ thuộc model có "nhớ" hay không.

Phân biệt guard rail và lời dặn

Guard rail hoạt động thế nào

Harness là lớp runtime bọc quanh model. Model chỉ quyết định "tôi muốn đọc file này" hoặc "tôi muốn chạy lệnh này"; harness mới là bên nhận tool call, quản quyền, gọi hook, cho tool chạy hoặc chặn, rồi trả kết quả lại cho model. Hook là script nhỏ harness tự gọi tại các thời điểm cố định trong vòng đời một tool call — lúc nhận prompt, trước tool, sau tool — để xen vào kiểm tra. Vì mọi hành động thật đều qua harness, đây là chỗ gắn guard rail.

Đọc thêm nền khái niệm: Harness Engineering là gì? của Duy /zuey/.

Bản đồ ClaudeKit Hooks

Chi tiết ClaudeKit Hooks có thể xem thêm tại VividKit Guides.

Hook không nằm trong model. Nó nằm ở lifecycle của Claude Code: settings.json quyết định hook nào được gọi, .ck.json/ENV quyết định runtime behavior, còn output của hook có thể cho chạy, chặn, inject context hoặc ghi state/artifact sau khi tool hoặc session kết thúc.

Flow một tool call qua guard rail

Điểm mấu chốt: pre-tool hook trả exit code. Exit 0 cho tool chạy, exit 2 chặn và đẩy lý do về model. Ba điểm chèn chính trong flow có tên kỹ thuật tương ứng: UserPromptSubmit (lúc nhận prompt), PreToolUse (trước tool), PostToolUse (sau tool). Riêng Stop/SubagentStop chạy khi session hoặc subagent kết thúc, nên nằm ở bản đồ lifecycle phía trên.

Hai kiểu chặn

Bảy nhóm guard rail trong CK

Nhóm nào đọc ở đâu

9 tình huống quen thuộc

Settings và các lớp config

Hai lớp config quyết định guard nào chạy: settings.json gắn hook vào lifecycle của Claude Code; .ck.json bật/tắt từng hook và chỉnh threshold.

# Global scope
~/.claude/settings.json
~/.claude/.ck.json
~/.claude/hooks/*.cjs

# Project scope
.claude/settings.json
.claude/.ck.json
.claude/hooks/*.cjs

settings.json: hook nào chạy ở mốc nào

Snippet dưới đây chỉ minh hoạ một lát cắt PreToolUse trong fresh CK install: CK cung cấp scout-block và privacy-block, rồi wire chúng vào lifecycle để Claude Code gọi trước khi tool chạy. Full hook config trên máy đã cài còn nhiều lifecycle event hơn; nơi cần xem là settings.json của Claude Code.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Glob|Grep|Read|Edit|Write",
        "hooks": [
          { "command": "node \".claude/hooks/scout-block.cjs\"" },
          { "command": "node \".claude/hooks/privacy-block.cjs\"" }
        ]
      }
    ]
  }
}

settings.json là bản đồ lifecycle: khi user gửi prompt thì hook nào chạy, trước khi tool chạy thì hook nào được gọi, sau khi tool xong thì hook nào xử lý tiếp. Với global install, CLI đổi command tương đối trong template thành dạng node "$HOME/.claude/hooks/scout-block.cjs"; với project install, path thường giữ ở dạng .claude/hooks/....

Đọc bảng hook theo 3 nhãn

Đừng gom mọi thứ thành "mặc định bật/tắt". Trạng thái của một hook có ba lớp khác nhau:

Bảng dưới đây là snapshot danh sách hook theo stable claudekit-engineer@2.19.1. Update 2026-06-09: claudekit-engineer@2.19.2-beta đang chuẩn bị remove task-completed-handler và teammate-idle-handler; khi upstream ClaudeKit release new version, danh sách này có thể còn 14 hook.

Điểm dễ sót: isHookEnabled() chỉ tắt khi hooks.<name> là false. Key thiếu thường được xem là enabled. Nhưng vài guard còn có công tắc riêng: privacy-block vẫn đọc key cũ privacyBlock=false, còn simplify-gate có simplify.gate.enabled và ENV CK_SIMPLIFY_DISABLED=1.

Manual bật/tắt và tự kiểm tra hook

Muốn chỉnh nhanh, sửa .ck.json ở scope cần tác động. Project config ưu tiên hơn global khi key được set rõ; key thiếu thì tiếp tục inherit/default. Với các hook đã được wire trong settings.json, đặt false là tắt, đặt true là bật lại sau khi scope cao hơn đã tắt. Tên hook trong cột Hook bên dưới cũng là key dùng trong hooks.<name>.

// .claude/.ck.json hoặc ~/.claude/.ck.json
{
  "hooks": {
    "scout-block": false,
    "privacy-block": true
  },
  "privacyBlock": true,
  "simplify": {
    "gate": {
      "enabled": true
    }
  }
}

Muốn biết hook có được trigger không, nhìn lifecycle event chứ không nhìn tên file. Cùng một hook script chỉ chạy khi event/matcher trong settings.json khớp với hành động hiện tại. Bảng dưới đây là cách kiểm nhanh từng hook; hook not wired cần wire trước hoặc gọi bằng manual CLI nếu script hỗ trợ.

// ~/.claude/settings.json hoặc .claude/settings.json
{
  "env": {
    "CK_SIMPLIFY_DISABLED": "1"
  }
}

scout-block — chặn đọc thư mục rác

Agent hay đọc node_modules/, glob **/*.ts ở root (glob là mẫu khớp đường dẫn; **/*.ts nghĩa là mọi file .ts ở mọi thư mục con), cat dist/index.js. Mỗi lần là vài chục nghìn token nhét vào context, kéo cost và chất lượng turn sau xuống. scout-block.cjs đăng ký PreToolUse, chạy trước mọi Read/Bash/Glob/Grep.

# Baseline .ckignore — pattern-matcher.cjs xử lý
node_modules
dist
build
.next
.nuxt
__pycache__
.venv
venv
vendor
target
.git
coverage

privacy-block — chặn secret, bắt user duyệt rõ ràng

Agent đụng .env, id_rsa, *.pem, credentials.yaml — secret lộ vào transcript. Một khi vào context, có thể bị log, quote lại trong reviewer output, paste vào PR.

@@PRIVACY_PROMPT_START@@
{ "type": "PRIVACY_PROMPT", "question": {...}, "options": [...] }
@@PRIVACY_PROMPT_END@@

Claude parse JSON, gọi AskUserQuestion. Nếu user duyệt, hook message hướng dẫn đọc file bằng đường approved, ví dụ cat ".env" sau khi đã hỏi; code cũng hỗ trợ prefix APPROVED:. Điểm chính: phải có approval rõ ràng, không để model tự diễn dịch consent.

simplify-gate — chặn ship khi diff phình quá scope

Một task nhỏ có thể phình ra thành PR đụng quá nhiều file: sửa validation, thêm cleanup, đổi format, chỉnh vài helper lân cận. Khi agent nói "OK ship", simplify-gate.cjs đăng ký UserPromptSubmit, đọc git diff HEAD, chỉ xét khi prompt có: ship merge pr deploy publish.

Các ngưỡng mặc định của simplify.threshold: tổng dòng thêm+xóa, số file bị đụng, và dòng thêm lớn nhất trong một file. Gate chỉ chặn khi simplify.gate.enabled=true; các số này có thể override trong .ck.json.

// project .ck.json — bật thật sự
{ "simplify": { "gate": { "enabled": true } } }

matchedSeverity() bỏ qua "don't ship", "ship on" → "ship on Friday" cũng đi qua. Muốn tắt gate cho mọi session ở scope đó, đặt CK_SIMPLIFY_DISABLED=1 trong settings.json dưới key env.

workflow-artifact-gate — 5 artifact JSON

Full pipeline → mỗi phase để lại file JSON ghi quyết định, như hoá đơn sau mỗi bước. Hook này được thiết kế để gắn vào UserPromptSubmit + PreToolUse(Bash), nhưng không nằm trong hook set chạy sẵn sau fresh install; muốn dùng phải opt-in.

Gate này có hai mức xử lý. Ở bước rủi ro như ship, push, PR hoặc deploy, hook có thể dừng flow ngay và trả lý do về cho model (emitBlock()). Ở bước nhẹ hơn như finalize hoặc commit, hook cho flow đi tiếp nhưng thêm cảnh báo vào context để model tự sửa (emitSoft()).

Hard-gate XML trong skill markdown

Hook chỉ chặn tool call. Có lỗi không phải tool call mà là trình tự: code trước plan, fix trước scout. CK gắn <HARD-GATE> vào skill markdown.

<HARD-GATE>
Do NOT write implementation code until a plan exists
and has been reviewed. Exception: --fast skips research
but still requires a plan step. User override: if user
explicitly says 'just code it', respect their instruction.
</HARD-GATE>

ck:cook và ck:fix mỗi skill có 4 hard-gate (plan/scout-first, exact-req hoặc root-cause, no-side-effects).

dev-rules-reminder — đưa rule vào context

dev-rules-reminder.cjs đăng ký UserPromptSubmit, đưa rules text vào mỗi prompt. Ở đây có hai lớp cần tách rõ: hook là cơ chế inject context, còn rule trong CLAUDE.md là nội dung được inject. TTL 5 phút theo (sessionId, baseDir) để tránh đốt token.

Guard skills — lớp guard user gọi

code-reviewer agent chạy checklist 9 mục: concurrency, error boundary, API contract, backwards compat, input validation, auth/authz, N+1, data leak, fact-check. Guard cuối trước merge.

Các gap đã biết

Best practices & pitfalls

6 câu kiểm tra trước khi tin guard rail

• settings.json đang gắn hook nào vào lifecycle nào?
• .ck.json đã disable hook nào? (outer + inner config)
• Claude Code session hiện tại có đang bỏ qua permission prompt không?
• Có project .ckignore override? node_modules có bị ! allowlist?
• Rule files trong CLAUDE.md có đầy đủ?
• Có hook nào crash âm thầm trong session này (check stderr)?

Thuật ngữ nhanh