# VibeGuard

[![CI](https://github.com/majiayu000/vibeguard/actions/workflows/ci.yml/badge.svg)](https://github.com/majiayu000/vibeguard/actions/workflows/ci.yml)

**阻止 AI 编造代码。**

[English README](../README.md) | [规则索引](rule-reference.md) | [贡献指南](../CONTRIBUTING.md)

无论你在用 Claude Code 还是 Codex，AI 都很容易出现同一类失误：编造不存在的 API、重复造轮子、硬编码假数据、顺手做一堆你没要求的“优化”。VibeGuard 通过 **规则注入 + 实时拦截 + 静态扫描** 三层防线，把这些问题尽量挡在代码落地之前。

> **VibeGuard vs Everything Claude Code：** ECC 更偏通用生产力工具箱；VibeGuard 更偏“防守系统”，重点是约束、拦截、验证和回放。两者不是互斥关系，反而适合一起使用。

设计思路参考了 [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) 和 [Stripe Minions](https://www.youtube.com/watch?v=bZ0z1ApYjJo)，并把 Harness 的 5 条黄金原则真正落到仓库级工具链里。

## 典型问题

```text
你：   “加一个登录接口”
AI：   新建 auth_service.py（仓库里其实已经有 auth.py）
      引入不存在的库 `flask-auth-magic`
      把 JWT secret 硬编码成 "your-secret-key"
      顺手再加 200 行你根本没要的“改进”
```

**VibeGuard 的目标，就是在这些改动进入仓库之前先发现并打断。**

## 快速开始

```bash
git clone https://github.com/majiayu000/vibeguard.git ~/vibeguard
bash ~/vibeguard/setup.sh
```

安装需要 Python 3 和 Rust/Cargo，用于构建运行时 `vibeguard-runtime`。

安装后重新打开 Claude Code 或 Codex 会话。用下面的命令检查安装状态：

```bash
bash ~/vibeguard/setup.sh --check
```

## 文档导航

| 文档 | 作用 |
|------|------|
| [rule-reference.md](rule-reference.md) | 规则分层、guard 覆盖面、语言专项检查 |
| [CLAUDE.md.example](CLAUDE.md.example) | 只使用规则模板、不安装 hooks 的项目级 CLAUDE 模板 |
| [linux-setup.md](linux-setup.md) | Linux 安装说明 |
| [known-issues/false-positives.md](known-issues/false-positives.md) | 已知误报与修复经验 |
| [../CONTRIBUTING.md](../CONTRIBUTING.md) | 贡献流程、验证命令、提交规范 |

## 产品边界

VibeGuard 现在明确分成两层：

| 表面 | 范围 | canonical source |
|------|------|------------------|
| **VibeGuard Core** | 规则、hooks、静态 guards、安装/运行时契约、可观测性 | `rules/claude-rules/`、`schemas/install-modules.json`、`hooks/`、`guards/` |
| **VibeGuard Workflows** | Slash Commands、agent prompts、规划/执行预设 | `skills/`、`workflows/`、`agents/` |

如果这些表面之间冲突，先以 Core 契约为准，再同步 workflow 和文档。

仓库目录职责见 [Directory Map](directory-map.md)。

## 工作方式

### 1. 规则注入

`rules/claude-rules/` 中的原生规则会被安装到 `~/.claude/rules/vibeguard/`，直接影响 Claude Code 的推理层。同时，VibeGuard 还会把 7 层约束索引注入到 `~/.claude/CLAUDE.md`。

| 层级 | 约束 | 作用 |
|------|------|------|
| L1 | 先搜索再创建 | 新建文件/类/函数前先确认仓库里是否已有实现 |
| L2 | 命名规范 | 内部优先 `snake_case`，API 边界再用 `camelCase`，禁止别名 |
| L3 | 质量基线 | 禁止吞异常、公共接口滥用 `Any` |
| L4 | 数据真实性 | 没数据就显示空，不允许硬编码和虚构 API |
| L5 | 最小改动 | 只做被要求的事，不顺手加“升级” |
| L6 | 过程闸门 | 大改动先预检和规划，结束前必须验证 |
| L7 | 提交纪律 | 禁止 AI 标记、禁止 force push、禁止秘钥入库 |

这里大量使用了“负约束”表达，例如“X 不存在”“不要假设 Y 已经有”，通常比纯正向描述更能稳定影响 agent 行为。

当前 canonical 参考入口：
- 安装/运行时契约：`schemas/install-modules.json`
- 原生规则源：`rules/claude-rules/`
- 当前规则摘要：`docs/rule-reference.md`

### 2. Hooks 实时拦截

多数 hooks 都是在 AI 操作过程中自动触发。`skills-loader` 是可选的手动脚本；Codex 会部署原生 Bash/apply_patch/PermissionRequest/Stop hooks，读操作相关 hooks 仍只在 Claude Code 或 app-server wrapper 路径生效：

| 场景 | Hook | 结果 |
|------|------|------|
| AI 创建新的 `.py/.ts/.rs/.go/.js` 文件 | `pre-write-guard` | 默认 **告警**，提醒先搜索现有实现；设置 `VIBEGUARD_WRITE_MODE=block` 或 `write_mode=block` 后硬拦截 |
| AI 创建或编辑超过 800 行的生产源码文件 | `pre-write-guard`、`pre-edit-guard` | **拦截**，必须先拆分文件 |
| AI 执行 `git push --force`、`rm -rf`、`git clean -fd`、批量 `git checkout/restore .` | `pre-bash-guard` | **拦截**，给出安全替代命令；如确实要清理本地改动，先运行 `python3 ~/vibeguard/scripts/authorized-discard.py --plan` 查看逐路径计划，再用确认短语执行 |
| AI 编辑一个不存在的文件 | `pre-edit-guard` | **拦截**，要求先读取文件确认 |
| AI 编辑后引入 `unwrap()`、硬编码路径等问题 | `post-edit-guard` | **告警**，直接给修复建议 |
| AI 编辑后留下 `console.log` / `print()` | `post-edit-guard` | **告警**，要求换成正式日志方案 |
| AI 新建文件后出现重复定义或重名文件 | `post-write-guard` | **告警**，提示重复实现 |
| AI 连续搜索/读取却迟迟不行动 | `analysis-paralysis-guard` | **升级**，要求明确下一步或说明阻塞 |
| `full` / `strict` 档位下编辑源码 | `post-build-check` | **告警**，自动跑对应语言的构建检查 |
| `git commit` | `pre-commit-guard` | **拦截**，只检查 staged 改动，10 秒硬超时 |
| AI 想结束但还没有验证改动 | `stop-guard` | **闸门**，要求先补完验证 |
| 会话结束 | `learn-evaluator` | **评估**，收集指标并识别纠错信号 |

U-16 文件行数限制只覆盖非测试源码扩展名：`.rs`、`.ts`、`.tsx`、`.js`、`.jsx`、`.py`、`.go`。在 Codex 路径里，`apply_patch Add File` 和 `apply_patch Update File` 都会先被规范化再进入文件 hook；如果 patch 会让生产源码超过 800 行，会在写入前被 deny。

### 3. 静态 Guards

下面是最常用的一组独立扫描脚本。完整清单请看 [rule-reference.md](rule-reference.md)。

```bash
# 通用
bash ~/vibeguard/guards/universal/check_code_slop.sh /path/to/project
python3 ~/vibeguard/guards/universal/check_dependency_layers.py /path/to/project
python3 ~/vibeguard/guards/universal/check_circular_deps.py /path/to/project
bash ~/vibeguard/guards/universal/check_test_integrity.sh /path/to/project
bash ~/vibeguard/guards/universal/check_dependency_changes.sh --base origin/main --head HEAD
bash ~/vibeguard/guards/universal/check_test_weakening.sh --base origin/main --head HEAD

# Rust
bash ~/vibeguard/guards/rust/check_unwrap_in_prod.sh /path
bash ~/vibeguard/guards/rust/check_nested_locks.sh /path
bash ~/vibeguard/guards/rust/check_declaration_execution_gap.sh /path
bash ~/vibeguard/guards/rust/check_duplicate_types.sh /path
bash ~/vibeguard/guards/rust/check_semantic_effect.sh /path
bash ~/vibeguard/guards/rust/check_single_source_of_truth.sh /path
bash ~/vibeguard/guards/rust/check_taste_invariants.sh /path
bash ~/vibeguard/guards/rust/check_workspace_consistency.sh /path

# Go
bash ~/vibeguard/guards/go/check_error_handling.sh /path
bash ~/vibeguard/guards/go/check_goroutine_leak.sh /path
bash ~/vibeguard/guards/go/check_defer_in_loop.sh /path

# TypeScript
bash ~/vibeguard/guards/typescript/check_any_abuse.sh /path
bash ~/vibeguard/guards/typescript/check_console_residual.sh /path
bash ~/vibeguard/guards/typescript/check_component_duplication.sh /path
bash ~/vibeguard/guards/typescript/check_duplicate_constants.sh /path

# Python
python3 ~/vibeguard/guards/python/check_duplicates.py /path
python3 ~/vibeguard/guards/python/check_naming_convention.py /path
python3 ~/vibeguard/guards/python/check_dead_shims.py /path
```

## Slash Commands

仓库内置了 12 个自定义命令，覆盖从需求澄清到验证复盘的完整流程：

| 命令 | 作用 |
|------|------|
| `/vibeguard:preflight` | 修改前生成约束集 |
| `/vibeguard:check` | 全量 guard 扫描 + 合规报告 |
| `/vibeguard:review` | 结构化代码审查（安全 → 逻辑 → 质量 → 性能） |
| `/vibeguard:cross-review` | Claude + Codex 双模型对抗式审查 |
| `/vibeguard:build-fix` | 构建错误修复 |
| `/vibeguard:learn` | 从错误中生成 guard/rule，或提炼 Skill |
| `/vibeguard:skill-validate` | 用 repair/regression 证据门验证新 Skill 是否值得接受 |
| `/vibeguard:interview` | 深度需求访谈，输出 SPEC.md |
| `/vibeguard:exec-plan` | 长任务执行计划，支持跨会话恢复 |
| `/vibeguard:live-truth` | 为 latest、PR ready、merged、running、deployed、published 等可变状态声明提供新鲜证据门 |
| `/vibeguard:gc` | 垃圾回收（日志归档 + worktree 清理 + 规则预算 + code slop 扫描） |
| `/vibeguard:stats` | hook 触发统计 |

快捷别名：`/vg:pf` `/vg:gc` `/vg:ck` `/vg:lrn`

### 路由契约

工作流路由只在一个地方定义：[`workflows/references/routing-contract.md`](../workflows/references/routing-contract.md)。

- 优先级：`user_override` → `risk/destructive gate` → `ambiguity gate` → `readiness classifier` → `execution/delegation lane`
- readiness 输出只有三种：`execute_direct`、`plan_first`、`clarify_first`
- 规划类工作流统一输出 handoff 字段：`mode`、`artifacts`、`runtime_pinning_snapshot`、`verification_owner`、`stop_conditions`、`lane_map`
- 多 agent 委派统一使用 [`workflows/references/delegation-contract.md`](../workflows/references/delegation-contract.md)，明确子任务模板、并发限制和单一集成负责人

README、workflow prompts、dispatcher 都应该消费这份契约，而不是各自再写一套本地路由规则。

## 内置 Agent Prompts

仓库当前内置 14 个 agent prompt（13 个专项角色 + 1 个 dispatcher）：

| Agent | 作用 |
|------|------|
| `dispatcher` | 自动识别任务类型并路由到合适的 agent |
| `planner` / `architect` | 需求分析、系统设计 |
| `tdd-guide` | RED → GREEN → IMPROVE 测试驱动 |
| `code-reviewer` / `security-reviewer` | 分层审查、OWASP Top 10 |
| `build-error-resolver` | 构建错误定位与修复 |
| `go-reviewer` / `python-reviewer` / `database-reviewer` | 语言/数据库专项审查 |
| `refactor-cleaner` / `doc-updater` / `e2e-runner` | 重构、文档同步、端到端验证 |

## 可观测性与学习闭环

```bash
bash ~/vibeguard/scripts/quality-grader.sh
bash ~/vibeguard/scripts/stats.sh
bash ~/vibeguard/scripts/hook-health.sh 24
bash ~/vibeguard/scripts/doctors/codex-doctor.sh
bash ~/vibeguard/scripts/metrics/metrics-exporter.sh
bash ~/vibeguard/scripts/verify/doc-freshness-check.sh
```

Doctor 是现有防御系统之上的只读诊断入口，不替代 hooks 或 guards。它负责汇总安装状态、能力差异、噪声 hook、最近事件和修复命令；真正的拦截/告警仍然发生在 hook 和 guard 执行层。

学习系统分两种模式：

**模式 A：防御式学习**

```text
/vibeguard:learn <错误描述>
```

针对一次真实失误做 5-Why 根因分析，然后生成新的 guard / hook / rule，并回放验证。

**模式 B：积累式学习**

```text
/vibeguard:learn extract
```

把会话里出现的非显然解法提炼成 Skill，供后续任务复用。

## Codex 集成

VibeGuard 会同时给 Claude Code 和 Codex CLI 安装技能与 hooks。

### Codex Hooks

`~/.codex/hooks.json` 中当前会部署以下 VibeGuard 管理的 hook：

| 事件 | Hook | 作用 |
|------|------|------|
| `PreToolUse(Bash)` | `pre-bash-guard.sh` | 危险命令拦截 + 包管理器纠偏 |
| `PermissionRequest(Bash)` | `pre-bash-guard.sh` | 危险命令审批前的 fail-closed 闸门 |
| `PreToolUse(Edit/Write via apply_patch)` | `pre-edit-guard.sh`、`pre-write-guard.sh` | patch 前检查文件存在性和 search-first |
| `PermissionRequest(Edit/Write via apply_patch)` | `pre-edit-guard.sh`、`pre-write-guard.sh` | 需要额外权限的 patch 审批前闸门 |
| `PostToolUse(Bash/apply_patch)` | `post-build-check.sh` | 命令或 patch 后的构建失败检测 |
| `PostToolUse(Edit/Write via apply_patch)` | `post-edit-guard.sh`、`post-write-guard.sh` | patch 后质量检查与重复实现检查 |
| `Stop` | `stop-guard.sh` | 未验证改动的结束闸门 |
| `Stop` | `learn-evaluator.sh` | 会话指标与纠错信号采集 |

这是默认强制层，走 Codex 原生 hooks，不包也不替换 Codex server。Codex 当前没有原生 `Read`、`Glob`、`Grep` hook surface，所以 `analysis-paralysis` 不在原生 Codex 路径生效；需要读操作循环拦截时优先用 Claude Code。只有已经必须接入 `codex app-server` 的外部编排系统，才需要考虑下面的可选 wrapper。

Codex 中的 hook 命令名会使用 `vibeguard-*.sh` 命名空间，避免与别的工具链共享 `~/.codex/hooks.json` 时发生冲突。Claude 和 Codex 输出格式差异由 `run-hook-codex.sh` 负责适配；Codex 的 `apply_patch` 会先被 wrapper 规范化成 Edit/Write 形状，再复用现有文件 hook。对 `Update File` patch，wrapper 还会传递行数 delta，让 `pre-edit-guard.sh` 能在 Codex 真正改文件之前执行 U-16 拦截。若 hook 给出 `updatedInput` 建议，Codex CLI wrapper 目前不能自动改写命令，VibeGuard 会显式提示建议命令，而不是静默吞掉这条信息。

### 可选 App Server 外层封装

普通本地 Codex 使用不需要这一层，本地默认保护应使用 `~/.codex/hooks.json` 里的 Codex 原生 hooks。只有你已经在用 `codex app-server` 这类编排器，才需要考虑在外层再包一层 VibeGuard：

```bash
~/.vibeguard/installed/bin/vibeguard-runtime codex-app-server-wrapper \
  --repo-dir ~/vibeguard \
  --codex-command "codex app-server"
```

- `--strategy vibeguard`：默认模式，在外层补上 command、file-change、analysis-loop、post-turn gate
- `--strategy noop`：纯透传，方便调试
- app-server wrapper 是可选编排外壳，主要给已经使用 `codex app-server` 协议的上层系统
- 当前 app-server wrapper 已覆盖：Bash 审批拦截，`applyPatchApproval` / `item/fileChange/requestApproval` 文件变更审批，`pre-edit`、`pre-write`、`post-edit`、`post-write`，读命令循环的 `analysis-paralysis` 提醒，以及 turn 结束后的 stop/build 反馈。
- 运行时是 Rust-only 的 `vibeguard-runtime` 子命令，不再保留 Python app-server wrapper 兼容入口。
- 本地默认保护应使用 `~/.codex/hooks.json` 里的 Codex 原生 hooks
- 原生 Codex 路径仍不支持：`Read`/`Glob`/`Grep` 这类 hook，例如 `analysis-paralysis`

## 安装选项

```bash
# Profiles
bash ~/vibeguard/setup.sh                              # 默认 core profile
bash ~/vibeguard/setup.sh --profile minimal           # 最轻量 pre-hooks
bash ~/vibeguard/setup.sh --profile full              # 增加 Stop Gate、Build Check、学习闭环
bash ~/vibeguard/setup.sh --profile strict            # 与 full 相同 hook 集合，更严格运行策略

# 只安装指定语言规则/guards
bash ~/vibeguard/setup.sh --languages rust,python
bash ~/vibeguard/setup.sh --profile full --languages rust,typescript

# 检查 / 卸载
bash ~/vibeguard/setup.sh --check
bash ~/vibeguard/setup.sh --check --quiet
bash ~/vibeguard/setup.sh --check --json
bash ~/vibeguard/setup.sh --check --strict
bash ~/vibeguard/setup.sh --clean
```

### Profiles

| Profile | 安装内容 | 适用场景 |
|---------|----------|----------|
| `minimal` | `pre-write` + `pre-edit` + `pre-bash` | 最轻量的关键拦截 |
| `core` | `minimal` + `post-edit` + `post-write` + `analysis-paralysis` | 默认开发档 |
| `full` | `core` + `stop-guard` + `learn-evaluator` + `post-build-check` | 完整防线 + 学习闭环 |
| `strict` | 与 `full` 相同 hook 集合 | 更严格的运行策略 |

`setup.sh` 同时会准备共享的 pre-commit wrapper：`~/.vibeguard/pre-commit`，并给本仓库安装 git pre-commit hook。要把 wrapper 接到其他仓库，用 `scripts/project-init.sh` 或目标仓库自己的安装步骤。

### 给别的仓库做初始化

```bash
bash ~/vibeguard/scripts/project-init.sh /path/to/project
```

这个脚本会检测语言、输出建议的项目级约束片段，并把 pre-commit wrapper 接到目标仓库里。

### 自定义规则

你可以把自定义 `.md` 规则放进 `~/.vibeguard/user-rules/`。下次运行 `setup.sh` 时，这些规则会被同步到 `~/.claude/rules/vibeguard/custom/`。

## 已知限制

当前不少 guard 仍然依赖 grep/awk 或轻量 AST 辅助，因此在复杂语法场景里仍然可能出现误报。

- [known-issues/false-positives.md](known-issues/false-positives.md)：已确认误报场景、修复方式和经验总结

几个最重要的经验：

- **grep 不是 AST parser**：多层嵌套和跨块关系最好交给语言感知工具
- **修复提示本身也会驱动 agent**：提示写得太宽，会诱导 AI 做无关改动
- **项目类型很重要**：CLI、Web、MCP、Library 对同一条规则的可接受模式可能不同

## References

- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/)
- [Stripe Minions](https://www.youtube.com/watch?v=bZ0z1ApYjJo)
- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
