--- 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 个任务）。 --- （完）