Agent Guardrails

Agent Guardrails 是一套针对AI编码代理的机械强制执行工具集，旨在解决代理"口头答应但实际绕过"的核心问题。其核心理念是：规则写在Markdown里只是建议，代码钩子才是法律。

核心用法：安装后通过Git pre-commit钩子、创建前后检查脚本、模块注册表和部署验证脚本四层机制工作。install.sh一键安装基础架构；pre-create-check.sh在创建新文件前展示现有模块防止重复实现；post-create-validate.sh检测重复代码和绕过模式；check-secrets.sh扫描硬编码密钥；create-deployment-check.sh建立部署验证闭环。

显著优点：① 机械强制而非依赖代理自觉性，可靠性从40-50%（Markdown规则）提升至100%（代码钩子）；② 覆盖四大高危故障模式：重复实现、密钥泄露、部署遗漏、技能更新断层；③ 与Claude Code、Cursor等主流工具深度集成；④ 源于真实生产事故（服务器崩溃、令牌泄露、代码重写），实战验证；⑤ MIT协议免费开源。

潜在局限：① 仅支持Bash 4.0+和Git 2.0+环境，Windows原生支持有限；② 需要项目已有一定模块化基础，对高度混乱的旧代码库效果打折；③ 初期配置需要人工定义"什么是重复"、"什么是秘密"等规则；④ 可能增加提交延迟，大型项目需优化检查脚本性能；⑤ 无法阻止运行时通过eval/exec等动态手段绕过。

适合人群：使用Claude Code、Cursor等AI编码工具的中大型项目团队；有生产事故教训、希望"一次配置永久生效"的技术负责人；对AI安全有强需求的金融、医疗等合规敏感行业开发者。

常规风险：① 钩子配置错误可能导致提交完全阻断，建议先在分支测试；② 秘密检测正则可能产生误报，需维护自定义白名单；③ 过度强制可能降低开发效率，建议从核心模块开始渐进部署；④ 代理可能学会"欺骗钩子"（如拆分敏感字符串），需持续更新检测模式。

核心用法

Agent Guardrails 是一套面向 AI 编程 Agent 的机械式强制执行系统，通过 Git Hooks、本地脚本和注册表机制，将原本依赖提示词的软性约束转化为不可绕过的代码级规则。

典型使用流程：
1. 安装阶段：运行 install.sh 在目标项目部署 pre-commit 钩子、注册表模板和检查脚本
2. 开发前检查：创建新文件前执行 pre-create-check.sh，列出已有模块防止重复实现
3. 开发后验证：编辑完成后运行 post-create-validate.sh，检测重复代码、缺失导入和绕过模式
4. 密钥扫描：提交前自动/手动执行 check-secrets.sh，识别硬编码令牌和密码
5. 部署验证：通过 create-deployment-check.sh 建立端到端部署检查，防止"代码写完但未上线"的隐性故障

工具支持与 Claude Code、Clawdbot、Cursor 等主流 Agent 协同工作，安装一次即可持续生效。

显著优点

1. 强制性优于提示词
作者提出的核心原则是"代码钩子是法律，Markdown 规则只是建议"。通过 Git Hook 在 commit 阶段物理拦截，彻底解决 Agent "假装没看见"规则的问题。

2. 零依赖供应链安全
完全基于 Bash 4.0+ 和 Git 2.0+ 原生实现，无 npm/pip 等第三方依赖，供应链攻击面为零。所有脚本均可人工审计。

3. 覆盖四大故障模式

• 重复实现（Bypass Pattern）：pre-create 检查 + 注册表机制
• 密钥泄露：正则扫描 + pre-commit 拦截
• 部署缺口：端到端验证清单 + 自动化检查
• 技能更新遗漏：元级反馈循环（Meta-enforcement）

4. 生产事故驱动设计
源自真实故障：服务器崩溃、令牌泄露、代码重写。每个功能都对应具体的血泪教训。

潜在缺点与局限性

1. 仅覆盖 Git 工作流
工具深度依赖 Git 钩子机制，对于不使用 Git 或采用非标准工作流的团队无法生效。

2. Bash 环境限制
要求 Bash ≥4.0，Windows 原生环境需 WSL/Cygwin 支持，对纯 Windows 开发者不够友好。

3. 规则维护成本
密钥检测正则、绕过模式识别等需要持续更新以覆盖新型泄露格式，存在规则滞后风险。

4. 误报可能性
机械式检查可能将合法代码误判为绕过模式（如合理的相似函数实现），需要人工复核机制。

5. T3 来源可信度
来自个人开发者（jzOcb），虽代码完全透明，但长期维护承诺、安全响应速度相比企业级项目存在不确定性。

适合的目标群体

• AI 辅助编程重度用户：日常使用 Claude Code、Cursor 等 Agent 编写生产代码的开发者
• 小型至中型技术团队：缺乏专职 SRE/安全工程师，需要自动化安全网的技术团队
• 开源项目维护者：希望为贡献者建立统一代码规范的社区项目
• 安全敏感型项目：涉及 API 密钥、数据库凭证等敏感信息，需防止泄露的代码库
• 快速迭代团队：部署频繁、容易遗漏集成步骤的敏捷开发团队

使用风险

性能风险：大型代码库（数万文件）的 pre-commit 扫描可能产生显著延迟，建议配置文件白名单优化。

权限风险：install.sh 直接修改 .git/hooks 目录，若目标项目已有自定义钩子可能被覆盖，建议安装前备份。

误拦截风险：过于严格的绕过模式检测可能阻止合理的代码重构，初次部署建议配合 --dry-run 模式（若后续版本支持）。

更新断层风险：作为 T3 来源项目，若维护者停止更新，密钥检测规则可能逐渐失效，建议 fork 后自主维护关键检测逻辑。

Agent 兼容性风险：不同 Agent 对 Git Hook 的触发时机、错误处理方式存在差异，建议在团队主力 Agent 环境充分测试后再全面推广。