---
name: vibe-coding-governance
description: 面向多种编码 Agent 的 Vibe Coding 全流程规范。凡是评估、规划、实现、修复、重构、审查、验证、测试、交付或归档软件变更，尤其是根据需求文档改造现有项目时使用。采用 SDD 规范驱动与 TDD/验收驱动原则，执行 L0/L1/L2 影响分级、用户确认门禁、需求追溯、项目规范遵循、代码 Review、自我验证、发布记录和逻辑归档。
---

# Vibe Coding 开发规范

将本技能作为 Vibe Coding 任务的流程规范。核心规则保持平台中立，以便适配 Codex、Claude、OpenCode 或其他编码 Agent。

## 核心原则

遵循以下链路：

```text
规范 → 验收证据 → 测试 → 实现 → 审查 → 验证
```

必须：

- 区分用户需求、代码事实和 Agent 建议。
- 提出方案或修改代码前，调查项目及其作用域内的指令。
- 保留用户已有改动，遵循项目架构、规范和代码风格。
- 在确认范围内采用最小且充分的改动。
- 将需求追溯到方案、实现、冒烟用例和验证证据。
- 暴露矛盾、歧义、缺失决策和扩大影响，禁止主观猜测业务结论。
- 仅将实际执行的检查标记为通过；无法执行时记录“未验证”及原因。
- 阶段开始、完成、阻塞、重开或变化时更新状态历史。
- 对需求、日志、接口请求响应、测试数据和验证证据进行脱敏，禁止保存凭据、密钥和生产敏感数据。
- 禁止执行 `git add`、`git commit`、`git push`；暂存、提交和推送均由用户执行。其他 Git 命令按任务范围和安全规则使用。

## 每个编码请求的开始动作

1. 阅读 [references/目录索引.md](references/目录索引.md)。
2. 使用只读操作调查适用的项目指令及相邻代码。
3. 按最高风险项评估变更影响等级。
4. 向用户说明建议等级、判断依据、范围、风险和执行流程。
5. 编码前门禁未通过前，不得修改代码。

如果请求已经属于既有 PM 任务，继续工作前读取当前需求版本、`STATUS.md`、相关编号文档和代码基线。

## 影响等级与门禁

分级和状态转换参见 [references/01-分级与门禁.md](references/01-分级与门禁.md)。

- **L0：**确认一次精确的小改动，实施后做最小验证。
- **L1：**维护一份精简变更日志，确认一次后实施、Review 和验证。
- **L2：**执行完整流程和三次门禁：
  - G1 确认大需求 `技术侧需求分析.md`、子任务拆分和全部 `01.需求分析.md`。
  - G2 确认 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分。
  - G3 确认已完成验证结果的 `03.冒烟与逻辑验证.md`、`04.技术实现记录.md` 和 `05.代码Review报告.md`。

不得对风险维度取平均值；最高风险特征决定等级。影响扩大时，暂停受影响工作，提出升级、补齐产物并获得确认。未经用户确认不得降级。

## 按当前阶段加载参考文件

- L0 或 L1：读取 [references/02-L0与L1轻量流程.md](references/02-L0与L1轻量流程.md)。
- L2 接入、原始需求版本、状态、代码副本或矛盾处理：读取 [references/03-需求管理.md](references/03-需求管理.md)。
- L2 需求分析：读取 [references/04-需求分析.md](references/04-需求分析.md)。
- 技术方案：读取 [references/05-技术方案设计.md](references/05-技术方案设计.md)。
- 冒烟自测与逻辑验证：读取 [references/06-冒烟与逻辑验证.md](references/06-冒烟与逻辑验证.md)。
- 代码实现、项目风格和 TDD：读取 [references/07-代码实现.md](references/07-代码实现.md)。
- 代码 Review、逻辑验证或本地接口测试：读取 [references/08-代码审查与验证.md](references/08-代码审查与验证.md)。
- 测试交付、发布、完成、归档或 OpenSpec：读取 [references/09-交付与归档.md](references/09-交付与归档.md)。

任务跨阶段时读取多个相关文件。L0/L1 任务不得无差别加载全部 L2 规范。

## 模板使用

创建规范文档时，优先使用项目或用户提供的模板；否则使用 [assets/templates/模板索引.md](assets/templates/模板索引.md) 中的内置模板。

## 文档约定

每个 L2 子任务每个阶段只维护一份主文档：

```text
01.需求分析.md
02.技术实现方案.md
03.冒烟与逻辑验证.md
04.技术实现记录.md
05.代码Review报告.md
06.验收与交付报告.md
```

编号表示流程顺序，不表示文档版本。一个子任务的全部功能和接口方案集中写入唯一的 `02.技术实现方案.md`，通过目录和稳定的章节编号管理。

## 自动化工具

- 使用 `scripts/init_vibe_task.py` 初始化 L1/L2 文档目录；L2 未确定 PM 编号时使用 `待确认`，并在 G1 需求评审中由用户确定。
- 使用 `scripts/validate_vibe_docs.py` 在 G1、G2、G3 或归档前检查目录、模板占位符、相对链接和功能追溯。
- 脚本不得执行 `git add`、`git commit`、`git push`，不得覆盖非空目标文件。

## 规则优先级与例外

在遵守 Agent 平台上层安全规则的前提下，按以下顺序执行：

```text
用户本次明确指示
→ 已确认的任务文档和门禁结论
→ 作用域最近的项目指令
→ 项目自动化规则和模块既有惯例
→ 语言或框架通用惯例
```

这些来源发生实质冲突时，必须提出并请用户确认。项目级例外只有在明确记录后才能覆盖本流程。