vibe-coding/global-coding-governance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
xiang
2026-07-25 23:45:09 +08:00
commit c7bd957e6f
47 changed files with 3870 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vibe-coding-governance/SKILL.md
+104
View File
@@ -0,0 +1,104 @@
---
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
用户本次明确指示
→ 已确认的任务文档和门禁结论
→ 作用域最近的项目指令
→ 项目自动化规则和模块既有惯例
→ 语言或框架通用惯例
```
这些来源发生实质冲突时，必须提出并请用户确认。项目级例外只有在明确记录后才能覆盖本流程。
vibe-coding-governance/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "Vibe Coding 开发规范"
short_description: "按 L0/L1/L2 分级门禁执行完整 Vibe Coding 开发流程"
default_prompt: "使用 $vibe-coding-governance 按约定的 Vibe Coding 规范评估并执行这个开发任务。"
vibe-coding-governance/assets/templates/01-需求分析模板.md
+74
View File
@@ -0,0 +1,74 @@
# {{ST编号}} {{子任务名称}}需求分析
## 1. 文档信息与需求来源
- 大需求：{{PM编号及链接}}
- 子任务编号：{{ST编号}}
- 原始需求版本：{{版本及链接}}
- 文档版本：{{版本}}
- 当前状态：{{状态}}
- 最后更新：{{时间}}
## 2. 目标、范围与非范围
### 2.1 目标
### 2.2 本次范围
### 2.3 非本次范围
## 3. 业务规则、角色和权限
## 4. 业务流程
### 4.1 正常流程
### 4.2 异常流程
### 4.3 状态流转
## 5. 功能点清单
| 功能编号 | 功能名称 | 需求说明 | 验收标准编号 |
|---|---|---|---|
| F-001 | {{功能}} | {{说明}} | AC-001 |
## 6. 涉及工程及现有实现
| 工程 | 当前职责 | 现有入口/代码 | 基准 Commit | 与本任务关系 |
|---|---|---|---|---|
## 7. 复用、新增、修改和迁移分析
| 功能编号 | 分类 | 复用或改造对象 | 说明 |
|---|---|---|---|
## 8. 接口、数据及上下游影响
## 9. 非功能与上线要求
## 10. 子任务依赖
## 11. 验收标准
| 编号 | 对应功能 | 可观察的完成条件 | 验证方式 |
|---|---|---|---|
| AC-001 | F-001 | {{条件}} | {{方式}} |
## 12. 需求矛盾、风险和待确认项
### 12.1 需求矛盾
| 编号 | 描述位置 A | 描述 A | 描述位置 B | 描述 B | 影响范围 | 状态 | 确认结论 |
|---|---|---|---|---|---|---|---|
### 12.2 风险与待确认项
| 编号 | 类型 | 内容 | 影响 | 状态 | 结论 |
|---|---|---|---|---|---|
## 13. 关联文档
- [大需求总览]({{链接}})
- [技术实现方案](./02.技术实现方案.md)
- [冒烟与逻辑验证](./03.冒烟与逻辑验证.md)
vibe-coding-governance/assets/templates/02-技术实现方案模板.md
+123
View File
@@ -0,0 +1,123 @@
# {{ST编号}} {{子任务名称}}技术实现方案
## 目录
> 使用 Markdown 目录或维护章节索引。
## 1. 文档信息、依据和版本
- 大需求：{{PM编号及链接}}
- 子任务：{{ST编号}}
- 原始需求版本：{{版本}}
- 需求分析：[01.需求分析.md](./01.需求分析.md)
- 方案版本：{{版本}}
- 方案状态：{{状态}}
- 代码基线：{{工程、分支、Commit}}
- 最后更新：{{时间}}
## 2. 目标、范围和验收依据
## 3. 现有实现与复用分析
| 工程 | 模块/符号 | 当前职责 | 复用或改造方式 | 代码证据 |
|---|---|---|---|---|
## 4. 总体实现方案
### 4.1 总体流程
### 4.2 模块关系
### 4.3 与其他子任务的关系
## 5. 功能点和接口总览
| 功能编号 | 功能名称 | 接口类型 | 接口/方法 | 工程 | 变更类型 | 章节 |
|---|---|---|---|---|---|---|
## 6. 各功能点实现方案
### 6.1 F-001 {{功能名称}}
#### 6.1.1 目标与依据
#### 6.1.2 涉及工程和模块
#### 6.1.3 现有逻辑及复用
#### 6.1.4 实现范围
#### 6.1.5 正常、异常和边界流程
#### 6.1.6 接口设计
#### 6.1.7 业务规则和校验
#### 6.1.8 数据读写
#### 6.1.9 权限、事务、并发和幂等
#### 6.1.10 缓存、搜索和消息
#### 6.1.11 兼容、测试和风险
> 为每个功能点重复本节。
## 7. 数据模型设计
### 7.1 数据库
| 表/实体 | 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 业务含义 | 变更类型 |
|---|---|---|---|---|---|---|---|
### 7.2 Redis
| Key | 类型 | Value 结构 | TTL | 数据来源 | 更新/失效策略 |
|---|---|---|---|---|---|
### 7.3 Elasticsearch
- 索引与 Alias：
- 文档 ID：
- Mapping：
- 文档示例：
- 同步、重试和 Reindex：
### 7.4 跨存储一致性
## 8. 跨工程改造与依赖顺序
| 工程 | 模块 | 改造内容 | 输入 | 输出 | 依赖 |
|---|---|---|---|---|---|
## 9. 变更影响与回归范围
### 9.1 影响矩阵
| 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 影响说明 | 是否改造 |
|---|---|---|---|---|---|---|
### 9.2 回归范围
| 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
|---|---|---|---|---|---|
## 10. 权限、安全、事务、并发和幂等
## 11. 非功能、日志、监控和审计
## 12. 兼容、迁移、发布和回滚
## 13. 测试与验证设计
## 14. 实施步骤
| 顺序 | 工程 | 实施项 | 前置依赖 | 对应功能/验收项 |
|---|---|---|---|---|
## 15. 方案取舍、风险和待确认项
## 16. 需求追溯
| 需求/功能 | 方案章节 | 工程 | 验收标准 | 验证用例 |
|---|---|---|---|---|
vibe-coding-governance/assets/templates/03-冒烟与逻辑验证模板.md
+91
View File
@@ -0,0 +1,91 @@
# {{ST编号}} {{子任务名称}}冒烟与逻辑验证
## 1. 文档信息与验证基线
- 大需求编号：{{PM编号}}
- 子任务编号：{{ST编号}}
- 需求版本：{{版本}}
- 技术方案版本：{{版本}}
- 文档版本：{{版本}}
- 当前状态：{{状态}}
## 2. 验证目标、范围和非范围
- 核心主流程：{{流程}}
- 本次功能点：{{功能}}
- 关键回归：{{回归}}
- 非本次验证范围：{{非范围}}
## 3. 环境、前置条件和测试数据
- 计划环境：{{环境}}
- 前置依赖：{{依赖}}
- 测试数据及脱敏要求：{{数据}}
## 4. 验证计划
> 第 1–4 节在 G2 前完成并确认。
### 4.1 静态检查、构建和自动化测试计划
| 编号 | 检查/测试 | 计划命令或方式 | 预期结果 |
|---|---|---|---|
### 4.2 冒烟及功能用例
| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 验证类型 |
|---|---|---|---|---|---|---|
| TC-001 | F-001 | {{场景}} | {{条件}} | {{步骤}} | {{预期}} | {{接口/自动化/人工}} |
### 4.3 关键影响回归计划
| 回归编号 | 影响编号 | 工程/功能 | 回归场景 | 预期结果 |
|---|---|---|---|---|
## 5. 实际执行基线
> 第 5–12 节在代码实现和 Review 后填写。
- 实际环境：{{环境}}
- 工程和分支：{{记录}}
- Commit 或版本标识：{{记录}}
- 执行时间：{{时间}}
## 6. 静态检查、构建和自动化测试结果
| 编号 | 实际命令或方式 | 结果 | 证据或说明 |
|---|---|---|---|
## 7. 冒烟及功能用例结果
| 用例编号 | 实际结果 | 状态 | 脱敏证据 | 执行时间 |
|---|---|---|---|---|
## 8. 关键回归结果
| 回归编号 | 实际结果 | 状态 | 脱敏证据 |
|---|---|---|---|
## 9. 接口和数据验证
- 接口：
- 数据库：
- Redis：
- Elasticsearch：
- 消息及异步任务：
- 日志和监控：
## 10. 失败、修复和重验
| 编号 | 失败内容 | 原因 | 修复 | 重验结果 |
|---|---|---|---|---|
## 11. 未执行项、遗留问题和风险
## 12. 验证结论
- 核心主流程是否通过：{{是/否}}
- 范围内功能是否全部验证：{{是/否}}
- 是否存在阻断问题：{{是/否}}
- 未验证项：{{内容}}
- 是否具备提测条件：{{是/否}}
vibe-coding-governance/assets/templates/03-冒烟自测用例模板.md
+38
View File
@@ -0,0 +1,38 @@
# {{ST编号}} {{子任务名称}}冒烟自测用例
## 1. 文档信息
- 大需求编号：{{PM编号}}
- 子任务编号：{{ST编号}}
- 需求版本：{{版本}}
- 技术方案版本：{{版本}}
- 提测版本或 Commit：{{Commit}}
- 测试环境：{{环境}}
## 2. 自测范围
- 核心主流程：{{流程}}
- 本次功能点：{{功能}}
- 关键回归：{{回归}}
- 非本次自测范围：{{非范围}}
## 3. 前置条件和测试数据
## 4. 冒烟自测用例
| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
|---|---|---|---|---|---|---|---|---|
| TC-001 | F-001 | {{场景}} | {{条件}} | {{步骤}} | {{预期}} | | 未执行 | |
## 5. 功能覆盖检查
| 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
|---|---|---|---|
## 6. 自测结论
- 核心主流程是否通过：{{是/否/未执行}}
- 需求功能点是否全部验证：{{是/否}}
- 是否存在阻断问题：{{是/否}}
- 未通过或未验证项：{{内容}}
- 是否具备提测条件：{{是/否}}
vibe-coding-governance/assets/templates/04-技术实现记录模板.md
+54
View File
@@ -0,0 +1,54 @@
# {{ST编号}} {{子任务名称}}技术实现记录
## 1. 实现信息
- 需求版本：{{版本}}
- 技术方案版本：{{版本}}
- 开发工程：{{工程}}
- 开发分支：{{记录}}
- 实现前 Commit：{{记录}}
- 实现后 Commit：{{记录}}
- 当前状态：{{状态}}
## 2. 功能实现状态
| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
|---|---|---|---|---|---|
## 3. 工程及代码改动
| 工程 | 模块/文件 | 改动内容 | 对应功能 |
|---|---|---|---|
## 4. 数据模型改动
- 数据库：
- Redis：
- Elasticsearch：
- 数据迁移：
## 5. 接口改动
## 6. 自动化测试改动
## 7. 与技术方案的差异
## 8. 编译和测试结果
| 检查项 | 命令/方式 | 结果 | 说明 |
|---|---|---|---|
## 9. 项目规范遵循情况
- 已读取项目规范：
- 参考的同类实现：
- 执行的格式化或静态检查：
- 与既有风格的差异及原因：
## 10. 遗留问题及风险
## 11. 敏感信息与 Git 操作确认
- 文档、日志和验证证据是否完成脱敏：{{是/否}}
- Agent 是否执行过 `git add`、`git commit`、`git push`：否
- Git 分支、Commit 和差异：{{记录}}
vibe-coding-governance/assets/templates/05-代码Review报告模板.md
+52
View File
@@ -0,0 +1,52 @@
# {{ST编号}} {{子任务名称}}代码 Review 报告
## 1. Review 信息
- 需求版本：{{版本}}
- 技术方案版本：{{版本}}
- 工程及分支：{{工程/分支}}
- Review Commit：{{Commit}}
- Review 范围：{{范围}}
- 变更清单或差异来源：{{用户提供/本次编辑记录}}
- Review 时间：{{时间}}
## 2. 需求符合性
| 检查项 | 结论 | 说明 |
|---|---|---|
| 需求功能覆盖 | | |
| 技术方案符合 | | |
| 影响范围处理 | | |
| 无范围外实现 | | |
## 3. 项目规范符合性
| 检查项 | 结论 | 说明 |
|---|---|---|
| 架构与分层 | | |
| 命名与代码风格 | | |
| 异常、日志和错误码 | | |
| 测试风格 | | |
## 4. 核心架构变化
| 检查项 | 是否变化 | 是否符合方案 | 结论 |
|---|---|---|---|
## 5. Review 问题
| 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
|---|---|---|---|---|---|
## 6. 问题修复及复查
| 问题编号 | 修复内容 | 复查结果 | 证据 |
|---|---|---|---|
## 7. 未确认风险
## 8. Review 结论
- Critical/High 是否清零：{{是/否}}
- 是否需要重开方案门禁：{{是/否}}
- 结论：在本次检查范围内{{结论}}
vibe-coding-governance/assets/templates/06-逻辑验证报告模板.md
+55
View File
@@ -0,0 +1,55 @@
# {{ST编号}} {{子任务名称}}逻辑验证报告
## 1. 验证信息
- 需求版本：{{版本}}
- 技术方案版本：{{版本}}
- 验证工程和分支：{{工程/分支}}
- 验证 Commit：{{Commit}}
- 验证环境：{{环境}}
- 验证时间：{{时间}}
## 2. 静态检查与构建
| 检查项 | 命令/方式 | 结果 | 证据或说明 |
|---|---|---|---|
## 3. 自动化测试
| 测试类型 | 测试范围 | 通过 | 失败 | 结果 |
|---|---|---|---|---|
## 4. 冒烟自测
| 用例编号 | 功能点 | 预期结果 | 实际结果 | 状态 | 证据 |
|---|---|---|---|---|---|
## 5. 关键回归
| 回归编号 | 场景 | 结果 | 证据 |
|---|---|---|---|
## 6. 接口与数据验证
- 接口：
- 数据库：
- Redis：
- Elasticsearch：
- 消息及异步任务：
- 日志和监控：
## 7. 失败与修复
| 编号 | 失败 | 原因 | 修复 | 重验结果 |
|---|---|---|---|---|
## 8. 未执行项及原因
## 9. 遗留问题和风险
## 10. 验证结论
- 核心主流程是否通过：{{是/否}}
- 范围内功能是否全部验证：{{是/否}}
- 是否存在阻断问题：{{是/否}}
- 是否具备提测条件：{{是/否}}
vibe-coding-governance/assets/templates/06-验收与交付报告模板.md
+54
View File
@@ -0,0 +1,54 @@
# {{ST编号}} {{子任务名称}}验收与交付报告
## 1. 交付信息
- 需求版本：{{版本}}
- 涉及工程：{{工程}}
- 开发分支：{{分支}}
- 发布分支或 Tag：{{分支/Tag}}
- 发布 Commit：{{Commit}}
- Git 信息来源：{{用户提供的记录}}
## 2. 开发交付内容
## 3. 测试结果
- 测试环境：{{环境}}
- 测试时间：{{时间}}
- 测试人员：{{人员}}
- 测试结论：{{结论}}
- 缺陷及处理情况：{{内容}}
- 测试报告：{{链接或编号}}
## 4. 发布记录
- 发布时间：{{时间}}
- 发布环境：{{环境}}
- 发布版本：{{版本}}
- 发布工程：{{工程}}
- 数据脚本：{{脚本}}
- 配置变化：{{配置}}
- 实际发布顺序：{{顺序}}
## 5. 上线验证
| 检查项 | 验证方式 | 结果 | 证据 |
|---|---|---|---|
| 核心主流程 | | | |
| 关键接口 | | | |
| 数据库 | | | |
| Redis | | | |
| Elasticsearch | | | |
| 消息及任务 | | | |
| 日志和监控 | | | |
## 6. 遗留问题
## 7. 最终结论
- 是否测试通过：{{是/否}}
- 是否发布成功：{{是/否}}
- 是否完成上线验证：{{是/否}}
- 是否满足归档条件：{{是/否}}
> `git add`、`git commit`、`git push` 由用户执行；报告证据必须脱敏。
vibe-coding-governance/assets/templates/07-验收与交付报告模板.md
+51
View File
@@ -0,0 +1,51 @@
# {{ST编号}} {{子任务名称}}验收与交付报告
## 1. 交付信息
- 需求版本：{{版本}}
- 涉及工程：{{工程}}
- 开发分支：{{分支}}
- 发布分支或 Tag：{{分支/Tag}}
- 发布 Commit：{{Commit}}
## 2. 开发交付内容
## 3. 测试结果
- 测试环境：{{环境}}
- 测试时间：{{时间}}
- 测试人员：{{人员}}
- 测试结论：{{结论}}
- 缺陷及处理情况：{{内容}}
- 测试报告：{{链接或编号}}
## 4. 发布记录
- 发布时间：{{时间}}
- 发布环境：{{环境}}
- 发布版本：{{版本}}
- 发布工程：{{工程}}
- 数据脚本：{{脚本}}
- 配置变化：{{配置}}
- 实际发布顺序：{{顺序}}
## 5. 上线验证
| 检查项 | 验证方式 | 结果 | 证据 |
|---|---|---|---|
| 核心主流程 | | | |
| 关键接口 | | | |
| 数据库 | | | |
| Redis | | | |
| Elasticsearch | | | |
| 消息及任务 | | | |
| 日志和监控 | | | |
## 6. 遗留问题
## 7. 最终结论
- 是否测试通过：{{是/否}}
- 是否发布成功：{{是/否}}
- 是否完成上线验证：{{是/否}}
- 是否满足归档条件：{{是/否}}
vibe-coding-governance/assets/templates/L1-精简变更日志模板.md
+71
View File
@@ -0,0 +1,71 @@
# {{需求名称}}精简变更日志
## 1. 基本信息
- 需求编号：{{编号}}
- 影响等级：L1
- 当前状态：{{状态}}
- 创建时间：{{时间}}
- 最后更新：{{时间}}
## 2. 需求说明
{{需求内容及来源}}
## 3. 变更范围
- 涉及工程：{{工程}}
- 涉及功能：{{功能}}
- 涉及接口：{{接口}}
- 非本次范围：{{非范围}}
## 4. 影响及回归范围
| 变更项 | 受影响功能/接口 | 影响说明 | 回归场景 |
|---|---|---|---|
## 5. 技术实现计划
- 现有逻辑：{{现状}}
- 复用内容：{{复用}}
- 计划改动：{{改动}}
- 数据变化：{{数据}}
- 风险与待确认项：{{风险}}
## 6. 冒烟自测用例
| 编号 | 功能点 | 验证场景 | 预期结果 |
|---|---|---|---|
## 7. 用户确认记录
- 确认结论：{{结论}}
- 确认时间：{{时间}}
- 确认来源：{{来源}}
## 8. 实际代码改动
| 工程/文件 | 实际改动 | 对应功能 |
|---|---|---|
## 9. Code Review
| 编号 | 等级 | 问题 | 处理结果 |
|---|---|---|---|
## 10. 逻辑验证和冒烟结果
| 检查/用例 | 执行方式 | 结果 | 证据 |
|---|---|---|---|
## 11. 遗留问题
{{遗留问题或“无”}}
## 12. 完成结论
- 是否开发完成：{{是/否}}
- 是否具备提测条件：{{是/否}}
- 未验证项：{{内容}}
- 文档和证据是否完成脱敏：{{是/否}}
- Agent 是否执行过 `git add`、`git commit`、`git push`：否
vibe-coding-governance/assets/templates/代码副本清单模板.md
+11
View File
@@ -0,0 +1,11 @@
# 代码分析副本清单
| 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 | 备注 |
|---|---|---|---|---|---|---|
## 异常记录
| 时间 | 工程 | 异常 | 处理状态 |
|---|---|---|---|
> `code/` 只用于调查；需求开发在独立项目工作区完成。
vibe-coding-governance/assets/templates/任务状态模板.md
+40
View File
@@ -0,0 +1,40 @@
# {{PM编号}} 任务状态
## 1. 大需求状态
- 需求名称：{{名称}}
- 当前需求版本：{{版本}}
- 当前总体状态：{{状态}}
- 当前主要阶段：{{阶段}}
- 最后更新时间：{{时间}}
- 当前阻塞项：{{阻塞或“无”}}
## 2. 门禁状态
| 门禁 | 状态 | 原始需求版本 | 确认文档及版本 | 代码版本标识 | 确认时间 | 确认来源 | 确认范围/说明 |
|---|---|---|---|---|---|---|---|
| G1 需求门禁 | 待确认 | | | 不适用 | | | |
| G2 方案门禁 | 未开始 | | | | | | |
| G3 开发交付门禁 | 未开始 | | | | | | |
## 3. 子任务状态
| 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
|---|---|---|---|---|---|
## 4. 阶段完成情况
| 子任务 | 需求分析 | 技术方案 | 验证计划 | 实现 | Review | 逻辑验证 | 测试 | 上线 |
|---|---|---|---|---|---|---|---|---|---|
## 5. 阻塞事项
| 编号 | 子任务 | 阻塞内容 | 影响阶段 | 提出时间 | 处理方 | 状态 |
|---|---|---|---|---|---|---|
## 6. 状态变更历史
| 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 变更原因 | 操作者 | 证据 |
|---|---|---|---|---|---|---|
> `STATUS.md` 是状态唯一事实来源。其他文档中的状态字段仅用于展示，发生冲突时以本文件为准。
vibe-coding-governance/assets/templates/原始需求版本索引模板.md
+16
View File
@@ -0,0 +1,16 @@
# 原始需求版本索引
| 版本 | 接收时间 | 需求来源 | 文件或目录 | 主要变化 | 状态 |
|---|---|---|---|---|---|
| v1 | {{时间}} | {{来源}} | [查看](./v1/) | 初始版本 | 当前版本 |
## 补充需求记录
| 编号 | 时间 | 来源 | 内容 | 是否进入正式版本 |
|---|---|---|---|---|
## 管理规则
- 原始文件只读，不覆盖旧版本。
- 每个版本尽量保存完整材料。
- 新版本到达后进行差异和影响分析。
vibe-coding-governance/assets/templates/大需求总览模板.md
+36
View File
@@ -0,0 +1,36 @@
# {{PM编号}} {{需求名称}}
## 1. 基本信息
- 大需求编号：{{PM编号}}
- 当前需求版本：{{版本}}
- 当前状态：{{状态}}
- 创建时间：{{时间}}
- 最后更新：{{时间}}
## 2. 需求来源
- [原始需求版本索引](./source/README.md)
- 当前需求版本：{{相对链接}}
## 3. 技术侧需求分析
- [技术侧需求分析](./技术侧需求分析.md)
## 4. 子任务
| 编号 | 业务模块 | 当前阶段 | 当前状态 | 前置依赖 | 需求分析 |
|---|---|---|---|---|---|
| ST-001 | {{模块}} | {{阶段}} | {{状态}} | {{依赖}} | [查看](./tasks/ST-001-模块/01.需求分析.md) |
## 5. 代码基线
- [代码副本清单](./code/MANIFEST.md)
## 6. 状态与门禁
- [任务状态](./STATUS.md)
## 7. 归档
测试、上线和上线验证完成后生成 `归档记录.md`，并在此补充链接。
vibe-coding-governance/assets/templates/归档记录模板.md
+72
View File
@@ -0,0 +1,72 @@
# {{PM编号}} {{需求名称}}归档记录
## 1. 基本信息
- 大需求编号：{{PM编号}}
- 需求名称：{{名称}}
- 最终需求版本：{{版本}}
- 需求负责人：{{负责人}}
- 开发完成时间：{{时间}}
- 测试通过时间：{{时间}}
- 上线时间：{{时间}}
- 归档时间：{{时间}}
- 最终状态：已归档
## 2. 需求目标与最终范围
- 需求背景：{{背景}}
- 最终实现范围：{{范围}}
- 未实现、延期或取消范围：{{内容}}
- 需求变更摘要：{{摘要}}
## 3. 子任务完成情况
| 子任务 | 业务模块 | 开发状态 | 测试状态 | 上线状态 | 文档 |
|---|---|---|---|---|---|
## 4. 工程发布信息
| 工程 | 发布分支 | 发布版本/Tag | 上线 Commit | 上线时间 |
|---|---|---|---|---|
## 5. 数据及配置变更
- 数据库：
- Redis：
- Elasticsearch：
- 配置中心：
- 数据迁移：
- 其他：
## 6. 测试和验证结论
- Code Review：
- 冒烟与逻辑验证：
- 测试人员测试：
- 上线验证：
## 7. 关键文档索引
- 原始需求：
- 技术侧需求分析：
- 子任务需求分析：
- 技术实现方案：
- 冒烟与逻辑验证：
- Code Review：
- 验收与交付：
## 8. 遗留问题和已知风险
| 编号 | 问题 | 影响 | 当前处理 | 后续建议 |
|---|---|---|---|---|
## 9. 后续维护说明
- 可复用能力：
- 维护注意事项：
- 后续优化方向：
- 关联需求：
## 10. 归档结论
{{最终结论}}
vibe-coding-governance/assets/templates/技术侧需求分析模板.md
+50
View File
@@ -0,0 +1,50 @@
# {{PM编号}} 技术侧需求分析
## 1. 文档信息
- 需求名称：{{名称}}
- 当前需求版本：{{版本}}
- 文档版本：{{版本}}
- 文档状态：{{状态}}
- 依据代码版本：[MANIFEST](./code/MANIFEST.md)
- 最后更新：{{时间}}
## 2. 需求背景与目标
## 3. 技术侧需求解读
## 4. 范围与非范围
### 4.1 本次范围
### 4.2 非本次范围
## 5. 业务模块及子任务拆分
| 子任务 | 业务模块 | 目标 | 依赖 |
|---|---|---|---|
## 6. 功能迭代清单
### 6.1 新增
### 6.2 修改
### 6.3 复用
### 6.4 废弃或迁移
## 7. 涉及工程
| 工程 | 当前职责 | 涉及功能 | 影响原因 | 预计变更类型 | 证据 |
|---|---|---|---|---|---|
## 8. 接口、数据及上下游影响
## 9. 非功能需求
## 10. 发布、迁移、兼容和回滚要求
## 11. 依赖、风险和待确认项
## 12. 子任务文档索引
vibe-coding-governance/assets/templates/模板索引.md
+21
View File
@@ -0,0 +1,21 @@
# Vibe Coding 模板索引
项目或用户提供的模板优先；没有专用模板时复制以下内置模板。
| 模板 | 用途 | 建议落地文件 |
|---|---|---|
| [L1-精简变更日志模板.md](L1-精简变更日志模板.md) | L1 单文档全流程 | `01.精简变更日志.md` |
| [大需求总览模板.md](大需求总览模板.md) | L2 大需求导航 | `README.md` |
| [任务状态模板.md](任务状态模板.md) | 当前状态、门禁、阻塞和历史 | `STATUS.md` |
| [原始需求版本索引模板.md](原始需求版本索引模板.md) | source 版本索引 | `source/README.md` |
| [代码副本清单模板.md](代码副本清单模板.md) | 分析代码基线 | `code/MANIFEST.md` |
| [技术侧需求分析模板.md](技术侧需求分析模板.md) | 大需求的研发侧功能解读 | `技术侧需求分析.md` |
| [01-需求分析模板.md](01-需求分析模板.md) | L2 子任务需求分析 | `01.需求分析.md` |
| [02-技术实现方案模板.md](02-技术实现方案模板.md) | L2 子任务单文档技术方案 | `02.技术实现方案.md` |
| [03-冒烟与逻辑验证模板.md](03-冒烟与逻辑验证模板.md) | G2 验证计划和 G3 实际验证结果 | `03.冒烟与逻辑验证.md` |
| [04-技术实现记录模板.md](04-技术实现记录模板.md) | 实际代码改动记录 | `04.技术实现记录.md` |
| [05-代码Review报告模板.md](05-代码Review报告模板.md) | 代码审查 | `05.代码Review报告.md` |
| [06-验收与交付报告模板.md](06-验收与交付报告模板.md) | 测试、上线和交付 | `06.验收与交付报告.md` |
| [归档记录模板.md](归档记录模板.md) | 大需求逻辑归档 | `归档记录.md` |
复制后删除不适用的示例行，但保留必要章节；不适用的关键章节写明原因。
vibe-coding-governance/references/01-分级与门禁.md
+94
View File
@@ -0,0 +1,94 @@
# 影响分级与确认门禁
## 按最高影响分级
评估业务行为、工程数量、接口契约、数据、架构、权限与安全、回归范围、发布协同和可回滚性。最高风险维度决定最终等级。
| 维度 | L0 | L1 | L2 |
|---|---|---|---|
| 业务行为 | 不改变运行行为 | 小范围行为变化 | 核心流程或多模块变化 |
| 工程 | 单个极小位置 | 单工程或少量模块 | 多工程或跨服务 |
| 接口 | 不涉及 | 少量兼容性变化 | 大量或破坏性变化 |
| 数据 | 不涉及 | 小范围兼容调整 | 迁移、重构或跨存储变化 |
| 架构 | 不涉及 | 核心架构不变 | 架构或依赖方向变化 |
| 安全 | 不涉及 | 低风险局部逻辑 | 核心权限、隔离或敏感数据 |
| 回归 | 极小 | 清晰且可控 | 广泛、复杂或不确定 |
| 发布 | 简单 | 可控且容易回滚 | 多方协同、高风险或难回滚 |
注释、拼写、静态文案和非行为性文档只有在不改变配置、契约、合规含义或运行行为时才属于 L0。
典型 L1 包括范围明确的 CRUD、兼容性接口调整或影响已知的小型缺陷修复。
典型 L2 包括跨服务改造、核心流程重构、破坏性接口、复杂迁移、大范围权限调整、广泛回归、多工程协同发布或影响明显不确定。
## 提出分级建议
修改代码前输出：
```markdown
## 变更影响等级评估
- 建议等级：
- 判断依据：
- 涉及业务：
- 涉及工程：
- 接口影响：
- 数据影响：
- 架构影响：
- 回归范围：
- 主要风险：
- 建议执行流程：
```
最终等级由用户确认。确认前允许只读调查。
## 门禁
### L0
一次性确认具体改动、位置、影响和最小验证方式，然后实施并验证。
### L1
完成 `01.精简变更日志.md` 的计划部分，包括需求、范围、方案、影响与回归、冒烟用例。编码前确认一次，然后实施、Review、验证并补全同一份日志。
### L2
执行三次门禁：
1. **G1 需求门禁：**确认大需求 `技术侧需求分析.md`、业务子任务拆分、全部 `01.需求分析.md`、范围、矛盾和待决事项。
2. **G2 方案门禁：**确认 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 第 1–4 节，包括接口与数据设计、影响、回归和验证计划。
3. **G3 开发交付门禁：**提交完成执行结果的 `03.冒烟与逻辑验证.md`、`04.技术实现记录.md` 和 `05.代码Review报告.md`，确认可以交给测试人员。
代码 Review 和验证是实现后的强制质量动作，不得在其执行前人为增加确认门禁。
在 `STATUS.md` 记录门禁状态：
```text
G1 需求门禁：待确认 / 已通过
G2 方案门禁：待确认 / 已通过
G3 开发交付门禁：待确认 / 已通过
```
每次门禁必须绑定：
- 当前原始需求版本；
- 本门禁确认的文档及文档版本；
- 相关代码分支、Commit 或等价版本标识；
- 确认时间、确认来源和确认范围。
门禁通过后，确认对象发生实质修改时，将门禁改为“需要重新确认”，记录失效原因并停止进入下一阶段。仅修正错别字、链接等不改变语义的编辑可以保留门禁，但要写入状态历史。
## 重开与升级
出现以下情况时，暂停受影响工作并退回失效阶段：
- 出现需求矛盾；
- 必须改变已确认的业务规则；
- 影响扩大到其他工程或核心功能；
- 接口兼容、数据设计或架构发生实质变化；
- 原方案不可行；
- 需要破坏性或不可逆操作。
新证据触发更高等级时必须升级，并在继续前补齐产物。只有用户明确确认后才能降级。
不改变已确认行为、契约、数据、架构和影响范围的私有实现调整无需重开门禁，但要写入实现记录。
vibe-coding-governance/references/02-L0与L1轻量流程.md
+113
View File
@@ -0,0 +1,113 @@
# L0 与 L1 轻量流程
## L0
仅对影响极小且不改变运行行为的变更使用 L0。
```text
理解并定位
→ 说明具体改动和影响
→ 用户确认
→ 修改
→ 检查差异
→ 执行最小必要验证
→ 报告结果
```
确认内容可以很精简：
```markdown
变更等级：L0
计划修改：
- ...
影响范围：
- ...
验证方式：
- ...
```
L0 不创建完整的 L2 PM 文档集，但仍必须保留用户已有改动、遵循项目规则、检查最终差异，并说明实际执行了哪些验证。
如果看似简单的修改会改变配置、运行行为、对外含义、契约或业务规则，必须升级。
## L1
维护一份持续更新的文档：
```text
01.精简变更日志.md
```
落地位置分两种情况：
- 独立需求：放在该需求的 `management/PM-<编号>-<名称>/` 大需求根目录下。
- 大需求下的子任务：放在对应 `tasks/ST-<编号>-<名称>/` 子任务目录内。
PM 编号尚未确定时使用 `PM-待确认-<需求名称>`，在本次 L1 编码前确认中由用户决定后再改为正式目录。Agent 不得自行生成永久编号。
编码前完成第 1–6 节并取得一次确认；编码后补充第 7–12 节。
```markdown
# 精简变更日志
## 1. 基本信息
- 需求编号：
- 需求名称：
- 影响等级：L1
- 当前状态：
## 2. 需求说明
## 3. 变更范围
- 涉及工程：
- 涉及功能：
- 涉及接口：
- 非本次范围：
## 4. 影响及回归范围
## 5. 技术实现计划
- 现有逻辑：
- 复用内容：
- 计划改动：
- 数据变化：
- 风险与待确认项：
## 6. 冒烟自测用例
| 功能点 | 验证场景 | 预期结果 |
|---|---|---|
## 7. 用户确认记录
## 8. 实际代码改动
## 9. Code Review
## 10. 逻辑验证和冒烟结果
## 11. 遗留问题
## 12. 完成结论
```
执行流程：
```text
只读调查
→ 编写计划部分
→ 用户确认一次
→ 实现
→ Review
→ 逻辑验证和冒烟
→ 补全日志
→ 标记开发完成
```
编码前可以写 Review 检查范围，但不能伪造 Review 结论。实际 Review 和测试结果只能在执行后填写。
如果发现广泛依赖、核心架构变化、破坏性兼容问题、复杂迁移或无法界定的回归范围，升级为 L2。
Agent 在 L1 中不得执行 `git add`、`git commit`、`git push`；暂存、提交和推送由用户完成。变更日志中的请求响应、日志和测试证据必须脱敏。
vibe-coding-governance/references/03-需求管理.md
+144
View File
@@ -0,0 +1,144 @@
# L2 需求管理
## PM 目录
收到新的 L2 需求后创建：
```text
management/
└─ PM-<大需求编号>-<需求名称>/
├─ README.md
├─ STATUS.md
├─ 技术侧需求分析.md
├─ source/
│ ├─ README.md
│ ├─ v1/
│ └─ v2/
├─ code/
│ └─ MANIFEST.md
└─ tasks/
└─ ST-001-<业务模块>/
├─ 01.需求分析.md
├─ 02.技术实现方案.md
├─ 03.冒烟与逻辑验证.md
├─ 04.技术实现记录.md
├─ 05.代码Review报告.md
└─ 06.验收与交付报告.md
```
测试、上线和上线验证完成后，在大需求根目录新增一份 `归档记录.md`；不移动整个目录。
PM 编号由用户决定。尚未提供编号时，可以使用：
```text
PM-待确认-<需求名称>
```
作为需求分析期间的临时目录，并将 PM 编号列为 G1 需求评审的必确认项。用户确定编号后，在进入技术方案阶段前重命名为正式目录，并检查外部链接。Agent 不得自行生成永久 PM 编号。
大需求 `README.md` 负责总览和子任务索引。使用相对链接，并维护大需求与每个子任务之间的双向关联。
## 原始需求版本
将每次收到的需求保存为完整、不可变的版本快照：
```text
source/v1/
source/v2/
source/v3/
```
不得覆盖或修改原始文件。在 `source/README.md` 中记录版本、接收时间、来源、主要变化和当前/废止状态。对话中的临时补充在进入正式版本前，应作为补充需求单独记录。
收到新版本后：
1. 比较新旧版本；
2. 识别受影响的模块、需求、方案、用例和实现；
3. 重开失效阶段；
4. 更新状态历史；
5. 已通过门禁失效时重新确认。
除非变更说明明确，不得假设新版本自动解决了旧版本中的矛盾。
## 代码分析副本
用户在 `code/` 下维护分析用代码副本，默认基准分支为 `master`，项目另有配置时以项目为准。Agent 可以执行只读 Git 检查和安全的基准分支同步，但不得执行 `git add`、`git commit`、`git push`。
更新流程：
```text
检查仓库状态
→ 确认基准分支和本地无业务修改
→ 使用只允许安全快进的方式获取更新
→ 记录工程、分支、最新 Commit 和更新时间
→ 更新 MANIFEST
→ 重新判断既有分析是否过期
```
Agent 不得在副本中实现需求。允许使用 `git status`、`git diff`、`git log` 和安全同步命令调查；发现脏工作区、错误分支、历史分叉或无法安全快进时停止并报告，不得强制重置或擅自解决分叉。
维护 `code/MANIFEST.md`：
| 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 |
|---|---|---|---|---|---|
真正的需求开发在独立的项目开发工作区中完成。
## 需求矛盾与歧义
需求前后冲突、版本描述不一致、语义歧义或关键条件缺失时，禁止猜测。
在相关 `01.需求分析.md` 中记录：
| 编号 | 描述位置 A | 描述 A | 描述位置 B | 描述 B | 影响范围 | 状态 | 确认结论 |
|---|---|---|---|---|---|---|---|
使用 `RC-001` 等稳定编号。展示两处描述，说明受影响模块和功能，列出可能理解但不代替用户选择，并请求确认。
确认前：
- 标记为 `待确认`；
- 不设计或实现受影响的业务决策；
- 安全时可以继续不受影响的工作；
- 无法继续时将子任务标记为待确认或阻塞。
确认后记录结论、确认人、时间、来源和受影响文档，并同步更新。
## 状态历史
以 `STATUS.md` 作为当前状态和历史记录的唯一事实来源。阶段和状态分开维护。
阶段：
```text
需求接入 → 需求分析 → 技术方案设计 → 冒烟用例设计
→ 技术实现 → Code Review → 逻辑验证 → 测试 → 发布 → 归档
```
状态：
```text
未开始 / 进行中 / 待确认 / 已阻塞 / 待评审 / 已完成 / 已跳过 / 已取消
```
记录：
- 大需求状态摘要；
- 每个子任务的当前阶段和状态；
- G1/G2/G3 状态；
- 阻塞事项；
- 只追加的变更历史，包括时间、对象、原/新状态、原因、操作者和证据链接。
不得删除或改写历史来掩盖返工。旧记录有误时追加更正。验证或测试失败时，重新打开实现阶段并记录回退。
门禁记录必须包含确认的原始需求版本、文档及文档版本、用户提供的代码版本标识、确认时间、来源和范围。文档中的“当前状态”字段只作为展示，发生冲突时以 `STATUS.md` 为准。
当前状态表：
| 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
|---|---|---|---|---|---|
历史表：
| 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 原因 | 操作者 | 证据 |
|---|---|---|---|---|---|---|
vibe-coding-governance/references/04-需求分析.md
+125
View File
@@ -0,0 +1,125 @@
# L2 需求分析
## 目标和边界
将业务需求转换为研发可理解的功能范围和业务子任务，说明需要改变哪些能力、可能涉及哪些工程。本阶段描述“需要开发什么”，不展开完整实现设计。
## 执行流程
```text
归档原始需求版本
→ 通读全部材料
→ 识别矛盾和问题
→ 按业务能力拆分
→ 更新并阅读代码副本
→ 调查架构、文档、接口和代码
→ 识别涉及工程及复用
→ 编写技术侧需求解读
→ 编写各子任务 01 文档
→ 更新关联和 STATUS
→ 提交 G1
```
拆分前必须完整阅读需求及相关附件。
## 按业务模块拆分
使用可独立识别的业务能力，例如：
```text
品牌重构
├─ 品牌管理
├─ 品牌审核
└─ 品牌授权
```
子任务应具备可识别的业务目标、参与者/流程/状态边界、验收结果或独立交付能力。不得将前端、后端、数据库直接作为一级业务子任务；技术工作放入适用的业务子任务内部。
记录前后置依赖、共享能力、接口、数据、联调顺序和联合测试要求。只有跨模块公共能力可以独立设计、交付和验证时，才建立公共技术子任务。
## 技术侧需求解读
需求分析应说明：
- 业务背景和目标；
- 对业务需求的技术侧解读；
- 范围和非目标；
- 业务模块与子任务；
- 需要新增、修改、复用、废弃或迁移的功能；
- 涉及工程及原因；
- 现有能力和复用判断；
- 接口、数据及上下游影响；
- 非功能要求；
- 发布、迁移、灰度、兼容、回滚和上线后验证要求；
- 依赖、风险和待确认项。
本阶段不提供完整类与方法设计、完整字段级接口定义、详细表结构或逐文件实现步骤。
使用 `已确认`、`待确认`、`待代码核实`、`技术建议` 标注结论来源。不得将推导结果写成原始需求事实。
## 识别涉及工程
根据架构文档和已记录 Commit 的代码证据调查：
- 入口和调用链；
- 模块依赖；
- 现有接口及调用方；
- 领域与数据模型；
- 认证和授权；
- 消息、事件和定时任务；
- 下游与外部系统。
记录：
| 工程 | 当前职责 | 涉及模块 | 影响原因 | 预计变更类型 | 证据 |
|---|---|---|---|---|---|
不得只根据仓库名称推断。
## 复用分析
每个功能按以下类型分类：
```text
直接复用 / 扩展复用 / 适配复用 / 需要修改 / 需要新增 / 需要废弃或迁移 / 待确认
```
指出具体接口、模块或代码符号及其复用边界。用户指定原接口时，记录当前调用方、当前行为、问题、目标行为、兼容性、保留/废弃策略、影响和回归需求。
## `01.需求分析.md`
每个子任务至少包含：
```markdown
# ST-XXX 子任务需求分析
## 1. 文档信息与需求来源
## 2. 目标、范围与非范围
## 3. 业务规则、角色和权限
## 4. 正常流程、异常流程和状态流转
## 5. 功能点清单
## 6. 涉及工程及现有实现
## 7. 复用、新增、修改和迁移分析
## 8. 接口、数据及上下游影响
## 9. 非功能与上线要求
## 10. 子任务依赖
## 11. 验收标准
## 12. 需求矛盾、风险和待确认项
```
功能使用 `F-001` 等稳定编号，验收标准使用 `AC-001`。链接到大需求和原始需求版本。
## 提交 G1
提交以下完整确认包：
- 大需求级 `技术侧需求分析.md`；
- 业务子任务拆分；
- 全部子任务的 `01.需求分析.md`；
- 范围与非范围；
- 需求矛盾、待确认项和风险；
- 当前原始需求版本；
- PM 编号；尚未确定时由用户在本次评审中决定；
- 相关文档链接和版本。
用户确认 G1 后才能开始技术方案设计。确认结论必须写入 `STATUS.md` 并绑定上述版本。
vibe-coding-governance/references/05-技术方案设计.md
+133
View File
@@ -0,0 +1,133 @@
# L2 技术方案设计
## 每个子任务一份文档
每个子任务只创建一份：
```text
02.技术实现方案.md
```
该子任务的全部功能、接口、CRUD、消息、回调、定时任务、批处理和数据模型设计都写在同一文档内。除非用户明确要求，不得拆成多个功能方案文件。使用目录、编号标题、功能编号和接口总览表管理长文档。
## 设计流程
```text
读取已确认的 01
→ 确认需求版本和代码基线
→ 调查现有实现和测试
→ 识别复用和约束
→ 设计总体流程
→ 设计每个功能和接口
→ 设计数据模型和一致性
→ 分析影响与回归
→ 设计实施顺序和验证
→ 更新 STATUS
```
设计中发现业务规则缺失或矛盾时，将受影响内容退回需求分析。
## 文档结构
```markdown
# ST-XXX 技术实现方案
## 目录
## 1. 文档信息、依据和版本
## 2. 目标、范围和验收依据
## 3. 现有实现与复用分析
## 4. 总体实现方案
## 5. 功能点和接口总览
## 6. 各功能点实现方案
## 7. 数据模型设计
## 8. 跨工程改造与依赖顺序
## 9. 变更影响与回归范围
## 10. 权限、安全、事务、并发和幂等
## 11. 非功能、日志、监控和审计
## 12. 兼容、迁移、发布和回滚
## 13. 测试与验证设计
## 14. 实施步骤
## 15. 方案取舍、风险和待确认项
## 16. 需求追溯
```
确实不适用的章节写明原因，不得机械填充。
## 每个功能必须有方案
每个 `F-XXX` 都要说明：
- 目标及需求/验收依据；
- 涉及工程和模块；
- 现有实现、可复用符号及 Commit 证据；
- 新增、修改、复用和非范围；
- 正常、异常和适用的边界流程；
- 接口、请求、响应、错误码和权限；
- 业务校验；
- 数据读写；
- 事务、一致性、并发和幂等；
- 缓存、搜索和消息行为；
- 兼容性；
- 测试和验证；
- 风险与待确认项。
简单 CRUD 也必须提供精简方案，至少覆盖校验、唯一性、分页/筛选、删除语义、权限、数据影响、适用的幂等和冒烟验证。
## 数据模型设计
发生任何数据模型变化时，在同一文档第 7 节设计。
### 数据库
说明实体含义、表、字段类型/可空/默认值、主键、约束、索引及查询依据、关系、枚举、审计/逻辑删除、容量、DDL、历史迁移、兼容、发布和回滚。
### Redis
说明 Key 规则、数据类型和值结构、事实数据源、TTL、读写时机、更新/失效、未命中/空值、原子性、并发、热 Key/大 Key 风险和旧 Key 清理。
### Elasticsearch
说明索引/Alias、文档 ID 和示例、Mapping/分词、适用的分片/副本/Routing、查询场景、数据库到 ES 的同步、延迟目标、重试修复、Reindex、历史初始化、Alias 切换和回滚。
### 跨存储一致性
明确事实数据源、写入顺序、事件或 CDC 链路、缓存失效、ES 同步、幂等、重试/补偿、对账和失败行为。
没有数据模型变化时，也要写明并指出复用依据。
## 影响与回归
每个被修改的接口或功能都要调查：
- 上游调用方和下游依赖；
- 复用同一核心方法的其他接口；
- 共享数据库表、Redis Key 和 ES 文档；
- 消息、消费者、任务、报表、导入导出；
- 前端、客户端和外部集成；
- 权限、状态流转、监控和发布顺序。
影响分类：直接、间接、兼容、数据、行为、性能、发布、潜在或已验证无影响。
维护：
| 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 说明 | 是否改造 | 回归级别 |
|---|---|---|---|---|---|---|---|
以及：
| 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
|---|---|---|---|---|---|
禁止写“回归相关功能”等模糊描述。必须列出具体场景。“无影响”也要写明检查过的调用链和数据链证据。
影响超出已确认范围时，记录后果和选项并请用户确认，不得静默扩大范围。
## 追溯与 G2
建立：
```text
需求 → F-XXX → 方案章节 → 涉及工程 → AC-XXX → TC-XXX 验证用例
```
`02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分完成后，一起提交 G2；确认前不得开始实现。
vibe-coding-governance/references/06-冒烟与逻辑验证.md
+119
View File
@@ -0,0 +1,119 @@
# L2 冒烟与逻辑验证
## 文档定位
每个子任务只维护一份：
```text
03.冒烟与逻辑验证.md
```
该文档分两个生命周期使用：
1. **G2 前：**设计核心主流程、范围内功能点和关键回归的验证计划。
2. **代码 Review 后：**填写实际执行结果、证据、失败修复和提测结论。
冒烟用于证明提测版本主流程可用、需求范围内功能点已验证；逻辑验证补充静态检查、构建、自动化测试、接口、数据及关键回归。二者使用同一组 `TC-XXX` 编号，禁止再维护第二份重复结果。
## G2 前必须设计
- 核心业务主流程；
- `01.需求分析.md` 中全部范围内功能点；
- `02.技术实现方案.md` 中新增或修改的接口；
- 明确要求的关键业务规则；
- 关键权限和状态流转；
- 主要数据新增、修改、查询和删除结果；
- 接口变更直接影响的关键旧功能；
- 会阻断提测的主要异常场景；
- 计划执行的构建、自动化测试和静态检查。
通常不要求穷举性能压测、所有并发组合、故障注入、全量兼容和无关系统级回归。某类风险属于本次需求核心内容时必须纳入。
## 文档结构
```markdown
# ST-XXX 冒烟与逻辑验证
## 1. 文档信息与验证基线
## 2. 验证目标、范围和非范围
## 3. 环境、前置条件和测试数据
## 4. 验证计划
### 4.1 静态检查、构建和自动化测试计划
### 4.2 冒烟及功能用例
### 4.3 关键影响回归计划
## 5. 实际执行基线
## 6. 静态检查、构建和自动化测试结果
## 7. 冒烟及功能用例结果
## 8. 关键回归结果
## 9. 接口和数据验证
## 10. 失败、修复和重验
## 11. 未执行项、遗留问题和风险
## 12. 验证结论
```
G2 时只确认第 1–4 节。第 5–12 节必须在代码实现和 Review 后按实际结果填写。
## 用例设计
计划表只描述如何验证：
| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 验证类型 |
|---|---|---|---|---|---|---|
每个功能点至少一条有效用例。简单 CRUD 的最低验证：
| 功能点 | 最低验证 |
|---|---|
| 新增 | 创建成功且数据结果正确 |
| 修改 | 修改成功且查询结果正确 |
| 查询 | 能查询到正确目标数据 |
| 列表 | 核心筛选和分页可用 |
| 删除 | 删除成功且后续结果符合规则 |
只为明确关键的边界增加用例，例如无权限、非法状态、重复提交、审核中禁止删除或接口变更后的关键调用方回归。
## Review 后执行
Review 阻断问题处理完成后，执行：
- 最终代码检查；
- 项目适用的格式化、Lint、静态分析和类型检查；
- 编译或构建；
- 单元测试和集成测试；
- 核心调用链、权限、事务、幂等和状态流转检查；
- `TC-XXX` 冒烟及功能用例；
- 技术方案中的关键影响回归；
- 本地接口与数据库、Redis、ES、消息和日志验证。
结果表只记录实际执行事实：
| 用例编号 | 实际结果 | 状态 | 证据 | 执行时间 |
|---|---|---|---|---|
环境、权限或依赖不足时标记“未验证”并说明原因，禁止默认通过。
## 失败处理
```text
记录失败
→ 分析原因
→ 返回实现阶段修复
→ 重新 Code Review
→ 重跑失败项和受影响回归
→ 更新结果
```
不得删除失败测试、弱化断言、跳过必要用例、吞掉异常或只重跑成功项。
## 提测结论
只有以下条件同时满足，才能写“具备提测条件”：
- 核心主流程通过；
- 范围内功能点均有执行记录；
- 没有未处理的 Critical/High 或其他阻断缺陷；
- 接口变更影响的关键旧功能完成必要回归；
- 未验证内容已明确且不阻断提测；
- 已记录实际验证基线，包括工程、分支和 Commit 或等价版本标识。
完成第 5–12 节后，该文档与 04、05 一起提交 G3。
vibe-coding-governance/references/06-冒烟自测.md
+104
View File
@@ -0,0 +1,104 @@
# L2 冒烟自测
## 定位
`03.冒烟自测用例.md` 是提测前的精简自测清单，目标是：
1. 保证提测版本核心业务主流程可用；
2. 保证需求范围内每个功能点都经过有效验证。
它不是完整测试方案，不要求穷举所有异常、并发和基础设施故障。只有某类风险属于本次需求核心内容时，才必须纳入冒烟。
## 编写时机
技术方案完成后、编码前编写初稿：
```text
01 需求分析
→ 02 技术方案
→ 03 冒烟用例
→ G2
→ 代码实现
```
实现中发现新的关键功能或影响范围时，先更新 02 和 03。
## 必须覆盖
- 本次需求核心主流程；
- `01.需求分析.md` 中全部范围内功能点；
- `02.技术实现方案.md` 中新增或修改的接口；
- 明确要求的关键业务规则；
- 关键权限和状态流转；
- 主要数据新增、修改、查询和删除结果；
- 接口变更直接影响的关键旧功能；
- 会阻断提测的主要异常场景。
通常不在冒烟阶段全面覆盖性能压测、全部并发组合、故障注入、全量兼容和无关系统级回归。
## 文档结构
```markdown
# ST-XXX 冒烟自测用例
## 1. 文档信息
- 大需求编号：
- 子任务编号：
- 需求版本：
- 技术方案版本：
- 提测版本或 Commit：
- 测试环境：
## 2. 自测范围
- 核心主流程：
- 本次功能点：
- 关键回归：
- 非本次自测范围：
## 3. 前置条件和测试数据
## 4. 冒烟自测用例
| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
|---|---|---|---|---|---|---|---|---|
## 5. 功能覆盖检查
| 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
|---|---|---|---|
## 6. 自测结论
- 核心主流程是否通过：
- 需求功能点是否全部验证：
- 是否存在阻断问题：
- 未通过或未验证项：
- 是否具备提测条件：
```
编码前填写场景和预期结果；执行后再填写实际结果、状态和证据。
## 最小用例原则
每个功能点至少一条有效用例。简单 CRUD 可采用：
| 功能点 | 最低验证 |
|---|---|
| 新增 | 创建成功且数据结果正确 |
| 修改 | 修改成功且查询结果正确 |
| 查询 | 能查询到正确目标数据 |
| 列表 | 核心筛选和分页可用 |
| 删除 | 删除成功且后续结果符合规则 |
只有明确关键的边界才增加用例，例如无权限、非法状态、重复提交、审核中禁止删除，或接口变更后的关键调用方回归。
技术方案中的完整回归范围可以大于冒烟范围；冒烟只选择影响主流程、需求功能和提测质量的关键场景。
## 通过结论
只有以下条件同时满足，才能写“具备提测条件”：
- 核心主流程通过；
- 范围内功能点都有验证记录；
- 没有阻断缺陷；
- 接口变更影响的关键旧功能完成必要回归；
- 未验证内容已明确且不阻断提测。
环境、权限或依赖不足时标记“未验证”，禁止默认通过。
vibe-coding-governance/references/07-代码实现.md
+145
View File
@@ -0,0 +1,145 @@
# 代码实现
## 实现输入
L2 编码以三份已确认文档为直接依据：
```text
01.需求分析.md
02.技术实现方案.md
03.冒烟与逻辑验证.md
```
确认需求版本、代码基线、开发工程和真实开发工作区。不得误在 `management/.../code/` 分析副本中开发。
Agent 可以使用 `git status`、`git diff`、`git log` 等只读命令调查和 Review，但禁止执行 `git add`、`git commit`、`git push`。暂存、提交和推送均由用户完成；其他可能改变分支或历史的操作必须符合用户指示和安全规则。
## 项目规范优先
编码前调查：
- `AGENTS.md`、`CLAUDE.md` 等 Agent 指令；
- `README.md`、`CONTRIBUTING.md` 和架构文档；
- `.editorconfig`、格式化、Lint、静态分析和构建配置；
- 测试规范；
- 当前模块和相邻同类代码。
作用域更近的项目规则优先。没有书面规范时，从同一模块的同类近期实现中提炼惯例，不得凭单个偶然文件确定全局风格。
保持目录、分层、命名、DTO/VO/Entity 划分、校验、异常、错误码、日志、权限、事务、数据访问、Redis、ES、消息、配置、依赖注入、注释和测试风格一致。
保持风格不代表复制明显错误、过时代码或安全缺陷；发现问题时说明并采用最小安全处理。
## 控制范围
禁止借需求开发进行无关的：
- 全工程格式化；
- 大范围重命名；
- 目录或框架替换；
- 旧代码全面重构；
- 注释清洗；
- 个人偏好的设计模式改造；
- 不必要的第三方依赖引入。
新增依赖前检查项目已有能力、统一实现、兼容性、构建/部署/安全风险和必要性，并写入方案与实现记录。
## 敏感信息保护
- 不在代码、配置、需求文档、日志、测试记录或验证证据中写入密码、Token、Cookie、私钥、访问密钥和完整连接串。
- 手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
- 接口请求响应、数据库结果、日志和截图只保留验证所需字段。
- 凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
- 发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。
## 实施顺序
```text
检查工作区、分支、Commit 和用户已有改动
→ 读取项目规范
→ 确认开发基线
→ 按功能点和工程依赖实施
→ 编写/更新自动化测试
→ 构建和测试
→ 对照冒烟用例自测
→ 更新实现记录和 STATUS
```
多工程通常按照：
```text
数据脚本与公共模型
→ 服务提供方
→ 服务调用方
→ 消息消费者
→ 前端或外部接入方
→ 联调
```
实际顺序以已确认方案为准。
## TDD
适合自动化的功能执行：
```text
建立失败测试
→ 确认因目标能力缺失而失败
→ 最小实现
→ 测试通过
→ 重构
→ 相关回归
```
缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。
不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。
## 方案偏差
编码中发现方案不可行时：
```text
记录问题
→ 判断需求和影响
→ 更新 02
→ 更新 03
→ 必要时重开门禁
→ 继续实现
```
接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。
## `04.技术实现记录.md`
记录实现事实，不复制整份方案：
```markdown
# ST-XXX 技术实现记录
## 1. 实现信息
- 需求版本：
- 技术方案版本：
- 开发工程：
- 开发分支：
- 实现前 Commit：
- 实现后 Commit：
- 当前状态：
## 2. 功能实现状态
| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
|---|---|---|---|---|---|
## 3. 工程及代码改动
## 4. 数据模型改动
## 5. 接口改动
## 6. 自动化测试改动
## 7. 与技术方案的差异
## 8. 编译和测试结果
## 9. 项目规范遵循情况
## 10. 遗留问题及风险
```
项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。
实现完成仅表示代码准备进入 Review，不等于子任务最终完成。
vibe-coding-governance/references/08-代码审查与验证.md
+127
View File
@@ -0,0 +1,127 @@
# 代码 Review 与逻辑验证
## 固定顺序
```text
代码实现完成
→ Code Review
→ 修复 Review 问题
→ 再次 Review
→ 执行 03 中的逻辑验证和本地接口冒烟
→ 输出结论
```
## Code Review
检查完整变更及必要的相邻上下文，不只看修改行。可以使用 `git status`、`git diff`、`git log` 等只读命令确定 Review 范围，但不得执行 `git add`、`git commit`、`git push`。
### 需求符合性
- 是否覆盖全部确认功能；
- 是否符合 01、02、03；
- 是否遗漏接口影响和回归；
- 是否擅自增加范围。
### 项目规范与质量
- 架构、分层、命名和代码风格；
- 复用、重复实现、异常、日志和错误码；
- 无关修改和大范围格式化；
- 依赖和测试风格。
### 核心架构变化
检查模块职责、分层边界、依赖方向、核心接口、数据事实源、Redis/ES/消息链路、权限、事务和状态流转。
分类为：
```text
方案内预期变化
实现细节调整且不影响架构
方案外架构变化，需要确认
疑似架构破坏，必须修复
```
### 严重缺陷
重点检查：
- 代码中不得有在循环中查询数据库的情况
- 越权、注入和敏感信息泄漏；
- 数据错误、丢失或覆盖；
- 空指针和未处理异常；
- 事务、并发、幂等和状态错误；
- 缓存/数据库/ES 不一致；
- 消息重复、丢失或无限重试；
- 死循环、资源泄漏和明显性能问题；
- 接口兼容破坏；
- 不可恢复的删除或迁移；
- 异常路径错误返回成功；
- 测试被弱化或跳过。
只能写“在本次检查范围内未发现严重问题”，不得承诺绝对无 Bug。
问题分级：
| 等级 | 含义 | 要求 |
|---|---|---|
| Critical | 安全、数据丢失、系统不可用 | 修复后才能继续 |
| High | 核心错误、架构破坏、明显兼容问题 | 修复后才能继续 |
| Medium | 局部逻辑、维护性或规范问题 | 原则上修复并记录 |
| Low | 优化或轻微风格问题 | 按范围处理 |
## `05.代码Review报告.md`
```markdown
# ST-XXX 代码 Review 报告
## 1. Review 信息和范围
## 2. 需求符合性
## 3. 项目规范符合性
## 4. 核心架构变化
## 5. Review 问题
| 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
|---|---|---|---|---|---|
## 6. 修复及复查
## 7. 未确认风险
## 8. Review 结论
```
发现问题后返回实现阶段，修复并重新 Review。
## 逻辑验证
Review 的阻断问题处理后，执行：
- 最终差异检查；
- 格式化、Lint、静态分析和类型检查；
- 编译或构建；
- 单元与集成测试；
- 关键调用链、数据读写、权限、事务、幂等和状态流转检查；
- 技术方案中的关键影响回归；
- `03.冒烟与逻辑验证.md` 中确认的验证计划。
失败时记录、分析、修复、重跑失败项和受影响回归。不得只重跑成功用例。
## 本地接口测试
本地环境可启动时：
```text
确认依赖和数据安全
→ 启动相关工程
→ 准备专用测试数据
→ 执行核心主流程接口
→ 验证范围内全部功能
→ 回归关键受影响接口
→ 检查数据库、Redis、ES、消息和日志
→ 保存证据
```
检查状态码、响应结构、业务字段、落库、缓存/索引、状态流转、权限、关键异常和直接受影响旧接口。
开始写数据前确认不是生产或不可随意修改的共享环境。需要人工登录、凭据或外部依赖时，明确请求用户协助。测试数据、请求响应、日志和截图必须脱敏，不得将凭据或生产敏感数据写入验证文档。
实际结果统一写入 `03.冒烟与逻辑验证.md` 第 5–12 节，不再创建单独逻辑验证报告。只有实际执行并有证据的内容可以标记通过；环境受限的内容写“未验证”及原因。
完成后提交 03、04、05 及关键证据，进入 G3。
vibe-coding-governance/references/09-交付与归档.md
+128
View File
@@ -0,0 +1,128 @@
# 交付、上线与归档
## 开发完成与需求完成
Review、逻辑验证和冒烟通过后，子任务可标记：
```text
逻辑验证：已完成
子任务：开发完成 / 待提测
```
这不等于需求已测试、上线或归档。
后续状态：
```text
开发完成 → 待提测 → 测试中 → 测试通过
→ 待发布 → 已上线 → 上线验证通过 → 已归档
```
测试失败时返回实现阶段，完成修复、Review、验证和重新提测，并追加状态历史。
## G3
向用户提交：
- `04.技术实现记录.md`；
- `05.代码Review报告.md`；
- 已填写执行结果的 `03.冒烟与逻辑验证.md`；
- 功能完成与未完成项；
- 验证证据；
- 遗留问题和风险；
- 是否具备提测条件。
用户确认后将 G3 标记为通过，进入测试人员提测流程。
## `06.验收与交付报告.md`
```markdown
# ST-XXX 验收与交付报告
## 1. 交付信息
- 需求版本：
- 涉及工程：
- 开发分支：
- 发布分支或 Tag：
- 发布 Commit：
## 2. 开发交付内容
## 3. 测试结果
- 测试环境：
- 测试时间：
- 测试人员：
- 测试结论：
- 缺陷及处理：
- 测试报告：
## 4. 发布记录
- 发布时间：
- 发布环境：
- 发布版本：
- 发布工程：
- 数据脚本：
- 配置变化：
- 实际顺序：
## 5. 上线验证
- 核心主流程：
- 关键接口：
- 数据库：
- Redis：
- Elasticsearch：
- 消息和任务：
- 日志和监控：
## 6. 遗留问题
## 7. 最终结论
```
外部测试报告可以保存链接、编号或副本，不必重复全文。
`git add`、`git commit`、`git push` 均由用户执行。Agent 可以读取并记录用户完成后的发布分支、Tag 和 Commit。
## 逻辑归档
归档不移动大需求目录。测试通过、上线并完成上线验证后，在大需求根目录维护一份：
```text
归档记录.md
```
归档文档汇总：
- 基本信息、最终需求版本和时间；
- 最终范围、延期或取消内容、需求变化；
- 子任务完成情况；
- 各工程发布分支、Tag、Commit 和时间；
- 数据库、Redis、ES、配置和迁移；
- Review、冒烟与逻辑验证、测试和上线结论；
- 关键文档相对链接；
- 遗留问题、风险和后续维护建议；
- 最终归档结论。
同时在 `STATUS.md` 追加：
```text
已上线 → 上线验证通过 → 已归档
```
目录、原始需求版本和历史状态不得删除。`code/` 副本即使以后继续更新，归档文档也必须保留本次实际发布的 Tag 和 Commit。
## 后续维护
归档事实记录原则上不直接改写。后续优化或修复建立新需求或维护任务，关联原 PM、最终需求版本和上线 Commit。
## OpenSpec 适配
默认归档载体为 `归档记录.md`。项目启用 OpenSpec 时，将其作为可替换归档后端：
```text
management 过程文档
→ 字段映射或转换
→ OpenSpec 归档
```
初期保持 management 文档为过程事实来源，避免人工双写。项目级适配规则应规定字段映射、归档命令、幂等、失败回退、状态同步和后续维护。
OpenSpec 的引入不得改变前置开发流程、文档编号、需求追溯和状态历史。
vibe-coding-governance/references/目录索引.md
+32
View File
@@ -0,0 +1,32 @@
# 参考文件目录索引
根据当前影响等级和阶段，只加载所需规则。
| 文件 | 适用场景 |
|---|---|
| [01-分级与门禁.md](01-分级与门禁.md) | 新需求分级、选择门禁、范围升级或更新门禁状态 |
| [02-L0与L1轻量流程.md](02-L0与L1轻量流程.md) | 执行 L0 或 L1 变更 |
| [03-需求管理.md](03-需求管理.md) | 建立或维护 L2 PM 目录、原始需求版本、代码副本、状态历史或需求矛盾 |
| [04-需求分析.md](04-需求分析.md) | 阅读需求、拆分业务子任务、识别工程或编写 `01.需求分析.md` |
| [05-技术方案设计.md](05-技术方案设计.md) | 编写或修改 `02.技术实现方案.md`，包括接口、数据模型、影响和回归范围 |
| [06-冒烟与逻辑验证.md](06-冒烟与逻辑验证.md) | 编写验证计划，执行冒烟、自动化检查和本地接口验证，并维护 `03.冒烟与逻辑验证.md` |
| [07-代码实现.md](07-代码实现.md) | 实现代码、遵循项目风格、执行 TDD 或维护 `04.技术实现记录.md` |
| [08-代码审查与验证.md](08-代码审查与验证.md) | Review 完成代码、检查严重缺陷、验证逻辑、启动本地服务或测试接口 |
| [09-交付与归档.md](09-交付与归档.md) | 标记开发完成、提测、记录发布、维护 `06.验收与交付报告.md` 或逻辑归档 |
## 阶段路由
```text
分级
├─ L0 → 01 + 02
├─ L1 → 01 + 02 + 07 + 08
└─ L2
├─ 接入与状态 → 01 + 03
├─ G1 需求 → 03 + 04
├─ G2 方案与验证计划 → 05 + 06
├─ 实现 → 07
├─ Review 与验证 → 08
└─ G3、交付与归档 → 09
```
需求变化时，重新读取所有被影响阶段的参考文件，不得只更新最新一份文档。
vibe-coding-governance/scripts/init_vibe_task.py
+221
View File
@@ -0,0 +1,221 @@
#!/usr/bin/env python3
"""安全初始化 Vibe Coding 的 L1 或 L2 文档目录。"""
from __future__ import annotations
import argparse
import datetime as dt
import re
import shutil
import sys
import tempfile
from pathlib import Path
SKILL_ROOT = Path(__file__).resolve().parent.parent
TEMPLATES = SKILL_ROOT / "assets" / "templates"
INVALID_NAME = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
def safe_name(value: str) -> str:
cleaned = INVALID_NAME.sub("_", value).strip().rstrip(".")
if not cleaned:
raise ValueError("名称不能为空或只包含非法字符")
return cleaned
def render(template_name: str, replacements: dict[str, str]) -> str:
text = (TEMPLATES / template_name).read_text(encoding="utf-8")
for key, value in replacements.items():
text = text.replace("{{" + key + "}}", value)
return text
def write_new(path: Path, content: str) -> None:
if path.exists():
raise FileExistsError(f"拒绝覆盖已有文件：{path}")
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
def parse_subtask(raw: str) -> tuple[str, str]:
if ":" not in raw:
raise ValueError(f"子任务格式应为 ST-001:名称，实际为：{raw}")
number, name = raw.split(":", 1)
number = number.strip().upper()
if not re.fullmatch(r"ST-\d{3}", number):
raise ValueError(f"子任务编号格式错误：{number}")
return number, safe_name(name)
def build_l1(args: argparse.Namespace) -> Path:
now = dt.datetime.now().astimezone().isoformat(timespec="seconds")
replacements = {
"需求名称": args.name,
"编号": args.requirement_id or "待确认",
"状态": "待确认",
"时间": now,
}
if args.subtask_dir:
target_dir = Path(args.subtask_dir).resolve()
if not target_dir.is_dir():
raise FileNotFoundError(f"子任务目录不存在：{target_dir}")
write_new(
target_dir / "01.精简变更日志.md",
render("L1-精简变更日志模板.md", replacements),
)
return target_dir
management_root = Path(args.management_root).resolve()
management_root.mkdir(parents=True, exist_ok=True)
pm_id = safe_name(args.requirement_id or "待确认")
target = management_root / f"PM-{pm_id}-{safe_name(args.name)}"
if target.exists():
raise FileExistsError(f"目标目录已存在：{target}")
temporary = Path(tempfile.mkdtemp(prefix=".vibe-init-", dir=management_root))
try:
write_new(
temporary / "01.精简变更日志.md",
render("L1-精简变更日志模板.md", replacements),
)
temporary.replace(target)
except Exception:
shutil.rmtree(temporary, ignore_errors=True)
raise
return target
def build_l2(args: argparse.Namespace) -> Path:
management_root = Path(args.management_root).resolve()
management_root.mkdir(parents=True, exist_ok=True)
pm_id = safe_name(args.pm_id or "待确认")
demand_name = safe_name(args.name)
target = management_root / f"PM-{pm_id}-{demand_name}"
if target.exists():
raise FileExistsError(f"目标目录已存在：{target}")
subtasks = [parse_subtask(item) for item in args.subtask]
if not subtasks:
raise ValueError("L2 至少需要一个 --subtask ST-001:名称")
numbers = [number for number, _ in subtasks]
if len(numbers) != len(set(numbers)):
raise ValueError("子任务编号不能重复")
now = dt.datetime.now().astimezone().isoformat(timespec="seconds")
common = {
"PM编号": pm_id,
"需求名称": demand_name,
"名称": demand_name,
"状态": "需求分析中",
"阶段": "需求分析",
"时间": now,
}
temporary = Path(tempfile.mkdtemp(prefix=".vibe-init-", dir=management_root))
try:
source_version = safe_name(args.source_version)
(temporary / "source" / source_version).mkdir(parents=True)
(temporary / "code").mkdir(parents=True)
(temporary / "tasks").mkdir(parents=True)
overview = render("大需求总览模板.md", common)
default_row = (
"| ST-001 | {{模块}} | 需求分析 | 需求分析中 | {{依赖}} | "
"[查看](./tasks/ST-001-模块/01.需求分析.md) |"
)
rows = "\n".join(
f"| {number} | {name} | 需求分析 | 未开始 | 待梳理 | "
f"[查看](./tasks/{number}-{name}/01.需求分析.md) |"
for number, name in subtasks
)
overview = overview.replace(default_row, rows)
write_new(temporary / "README.md", overview)
write_new(temporary / "STATUS.md", render("任务状态模板.md", common))
write_new(
temporary / "技术侧需求分析.md",
render("技术侧需求分析模板.md", common),
)
source_index = render("原始需求版本索引模板.md", common)
source_index = source_index.replace("| v1 |", f"| {source_version} |")
source_index = source_index.replace("./v1/", f"./{source_version}/")
write_new(temporary / "source" / "README.md", source_index)
write_new(
temporary / "code" / "MANIFEST.md",
render("代码副本清单模板.md", common),
)
phase_templates = [
("01-需求分析模板.md", "01.需求分析.md"),
("02-技术实现方案模板.md", "02.技术实现方案.md"),
("03-冒烟与逻辑验证模板.md", "03.冒烟与逻辑验证.md"),
("04-技术实现记录模板.md", "04.技术实现记录.md"),
("05-代码Review报告模板.md", "05.代码Review报告.md"),
("06-验收与交付报告模板.md", "06.验收与交付报告.md"),
]
for number, name in subtasks:
task_dir = temporary / "tasks" / f"{number}-{name}"
replacements = dict(common)
replacements.update(
{
"ST编号": number,
"子任务名称": name,
"PM编号及链接": f"[{pm_id}](../../README.md)",
"链接": "../../README.md",
}
)
for template_name, output_name in phase_templates:
write_new(
task_dir / output_name,
render(template_name, replacements),
)
temporary.replace(target)
except Exception:
shutil.rmtree(temporary, ignore_errors=True)
raise
return target
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="初始化 Vibe Coding L1/L2 文档，拒绝覆盖已有目标。",
)
subparsers = parser.add_subparsers(dest="level", required=True)
l1 = subparsers.add_parser("l1", help="初始化一份 L1 精简变更日志")
l1.add_argument("--name", required=True, help="需求名称")
l1.add_argument("--requirement-id", help="需求编号；未提供时使用“待确认”")
l1_target = l1.add_mutually_exclusive_group(required=True)
l1_target.add_argument("--management-root", help="独立需求的 management 目录")
l1_target.add_argument("--subtask-dir", help="既有大需求下的子任务目录")
l2 = subparsers.add_parser("l2", help="初始化完整 L2 PM 目录")
l2.add_argument("--management-root", required=True, help="management 目录")
l2.add_argument("--name", required=True, help="大需求名称")
l2.add_argument("--pm-id", help="PM 编号；未提供时使用“待确认”")
l2.add_argument("--source-version", default="v1", help="初始原始需求版本")
l2.add_argument(
"--subtask",
action="append",
default=[],
help="子任务，格式 ST-001:名称；可重复",
)
return parser
def main() -> int:
parser = build_parser()
args = parser.parse_args()
try:
target = build_l1(args) if args.level == "l1" else build_l2(args)
except (OSError, ValueError) as exc:
print(f"初始化失败：{exc}", file=sys.stderr)
return 1
print(f"初始化完成：{target}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
vibe-coding-governance/scripts/validate_vibe_docs.py
+208
View File
@@ -0,0 +1,208 @@
#!/usr/bin/env python3
"""校验 Vibe Coding 文档结构、链接、占位符和功能追溯。"""
from __future__ import annotations
import argparse
import re
import sys
from pathlib import Path
PLACEHOLDER = re.compile(r"\{\{[^{}\n]+\}\}")
MARKDOWN_LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
FUNCTION_ID = re.compile(r"\bF-\d{3}\b")
OLD_NAMES = {
"03.冒烟自测用例.md",
"06.逻辑验证报告.md",
"07.验收与交付报告.md",
}
class Report:
def __init__(self) -> None:
self.errors: list[str] = []
self.warnings: list[str] = []
def error(self, message: str) -> None:
self.errors.append(message)
def warning(self, message: str) -> None:
self.warnings.append(message)
def read_text(path: Path, report: Report) -> str:
try:
return path.read_text(encoding="utf-8")
except UnicodeDecodeError:
report.error(f"文件不是有效 UTF-8：{path}")
except OSError as exc:
report.error(f"无法读取文件：{path}（{exc}）")
return ""
def check_links(path: Path, text: str, report: Report) -> None:
for match in MARKDOWN_LINK.finditer(text):
target = match.group(1).strip()
if (
not target
or target.startswith(("#", "http://", "https://", "mailto:"))
or "{{" in target
):
continue
relative = target.split("#", 1)[0]
if not (path.parent / relative).resolve().exists():
report.error(f"失效链接：{path} -> {target}")
def required_root_files(root: Path) -> list[Path]:
return [
root / "README.md",
root / "STATUS.md",
root / "技术侧需求分析.md",
root / "source" / "README.md",
root / "code" / "MANIFEST.md",
]
def task_directories(root: Path) -> list[Path]:
tasks_root = root / "tasks"
if not tasks_root.is_dir():
return []
return sorted(path for path in tasks_root.iterdir() if path.is_dir())
def required_task_names(phase: str) -> list[str]:
names = ["01.需求分析.md"]
if phase in {"g2", "g3", "archive"}:
names += ["02.技术实现方案.md", "03.冒烟与逻辑验证.md"]
if phase in {"g3", "archive"}:
names += ["04.技术实现记录.md", "05.代码Review报告.md"]
if phase == "archive":
names += ["06.验收与交付报告.md"]
return names
def check_traceability(task: Path, report: Report) -> None:
requirement = read_text(task / "01.需求分析.md", report)
design = read_text(task / "02.技术实现方案.md", report)
validation = read_text(task / "03.冒烟与逻辑验证.md", report)
required_ids = set(FUNCTION_ID.findall(requirement))
if not required_ids:
report.warning(f"未在需求分析中发现功能编号：{task}")
return
for function_id in sorted(required_ids):
if function_id not in design:
report.error(f"{task.name} 的 {function_id} 未出现在技术方案中")
if function_id not in validation:
report.error(f"{task.name} 的 {function_id} 未出现在验证文档中")
def validate_l1(
root: Path,
allow_placeholders: bool,
report: Report,
) -> None:
document = root / "01.精简变更日志.md"
if not document.is_file():
report.error(f"缺少 L1 文档：{document}")
return
text = read_text(document, report)
if not allow_placeholders and PLACEHOLDER.search(text):
report.error(f"存在未填写占位符：{document}")
check_links(document, text, report)
def validate_l2(
root: Path,
phase: str,
allow_placeholders: bool,
report: Report,
) -> None:
required = required_root_files(root)
tasks = task_directories(root)
if not tasks:
report.error(f"未发现子任务目录：{root / 'tasks'}")
for task in tasks:
for name in required_task_names(phase):
required.append(task / name)
for child in task.iterdir():
if child.name in OLD_NAMES:
report.error(f"发现旧版文档名称：{child}")
if phase == "archive":
required.append(root / "归档记录.md")
existing_required: list[Path] = []
for path in required:
if not path.is_file():
report.error(f"缺少必需文件：{path}")
else:
existing_required.append(path)
status = root / "STATUS.md"
if status.is_file():
status_text = read_text(status, report)
for heading in ("原始需求版本", "确认文档及版本", "代码版本标识"):
if heading not in status_text:
report.error(f"STATUS.md 缺少门禁绑定字段：{heading}")
for path in existing_required:
text = read_text(path, report)
if not allow_placeholders and PLACEHOLDER.search(text):
report.error(f"存在未填写占位符：{path}")
check_links(path, text, report)
if phase in {"g2", "g3", "archive"}:
for task in tasks:
if all((task / name).is_file() for name in required_task_names("g2")):
check_traceability(task, report)
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="校验 Vibe Coding 的 L1/L2 文档完整性。",
)
parser.add_argument("path", help="L1 所在目录或 L2 PM 目录")
parser.add_argument(
"--phase",
choices=["l1", "structure", "g1", "g2", "g3", "archive"],
required=True,
help="目标校验阶段",
)
parser.add_argument(
"--allow-placeholders",
action="store_true",
help="允许模板占位符，适合刚初始化后的结构检查",
)
return parser
def main() -> int:
args = build_parser().parse_args()
root = Path(args.path).resolve()
if not root.is_dir():
print(f"校验失败：目录不存在：{root}", file=sys.stderr)
return 1
report = Report()
if args.phase == "l1":
validate_l1(root, args.allow_placeholders, report)
else:
validate_l2(root, args.phase, args.allow_placeholders, report)
for warning in report.warnings:
print(f"警告：{warning}")
for error in report.errors:
print(f"错误：{error}", file=sys.stderr)
if report.errors:
print(f"校验失败：{len(report.errors)} 个错误，{len(report.warnings)} 个警告")
return 1
print(f"校验通过：0 个错误，{len(report.warnings)} 个警告")
return 0
if __name__ == "__main__":
raise SystemExit(main())