MaruCheck

项目简介

MaruCheck 是一款开源工具，为 AI 生成的代码提供独立的 QA 与验证服务。它将产品意图转化为"质量契约"（Quality Contract），分析代码变更，记住历史回归，测试编码代理遗漏的内容。核心解决一个问题：AI 代理同时编写实现和判定实现的测试套件——套件全绿只证明内部一致性，不代表行为符合预期。

核心功能

1. 质量契约（Quality Contract） — 由人工拥有、版本化的规范文件，定义"什么是正确的行为"。AI 代理可以修改代码，但不能悄悄修改契约，从而将裁判权与运动员权分离。
2. 独立验证（Verify） — 对比契约中定义的行为与 AI 代理实际修改后的代码，发现不一致时阻止合并，提供预期行为与实际行为的差异报告。
3. 语义漂移检测（Drift Check） — 定期对比契约中的规范与代码实际表现是否一致，防止代理在多轮修改中逐渐偏离原始意图。
4. Claude Code 停止钩子 — maru hook install 将验证注册为 Claude Code 的停止钩子：代理在验证门未通过时无法结束本轮，必须处理失败需求，且不得编辑契约作为修复手段。
5. 本地优先 — 无需账号、无需模型 API Key，代码不离开你的机器，保护内部代码隐私。
6. 多测试框架支持 — 支持 Jest 和 Node.js 原生测试框架，可与现有 CI/CD 流水线集成。
7. MCP 服务器支持 — 可作为 MCP 服务器调用，方便与 Cursor、Windsurf 等支持 MCP 的编辑器集成。

技术实现

MaruCheck 的工作流程分为三个阶段：

Phase 1：初始化 — maru init 创建项目结构，定义第一个质量契约。

Phase 2：验证门（Verify Gate） — 对比契约中声明的行为与代码实际表现，输出详细的 blocking findings 列表。

Phase 3：漂移检测（Drift Check） — 定期运行 maru drift check，检测代码是否已偏离契约规范。

关键设计原则：代理不能同时是运动员又是裁判。验证结果必须由独立的 MaruCheck 进程裁决，且失败时强制代理处理需求而非修改契约。

快速上手

1. 安装：npx --yes marucheck@0.4.0 init
2. 配置：npx marucheck@0.4.0 doctor 验证环境
3. 运行验证：npx marucheck@0.4.0 verify --diff
4. 安装钩子：maru hook install（使验证成为 Claude Code 停止钩子）
5. CI 集成：在 CI 流水线中加入 maru verify 作为代码合并的前置门禁

适用人群

• 使用 AI 编程代理的开发团队：Claude Code、Cursor、Windsurf 等工具的用户，希望确保 AI 修改不破坏产品规范。
• 安全敏感型团队：对 AI 生成代码有严格审查要求，需要保留完整 QA 记录的企业。
• 平台工程团队：负责管理 AI 编程工具的企业内部平台团队，需要确保工具输出质量可控。
• AI 应用开发者：需要为 AI 生成代码建立质量保障流程的个人开发者或小型团队。

官方链接

https://github.com/Kidus-M/MaruCheck