Agentic Validators
目标
把“智能体写了代码”变成“智能体写了代码，并且变更被自动验证”。
该技能帮助你：
- 选择合适的验证策略（按文件 vs 全仓库）
- 实现 post-tool-use 与 stop 钩子
- 创建窄验证器（快速、确定性的检查）
- 组织工作方式，使多个智能体可以并行运行而不丢失正确性
心智模型
- 智能体是非确定性的；验证器是确定性的。
- 上下文是脆弱的；验证与日志是持久的。
- 优先采用贴近变更的小而快的检查（按文件），再加一道最终全局闸门（全仓库）。
何时使用哪种钩子
Post-tool-use 钩子（最佳默认）
在以下情况使用：
- 你希望在编辑后立即获得反馈
- 你可以验证被触及的特定文件
- 你希望在不运行完整测试套件的情况下获得高信号
典型检查：
- 格式化（prettier/black）
- 代码检查（eslint/ruff）
- 针对该文件/模块的类型检查（带项目配置的 tsc --noEmit）
Stop 钩子（运行结束闸门）
在以下情况使用：
- 你需要全仓库范围的不变量
- 你想要最后一道“退出标准”检查
典型检查：
- 单元测试
- 构建
- 集成测试
逐步操作：为仓库添加验证器
-
识别文件类型与快速检查
- JS/TS：prettier + eslint + 类型检查
- Python：ruff + pytest（可选）
- Go：gofmt + go test（可选）
-
实现按文件验证器
验证器应当：
- 快速（<5–30s）
- 确定性
- 输出清晰
- 可安全重复运行
-
接入钩子
- 实现 post-tool-use 钩子，用文件路径调用验证器。
-
添加日志
- 写入可预期位置（例如 .agent-logs/validators.log）
-
添加 stop 钩子“最终闸门”
- 运行一次更广的检查。
示例验证器模式
模式 A：对“被触及文件”的“格式化 + 检查”
- 格式化文件
- 检查文件
- 如果格式化器做出了任何更改，则失败并要求智能体在提交格式化更改后重新运行
模式 B：“契约测试”
- 对被触及模块，运行聚焦的单元测试子集
模式 C：“readme/文档不变量”
- 如果文档发生更改，运行 markdown 检查 + 链接检查器
并行模式
如果你有许多类似文件（CSV、配置、文档）：
- 为每个文件生成一个子智能体
- 每个子智能体运行自己的 post-tool-use 验证器
- 聚合智能体只接受验证器通过的结果
常见失败模式与修复
- 验证器太慢 → 拆分为快速的按文件检查 + 较慢的 stop 钩子。
- 验证器不稳定 → 移除网络调用，固定版本，仅在安全处添加重试。
- 智能体忽略工具文档 → 写一段简短的“宪法”章节并指向参考文件。
参考
- 参见 Hook recipes
- 参见 Validator design checklist