agent-guardrails

阻止人工智能代理秘密绕过您的规则。使用 git hooks、秘密检测、部署验证和导入注册表进行机械执行。源于真实的生产事件：服务器崩溃、令牌泄漏、代码重写。适用于 Claude Code、Clawdbot、Cursor。安装一次，永久执行。

# Agent Guardrails

Mechanical enforcement for AI agent project standards. Rules in markdown are suggestions. Code hooks are laws.

## Quick Start

```bash
cd your-project/
bash /path/to/agent-guardrails/scripts/install.sh
```

This installs the git pre-commit hook, creates a registry template, and copies check scripts into your project.

## Enforcement Hierarchy

1. **Code hooks** (git pre-commit, pre/post-creation checks) — 100% reliable
2. **Architectural constraints** (registries, import enforcement) — 95% reliable
3. **Self-verification loops** (agent checks own work) — 80% reliable
4. **Prompt rules** (AGENTS.md, system prompts) — 60-70% reliable
5. **Markdown rules** — 40-50% reliable, degrades with context length

## Tools Provided

### Scripts

| Script | When to Run | What It Does |
|--------|------------|--------------|
| `install.sh` | Once per project | Installs hooks and scaffolding |
| `pre-create-check.sh` | Before creating new `.py` files | Lists existing modules/functions to prevent reimplementation |
| `post-create-validate.sh` | After creating/editing `.py` files | Detects duplicates, missing imports, bypass patterns |
| `check-secrets.sh` | Before commits / on demand | Scans for hardcoded tokens, keys, passwords |
| `create-deployment-check.sh` | When setting up deployment verification | Creates .deployment-check.sh, checklist, and git hook template |
| `install-skill-feedback-loop.sh` | When setting up skill update automation | Creates detection, auto-commit, and git hook for skill updates |

### Assets

| Asset | Purpose |
|-------|---------|
| `pre-commit-hook` | Ready-to-install git hook blocking bypass patterns and secrets |
| `registry-template.py` | Template `__init__.py` for project module registries |

### References

| File | Contents |
|------|----------|
| `enforcement-research.md` | Research on why code > prompts for enforcement |
| `agents-md-template.md` | Template AGENTS.md with mechanical enforcement rules |
| `deployment-verification-guide.md` | Full guide on preventing deployment gaps |
| `skill-update-feedback.md` | Meta-enforcement: automatic skill update feedback loop |
| `SKILL_CN.md` | Chinese translation of this document |

## Usage Workflow

### Setting up a new project

```bash
bash scripts/install.sh /path/to/project
```

### Before creating any new .py file

```bash
bash scripts/pre-create-check.sh /path/to/project
```

Review the output. If existing functions cover your needs, import them.

### After creating/editing a .py file

```bash
bash scripts/post-create-validate.sh /path/to/new_file.py
```

Fix any warnings before proceeding.

### Setting up deployment verification

```bash
bash scripts/create-deployment-check.sh /path/to/project
```

This creates:
- `.deployment-check.sh` - Automated verification script
- `DEPLOYMENT-CHECKLIST.md` - Full deployment workflow
- `.git-hooks/pre-commit-deployment` - Git hook template

**Then customize:**
1. Add tests to `.deployment-check.sh` for your integration points
2. Document your flow in `DEPLOYMENT-CHECKLIST.md`
3. Install the git hook

See `references/deployment-verification-guide.md` for full guide.

### Adding to AGENTS.md

Copy the template from `references/agents-md-template.md` and adapt to your project.

## 中文文档 / Chinese Documentation

See `references/SKILL_CN.md` for the full Chinese translation of this skill.

## Common Agent Failure Modes

### 1. Reimplementation (Bypass Pattern)
**Symptom:** Agent creates "quick version" instead of importing validated code.
**Enforcement:** `pre-create-check.sh` + `post-create-validate.sh` + git hook

### 2. Hardcoded Secrets
**Symptom:** Tokens/keys in code instead of env vars.
**Enforcement:** `check-secrets.sh` + git hook

### 3. Deployment Gap
**Symptom:** Built feature but forgot to wire it into production. Users don't receive benefit.
**Example:** Updated `notify.py` but cron still calls old version.
**Enforcement:** `.deployment-check.sh` + git hook

This is the **hardest to catch** because:
- Code runs fine when tested manually
- Agent marks task "done" after writing code
- Problem only surfaces when user complains

**Solution:** Mechanical end-to-end verification before allowing "done."

### 4. **Skill Update Gap** (META - NEW)
**Symptom:** Built enforcement improvement in project but forgot to update the skill itself.
**Example:** Created deployment verification for Project A, but other projects don't benefit because skill wasn't updated.
**Enforcement:** `install-skill-feedback-loop.sh` → automatic detection + semi-automatic commit

This is a **meta-failure mode** because:
- It's about enforcement improvements themselves
- Without fix: improvements stay siloed
- With fix: knowledge compounds automatically

**Solution:** Automatic detection of enforcement improvements with task creation and semi-automatic commits.

## Key Principle

> Don't add more markdown rules. Add mechanical enforcement.
> If an agent keeps bypassing a standard, don't write a stronger rule — write a hook that blocks it.
>
> **Corollary:** If an agent keeps forgetting integration, don't remind it — make it mechanically verify before commit.

---

## 中文说明

# Agent Guardrails（代理护栏）

为 AI 代理项目标准提供机械执行。markdown 中的规则只是建议。代码钩子才是法律。

## 快速开始

```bash
cd your-project/
bash /path/to/agent-guardrails/scripts/install.sh
```

这会安装 git pre-commit 钩子、创建注册表模板，并将检查脚本复制到你的项目中。

## 执行层级

1. **代码钩子**（git pre-commit、创建前/后检查）— 100% 可靠
2. **架构约束**（注册表、导入强制）— 95% 可靠
3. **自我验证循环**（代理检查自己的工作）— 80% 可靠
4. **提示词规则**（AGENTS.md、系统提示词）— 60-70% 可靠
5. **Markdown 规则** — 40-50% 可靠，随上下文长度增加而退化

## 提供的工具

### 脚本

| 脚本 | 何时运行 | 作用 |
|--------|------------|--------------|
| `install.sh` | 每个项目运行一次 | 安装钩子和脚手架 |
| `pre-create-check.sh` | 创建新 `.py` 文件之前 | 列出现有模块/函数以防止重复实现 |
| `post-create-validate.sh` | 创建/编辑 `.py` 文件之后 | 检测重复、缺失的导入、绕过模式 |
| `check-secrets.sh` | 提交前/按需 | 扫描硬编码的令牌、密钥、密码 |
| `create-deployment-check.sh` | 设置部署验证时 | 创建 .deployment-check.sh、清单和 git 钩子模板 |
| `install-skill-feedback-loop.sh` | 设置技能更新自动化时 | 为技能更新创建检测、自动提交和 git 钩子 |

### 素材

| 素材 | 用途 |
|-------|---------|
| `pre-commit-hook` | 即装即用的 git 钩子，阻止绕过模式和秘密 |
| `registry-template.py` | 用于项目模块注册表的模板 `__init__.py` |

### 参考

| 文件 | 内容 |
|------|----------|
| `enforcement-research.md` | 关于为何代码优于提示词进行强制的研究 |
| `agents-md-template.md` | 带机械执行规则的模板 AGENTS.md |
| `deployment-verification-guide.md` | 关于防止部署缺口的完整指南 |
| `skill-update-feedback.md` | 元执行：自动技能更新反馈循环 |
| `SKILL_CN.md` | 本文档的中文翻译 |

## 使用工作流

### 设置新项目

```bash
bash scripts/install.sh /path/to/project
```

### 创建任何新 .py 文件之前

```bash
bash scripts/pre-create-check.sh /path/to/project
```

查看输出。如果现有函数满足你的需求，请导入它们。

### 创建/编辑 .py 文件之后

```bash
bash scripts/post-create-validate.sh /path/to/new_file.py
```

在继续之前修复所有警告。

### 设置部署验证

```bash
bash scripts/create-deployment-check.sh /path/to/project
```

这会创建：
- `.deployment-check.sh` - 自动化验证脚本
- `DEPLOYMENT-CHECKLIST.md` - 完整的部署工作流
- `.git-hooks/pre-commit-deployment` - Git 钩子模板

**然后自定义：**
1. 在 `.deployment-check.sh` 中为你的集成点添加测试
2. 在 `DEPLOYMENT-CHECKLIST.md` 中记录你的流程
3. 安装 git 钩子

完整指南请参阅 `references/deployment-verification-guide.md`。

### 添加到 AGENTS.md

从 `references/agents-md-template.md` 复制模板并根据你的项目进行调整。

## 中文文档 / Chinese Documentation

本技能的完整中文翻译请参阅 `references/SKILL_CN.md`。

## 常见的代理故障模式

### 1. 重复实现（绕过模式）
**症状：** 代理创建"快速版本"而不是导入已验证的代码。
**强制：** `pre-create-check.sh` + `post-create-validate.sh` + git 钩子

### 2. 硬编码秘密
**症状：** 令牌/密钥写在代码中而不是环境变量中。
**强制：** `check-secrets.sh` + git 钩子

### 3. 部署缺口
**症状：** 构建了功能但忘记将其接入生产环境。用户没有获得好处。
**示例：** 更新了 `notify.py` 但 cron 仍然调用旧版本。
**强制：** `.deployment-check.sh` + git 钩子

这是**最难捕捉的**，因为：
- 手动测试时代码运行正常
- 代理在写完代码后将任务标记为"完成"
- 问题只在用户抱怨时才浮现

**解决方案：** 在允许"完成"之前进行机械的端到端验证。

### 4. **技能更新缺口**（元 - 新增）
**症状：** 在项目中构建了强制改进，但忘记更新技能本身。
**示例：** 为项目 A 创建了部署验证，但其他项目没有受益，因为技能未更新。
**强制：** `install-skill-feedback-loop.sh` → 自动检测 + 半自动提交

这是一种**元故障模式**，因为：
- 它关乎强制改进本身
- 不修复：改进保持孤立
- 修复后：知识自动累积

**解决方案：** 自动检测强制改进，并创建任务和半自动提交。

## 关键原则

> 不要添加更多 markdown 规则。添加机械执行。
> 如果代理不断绕过某个标准，不要