设计Agent 生成代码的 Lint 规则体系，理解 Hook 机制

上一章我们建立了一个关键认知：Rules 文件是概率性的约束——Agent "大概率"会遵守，但不保证。当你告诉 Agent “不要硬编码 API Key”，它在 99 次调用中可能都遵守了，但第 100 次可能因为上下文过长或注意力分散而忽略这条规则。

在 In the Loop 模式中，人类审查是最后的安全网。但在 On the Loop 模式中，我们不希望依赖人类审查——我们希望有一个确定性的机制来自动拦截违规代码。

这就是Hook的价值所在。Hook 是挂载在 Agent 生命周期事件上的确定性脚本——当 Agent 试图执行某个操作时，Hook 脚本会被触发，如果检查不通过，操作会被直接阻止，Agent 无法跳过。

“Hooks guarantee execution; prompts do not.”
—— blakecrosley.com, Agent Architecture Guide

核心概念

传统 Lint 与 Agent Lint 的区别

传统的 Lint 工具（ESLint、Pylint、golangci-lint）是为人类开发者设计的——它们检查代码风格、潜在 Bug、未使用的变量等。当代码不合规时，Lint 会给出警告，但开发者可以选择忽略。

Agent Lint 需要解决一类不同的问题：

维度传统 LintAgent Lint
检查对象人类写的代码AI 生成的代码
关注重点代码风格、最佳实践安全、权限、架构边界
执行方式开发者手动运行或 CI每次操作自动触发，不可跳过
失败处理警告或错误exit code 2 直接阻止操作
检查时机代码写完后代码写之前（PreToolUse）和写之后（PostToolUse）

Agent Lint 的核心差异在于执行时机和不可跳过性：

  • PreToolUse：在 Agent 执行工具（如 Bash、Write）之前检查——可以在代码生成之前就拦截危险操作
  • 不可跳过：exit code 2 会直接阻止操作，Agent 没有办法绕过

Hook 架构：Agent 生命周期的 12+ 个事件

Claude Code 定义了一组完整的生命周期事件，每个事件都可以挂载 Hook：

Hook 事件触发时机能否阻止？最佳用途
SessionStart会话开始否加载上下文、设置环境变量
UserPromptSubmit用户发送消息是上下文注入、输入验证
PreToolUse工具执行之前是安全阻止、自动审批
PermissionRequest权限对话框出现是自动审批/拒绝
PostToolUse工具成功执行后否*自动格式化、Lint、日志
PostToolUseFailure工具执行失败后否错误处理
SubagentStart子 Agent 启动否子 Agent 初始化
SubagentStop子 Agent 结束是子 Agent 验证
StopAgent 完成响应是任务完成验证
PreCompact上下文压缩前否会话记录备份
Setup–init/–maintenance否一次性设置
SessionEnd会话结束否清理、日志记录

*PostToolUse 可以向 Agent 提供反馈，但无法撤销已执行的操作。

最核心的两个 Hook 是PreToolUse和PostToolUse：

  • PreToolUse：在 Agent 执行操作之前运行检查脚本。如果脚本返回 exit code 2，操作被阻止，stderr 的内容会发送给 Agent 作为反馈。
  • PostToolUse：在 Agent 成功执行操作之后运行处理脚本。常用于自动格式化、Lint 检查、审计日志。

Exit Code：控制机制

Hook 通过 exit code 与 Harness 运行时通信：

Exit Code含义行为
0成功Hook 正常运行，stdout 被处理
2阻止操作被停止，stderr 发送给 Agent
其他错误stderr 展示给用户，执行继续

Exit code 2 是你的核心武器。一个返回 exit code 2 的 PreToolUse Hook 可以阻止任何危险操作。一个返回 exit code 2 的 Stop Hook 可以强制 Agent 继续工作。

原理剖析

Hook 配置结构

Hook 在.claude/settings.json中配置：

{"hooks":{"PreToolUse"