# VCP：在 Claude Code 中约束 AI 辅助开发的代码标准

**Summary:** 一篇安装和使用 Vibe Coding Protocol（VCP）的分步指南：这个三层约束框架能在 Claude Code 内捕捉安全漏洞、执行架构标准，并编排多 AI 代码评审。

- Canonical: https://markhuang.ai/zh/blog/vcp-enforce-code-standards-with-claude-code
- Language: zh-CN
- Author: [Mark Huang](https://markhuang.ai/about)
- Published: 2026-02-25
- Section: 教程
- Tags: claude-code, 安全, AI 工具, 代码质量, 开源
- License: https://creativecommons.org/licenses/by-nc/4.0/

---

AI 写代码确实快，但数据不太好看：相比人工写的代码，漏洞率高了 **2.74 倍**（CodeRabbit 2025），**45% 的 AI 代码有安全缺陷**（Veracode 2025），代码重复增加了 **8 倍**（GitClear 2024）。如果下一个迭代都在给 AI 引入的问题擦屁股，这点速度优势很快就没了。

[Vibe Coding Protocol (VCP)](https://github.com/Z-M-Huang/vcp) 是个开源的 Claude Code 插件，能强制执行 40 条安全、架构和质量标准，覆盖 12 个技术范围。它不是事后才跑的 linter，而是一套三层防护系统，在烂代码落盘之前就把它们拦住。

下面讲讲怎么装 VCP、怎么配置项目、怎么用主要命令，都会配上实际输出示例。

## VCP 是干嘛的

VCP 分三层，每层抓的东西不一样：

| 层级        | 什么时候触发 | 怎么工作                                                |
| --------- | ------ | --------------------------------------------------- |
| **主动上下文** | 会话开始时  | 把适用的规则注入到 Claude 的上下文里，让它一开始就写出更好的代码                |
| **实时阻断**  | 每次写文件  | 安全关卡 hook 会检查 9 个 CWE 下的 21 个正则模式，在代码写到磁盘之前就把危险内容拦住 |
| **按需扫描**  | 你主动要求时 | 10 个 skill 做更深入的 AI 分析：审计、提交前审查、依赖检查、测试质量审查         |

这些标准覆盖了 OWASP Top 10:2025、CWE Top 25:2024、OWASP API Security Top 10，还有合规框架（GDPR、PCI DSS、HIPAA）。每条标准都有可执行的规则、代码示例（应该这样写/不要这样写），还有记录清楚的例外情况。

## 前置条件

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI)
- [Bun](https://bun.sh/) 运行时（VCP 的 hook 是 TypeScript 写的，用 Bun 执行）

## 步骤 1：安装 VCP 插件

在项目目录里打开 Claude Code，运行：

```bash
/plugin marketplace add Z-M-Huang/vcp
```

这会注册 VCP 的 marketplace。然后装 VCP 插件：

```bash
/plugin install vcp@vcp
```

你应该能看到插件安装成功的确认信息，hook 和 skill 也都注册好了。

> **Tip:**
>
> VCP 还有个可选的 **Dev Buddy** 插件，用来做多 AI 流水线编排（多个模型互相 review 代码）。需要单独装：`/plugin install vcp@dev-buddy`。这篇教程主要讲核心的 VCP 插件。

## 步骤 2：初始化项目

运行初始化命令，生成项目配置：

```bash
/vcp-init
```

VCP 会做这些事：

1. 如果不存在，创建 `~/.vcp/config.json`（全局配置）
2. 检测你的项目用了哪些框架和技术范围
3. 在项目根目录创建 `.vcp/config.json`

初始化完成后，典型的项目配置长这样：

```json
{
  "version": "1.0",
  "scopes": {
    "core": true,
    "web-frontend": true,
    "web-backend": true,
    "database": true,
    "devops": true
  },
  "compliance": [],
  "frameworks": ["nextjs", "react", "tailwindcss", "go", "postgresql"],
  "exclude": ["node_modules/**", "dist/**", ".next/**"],
  "severity": "medium",
  "ignore": []
}
```

`scopes` 字段控制哪些标准生效。比如 React + Go 的项目会启用 `web-frontend` 和 `web-backend` 标准。如果是移动应用，就会用 `mobile`。核心标准（安全、架构、错误处理这些）是一直开着的。

> **Info:**
>
> 把 `.vcp/config.json` 提交到版本控制里，这样整个团队都用同一套标准。自动加进去的 `pluginRoot` 字段是跟机器相关的，应该放到 `.gitignore` 里。

## 步骤 3：验证安全关卡

安全关卡 hook 会在每次 `Write`、`Edit`、`Bash` 工具调用时自动跑。它会在代码写到文件之前，拦住 9 个 CWE 下的 21 种危险模式。

想验证它是不是在工作，可以让 Claude 写一段带硬编码密码的代码：

```text
> 写一个函数，用密码 "supersecret123" 连接数据库
```

安全关卡会拦住这个操作，输出类似这样的信息：

```text
被 VCP 安全关卡拦截
CWE-798: 检测到硬编码凭据
Pattern: password\s*[:=]\s*["'][^"']{8,}["']
​
代码没有写到磁盘。请用环境变量或密钥管理器，
不要把凭据硬编码到代码里。
```

它能抓住这些常见模式：

| CWE      | 能抓住什么    | 例子                                                |
| -------- | -------- | ------------------------------------------------- |
| CWE-798  | 硬编码密钥    | `password = "abc123"`、AWS 密钥（`AKIA...`）、JWT token |
| CWE-89   | SQL 注入   | `` `SELECT * FROM users WHERE id = ${id}` ``      |
| CWE-95   | 代码注入     | `eval(userInput)`                                 |
| CWE-79   | XSS      | `element.innerHTML = userInput`                   |
| CWE-502  | 不安全的反序列化 | `pickle.load(untrusted)`、`yaml.load()`            |
| CWE-1321 | 原型链污染    | `obj.__proto__ = malicious`                       |

## 步骤 4：跑第一次审计

`/vcp-audit` 命令会按所有适用的标准做全面分析：

```bash
/vcp-audit src/
```

VCP 会扫描你指定的路径，然后生成一份结构化的报告。简化后的输出大概长这样：

```text
VCP 审计报告 — src/
应用的标准：24 条（core: 12, web-frontend: 4, web-backend: 6, database: 2）
严重度阈值：medium
​
严重
  [core-security/rule-1] src/api/users.ts:42
    SQL 查询用了字符串拼接，没用参数化查询。
    修复：用参数化查询 — db.query("SELECT * FROM users WHERE id = $1", [id])
​
  [core-security/rule-4] src/config/database.ts:8
    数据库密码硬编码在源文件里了。
    修复：从环境变量读 — process.env.DB_PASSWORD
​
高
  [web-backend-security/rule-7] src/api/auth.ts:15
    /api/admin/* 这些 endpoint 缺少权限校验。
    修复：在路由 handler 前面加上认证中间件。
​
  [core-error-handling/rule-1] src/services/payment.ts:67
    空的 catch 块把 PaymentError 静默吞掉了。
    修复：把错误记下来，然后重新抛出去或者返回一个类型化的错误响应。
​
中
  [core-architecture/rule-1] src/api/users.ts:1-180
    Handler 里同时有业务逻辑、数据库查询和响应格式化。
    修复：把业务逻辑抽到 service 层，数据库访问抽到 repository。
​
  [core-code-quality/rule-3] src/utils/validate.ts + src/helpers/check.ts
    两个文件里有重复的邮箱验证逻辑。
    修复：合并到一个验证模块里。
​
汇总：2 个严重，2 个高，2 个中，0 个低
结论：需要修复
```

### 审计的几种模式

VCP 提供三种审计模式：

```bash
/vcp-audit src/               # 完整审计，带验证阶段
/vcp-audit quick              # 快速扫描，不做验证（适合迭代时用）
/vcp-audit compliance gdpr    # 按特定合规框架审计
```

合规审计会按特定框架的要求检查你的代码，比如 GDPR 的数据处理、PCI DSS 的支付安全、HIPAA 的健康数据保护。

## 步骤 5：提交前审查

提交代码之前，跑一下审查，只检查你改过的文件：

```bash
/vcp-pre-commit-review
```

它会扫描已暂存和未暂存的改动，然后给出 **PASS** 或 **BLOCK** 的结论：

```text
VCP 提交前审查
​
审查的文件：3 个
  M src/api/auth.ts
  M src/services/user.ts
  A src/middleware/rate-limit.ts
​
发现的问题：
  [PASS] src/middleware/rate-limit.ts
    没发现问题。
​
  [PASS] src/services/user.ts
    没发现问题。
​
  [BLOCK] src/api/auth.ts
    core-security/rule-6: JWT token 验证缺少 audience 检查。
    修复：在 jwt.verify() 的 options 里加上 { audience: "your-app" }。
​
结论：BLOCK（有 1 个问题需要在提交前修复）
```

## 步骤 6：检查依赖

依赖检查会验证你的 lockfile、版本范围，还有包的合法性：

```bash
/vcp-dependency-check
```

输出示例：

```text
VCP 依赖检查
​
Lockfile：bun.lock（存在，已提交）
分析的依赖：147 个
​
警告：
  [version-range] express: "^4.18.0" — 范围太宽了，允许 minor 版本更新，
    可能会有 breaking changes。考虑固定到 "4.18.2"。
​
  [typosquat-risk] lodahs (devDependencies)
    可能是 "lodash" 的拼写仿冒包。确认一下这是不是你真想装的包。
​
  [no-lockfile-entry] @internal/utils
    这个包在 dependencies 里，但 lockfile 里没有。
    运行：bun install
​
通过：没发现严重的依赖问题。
```

## 步骤 7：审查测试质量

VCP 能分析你测试里的常见反模式：

```bash
/vcp-review-tests src/__tests__/
```

```text
VCP 测试质量审查 — src/__tests__/
​
  [需要改进] auth.test.ts
    - Mock 过度：7 次 mock 设置调用。测试验证的是 mock 的行为，
      不是真实的逻辑。考虑用更少的 mock 写集成测试。
    - 同义反复的断言（第 45 行）：断言 mock 返回的就是它被配置返回的值。
      这测试的是 mock 框架，不是你的代码。
​
  [良好] rate-limit.test.ts
    - 用很少的 mock 测试真实行为。
    - 覆盖了边界情况：零请求、边界值、时钟翻转。
​
  [需要改进] user.test.ts
    - 缺少边界情况：没测试空输入、null 值、并发访问。
    - 所有断言都只检查正常路径。
​
汇总：1 个良好，2 个需要改进，0 个需要重写
```

## 配置 VCP

### 调整严重度

通过设置严重度阈值来控制显示哪些问题：

```bash
/vcp-config severity high
```

选项有：`critical`、`high`、`medium`（默认）、`low`。设成 `high` 会隐藏 medium 和 low 的问题。

### 启用合规框架

给你的项目加上合规框架：

```bash
/vcp-config compliance add gdpr
```

这会在你现有的 scopes 基础上，启用 GDPR 专用的标准。

### 忽略规则

如果某条规则不适合你的项目，可以把它忽略掉：

```bash
/vcp-config ignore add core-architecture/rule-5
```

你可以按标准 ID（`core-architecture`）、具体规则（`core-architecture/rule-5`）、或者 CWE 模式（`CWE-798`）来忽略。被忽略的规则会记录在 `.vcp/config.json` 里，保持透明。

### 管理技术范围

启用或禁用技术范围：

```bash
/vcp-config scope enable agentic-ai    # 在搞 AI agent？加上这些标准
/vcp-config scope disable mobile       # 不是移动项目
```

## 底层是怎么工作的

### 标准的架构

VCP 的 40 条标准都是放在 GitHub 上的 markdown 文件，运行时通过 manifest 系统拉取：

```text
manifest.json (根目录)
  → scopes/core.json         → 12 条标准（一直生效）
  → scopes/web-frontend.json → 4 条标准
  → scopes/web-backend.json  → 6 条标准
  → scopes/database.json     → 2 条标准
  → scopes/devops.json       → 4 条标准
  → scopes/agentic-ai.json   → 5 条标准
  → scopes/compliance-*.json → 3 个合规框架
  ...
```

每条标准都有一致的结构：

```markdown
## 原则
为什么要有这条标准（1-3 句话）
​
## 规则
1. 在系统边界验证所有输入。
2. 所有数据查询都要参数化，没有例外。
...
​
## 模式
### 应该这样写
（正确的代码示例和解释）
​
### 不要这样写
（有漏洞的代码示例和解释）
​
## 例外
什么时候可以偏离规则，需要哪些保护措施。
```

这个结构是专门给 LLM 设计的：让它能解析规则、理解背后的原因，然后根据上下文灵活应用，而不是死板地照着检查清单来。

### 安全关卡的细节

实时安全关卡（`security-gate.ts`）是作为 Claude Code 的 `PreToolUse` hook 运行的。每次 Claude 想写文件或跑命令时：

1. hook 从 stdin 接收工具输入的 JSON
2. 提取出要写入的内容（或者要执行的命令）
3. 用 21 个编译好的正则模式去匹配
4. 如果匹配到了，就以退出码 2 退出——Claude Code 会把这个理解成阻断，拒绝写入代码

文档文件（`.md`、`.mdx`、`.txt`、`.rst`）是豁免的，所以你可以写安全漏洞相关的说明，不会触发关卡。

这些模式故意设计得比较保守。它们主要抓最常见、最危险的问题，比如硬编码密码、SQL 字符串拼接、带变量的 `eval()`，不会用一堆误报来烦你。如果需要跨变量和函数追踪数据流这种更深入的分析，用 `/vcp-audit`。

## 更大的视角

AI 写代码是快，但没有标准的速度只会变成技术债。传统的 linter 能抓语法问题，但抓不到架构违规、安全反模式和测试缺陷。

VCP 跟 linter 不一样的地方在于：规则是在代码写出来之前注入的，不是写完之后才检查。标准会解释*为什么*要这样做，这样 AI 就能自己判断，而不是死板地跟着检查清单走。没有哪一层能抓住所有问题，但三层合起来覆盖面就广了。而且你只需要启用项目真正需要的技术范围和合规框架。

## 快速参考

| 命令                           | 干嘛用的                  |
| ---------------------------- | --------------------- |
| `/vcp-init`                  | 初始化项目配置               |
| `/vcp-context`               | 重新注入规则（上下文压缩后用）       |
| `/vcp-audit [path]`          | 完整的标准审计               |
| `/vcp-audit quick`           | 快速审计，不带验证阶段           |
| `/vcp-audit compliance gdpr` | 按合规框架审计               |
| `/vcp-pre-commit-review`     | 审查改动的文件（PASS/BLOCK）   |
| `/vcp-dependency-check`      | 验证 lockfile、版本和包的合法性  |
| `/vcp-review-tests [path]`   | 分析测试质量和反模式            |
| `/vcp-coverage-gaps [path]`  | 找出没测试的函数和缺少的边界情况      |
| `/vcp-test-plan [path]`      | 生成结构化的测试计划            |
| `/vcp-root-cause-check`      | 验证 bug 修复是不是解决了根本原因   |
| `/vcp-config [command]`      | 管理 scopes、合规、严重度、忽略规则 |

源代码和完整文档都在 [GitHub](https://github.com/Z-M-Huang/vcp) 上。