vibe-guard

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

它主要解决几类常见问题：

• 编码前不知道已有同类项目，重复造轮子

• AI 直接开始写代码，缺少规格、架构和任务边界

• 大项目越写越偏，缺少可持续的上下文入口

• 没有测试、类型检查、审查记录，质量不可控

• 外部工具初始化容易误执行、误覆盖

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

当前状态

当前版本是 0.1.0 MVP。已实现并测试：

• CLI

• MCP Server

• 外部集成检测

• 默认 dry-run 的外部初始化命令

• prior-art research 调研报告

• 项目状态门禁

• 质量门禁

• Agent 指引文件生成

• 按需加载的 skills 索引

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

环境要求

必需：

• Node.js 22 或更高版本

• npm

• Git

推荐：

• GitHub CLI：gh

• Python

• uv / uvx

• Claude Code

• Codex

检查本机环境：

node dist/cli.js doctor

如果已经执行过 npm link：

vguard doctor

从源码安装

git clone https://github.com/sikuai2333/vibe-guard.git
cd vibe-guard
npm install
npm run build
npm test
npm link

之后可以直接使用：

vguard doctor

在一个项目中使用

vguard init C:\path\to\your-project
cd C:\path\to\your-project
vguard integrations .
vguard skills .
vguard research "你的项目想法"
vguard start .
vguard check

vguard init 会创建 .vibe-guard/ 目录，并在 AGENTS.md 和 CLAUDE.md 中写入托管区块。已有内容会保留；工具只更新 <!-- vibe-guard:begin --> 和 <!-- vibe-guard:end --> 之间的内容。

推荐工作流

1. vguard doctor 检查本机运行时和 Agent 工具是否可用。

2. vguard init . 初始化项目治理文件。

3. vguard integrations . 检查 Spec Kit、Archcore、BMAD、Task Master、agent-install 是已安装、可通过 npx/uvx 运行，还是缺失。

4. vguard integration-run <id> . 预览外部工具初始化命令。默认 dry-run，不会执行。

5. vguard skills . 查看可按需引入的 skills 来源和使用场景。默认不常驻加载。

6. vguard research "项目想法" 搜索 GitHub、npm、PyPI 风格候选，并写入 .vibe-guard/research.md。

7. vguard start . 检查 research、spec、architecture、tasks、quality 这些启动门禁。

8. vguard next . 从 .vibe-guard/tasks.json 读取下一个未阻塞任务。

9. vguard check 运行可检测到的质量检查，或记录显式跳过原因。

命令说明

vguard doctor

检查 Node.js、npm、Python、Git、GitHub CLI、uv、Claude Code、Codex，以及已知外部工作流工具。

vguard init [path]

创建或更新：

• .vibe-guard/config.json

• .vibe-guard/links.json

• .vibe-guard/runbook.md

• .vibe-guard/skills/README.md

• .vibe-guard/skills/skills.json

• .vibe-guard/reports/integrations.md

• AGENTS.md 托管区块

• CLAUDE.md 托管区块

vguard integrations [path] [--json]

报告以下工具的可用状态：

• Spec Kit

• Archcore

• BMAD Method

• Task Master AI

• agent-install

输出会包含当前状态、用途、文档链接和可执行建议命令。

vguard integration-run <id> [path] [--execute --yes]

支持的 id：

• spec-kit

• archcore

• bmad

• task-master

• agent-install

默认只预览命令：

vguard integration-run spec-kit .

真正执行必须同时提供 --execute 和 --yes：

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

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

vguard research "<idea>"

执行平衡模式的项目前调研，并写入 .vibe-guard/research.md。当前会检查：

• GitHub 仓库，优先使用 gh

• npm 包

• PyPI 风格搜索结果

如果某个来源失败，报告会记录失败原因，不会把“搜索失败”误判为“没有同类项目”。

vguard skills [path]

查看按需加载的 skills 索引。当前默认索引包含：

• mattpocock/skills

• multica-ai/andrej-karpathy-skills

vibe-guard 不会把这些 skills 全部塞进 AGENTS.md 或 CLAUDE.md。常驻入口只保留一行提示，详细说明在 .vibe-guard/skills/README.md，需要专项能力时再加载。

vguard status [path]

输出目标项目的门禁状态。

vguard start [path]

检查启动门禁。如果缺少必要门禁，会以非零状态退出。

vguard next [path]

读取 .vibe-guard/tasks.json，返回依赖已经完成的下一个待处理任务。

vguard check [--skip "reason"]

检测并运行质量检查。Node 项目会优先使用已有 npm scripts，例如 lint、typecheck、test、check。

显式跳过：

vguard check --skip "仅文档变更"

跳过原因会写入 .vibe-guard/reports/skip-log.md。

vguard install-agent claude|codex|cursor|all

为指定 Agent 写入非破坏性的使用指引。

vguard uninstall-agent claude|codex|cursor|all

只移除 vibe-guard 托管区块，不删除用户其他配置。

MCP Server

启动 MCP Server：

node dist/mcp.js

如果已经全局链接：

vibe-guard-mcp

提供的 MCP tools：

• vguard_project_status

• vguard_prior_art

• vguard_next_task

• vguard_quality_gate

• vguard_context_packet

• vguard_integrations

• vguard_integration_run

• vguard_skills

目录结构

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

安全模型

• 保留已有 AGENTS.md 和 CLAUDE.md 内容。

• 生成内容放在明确的托管区块内。

• 外部初始化命令默认 dry-run。

• 真实执行必须带 --execute --yes。

• 执行前会备份已知工具托管目录。

• 未替换占位符和不安全 shell 控制字符会被拒绝。

• 质量门禁允许跳过，但必须记录原因。

• skills 只做索引和按需加载提示，不默认塞进常驻上下文。

开发

npm install
npm run build
npm test
node dist/cli.js doctor

测试使用 Node.js 内置 test runner。

许可证

MIT