Vibe Guard

Node.js >=22 MCP Server Claude Code Codex License MIT

vibe-guard 是一个本地 CLI + MCP Server，用来给 AI 辅助开发加上项目前调研、规划门禁、任务门禁和质量门禁。它不替代 Spec Kit、Archcore、BMAD Method、Task Master、Context7 或 DeepWiki，而是把这些工具串成一个统一入口。

[!IMPORTANT] 一行安装到本机，并同时注册 Claude Code 与 Codex 的全局 MCP 配置：

npm install -g github:sikuai2333/vibe-guard; vguard setup

安装完成后重启 Claude Code / Codex，新会话会自动加载 vibe-guard MCP tools。

为什么需要它

核心原则：少写框架，多做集成；少占上下文，多落地文件；少靠提示词，多靠阶段门禁。

当前能力

开发和测试环境：Windows + Node.js 22。

快速开始

1. 安装并注册 MCP

npm install -g github:sikuai2333/vibe-guard; vguard setup

只配置某一个宿主：

vguard setup claude
vguard setup codex

检查本机环境：

vguard doctor

2. 初始化目标项目

vguard init C:\path\to\your-project

这会在目标项目里创建或更新 .vibe-guard/、AGENTS.md、CLAUDE.md 等治理入口。已有内容会保留；工具只更新 <!-- vibe-guard:begin --> 和 <!-- vibe-guard:end --> 之间的托管区块。

3. 重启 Claude Code / Codex

重启后，新会话会看到 vibe-guard MCP tools。用户只需要告诉 agent 想做什么，agent 就可以按门禁流程调用工具。

flowchart LR
  A["用户提出开发目标"] --> B["vguard_development_guidance"]
  B --> C["vguard_prior_art"]
  C --> D["规格 / 架构 / 任务"]
  D --> E["vguard_next_task"]
  E --> F["实现代码"]
  F --> G["vguard_quality_gate"]
  G --> H["提交 / 交付"]

MCP Tools

命令速查

vguard setup 做了什么

[!NOTE] 所有写入都是合并模式，不覆盖已有其他配置。

手动启动 MCP Server：

vibe-guard-mcp

或从源码目录启动：

node dist/mcp.js

项目初始化产物

vguard init [path] 会创建或更新：

.vibe-guard/
  config.json
  links.json
  runbook.md
  skills/
    README.md
    skills.json
  reports/
    integrations.md
AGENTS.md
CLAUDE.md

[!CAUTION] 本仓库不会提交真实 .vibe-guard/、AGENTS.md、CLAUDE.md 或 .mcp.json。这些文件可能包含本机绝对路径或项目上下文，默认应留在目标项目本地。

外部集成

真正执行外部初始化命令必须显式确认：

vguard integration-run task-master . --execute --yes

执行前会备份已存在的工具托管目录，例如 .specify、.archcore、.taskmaster、.bmad-core。包含 <server> 这类未替换占位符，或包含不安全 shell 控制字符的命令，会被拒绝执行。

git clone https://github.com/sikuai2333/vibe-guard.git
cd vibe-guard
npm install
npm run build
npm test
node dist/cli.js doctor

src/
  agents.ts        Agent 指引安装 + 全局 MCP 设置
  check.ts         质量门禁检测和执行
  cli.ts           CLI 入口
  doctor.ts        本机环境检查
  integrations.ts  外部工具注册表和安全初始化执行器
  mcp.ts           MCP Server
  project.ts       项目文件、状态、runbook、任务
  research.ts      项目前调研
  skills.ts        按需加载的 skills 索引

许可证

MIT