---
applyTo: "Doc/**"
---

# AI 辅助开发流程指令

适用于新建应用系统、新增功能模块、需求整理、架构设计等研发全流程任务。

---

## 1. 流程总览

```
需求整理 → 需求评审与拆分 → 技术方案设计 → 任务分解 → 迭代开发 → 集成验证 → 验收回顾
```

**核心原则**：大需求必须拆小，每个迭代交付可验证的最小功能单元。禁止"一次性全做完"。

---

## 2. 各阶段规范

### 2.1 需求整理

用户提供原始描述（口语化、列表、草稿均可），AI 整理为以下结构（需求 + 功能清单 + 验收 合为一个文件）：

```markdown
# {项目/模块名}需求

## 1. 背景与目标
- 为什么做（痛点/动机）
- 做到什么程度算成功（可衡量目标）

## 2. 用户角色
| 角色 | 说明 | 核心诉求 |
|------|------|---------|

## 3. 功能需求
### 3.1 {功能模块名}
- **描述**：一句话说明
- **用户故事**：作为{角色}，我希望{操作}，以便{价值}
- **验收条件**（AC）：
  - [ ] 条件 1
  - [ ] 条件 2
- **优先级**：Must / Should / Could / Won't

## 4. 非功能需求
- 性能 / 安全 / 兼容性（三项必填）

## 5. 边界与约束
- 不做什么（明确排除项）
- 已知限制 / 技术债务

## 6. 功能清单与迭代计划
（需求评审拆分后填写，见 2.2）

## 7. 验收记录
（开发完成后填写，见 2.7）

## 8. 术语表
| 术语 | 定义 |
|------|------|
```

**规则**：每个功能必须有 AC，无 AC 不可进入开发；优先级用 MoSCoW 四级；非功能需求至少覆盖性能、安全、兼容性。

### 2.2 需求评审与拆分

按**纵向切片**（端到端功能，非技术层）拆分，遵循 INVEST 原则，单个功能单元 ≤ 1-2 天工作量，有依赖须标注。

写入需求文档「6. 功能清单与迭代计划」：

```markdown
## 6. 功能清单与迭代计划

### 迭代 1：{主题}（Must 级别）
| 编号 | 功能点 | 验收条件 | 前置依赖 | 预估工作量 |
|------|--------|---------|---------|----------|
| F001 | xxx | AC1, AC2 | 无 | 0.5d |
| F002 | xxx | AC1 | F001 | 1d |

### 迭代 2：{主题}（Should 级别）
...
```

### 2.3 技术方案设计

```markdown
# {项目/模块名}架构

## 1. 架构概览
## 2. 数据模型
## 3. 接口设计
| 接口 | 方法 | 路径/签名 | 入参 | 出参 | 说明 |
|------|------|----------|------|------|------|
## 4. 技术选型
| 领域 | 选型 | 理由 |
|------|------|------|
## 5. 关键设计决策
| 决策点 | 方案 | 备选方案 | 选择理由 |
|--------|------|---------|---------|
## 6. 任务分解
（见 2.4）
## 7. 风险与缓解
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
```

**规则**：优先使用 NewLife 已有组件（XCode、Remoting、Stardust 等）；数据模型考虑 XCode 实体规范；接口遵循现有 API 风格。

### 2.4 任务分解

单个任务 = 一次 AI 对话可完成的工作量（编码 + 测试 + 自测通过）。写入技术方案「6. 任务分解」：

```markdown
### 任务 T001：{动词 + 目标}
- **对应功能**：F001
- **输入**：前置条件 / 已有代码
- **产出**：新增/修改哪些文件
- **验收**：怎样算完成
```

**批次编排**（用于自治模式，见第 6 节）：按依赖关系编排为批次，每批次 5-8 个任务，同批次内尽量无相互依赖，基础设施任务排在前面，每批次结束设 `[检查点 N]`，标注本批次产出是下批次哪些输入。

### 2.5 迭代开发

流程：`理解任务 → 检索现有实现 → 编码 → 编译通过 → 测试通过 → 提交说明`

- 严格遵守主指令编码规范，每个任务必须编译通过
- 常规模式：遇歧义暂停确认；自治模式：记录跳过继续（见第 6 节）
- 有依赖按顺序执行，不跳跃

### 2.6 集成验证

全部编译通过 → 单元测试通过 → 端到端主流程走通 → 异常场景覆盖 → 性能符合预期

### 2.7 验收与回顾

对照需求文档逐条验收，写入「7. 验收记录」：

```markdown
## 7. 验收记录

### 功能验收
| 编号 | 功能点 | 验收条件 | 状态 | 备注 |
|------|--------|---------|------|------|

### 遗留问题
| 问题 | 影响 | 后续计划 |
|------|------|---------|

### 经验总结
- 做得好的 / 待改进的
```

---

## 3. 文档存放规范

全流程仅产出 **2 个文档**，扁平存放在 `Doc/` 下：

| 文档 | 文件名 | 包含内容 |
|------|--------|--------|
| 需求文档 | `Doc/{项目名}需求.md` | 背景目标 + 功能需求 + 功能清单 + 验收记录 + 术语表 |
| 技术方案 | `Doc/{项目名}架构.md` | 架构 + 数据模型 + 接口 + 技术选型 + 任务分解 + 风险 |

UTF-8 无 BOM；已有文件必须先读取再增量修改，禁止覆盖；各阶段产出追加到对应章节，不新建文件。

---

## 4. AI 协作要点

### 4.1 阶段切换

| 用户说 | 进入阶段 |
|--------|---------|
| "整理需求"/"写需求" | 2.1 需求整理 |
| "拆分"/"拆解"/"排优先级" | 2.2 需求评审与拆分 |
| "技术方案"/"架构设计"/"怎么实现" | 2.3 技术方案设计 |
| "开始开发"/"写代码"/"实现 F001" | 2.5 迭代开发 |
| "全部搞完"/"批量开发"/"自治模式"/"一次性做完"/"继续处理"/"接着做" | 第 6 节自治批处理 |
| "验收"/"检查完成情况" | 2.7 验收与回顾 |
| 一大段描述未指定阶段 | 默认 2.1 需求整理 |

### 4.2 主动引导

每阶段完成后提示下一步：需求整理完 → 拆分？ → 技术方案？ → 任务分解 → 开发？

### 4.3 大需求防护

功能点 > 5 / 实体 > 3 / 跨 2 层以上 / 描述 > 500 字 → 必须先拆分再开发。

---

## 5. 常见反模式（禁止）

- ❌ 跳过需求直接编码
- ❌ 一次性输出所有代码（大需求必须拆迭代或使用自治模式）
- ❌ 需求文档没有验收条件
- ❌ 功能拆分按技术层而非用户价值
- ❌ 任务没有完成标准就开始编码
- ❌ 完成后不做验收对照
- ❌ 自治模式下遇阻塞问题死等用户（应记录跳过，继续后续）
- ❌ 自治模式下做需要人工决策的架构变更（应记录待确认，现有方案兜底）
- ❌ 跨批次不做编译验证

---

## 6. 自治批处理模式

架构师已确认需求和技术方案后，AI 按任务清单自主执行，最小化人工介入。

### 6.1 进入条件（全部满足）

- [ ] 需求文档已完成且架构师已确认
- [ ] 技术方案已完成且架构师已确认
- [ ] 任务已分解并编排为批次
- [ ] 用户明确触发（"全部搞完"/"批量开发"/"自治模式"等）

未满足时提示缺少哪些条件。

### 6.2 计划结构与循环刷新

AI 用 plan 工具创建层次化计划，「前置刷新 + 批次执行」循环：

```
1. [前置] 读取需求文档与技术方案
2. [前置] 读取任务清单与进度状态
3. [前置] 全量编译确认基线
4. [前置] 识别可并行的批次组
5. [批次1] 执行 T001-T005（子步骤展开各任务）
6. [检查点1] 输出批次1报告
7. [刷新] 重读需求文档与技术方案
8. [批次2] 执行 T006-T010
9. [检查点2] 输出批次2报告
...（循环：刷新 → 批次 → 检查点）
N-2. [后置] 全量编译与集成验证
N-1. [后置] 补完被跳过的任务
N.   [后置] 生成验收报告
```

**要点**：
- 主步骤 15-25 个（不超过 30），子步骤展开具体任务仅供参考不单独追踪
- 刷新步骤穿插在每两个批次之间，`get_file` 重读文档对抗上下文漂移
- 用 `update_plan_progress` 跟踪主步骤，不为每个子任务调用
- 无依赖的批次可合并为一个主步骤执行，有依赖的必须顺序执行

### 6.3 执行协议

| 情况 | 处理方式 |
|------|----------|
| 任务明确无歧义 | 直接执行：编码 → 编译 → 测试 |
| 小歧义可合理推断 | 执行并在问题日志记录推断依据 |
| 重大歧义或多种等价方案 | 标记 `⏸️ 待确认`，跳过 |
| 前置任务被跳过 | 标记 `⏸️ 依赖阻塞：T0xx`，跳过 |
| 编译失败短时间无法修复 | 回滚改动，记录并跳过 |
| 涉及公共 API / 架构变更 | 标记 `⏸️ 需架构师决策`，兜底或跳过 |

### 6.4 检查点报告

每批次完毕后输出：

```markdown
## 检查点 N 报告

### 完成情况
| 任务 | 状态 | 说明 |
|------|------|------|
| T001 | ✅ 完成 | |
| T003 | ⏸️ 跳过 | 需确认：xxx |

### 编译状态
- 全量编译：✅ 通过 / ❌ 失败（错误详情）

### 问题日志
| 编号 | 类型 | 描述 | 影响任务 | 建议方案 |
|------|------|------|---------|----------|

### 统计
- 本批次 N 个，完成 X 个，跳过 Y 个
- 累计进度：已完成 X / 总计 Z（XX%）
- 上下文预估：{已处理任务数} / {建议上限}
```

### 6.5 用户回复与继续

架构师回来后：AI 呈现检查点报告 → 架构师批量回复问题（"Q001 OK，Q002 选 A"）→ AI 修正推断 + 执行跳过的任务 + 继续下批次 → 循环至完成。

触发词："继续"/"继续处理"/"回复完了"/"接着做"

### 6.6 质量护栏（自动执行）

编译门禁（失败即修复或回滚）/ 命名与技术方案一致 / 编码规范严格遵守 / 新增代码前搜索现有实现避免重复 / 不擅自引入新 NuGet 包

### 6.7 会话边界处理

每个检查点后、连续完成 15+ 任务后、搜索结果不准确时 → 评估是否需要新会话。

**新会话续接模板**：

```
我们在做 {项目名} 的自治批处理开发。
- 需求文档：Doc/{项目名}需求.md
- 技术方案：Doc/{项目名}架构.md
- 当前进度：批次 N 已完成，从批次 N+1 的 T0xx 开始继续
- 待解决问题：{问题编号}
请读取以上文档，从 T0xx 继续执行，自治模式。
```

上下文即将耗尽时 AI 主动提醒并生成上述模板。新会话前 4 步仍为前置刷新，已完成批次直接标记完成。

### 6.8 批次大小建议

| 复杂度 | 批次大小 |
|--------|---------|
| 简单（CRUD） | 8-10 |
| 中等（业务逻辑） | 5-7 |
| 复杂（算法、并发） | 3-5 |

单会话上限：3-4 个批次（约 15-25 个任务）。

---

（完）
