majiayu000/vibeguard

# VibeGuard [](https://github.com/majiayu000/vibeguard/actions/workflows/ci.yml) **停止 Claude Code 和 Codex 重复犯同样昂贵的错误。** [中文文档](docs/README_CN.md) · [规则参考](docs/rule-reference.md) · [贡献指南](CONTRIBUTING.md) VibeGuard 在**代码进入代码库之前**，通过 **原生规则 + 实时钩子 + 静态防护** 捕获 AI 编码代理的错误： - 重复文件和重新发明的模块 - 虚构的 API、假的库和硬编码的占位值 - 危险的 shell/git 命令（`rm -rf`、`push --force`、`reset --hard`） - 分析瘫痪和未经验证的“我完成了”声明 - 静默的异常吞噬和 `Any` 类型滥用 - 每次提交都标记的 AI 烂码模式 适用于 **Claude Code** 和 **Codex CLI**。 ## 30 秒安装 ``` git clone https://github.com/majiayu000/vibeguard.git ~/vibeguard bash ~/vibeguard/setup.sh ``` 打开一个新的 Claude Code 或 Codex 会话。运行 `bash ~/vibeguard/setup.sh --check` 进行验证。 ## 你实际得到什么 | 层 | 作用 | |----|------| | **原生规则** | 在行动前引导模型远离糟糕决策 | | **钩子** | 实时阻止危险或低质量操作 | | **静态防护** | 扫描项目中的 AI 烂码、重复项和结构问题 | | **斜杠命令** | `/vibeguard:*` 工作流用于预检 / 审查 / 检查 / 学习 | | **学习系统** | 将重复的 AI 错误转化为可复用的防护 | | **可观测性** | 每次拦截的指标与健康状态 | ## 产品边界 VibeGuard 包含两个层面： | 表面 | 范围 | 规范来源 | |------|------|----------| | **VibeGuard Core** | 规则、钩子、静态防护、安装/运行时契约、可观测性 | `rules/claude-rules/`、`schemas/install-modules.json`、`hooks/`、`guards/` | | **VibeGuard Workflows** | 斜杠命令、Agent 提示、规划/执行预设 | `skills/`、`workflows/`、`agents/` | 如果这些表面存在不一致，**优先以 Core 契约为准**，然后更新 Workflow/文档表面以匹配。 有关仓库布局所有权，请参见 [目录地图](docs/directory-map.md)。 ## 实际效果  ``` You: "Add a login endpoint" AI: → tries to create auth_service.py ✗ VibeGuard blocks — duplicate of existing auth.py, search first → tries to import `flask-auth-magic` ✗ VibeGuard blocks — non-existent library, verify before adding → hardcodes JWT secret as "your-secret-key" ✗ VibeGuard flags — use env var or secret manager → runs `git push --force` ✗ VibeGuard denies — suggests `--force-with-lease` → keeps reading files without acting ⚠ VibeGuard escalates — force a concrete next step or report blocker → claims done without verifying ⚠ VibeGuard gates — run build/test before finishing ``` **每次拦截都会返回修复指令，而不仅仅是失败**——这样 Agent 可以自我纠正。 重新录制你自己的演示：参见 [docs/assets/README.md](docs/assets/README.md)（通过 asciinema + agg 的一条命令）。 ## 适用对象 如果以下情况符合你，请使用 VibeGuard： - 定期使用 Claude Code 或 Codex - 见过重复文件、虚构 API、过度设计或未验证的“已完成”声明 - 想要 **机械式强制**，而不仅仅是提示指南 如果你只是偶尔使用 AI 或不希望钩子级拦截，这可能过于复杂。 灵感来自 [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) 和 [Stripe Minions](https://www.youtube.com/watch?v=bZ0z1ApYjJo)。完整实现了全部 5 条 Harness 黄金原则。 ## 工作原理 ### 规则注入（从会话启动即激活） `rules/claude-rules/` 中的原生规则集被安装到 Claude Code 的原生规则系统（`~/.claude/rules/vibeguard/`），直接影响力学推理。此外，一个 7 层约束索引被注入到 `~/.claude/CLAUDE.md`： | 层 | 约束 | 效果 | |----|------|------| | L1 | 搜索优先于创建 | 创建新文件前必须先搜索现有实现 | | L2 | 命名约定 | 内部使用 `snake_case`，API 边界使用 `camelCase`，禁止别名 | | L3 | 质量基线 | 禁止静默异常吞噬、禁止公共方法中使用 `Any` 类型 | | L4 | 数据完整性 | 无数据则显示空白，禁止硬编码、禁止虚构 API | | L5 | 最小变更 | 仅执行要求，不做多余的“改进” | | L6 | 流程门控 | 大量变更需预检、结构化规划和验证 | | L7 | 提交纪律 | 禁止 AI 标记、禁止强制推送、禁止泄露密钥 | 规则使用**负向约束**（“X 不存在”）来间接引导 AI，这通常比正面描述更有效。 本契约的规范参考： - 安装/运行时契约：`schemas/install-modules.json` - 原生规则源：`rules/claude-rules/` - 当前规则表面公共摘要：`docs/rule-reference.md` ### 钩子 — 实时拦截 大多数钩子在 AI 操作期间自动触发。`skills-loader` 仍是一个可选的 manual 钩子，且 Codex 目前仅部署 Bash/Stop 钩子事件： | 场景 | 钩子 | 结果 | |------|------|------| | AI 创建新文件（`.py/.ts/.rs/.go/.js`） | `pre-write-guard` | **拦截**——必须先搜索 | | AI 执行 `git push --force`、`rm -rf`、`reset --hard` | `pre-bash-guard` | **拦截**——建议安全替代方案 | | AI 编辑不存在的文件 | `pre-edit-guard` | **拦截**——必须先读取文件 | | AI 添加 `unwrap()`、硬编码路径 | `post-edit-guard` | **警告**——提供修复指令 | | AI 添加 `console.log` / `print()` 调试语句 | `post-edit-guard` | **警告**——改用日志器 | | AI 在新建文件后创建重复定义 | `post-write-guard` | **警告**——检测重复符号与同名文件 | | AI 持续读取/搜索而不行动 | `analysis-paralysis-guard` | **升级**——强制给出具体下一步或阻塞报告 | | AI 在 `full` / `strict` 模式下编辑代码 | `post-build-check` | **警告**——运行语言级构建检查 | | `git commit` | `pre-commit-guard` | **拦截**——质量与构建检查（仅暂存文件），超时 10 秒 | | AI 尝试在未验证变更时完成 | `stop-guard` | **门控**——必须先完成验证 | | 会话结束 | `learn-evaluator` | **评估**——收集指标并检测修正信号 | ### 静态防护 —— 随时运行 可在任何项目上运行的代表性独立检查。完整清单位于 [docs/rule-reference.md](docs/rule-reference.md)。 ``` # 通用 bash ~/vibeguard/guards/universal/check_code_slop.sh /path/to/project # AI code slop python3 ~/vibeguard/guards/universal/check_dependency_layers.py /path # dependency direction python3 ~/vibeguard/guards/universal/check_circular_deps.py /path # circular deps bash ~/vibeguard/guards/universal/check_test_integrity.sh /path # test shadowing / integrity issues # Rust bash ~/vibeguard/guards/rust/check_unwrap_in_prod.sh /path # unwrap/expect in prod bash ~/vibeguard/guards/rust/check_nested_locks.sh /path # deadlock risk bash ~/vibeguard/guards/rust/check_declaration_execution_gap.sh /path # declared but not wired bash ~/vibeguard/guards/rust/check_duplicate_types.sh /path # duplicate type definitions bash ~/vibeguard/guards/rust/check_semantic_effect.sh /path # semantic side effects bash ~/vibeguard/guards/rust/check_single_source_of_truth.sh /path # single source of truth bash ~/vibeguard/guards/rust/check_taste_invariants.sh /path # taste/style invariants bash ~/vibeguard/guards/rust/check_workspace_consistency.sh /path # workspace dep consistency # Go bash ~/vibeguard/guards/go/check_error_handling.sh /path # unchecked errors bash ~/vibeguard/guards/go/check_goroutine_leak.sh /path # goroutine leaks bash ~/vibeguard/guards/go/check_defer_in_loop.sh /path # defer in loop # TypeScript bash ~/vibeguard/guards/typescript/check_any_abuse.sh /path # any type abuse bash ~/vibeguard/guards/typescript/check_console_residual.sh /path # console.log residue bash ~/vibeguard/guards/typescript/check_component_duplication.sh /path # duplicated component files bash ~/vibeguard/guards/typescript/check_duplicate_constants.sh /path # repeated constant definitions # Python python3 ~/vibeguard/guards/python/check_duplicates.py /path # duplicate functions/classes/protocols python3 ~/vibeguard/guards/python/check_naming_convention.py /path # camelCase mix python3 ~/vibeguard/guards/python/check_dead_shims.py /path # dead re-export shims ``` ## 斜杠命令 10 个自定义命令覆盖完整开发生命周期。快捷方式：`/vg:pf` `/vg:gc` `/vg:ck` `/vg:lrn`。 | 命令 | 目的 | |------|------| | `/vibeguard:preflight` | 在变更前生成约束集 | | `/vibeguard:check` | 完整防护扫描 + 合规报告 | | `/vibeguard:review` | 结构化代码审查（安全 → 逻辑 → 质量 → 性能） | | `/vibeguard:cross-review` | 双模型对抗审查（Claude + Codex） | | `/vibeguard:build-fix` | 构建错误解决 | | `/vibeguard:learn` | 从错误生成防护规则 / 从发现提取 Skills | | `/vibeguard:interview` | 深度需求访谈 → SPEC.md | | `/vibeguard:exec-plan` | 长任务执行计划，支持跨会话恢复 | | `/vibeguard:gc` | 垃圾回收（日志归档 + 工作区清理 + 代码烂码扫描） | | `/vibeguard:stats` | 钩子触发统计 | **复杂度路由** | 范围 | 流程 | |------|------| | 1-2 个文件 | 直接实现 | | 3-5 个文件 | `/vibeguard:pref` → 约束 → 实现 | | 6 个及以上文件 | `/vibeguard:interview` → SPEC → `/vibeguard:preflight` → 实现 | ## 多 Agent 分发 14 个内置 Agent 提示（13 个专家 + 1 个调度器），带自动路由： | 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 ~/vibeguard/scripts/quality-grader.sh # Quality grade (A/B/C/D) bash ~/vibeguard/scripts/stats.sh # Hook trigger stats (7 days) bash ~/vibeguard/scripts/hook-health.sh 24 # Hook health snapshot bash ~/vibeguard/scripts/metrics/metrics-exporter.sh # Prometheus metrics export bash ~/vibeguard/scripts/verify/doc-freshness-check.sh # Rule-guard coverage check ``` ## 学习系统 闭环学习从错误中演化防护： **模式 A — 防御式** ``` /vibeguard:learn ``` 分析根因（5-Why）→ 生成新防护/钩子/规则 → 验证检测 → 同类错误不再发生。 **模式 B — 累积式** ``` /vibeguard:learn extract ``` 将非显而易见的解决方案提取为结构化的 Skill 文件，供未来复用。 ## 安装 ### 配置文件与语言 ``` # 配置文件 bash ~/vibeguard/setup.sh # Install (default: core profile) bash ~/vibeguard/setup.sh --profile minimal # Minimal: pre-hooks only (lightweight) bash ~/vibeguard/setup.sh --profile full # Full: adds Stop Gate + Build Check + Pre-Commit bash ~/vibeguard/setup.sh --profile strict # Strict: same hook set as full, for stricter runtime policy # 语言选择（仅安装指定语言的规则/防护） bash ~/vibeguard/setup.sh --languages rust,python bash ~/vibeguard/setup.sh --profile full --languages rust,typescript # 验证/卸载 bash ~/vibeguard/setup.sh --check # Verify installation bash ~/vibeguard/setup.sh --clean # Uninstall ``` | 配置文件 | 启用的钩子 | 用途 | |----------|------------|------| | `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 相同的钩子集合 | 最大强制 | ### Codex 集成 VibeGuard 同时向 Claude Code 和 Codex CLI 部署钩子与技能。 钩子位于 `~/.codex/hooks.json`（需在 `config.toml` 中启用 `codex_hooks = true`）： | 事件 | 钩子 | 功能 | |------|------|------| | `PreToolUse(Bash)` | `pre-bash-guard.sh` | 危险命令拦截 + 包管理器修正 | | `PostToolUse(Bash)` | `post-build-check.sh` | 构建失败检测 | | `Stop` | `stop-guard.sh` | 未提交变更门控 | | `Stop` | `learn-evaluator.sh` | 会话指标收集 | Codex 钩子命令以 `vibeguard-*.sh` 命名以避免与其他工具链冲突。输出格式差异由 `run-hook-codex.sh` 包装器处理（Claude Code 的 `decision:block` → Codex 的 `permissionDecision:deny`）。当钩子建议 `updatedInput` 时，Codex CLI 无法自动应用，因此 VibeGuard 会显式输出建议的替换命令，而不是静默丢弃。 **应用服务器包装器**（Symphony 风格编排器）： ``` python3 ~/vibeguard/scripts/codex/app_server_wrapper.py --codex-command "codex app-server" ``` - `--strategy vibeguard`（默认）：在外部应用 pre/stop/post 门控 - `--strategy noop`：纯透传用于调试 - 当前包装器作用域：Bash 批准拦截 + post-turn stop/build 反馈（带明确的 `thread/session/turn` 传播） - 暂不支持路径：`pre-edit`、`pre-write`、`post-edit`、`post-write`、`analysis-paralysis` ### 适用于任意项目 | 工具 | 方法 | |------|------| | **OpenAI Codex** | `cp ~/vibeguard/templates/AGENTS.md ./AGENTS.md` + `bash ~/vibeguard/setup.sh`（安装技能 + Codex 钩子） | | **任意项目（仅规则）** | `cp ~/vibeguard/docs/CLAUDE.md.example ./CLAUDE.md` | ### 项目引导 使用项目特定指导与预提交包装器引导另一个仓库： ``` bash ~/vibeguard/scripts/project-init.sh /path/to/project ``` ### 本地契约检查（贡献者） 在推送前于本地运行稳定的契约检查，或将其配置为 pre-commit 钩子： ``` bash scripts/local-contract-check.sh # run the full local gate bash scripts/install-pre-commit-hook.sh # install as git pre-commit hook ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解本地与 CI 的分工以及 `--quick` 标志。 ### 自定义规则 将自定义规则添加到 `~/.vibeguard/user-rules/`。任何放置在该目录下的 `.md` 文件都会在下次运行 setup 时自动安装到 `~/.claude/rules/vibeguard/custom/`。格式：标准 Claude Code 规则文件（含 YAML 前置元数据）。 ## 设计原则 | 原则 | 来源 | 实施 | |------|------|------| | 自动化优先于文档 | Harness #3 | 钩子 + 防护脚本机械式强制执行 | | 错误信息即修复指令 | Harness #3 | 每次拦截都告诉 AI 如何修复，而不仅仅是指出问题 | | 地图而非手册 | Harness #5 | 7 层索引 + 负向约束 + 惰性加载 | | 失败 → 能力 | Harness #2 | 错误 → 学习 → 新防护 → 永不复发 | | 若 Agent 不可见，则不存在 | Harness #1 | 所有决策写入仓库（`CLAUDE.md` / 执行计划 / 日志） | | 赋予 Agent 视觉 | Harness #4 | 可观测性堆栈（日志 + 指标 + 告警） | ## 已知问题 防护脚本严重依赖模式匹配（grep/awk 或轻量 AST 辅助），这意味着某些场景下仍可能出现误报。 - [已知误报](docs/known-issues/false-positives.md) —— 已识别的误报场景、修复与经验总结 关键经验： - **grep 不是 AST 解析器**——嵌套作用域与多块结构需要语言感知工具 - **防护修复消息会被 AI 代理消费**——不精确的修复提示本身可能触发不必要的编辑 - **项目类型感知很重要**——CLI/Web/MCP/Library 代码库可能需要针对同一语言规则的不同可接受模式 ## 文档 | 文档 | 目的 | |------|------| | [docs/README_CN.md](docs/README_CN.md) | 中文概览与安装指南 | | [docs/rule-reference.md](docs/rule-reference.md) | 规则层、防护覆盖范围与语言特定检查 | | [docs/CLAUDE.md.example](docs/CLAUDE.md.example) | 无需安装钩子的项目级 CLAUDE 模板 | | [docs/linux-setup.md](docs/linux-setup.md) | Linux 特定安装说明 | | [docs/known-issues/false-positives.md](docs/known-issues/false-positives.md) | 已知防护误报与缓解说明 | | [docs/assets/README.md](docs/assets/README.md) | 演示录制脚本与资源 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献者工作流、验证命令与提交协议 | ## 参考 - [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) [中文文档 →](docs/README_CN.md)

标签：AI代码生成审查, AI代码防护, API集成, CI集成, Claude Code, Codex, Cutter, Shell命令拦截, 云安全监控, 云计算, 代码审查工具, 分布式计算, 去重, 可观测性, 可视化界面, 威胁情报, 安全防护, 实时拦截, 开发者工具, 异常处理, 类型安全, 规则引擎, 逆向工具, 钩子机制, 防止幻觉, 静态分析