大型复杂软件开发：AI 协作开发流程完整指南
·
AI 协作开发流程完整指南
面向大型复杂软件的 Spec-Driven + Multi-Agent + Quality Gates 开发体系
目录
- 第一部分：背景与目标
- 第二部分：核心问题分析
- 第三部分：解决方案框架
- 第四部分：需求分层与 Spec 驱动
- 第五部分：多 Agent 并行开发
- 第六部分：质量保障体系
- 第七部分：完整模板文件包
- 第八部分：落地实践指南
第一部分：背景与目标
1.1 现状
一般AI辅助开发的开发流程是：
OpenSpec 对齐需求 → Claude Code 开发 → 编译 → 修复编译错误 → 运行验证 → 提交 → 下一个需求
这个流程已经有雏形了，对小需求很有效，但是应对大型软件需求时，会遇到问题。
1.2 核心诉求
- 多个 Agent 并行开发，提升开发效率
- 和 AI 更清楚地对齐需求，但需求太大，不知道怎么逐条对齐
- AI 没理解需求时，需要让 AI 多次修改
- 让 AI 遵循合适的开发规范，保障代码质量，参考微软AI-SDLC
1.3 目标
我需要的是优秀的流程和实践，已经了解了以下体系的核心概念：
- 大型项目 + AI 协作开发
- 多 Agent 并行
- Spec 驱动
- 质量门禁
现在需要提供一套可复制粘贴的完整模板文件，以及可落地的工具配置、Agent 配置。
第二部分：核心问题分析
2.1 现有流程的 4 个典型问题
虽然现在的流程对小需求有效，但做大型项目时会出现以下问题：
| 问题 | 表现 | 根本原因 |
|---|---|---|
| 需求太大，AI 一次吃不下 | 漏需求、误解边界、上下文漂移 | 没有分层对齐机制 |
| 多个 Agent 并行会互相踩代码 | 改同一模块、接口不一致、合并冲突严重 | 没有明确的任务边界和并行规则 |
| AI 改了很多次，仍然不稳定 | 反复修改仍然不符合预期 | 没有明确的验收标准和失败反馈格式 |
| 代码质量不可控 | 架构、测试、可维护性未必达标 | 没有统一规范、质量门禁、测试策略、审查机制 |
2.2 问题根源分析
这些问题的根源不是"AI 不够聪明"，而是：
- 需求粒度过大 — 直接对齐"大需求"，上下文会漂移
- 缺少中间层 — 从需求到代码之间没有结构化的转换层
- 并行边界不清 — 多个 Agent 没有明确的任务隔离
- 质量约束不足 — 靠"提示词"而不是靠"门禁"
2.3 核心结论
现在的流程缺的不是"更多 AI"，而是**“中间层”**。
需要把目标从**“一个 AI 帮我写代码”**升级成：
一个人类负责人 + 一个 Orchestrator + 多个专职 Agent
第三部分：解决方案框架
3.1 需要补充的 4 层中间结构
在现有流程中加入 4 层：
┌─────────────────────────────────────────┐
│ 需求分层 │
│ Product Spec → Feature Spec → Task Spec │
│ → Implementation Plan → Acceptance │
├─────────────────────────────────────────┤
│ 多 Agent 分工 │
│ Planner → Architect → Coder → Reviewer │
│ → Tester → Integration │
├─────────────────────────────────────────┤
│ 返工协议 │
│ 标准返工模板 + 结构化反馈 │
├─────────────────────────────────────────┤
│ 质量门禁 │
│ Spec 检查 → 设计检查 → 编译 → 测试 │
│ → 安全分析 → 验收 │
└─────────────────────────────────────────┘
3.1.1 需求分层
把"大需求"拆成：
| 层级 | 说明 |
|---|---|
| Product Spec（产品目标） | 为什么做这个功能 |
| Feature Spec（功能规格） | 功能边界和验收标准 |
| Story / Task Spec（任务规格） | 可执行的最小单元 |
| Implementation Plan（实现计划） | 技术方案和文件变更范围 |
| Acceptance Criteria（验收标准） | 可验证的完成条件 |
这样 AI 就不是直接面对"大而模糊的需求"，而是逐层往下执行。
3.1.2 多 Agent 分工
不要让所有 Agent 都"同时写代码"，应该让他们分别扮演角色：
| Agent | 职责 | 禁止 |
|---|---|---|
| Planner Agent | 拆需求、排依赖、生成任务图 | 不写代码 |
| Architect Agent | 定义接口、模块边界、数据流 | 不直接写生产代码 |
| Coder Agent A/B/C | 并行开发不同模块 | 不扩 scope |
| Reviewer Agent | 代码审查、规范检查 | 不替代 implementer 完成大改 |
| Tester Agent | 生成测试用例、回归验证 | - |
| Integration Agent | 合并、处理冲突、检查系统联调 | - |
3.1.3 返工协议
不要靠自然语言随便说"改一下"，要形成标准返工模板：
- 哪个需求没满足
- 哪个行为不符合预期
- 当前输出与 spec 的偏差是什么
- 要保留什么，不要误改什么
- 修改完成后如何验证
3.1.4 质量门禁
类似 AI-SDLC 的核心不是"AI 写代码"，而是 AI 每一步都有检查点：
| 门禁 | 检查项 |
|---|---|
| Spec 完整性检查 | 目标、非目标、验收标准、边界条件、依赖关系 |
| 设计一致性检查 | 模块边界、接口契约、数据结构 |
| 编译通过 | build |
| 单元测试通过 | unit test |
| 集成测试通过 | integration test |
| 安全/静态分析通过 | SAST, lint |
| 验收标准满足 | acceptance criteria |
| 提交说明完整 | changelog |
3.2 推荐的落地流程
升级后的主流程：
Epic → Story 切片 → Spec 对齐 → 设计 → 并行实现
→ 编译/静态检查/测试 → AI Review → 人工验收 → 提交
3.2.1 最关键的 4 个改造点
改造点 1：并行不是"多个 Agent 同时改主分支"
而是：
- 一个 story 一个分支
- 一个 agent 一个 worktree
- 一个 worktree 只负责一个明确 task
- 最后由 reviewer agent 做合并前检查
story-012-shell
story-012-view
story-012-service
story-012-tests
并行开发的是 task，不是"整段需求"。
改造点 2：大需求不要逐条对齐，要先切成 4 层
建议固定分层：
Product Vision → Epic → Story → Task
你和 AI 真正逐条对齐的，只应该是 Story 层。
改造点 3：AI 没理解需求，不要继续口头纠偏
改成固定的 变更单机制：
- AI 误解
- 不要直接说"不是这个意思，重新改"
- 新增一个
change-request.md - 里面写：现状偏差、正确行为、不允许改动的范围、新验收标准
这样 AI 第二轮、第三轮修改不会丢上下文。
改造点 4：质量不是靠"提示词更狠"，而是靠门禁
真正稳定的是：
- 编译必须过
- clang-tidy 必须过
- 单元测试必须过
- story 验收脚本必须过
- reviewer agent 必须过
- 人工 smoke test 必须过
3.3 4 个核心机制
你可以把整个体系理解成 4 个核心机制：
| 机制 | 解决问题 |
|---|---|
| Spec 机制 | 解决"AI 不懂我要什么" |
| Task slicing 机制 | 解决"大需求无法逐条对齐" |
| Multi-agent orchestration 机制 | 解决"如何并行提效" |
| Quality gates + SDL 机制 | 解决"如何保证代码质量、安全和可交付" |
只要这 4 个机制搭起来，你的流程就会从"AI 辅助编码"升级成"AI 驱动工程系统"。
第四部分：需求分层与 Spec 驱动
4.1 需求拆解金字塔
不要试图一次把"大需求"对齐完，要分层对齐：
L0：产品目标层
↓
L1：能力模块层
↓
L2：Epic / Feature 层
↓
L3：验收标准层
↓
L4：工程任务层
4.1.1 L0：产品目标层
一句话说明为什么做这个功能。
模板：
- 目标用户是谁
- 解决什么问题
- 成功指标是什么
- 不做什么
例子：
目标： 让企业用户可以批量导入客户数据，减少手工录入
成功： 1 万条 CSV 在 3 分钟内导入完成，错误行可回溯
不做： 暂不支持 Excel 宏、暂不支持多语言列名自动识别
4.1.2 L1：能力模块层
把目标拆成几个"能力块"：
- 文件上传
- 格式校验
- 异步导入
- 错误报告
- 导入历史查询
- 权限控制
4.1.3 L2：Epic / Feature 层
每个能力模块再拆成 Feature。
例如"用户与权限"拆成：
- 登录
- 注册
- 找回密码
- 角色管理
- 权限校验中间件
- 用户资料管理
每个 Feature 要写清楚：用户故事、边界、输入输出、异常场景、验收标准
4.1.4 L3：验收标准层
这一层最重要。每条都要可验证。
用这种格式：Given … When … Then …
比如：
- Given 用户拥有 customer.import 权限，When 上传符合模板的 CSV，Then 系统创建导入任务并返回任务 ID
- Given 第 32 行邮箱格式非法，When 任务执行完成，Then 错误报告中包含第 32 行及错误原因
4.1.5 L4：工程任务层
最后才是 AI 编码任务：
- 新增上传 API
- 新增 import_jobs 表
- 实现 CSV validator
- 实现 background worker
- 实现错误报告下载接口
- 增加 E2E 测试
4.2 Spec 模板
4.2.1 Epic 模板
# Epic: <epic-id> <title>
## Goal
一句话说明业务目标。
## User Value
用户为什么需要它。
## In Scope
-
-
## Out of Scope
-
-
## Constraints
- Qt/C++
- Desktop only
- Local single-user deployment
- No cloud dependency unless explicitly stated
## Risks
-
-
## Story Candidates
- story-001
- story-002
- story-003
4.2.2 Story 模板
# Story: <story-id> <title>
## User Goal
作为 <用户>，我希望 <动作>，从而 <价值>。
## Context
当前场景：
## In Scope
-
-
## Out of Scope
-
-
## Inputs
-
-
## Expected Behavior
-
-
## Failure Behavior
-
-
## Edge Cases
-
-
## Affected Modules
- UI:
- Application:
- Domain:
- Infrastructure:
## Constraints
-
-
## Dependencies
-
-
## Notes
-
-
4.2.3 Task 模板
# Task: [任务标题]
## 1. 背景
这个任务属于哪个 Epic / Feature？为什么要做？和哪些模块相关？
## 2. 目标
本任务必须实现的内容：
-
-
-
## 3. 非目标
本任务明确不做：
-
-
-
## 4. 输入上下文
**相关文档：**
- docs/specs/xxx.md
- docs/architecture/xxx.md
**相关代码：**
- src/modules/xxx
- src/shared/xxx
**依赖任务：**
- TASK-101
- TASK-102
## 5. 约束
- 不允许修改 xxx
- 必须复用 xxx
- 必须兼容旧接口
- 不得引入新依赖
## 6. 详细需求
### 功能要求
-
-
-
### 异常场景
-
-
-
### 边界条件
-
-
-
## 7. 接口/数据契约
### API
- path:
- method:
- request:
- response:
- errors:
### 数据模型
- 字段
- 类型
- 是否必填
- 默认值
- 约束
## 8. 验收标准
- [ ] 编译通过
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 满足场景 A/B/C
- [ ] 不影响已有功能 D
- [ ] 文档已更新
## 9. 实现建议（可选）
推荐改哪些文件：
避免哪些做法：
## 10. 输出要求
提交内容必须包括：
- 代码
- 测试
- 文档
- 风险说明
- 未完成项说明
4.2.4 Design 模板
# Design: <story-id>
## Goal
本次设计要解决什么问题。
## Current State
当前系统相关行为：
## Proposed Design
### Module Changes
-
### UI Flow
1.
2.
3.
### Data Flow
1.
2.
3.
### Error Handling
-
-
### State Management
-
-
## Alternatives Considered
### Option A
优点：
缺点：
### Option B
优点：
缺点：
## Decision
选择哪种方案，为什么。
## Testing Strategy
- unit tests
- integration tests
- acceptance checks
- manual smoke
## Risks
-
## Rollback Plan
-
4.2.5 Acceptance Checklist 模板
# Acceptance Checklist: <story-id>
## Functional
- [ ]
- [ ]
- [ ]
## Error Handling
- [ ]
- [ ]
## UI Behavior
- [ ]
- [ ]
## Regression
- [ ]
- [ ]
## Manual Smoke
- [ ]
- [ ]
## Evidence
- build log:
- test log:
- screenshots:
4.3 需求澄清与纠偏机制
4.3.1 需求澄清 Prompt 模板
你现在是本任务的需求分析助手。不要直接写代码。
请基于以下需求，完成 4 件事：
1. 用你自己的话复述需求
2. 列出已知范围、未知范围、潜在歧义
3. 给出必须确认的关键问题（最多 10 个，按优先级排序）
4. 生成一个结构化 Task Spec 草稿
要求：
- 不要擅自假设关键业务规则
- 如果某个信息缺失会影响实现，必须显式指出
- 输出必须分节，便于我逐条确认
需求如下：
[粘贴需求]
4.3.2 三次确认法
在 Builder Agent 真正写代码前，必须先做 3 步确认：
第一次确认：需求重述
让 AI 先回答：
- 我理解的目标是什么
- 本任务包含什么、不包含什么
- 依赖哪些已有能力
- 风险点是什么
如果这一步没对齐，禁止开始编码。
第二次确认：实现方案
让 AI 先给出：
- 准备修改哪些文件、新增哪些文件
- 接口怎么设计、数据结构怎么设计
- 测试怎么写
你确认后再让它写。
第三次确认：完成报告
编码后必须输出：
- 实现了什么
- 哪些验收项已满足、哪些没做
- 可能的风险
- 建议你如何验证
4.3.3 需求纠偏模板
你这次实现没有满足需求。请不要直接继续改代码，先输出"偏差分析"。
请按以下格式回答：
1. 你理解的原始需求
2. 你当前实现了什么
3. 与需求不一致的点
4. 造成偏差的原因
5. 你的修正方案
6. 受影响文件列表
7. 需要新增/修改的测试
8. 风险与回滚点
只有在我确认后再开始修改代码。
4.3.4 返工/修正单模板
# Rework Request
## Original Task
[任务名称]
## What is wrong
[具体描述哪里不对]
## Expected Behavior
[期望行为]
## Current Behavior
[当前行为]
## Violated Spec / Acceptance Criteria
- [哪条 spec 没满足]
- [哪条验收条件没满足]
## Constraints
- 保留哪些已有实现
- 不要修改哪些模块
- 不要改变哪些接口
## Required Fix
1. [修复点 1]
2. [修复点 2]
3. [修复点 3]
## Validation
修复后必须通过：
- [测试 1]
- [测试 2]
- [验收项 1]
第五部分：多 Agent 并行开发
5.1 并行开发的原则
5.1.1 适合并行的内容
| 适合并行 | 不适合并行 |
|---|---|
| 不同模块 | 同一核心文件被多人改 |
| 不同服务 | 需求本身还未稳定 |
| 已明确接口契约的上下游 | 接口契约还没定 |
| 测试与实现 | 还在频繁重构基础架构 |
| 文档与代码 | - |
| 前后端（契约确定后） | - |
5.1.2 并行的关键原则
原则 1：先冻结"共享面"，再并行"实现面"
并行前先锁定这些内容：
- 接口定义
- 数据模型
- 目录结构
- 编码规范
- 测试约定
- Feature flag 策略
否则多个 agent 会各自脑补。
原则 2：每个 agent 只改一个 bounded context
给 agent 的任务说明里明确：
- 允许改哪些目录
- 禁止改哪些公共文件
- 如果必须改 shared contract，先提变更申请，不直接改
原则 3：每个 agent 都要输出同一种交付物
不是只交代码，而是交：
- 修改摘要
- 影响范围
- 风险点
- 测试结果
- 未完成项
- 需要主控 agent 决策的问题
5.2 推荐的并行模式：主从式 5 Agent 模型
┌─────────────────────────────────────────────────────────┐
│ Agent 1: Planner / Spec Agent │
│ - 分析需求、生成任务树、识别依赖 │
│ - 输出任务卡、补齐验收标准 │
│ - 不直接写业务代码 │
├─────────────────────────────────────────────────────────┤
│ Agent 2: Architect Agent │
│ - 做技术方案、定模块边界、定接口契约、定数据模型 │
│ - 审核是否符合架构规范 │
├─────────────────────────────────────────────────────────┤
│ Agent 3~N: Builder Agents │
│ - 按任务卡编码实现 │
│ - 每个 Agent 只负责一个独立任务或子模块 │
│ - 必须遵守任务边界 │
├─────────────────────────────────────────────────────────┤
│ Agent X: Reviewer Agent │
│ - 检查需求覆盖率、检查是否越界修改 │
│ - 检查代码规范、检查潜在 bug/安全问题/测试缺失 │
├─────────────────────────────────────────────────────────┤
│ Agent Y: QA / Validation Agent │
│ - 运行测试、对照验收标准做回归验证 │
│ - 输出"通过 / 不通过 + 原因列表" │
└─────────────────────────────────────────────────────────┘
5.2.1 不同角色的产物边界
| 角色 | 只输出 |
|---|---|
| Spec Agent | 任务卡、Feature Spec、验收标准、风险清单 |
| Architect Agent | 技术设计、接口定义、数据模型、模块边界说明 |
| Builder Agent | 代码、测试、必要文档更新 |
| Reviewer Agent | Review 意见、风险和缺陷列表、修复建议 |
| QA Agent | 验证结果、测试报告、未通过项清单 |
这样做的好处：AI 不再"又当产品、又当架构、又当程序员、又当测试"，减少混乱和幻觉。
5.3 一个实用工作流
Step 0：主分支不直接开发
所有 agent 都从最新 main 切分支。
↓
Step 1：主规划 agent 生成任务图
输出：epic, feature, task, dependency graph, 可并行项，合并顺序
↓
Step 2：公共契约先行
先让一个 agent 或你自己完成：
API schema, migration plan, interface / type contract, acceptance tests skeleton
↓
Step 3：实现 agent 并行
agent-1：后端订单创建
agent-2：前端订单页面
agent-3：支付适配器
agent-4：测试与 CI
↓
Step 4：审查 agent 统一检查
检查：是否符合 spec、是否引入 breaking changes、测试是否足够、是否违反安全/质量规则
↓
Step 5：集成 agent / 人类合并
优先合并：contract → backend → core → frontend → tests / docs cleanup
5.4 避免代码冲突的规则
规则 1：共享文件必须列为"受控文件"
例如：
routes/index.tsapp.tsschema.tspackage.json- 公共类型定义文件
- 核心配置文件
这些文件不能让多个 Builder 同时改。
规则 2：先接口契约，后并行开发
如果多个 Agent 会依赖同一个接口：
- 先由 Architect 输出契约
- Builder 按契约开发
- 最后统一集成
规则 3：每个 Agent 独立分支
feature/TASK-101-auth-login
feature/TASK-102-role-api
feature/TASK-103-login-page
规则 4：先合底层，再合上层
例如：
- 先合数据模型 / API
- 再合前端页面 / 集成逻辑
规则 5：合并前必须过"集成 Agent"
如果你并行很多任务，最好增加一个"集成 Agent"：
职责：
- 拉取多个任务分支
- 解决集成问题
- 跑完整测试
- 输出集成报告
5.5 Agent 提示词模板
5.5.1 Planner Agent
你是 Planner Agent。
**目标：**
把一个大需求拆成可执行的 Epic / Story / Task，供后续 Agent 使用。
**必须输出：**
1. Epic Summary
2. Story List
3. 对每个 Story 给出：
- 用户目标
- 非目标
- 边界条件
- 验收标准
- 风险
- 推荐实现顺序
4. 每个 Story 再拆成 1~4 个 Task
5. 标出可以并行执行的 task
**约束：**
- 不写代码
- 不给模糊描述
- 每个 story 必须可独立演示和验收
- 每个 task 必须小而明确
- 避免"优化""完善""支持更多情况"这类模糊词
请优先识别：
- UI 状态复杂度
- 跨模块影响
- 本地文件/配置影响
- 性能风险
- 回滚难度
5.5.2 Architect Agent
你是 Architect Agent。
**输入：**
- story.md
- acceptance-checklist.md
- 相关代码
**输出：**
1. 变更目标
2. 影响模块
3. UI 事件流
4. 数据流
5. 错误流
6. 状态变化
7. 替代方案比较
8. 推荐方案
9. 测试策略
10. 风险与回滚方案
**要求：**
- 面向 Qt/C++ 桌面单体软件
- 优先保持模块边界清晰
- 尽量避免牵一发动全身
- 明确列出"不改什么"
5.5.3 Builder Agent
你是 Builder Agent。
**开始前必须阅读：**
- AGENTS.md
- story.md
- design.md
- acceptance-checklist.md
- DEFINITION_OF_DONE.md
**工作方式：**
1. 先给出 implementation plan
2. 明确要改哪些文件
3. 只实现当前 task
4. 改动最小化
5. 完成后执行本地验证
6. 输出 summary / risks / validation
**必须遵守：**
- 不扩 scope
- 不擅自重构无关代码
- 不凭猜测实现未写入 spec 的需求
- 必须处理失败路径与边界条件
- 必须补测试或至少补验收脚本
5.5.4 Reviewer Agent
你是 Reviewer Agent。
你的职责不是表扬代码，而是发现问题。
请从以下角度审查：
1. 是否符合 story 和 acceptance-checklist
2. 是否误解需求
3. 是否存在过度实现
4. 是否改动过大
5. Qt/C++ 生命周期/线程/信号槽/所有权风险
6. 测试是否足够
7. 是否存在隐性回归风险
**输出格式：**
- Must Fix
- Should Improve
- Nice to Have
- Merge Recommendation: YES / NO
5.5.5 Verifier Agent
你是 Verifier Agent。
**目标：**
验证当前 story 是否真正完成。
**必须检查：**
- build
- tests
- lint
- acceptance checklist
- smoke path
**输出：**
1. Verification Summary
2. Evidence
3. Failed Checks
4. Risk Notes
5. Final Verdict: PASS / FAIL
第六部分：质量保障体系
6.1 质量门禁设计
6.1.1 6 道质量门
| 门禁 | 检查内容 |
|---|---|
| Gate 1：Spec 完整性检查 | 目标、非目标、验收标准、边界条件、依赖关系（如果没有，不允许开发） |
| Gate 2：设计一致性检查 | 是否符合架构原则、是否违反模块边界、接口是否定义清楚、数据模型是否清楚 |
| Gate 3：实现质量检查 | 编译通过、lint 通过、类型检查通过、静态分析通过 |
| Gate 4：测试质量检查 | 单元测试、集成测试、回归测试、关键路径测试 |
| Gate 5：安全与稳定性检查 | 输入校验、权限控制、敏感数据、异常处理、日志合理、资源泄漏/并发问题/超时问题 |
| Gate 6：验收检查 | 是否满足任务卡中的验收标准、是否更新文档、是否可演示、是否有已知风险说明 |
6.1.2 质量门禁分类
| 门禁类型 | 检查项 |
|---|---|
| 基础门禁 | lint, format, type check, unit test, integration test, build |
| 质量门禁 | coverage threshold, complexity threshold, dead code check, API contract check, migration check |
| 安全门禁 | SAST, dependency scan, secrets scan, license scan, container/image scan, IaC scan |
6.2 Definition of Ready / Done
6.2.1 Definition of Ready
一个任务只有在满足以下条件时才能交给 AI 开发：
# Definition of Ready
- [ ] 有明确任务标题
- [ ] 有背景说明
- [ ] 有目标与非目标
- [ ] 有清晰验收标准
- [ ] 有涉及文件/模块范围
- [ ] 有接口/数据契约（如适用）
- [ ] 有依赖任务说明
- [ ] 有边界和限制说明
- [ ] 没有关键歧义未解决
6.2.2 Definition of Done
# Definition of Done
- [ ] 代码已实现
- [ ] 编译通过
- [ ] Lint/类型检查通过
- [ ] 单元测试通过
- [ ] 集成测试通过（如适用）
- [ ] 验收标准已逐条满足
- [ ] 文档已更新
- [ ] 无高风险安全问题
- [ ] 无已知阻塞性缺陷
- [ ] 提交说明完整
6.3 规范前置：仓库里的 5 类核心文件
在 repo 根目录放：
| 文件 | 内容 |
|---|---|
| AGENTS.md | 给所有 agent 的统一行为规范：项目目标、技术栈、目录说明、禁止事项、代码风格、测试要求、提交要求、安全要求 |
| ARCHITECTURE.md | 系统边界、模块职责、接口关系、数据流、关键约束 |
| ENGINEERING_STANDARDS.md | 命名规范、错误处理规范、日志规范、事务规范、API 规范、DTO / domain model 分层规则、前端状态管理规则、可观测性要求 |
| SECURITY_REQUIREMENTS.md | 身份认证、权限校验、secrets 管理、输入校验、输出编码、审计日志、三方依赖要求、数据脱敏、PII 处理、禁止硬编码密钥 |
| PR_TEMPLATE.md | 要求 AI 每次 PR 都说明：对应 spec、验收标准覆盖情况、风险、测试、安全影响、回滚方案 |
6.4 Qt/C++ 特定规则
6.4.1 生命周期规则
# Qt/C++ Rules
## 生命周期
- 优先使用 RAII
- QObject 必须明确父子关系
**禁止：**
- 不明确裸指针所有权
- 跨线程 UI 调用
## 信号槽
- 避免重复连接
- 避免复杂逻辑在槽函数
## UI 与业务分离
UI 层只处理：
- 交互
- 状态展示
业务逻辑必须下沉到 service。
6.4.2 Review Checklist
# Review Checklist
## 需求一致性
- [ ] 是否完全满足 story 的"必须项"
- [ ] 是否误实现了"非目标"
- [ ] 是否漏掉边界行为
- [ ] 是否漏掉错误提示
- [ ] 是否漏掉状态恢复
## Qt / C++ 质量
- [ ] 对象生命周期是否清晰
- [ ] 父子对象所有权是否正确
- [ ] 信号槽连接是否安全
- [ ] 跨线程访问是否安全
- [ ] RAII 是否正确使用
- [ ] 是否存在裸指针风险
- [ ] 异常/错误码处理是否一致
- [ ] UI 状态切换是否完整
## 架构一致性
- [ ] UI 层没有塞业务逻辑
- [ ] Service 层没有依赖 View 层
- [ ] 新接口命名是否一致
- [ ] 配置、路径、持久化是否集中管理
## 测试
- [ ] 新逻辑有测试覆盖
- [ ] 回归风险点有验证
- [ ] 至少一个失败路径被验证
## 变更纪律
- [ ] 改动是否最小化
- [ ] 是否避免了无关重构
- [ ] 是否保留可回滚性
6.5 失败闭环
| 失败类型 | 处理方式 |
|---|---|
| A：需求理解错误 | 回到 Spec 层，修改任务卡，增加非目标和边界说明 |
| B：实现方案错误 | 回到 Architect 层，重定义接口和文件边界 |
| C：代码质量不足 | Reviewer 出缺陷单，Builder 按缺陷单修 |
| D：验收不通过 | QA 逐条指出失败验收项，Builder 只修失败项，不重做整个任务 |
第七部分：完整模板文件包
7.1 目录结构
repo/
├─ AGENTS.md
├─ Makefile
├─ .editorconfig
├─ .gitignore
│
├─ docs/
│ ├─ ai/
│ │ ├─ AI-SDLC.md
│ │ ├─ AGENT_ROLES.md
│ │ ├─ DEFINITION_OF_READY.md
│ │ ├─ DEFINITION_OF_DONE.md
│ │ ├─ REVIEW_CHECKLIST.md
│ │ ├─ CHANGE_REQUEST_TEMPLATE.md
│ │ ├─ STORY_SPLITTING_GUIDE.md
│ │ ├─ QT_CPP_RULES.md
│ │ └─ PROMPTS/
│ │ ├─ planner.md
│ │ ├─ designer.md
│ │ ├─ implementer.md
│ │ ├─ reviewer.md
│ │ └─ verifier.md
│ │
│ └─ specs/
│ ├─ README.md
│ ├─ backlog/
│ ├─ active/
│ ├─ done/
│ └─ _templates/
│ ├─ epic.md
│ ├─ story.md
│ ├─ design.md
│ ├─ task.md
│ └─ acceptance-checklist.md
│
├─ ops/
│ ├─ agents.json
│ └─ workflow.json
│
├─ scripts/
│ ├─ ai/
│ │ ├─ new_story.sh
│ │ ├─ spawn_parallel.sh
│ │ ├─ verify_story.sh
│ │ ├─ review_story.sh
│ │ └─ close_story.sh
│ ├─ build.sh
│ ├─ test.sh
│ ├─ lint.sh
│ ├─ package.sh
│ └─ quality_gate.sh
│
├─ tests/
│ ├─ acceptance/
│ │ └─ README.md
│ └─ smoke/
│ └─ README.md
│
└─ CMakePresets.json
7.2 核心文件内容
7.2.1 AGENTS.md
# AGENTS.md
本仓库采用 **Spec-Driven + Multi-Agent + Quality Gates** 开发方式。
## 总原则
1. 不允许直接根据聊天记录实现需求，必须基于 `docs/specs/active/<story-id>/` 下的文档工作。
2. 实现前必须先阅读：
- `story.md`
- `design.md`
- `acceptance-checklist.md`
- `docs/ai/DEFINITION_OF_READY.md`
- `docs/ai/DEFINITION_OF_DONE.md`
3. 每个 Agent 只承担一个职责：
- Planner: 切分需求、补齐边界
- Designer: 输出设计与风险
- Implementer: 实现代码
- Reviewer: 审查代码、架构、一致性
- Verifier: 编译、测试、验收、回归
4. 不允许跨 story 顺手修复无关问题。
5. 所有修改必须最小化，禁止"顺便重构大段代码"，除非 story 明确授权。
6. 所有变更必须可编译、可测试、可回滚。
7. 对 Qt/C++ 项目，优先保持：
- UI / View
- Application / Controller
- Domain / Service
- Infrastructure
的边界清晰。
## 修改范围规则
Agent 必须在输出中明确：
- 改了哪些文件
- 为什么改
- 哪些地方故意没改
- 风险点是什么
## 实现规则
1. 先补测试，再改实现，或至少同步补测试。
2. 新增逻辑必须带：
- 失败路径
- 边界条件
- 错误提示
- 日志
3. UI 需求必须落到可验证行为，不允许只说"优化体验"。
## 禁止事项
- 禁止凭猜测实现未写入 spec 的行为
- 禁止偷偷改接口语义
- 禁止用注释代替实现
- 禁止为了通过编译删除必要逻辑
- 禁止修改无关 story 的代码风格
- 禁止提交未通过 quality gate 的代码
## 交付格式
每次 Agent 输出必须包含：
### Summary
一句话说明本轮完成内容。
### Files Changed
- file1
- file2
### Decisions
- 决策 1
- 决策 2
### Risks
- 风险 1
- 风险 2
### Validation
- build: pass/fail
- tests: pass/fail
- lint: pass/fail
- acceptance: pass/fail
7.2.2 AI-SDLC.md
# AI-SDLC
本项目采用面向 AI 协作的软件开发生命周期。
## Phase 0 - Intake
**目标：** 确认需求进入 backlog 的最小必要信息。
**输入：**
- 用户目标
- 使用场景
- 非目标
- 约束条件
- 平台约束
- 风险约束
**输出：**
- epic 草案
- story 候选列表
- 初始验收标准
## Phase 1 - Alignment
**目标：** 先对齐，再设计，再编码。
**必须产出：**
- story.md
- acceptance-checklist.md
- design.md（复杂 story 必须有）
**通过条件：**
- 边界明确
- 非目标明确
- 失败行为明确
- 验收标准明确
- 可拆成 1~4 个 task
## Phase 2 - Design
**目标：** 控制复杂度，防止 AI 乱改。
**必须说明：**
- 涉及模块
- 数据流
- UI 事件流
- 状态变化
- 错误处理
- 回滚方案
- 测试策略
## Phase 3 - Implement
**目标：** 小步提交，局部实现。
**要求：**
- 一个 task 一个 worktree
- 一个实现 agent 一次只做一个 task
- 先写变更计划，再改代码
- 改完立即跑局部验证
## Phase 4 - Verify
**目标：** 让"完成"可证明。
**必须通过：**
- build
- unit tests
- lint / static checks
- acceptance checklist
- smoke test
## Phase 5 - Review
**目标：** 检查 AI 常见失误。
**重点检查：**
- 是否误读需求
- 是否改了不该改的东西
- 是否破坏原有语义
- 是否存在 UI 状态遗漏
- 是否存在资源释放 / 生命周期问题
- 是否有线程/信号槽风险
- 是否引入 Qt 对象所有权问题
## Phase 6 - Release / Close
**目标：** 安全合入。
**要求：**
- 变更说明
- 风险说明
- 验证记录
- 回滚点
7.2.3 ops/agents.json
{
"version": 1,
"default_workflow": "spec_parallel_qt_cpp",
"agents": [
{
"id": "planner",
"role": "Planner Agent",
"prompt_file": "docs/ai/PROMPTS/planner.md",
"allowed_actions": ["read_specs", "read_code", "write_specs"],
"forbidden_actions": ["write_production_code", "merge_branch"]
},
{
"id": "designer",
"role": "Designer Agent",
"prompt_file": "docs/ai/PROMPTS/designer.md",
"allowed_actions": ["read_specs", "read_code", "write_design"],
"forbidden_actions": ["merge_branch"]
},
{
"id": "implementer",
"role": "Implementer Agent",
"prompt_file": "docs/ai/PROMPTS/implementer.md",
"allowed_actions": ["read_specs", "read_code", "write_code", "run_build", "run_tests"],
"forbidden_actions": ["change_scope", "merge_branch"]
},
{
"id": "reviewer",
"role": "Reviewer Agent",
"prompt_file": "docs/ai/PROMPTS/reviewer.md",
"allowed_actions": ["read_specs", "read_code", "run_build", "run_tests", "write_review"],
"forbidden_actions": ["implement_large_changes", "merge_branch"]
},
{
"id": "verifier",
"role": "Verifier Agent",
"prompt_file": "docs/ai/PROMPTS/verifier.md",
"allowed_actions": ["read_specs", "read_code", "run_build", "run_tests", "run_lint", "write_verification"],
"forbidden_actions": ["change_scope", "merge_branch"]
}
]
}
7.2.4 ops/workflow.json
{
"workflows": [
{
"id": "spec_parallel_qt_cpp",
"steps": [
"planner",
"designer",
"implementer_parallel",
"reviewer",
"verifier",
"human_acceptance"
],
"parallel_rules": {
"max_parallel_agents": 4,
"parallel_unit": "task",
"require_separate_worktree": true,
"require_separate_branch": true
},
"quality_gates": [
"build",
"tests",
"lint",
"acceptance_checklist",
"review_pass"
]
}
]
}
7.3 脚本文件
7.3.1 scripts/ai/new_story.sh
#!/usr/bin/env bash
set -euo pipefail
if [ $# -lt 2 ]; then
echo "Usage: $0 <story-id> <story-title>"
exit 1
fi
STORY_ID="$1"
shift
TITLE="$*"
DIR="docs/specs/active/${STORY_ID}"
mkdir -p "${DIR}/change-requests"
cp docs/specs/_templates/story.md "${DIR}/story.md"
cp docs/specs/_templates/design.md "${DIR}/design.md"
cp docs/specs/_templates/task.md "${DIR}/tasks.md"
cp docs/specs/_templates/acceptance-checklist.md "${DIR}/acceptance-checklist.md"
sed -i.bak "s/<story-id>/${STORY_ID}/g" "${DIR}/story.md" "${DIR}/design.md" "${DIR}/tasks.md" "${DIR}/acceptance-checklist.md"
sed -i.bak "s/<title>/${TITLE}/g" "${DIR}/story.md"
find "${DIR}" -name "*.bak" -delete
echo "[OK] created ${DIR}"
7.3.2 scripts/ai/spawn_parallel.sh
#!/usr/bin/env bash
set -euo pipefail
if [ $# -lt 2 ]; then
echo "Usage: $0 <story-id> <task-name-1> [task-name-2] [task-name-3] ..."
exit 1
fi
STORY_ID="$1"
shift
BASE_BRANCH="$(git branch --show-current)"
WORKTREE_ROOT="../${STORY_ID}-worktrees"
mkdir -p "${WORKTREE_ROOT}"
for TASK in "$@"; do
SAFE_TASK="$(echo "${TASK}" | tr ' ' '-' | tr '[:upper:]' '[:lower:]')"
BRANCH="${STORY_ID}/${SAFE_TASK}"
WT_DIR="${WORKTREE_ROOT}/${SAFE_TASK}"
git worktree add -b "${BRANCH}" "${WT_DIR}" "${BASE_BRANCH}"
cat > "${WT_DIR}/.agent-context.md" <<EOF
# Agent Context
Story: ${STORY_ID}
Task: ${TASK}
Read first:
- AGENTS.md
- docs/ai/DEFINITION_OF_DONE.md
- docs/specs/active/${STORY_ID}/story.md
- docs/specs/active/${STORY_ID}/design.md
- docs/specs/active/${STORY_ID}/acceptance-checklist.md
- docs/specs/active/${STORY_ID}/tasks.md
Rules:
- Only implement this task
- Keep changes minimal
- Run local validation before handoff
EOF
echo "[OK] ${TASK} -> ${WT_DIR} (${BRANCH})"
done
echo "[DONE] Spawned parallel worktrees under ${WORKTREE_ROOT}"
7.3.3 scripts/build.sh
#!/usr/bin/env bash
set -euo pipefail
cmake --preset dev
cmake --build --preset dev -j
7.3.4 scripts/test.sh
#!/usr/bin/env bash
set -euo pipefail
ctest --preset dev --output-on-failure
7.3.5 scripts/lint.sh
#!/usr/bin/env bash
set -euo pipefail
if command -v run-clang-tidy >/dev/null 2>&1; then
run-clang-tidy -p build/dev
else
echo "run-clang-tidy not found, skipping"
fi
7.3.6 scripts/quality_gate.sh
#!/usr/bin/env bash
set -euo pipefail
echo "== build =="
./scripts/build.sh
echo "== test =="
./scripts/test.sh
echo "== lint =="
./scripts/lint.sh
echo "[OK] quality gate passed"
7.4 配置文件
7.4.1 Makefile
.PHONY: build test lint package quality-gate
build:
bash ./scripts/build.sh
test:
bash ./scripts/test.sh
lint:
bash ./scripts/lint.sh
package:
bash ./scripts/package.sh
quality-gate:
bash ./scripts/quality_gate.sh
7.4.2 CMakePresets.json
{
"version": 6,
"cmakeMinimumRequired": {
"major": 3,
"minor": 24,
"patch": 0
},
"configurePresets": [
{
"name": "dev",
"generator": "Ninja",
"binaryDir": "${sourceDir}/build/dev",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug",
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
"BUILD_TESTING": "ON"
}
},
{
"name": "release",
"generator": "Ninja",
"binaryDir": "${sourceDir}/build/release",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Release",
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
"BUILD_TESTING": "ON"
}
}
],
"buildPresets": [
{
"name": "dev",
"configurePreset": "dev"
},
{
"name": "release",
"configurePreset": "release"
}
],
"testPresets": [
{
"name": "dev",
"configurePreset": "dev",
"output": {
"outputOnFailure": true
}
}
]
}
7.4.3 .editorconfig
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
[*.{cpp,h,hpp,c,cc,cxx}]
indent_style = space
indent_size = 4
[*.md]
trim_trailing_whitespace = false
7.4.4 .gitignore
/build/
/out/
/dist/
/artifacts/
/.cache/
*.user
*.autosave
*.DS_Store
compile_commands.json
第八部分：落地实践指南
8.1 最小可落地版本（MVP）
8.1.1 版本 V1：3 Agent 就够了
| Agent | 职责 |
|---|---|
| Agent A：Spec + Architect | 拆需求、产出任务卡、定边界 |
| Agent B：Builder | 写代码、写测试、自检 |
| Agent C：Reviewer + QA | 审查、验收、输出修复清单 |
8.1.2 V1 流程
大需求 → Spec/Architect 拆成 Task → Builder 先复述理解 → 你确认
→ Builder 实现 → Reviewer/QA 验收 → 不通过则按缺陷单修复
→ 通过后提交 → 进入下一任务
这个已经能比你现在的流程稳定很多。
8.2 日常操作流程
8.2.1 A. 新需求进入
- 建 Epic
- 用 Planner Agent 切 Story
- 选一个 Story 开始
- 生成 story 目录
bash scripts/ai/new_story.sh story-012 "导出对话记录到本地文件"
8.2.2 B. 先对齐再设计
先让 AI 只做两件事：
- 补
story.md - 补
acceptance-checklist.md
确认后，再让 Designer Agent 写 design.md。
8.2.3 C. 并行开发
如果这个 story 可拆 3 个 task：
bash scripts/ai/spawn_parallel.sh story-012 \
"ui-dialog" \
"export-service" \
"tests"
然后你分别在 3 个 worktree 开 Claude Code。
每个会话第一句话都固定：
请先阅读：
- AGENTS.md
- docs/specs/active/story-012/story.md
- docs/specs/active/story-012/design.md
- docs/specs/active/story-012/acceptance-checklist.md
- .agent-context.md
你只负责当前 task，先输出 implementation plan，再开始修改。
8.2.4 D. 合并前 Review + Verify
先 reviewer：
bash scripts/ai/review_story.sh story-012
再 verifier：
bash scripts/ai/verify_story.sh story-012
最后人工 smoke。
8.3 每个需求的 SOP
1. 创建任务卡
用 OpenSpec 生成任务卡，补齐目标、非目标、验收标准、约束
2. Builder 预确认
先输出理解、方案、文件变更范围，人工确认
3. 实现
Claude Code 编码，本地编译、测试、自检
4. 审查
Reviewer 审查需求覆盖与规范
5. 验收
QA 对照验收标准检查
6. 修复
使用缺陷单反馈，不使用模糊反馈
7. 提交
只在满足 DoD 后提交
8. 归档
记录本任务踩坑、补充规范、更新模板
8.4 额外建议：6 条硬规则
| 规则 | 说明 |
|---|---|
| 规则 1：一个 story 最多 4 个 task | 再多就说明 story 仍然太大 |
| 规则 2：一个 agent 一次只改一种层级 | 例如只改 UI，或只改 service |
| 规则 3：复杂 UI 一定写状态清单 | Qt 桌面项目最容易翻车的就是 UI 状态遗漏 |
| 规则 4：误解需求必须写 change request | 不要靠聊天纠偏 |
| 规则 5：没有 acceptance checklist，不准编码 | 这是你防止 AI 跑偏的关键 |
| 规则 6：reviewer agent 必须默认"挑刺" | 不能让 reviewer 变成夸夸团 |
8.5 最适合的 Agent 组合
推荐固定 5 个，不要更多：
- Planner
- Designer
- Implementer-A（UI）
- Implementer-B（Domain/Service）
- Reviewer/Verifier
一般别上 8 个、10 个 agent。单体 Qt/C++ 桌面项目里，过多 agent 的协调成本会比收益更大。
多 Agent 真正有收益的前提，是 spec 足够细、任务边界足够清楚。
8.6 最小执行标准
从明天开始，你只要强制自己做到这 5 条，效率就会明显提升：
- 不再直接把大需求扔给 AI
- 先切 story，再写 acceptance
- 并行单位改成 task + worktree
- 误解需求一律写 change request
- 所有 story 合并前必须过 quality gate
8.7 落地建议：三阶段推进
第一阶段：流程文档化
先把以下内容全部固化下来：
- 任务卡模板
- Agent 角色
- 验收模板
- 缺陷单模板
- DoR / DoD
- 开发规范
第二阶段：半自动执行
人工触发各 Agent，但按统一模板运行。
第三阶段：再自动编排
等流程稳定后，再把它做成：
- 自动任务分发
- 自动拉分支
- 自动跑审查
- 自动生成修复单
- 自动汇总报告
8.8 建议你马上做的 7 件事
- 建立
docs/ai/目录 - 写
coding-standards.md - 写
definition-of-ready-done.md - 把大需求拆成 Epic / Feature / Task
- 强制 Builder 先"复述理解"，再编码
- 改掉"你再改改"的反馈方式，改成"缺陷单"
- 先试运行 3 Agent 模式，再扩到多 Agent 并行
文档版本：v1.0
最后更新：2026 年 3 月
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
10
0- 0
已为社区贡献3条内容
所有评论(0)