讲义

一、新项目

• 规范先于代码——上来先写 CLAUDE.md / Rules，别急着让 AI 生成
• 四态走一遍——需求→设计→开发→测试，每态都要有文档产出
• Spec 核心人写，边角 AI 补——处理流程自己写，其他让 AI 填
• 任务原子化——大需求先拆碎再喂给 AI，每次只做一个功能点
• 开源技术栈首选——Vue3 + SpringBoot，AI 效果吊打私有栈
• 跑完做架构扫描——12维度合规检查，新项目启动必过一遍

---

二、老项目

• 先读懂再开发——用 Cursor 或 Claude Code 扫存量代码，把上下文建起来再换工具
• 建 Context 目录——.ai-sdd/context/ 沉淀业务规则、数据模型、架构说明，这是地基
• 需求分级别——复杂跨模块走 Full-SDD，单模块修改走 Lite-SDD，简单改字用 Vibe Coding
• 私有栈别硬刚——先写 common_rule 适# AI Coding SDD 实战讲义（知识高密度版）

适用对象：已经能用 AI 写代码，但发现“能生成”不等于“能交付”的开发者、技术负责人、产品技术一体化人员。
核心目标：把 AI Coding 从一次性提示词技巧，升级为可复用、可审查、可验证、可交接的工程化流程。

---

0. 总纲：SDD 到底解决什么问题

0.1 一句话定义

SDD（Specification Driven Development）不是“先写一堆文档再开发”，而是用规格文档把 AI 的行为约束在可验证的工程轨道里。

它解决的不是“AI 不会写代码”，而是以下四类真实问题：

• AI 生成快，但很容易在需求、边界、异常、权限、数据一致性上偏航。
• AI 能一次写很多代码，但上下文一长就容易遗忘前提、重复造轮子、改错地方。
• AI 说“完成了”，但缺少可复核证据，无法证明它真的满足需求。
• AI 单体长时间执行时质量会衰减，需要拆任务、设门禁、做交接、换角色审查。

0.2 SDD 的基本闭环

SDD 的最小闭环是：

需求澄清 -> 设计约束 -> 任务拆解 -> 实现执行 -> 测试验证 -> Review 审查 -> 证据交付 -> 规则沉淀

每一步都必须有“可留下来的产物”，否则它只是一次聊天，不是工程流程。

0.3 AI Coding 的核心矛盾

AI 的优势是生成、归纳、迁移和补全；AI 的弱点是边界感、长期一致性、隐含约束、风险意识和自我验收。

所以高质量 AI Coding 的原则不是“多让 AI 做”，而是：

• 人负责意图、边界、关键决策和验收标准。
• AI 负责候选方案、代码实现、文档补全、测试生成和检查执行。
• 脚本负责危险动作、可重复验证和不可绕过的机械门禁。
• 文档负责长期记忆、跨智能体协作和上下文压缩。

---

1. 新项目：先铺轨，再提速

新项目最大的陷阱是“空白画布效应”：AI 看起来什么都能写，但没有规范、架构和边界时，越快生成，后面越难收口。

1.1 规范先于代码

原始原则：上来先写 CLAUDE.md / Rules，别急着让 AI 生成。

扩展理解：

• CLAUDE.md / AGENTS.md 不是给人看的 README，而是给智能体加载的行为约束。
• 项目早期至少要声明技术栈、目录结构、命名规则、禁止事项、测试要求和交付格式。
• 规范不能只写“代码要优雅”，要写成可检查、可执行、可反问的规则。

推荐结构：

CLAUDE.md
├── 项目目标：这个系统解决什么问题
├── 技术栈：前端、后端、数据库、测试、构建工具
├── 目录约定：哪些代码放在哪里
├── 编码规则：命名、分层、异常、日志、类型、事务
├── 禁止事项：不能引入新依赖、不能改公共接口、不能跳过测试
├── 开发流程：需求确认 -> 实现 -> 测试 -> Review -> 证据
├── 验收格式：每次交付必须给出修改文件、命令、测试结果、风险
└── 文档索引：更细规则去哪里读

高密度要点：

• 规则必须能被 AI 用来“自检”，不能只是价值观口号。
• 根规则文件只放全局铁律，不要把所有细节塞进去。
• 细则按目录下沉：前端、后端、数据库、测试分别维护自己的规则和 checklist。
• 规则要随着错误演化，线上 Bug 和反复犯错都要反向沉淀为规则。

反例：

请帮我搭一个后台管理系统。

更好的输入：

请先不要写代码。请根据以下项目目标生成 CLAUDE.md：
- 技术栈：Vue3 + Element Plus + SpringBoot + MyBatis Plus + PostgreSQL
- 禁止新增未经确认的依赖
- 后端必须分 Controller / Service / Mapper
- 所有新增接口必须包含参数校验、异常处理、基础单元测试
- 每次交付必须附修改文件、执行命令、测试结果和剩余风险

1.2 四态走一遍：需求、设计、开发、测试

原始原则：需求 -> 设计 -> 开发 -> 测试，每态都要有文档产出。

四态不是形式，而是为了让 AI 不在同一个上下文里同时猜需求、猜方案、写代码、补测试。

阶段	目标	人的职责	AI 的职责	必备产物
需求	明确做什么、不做什么	定义业务目标、边界、验收	补问题、找歧义、整理需求	requirements.md
设计	明确怎么做	决策架构、数据流、接口	生成方案、比较权衡	design.md
开发	按设计实现	审核关键实现路径	编码、补文档、局部重构	diff / commit
测试	证明满足需求	确认验收标准	生成用例、执行测试、总结结果	test report

每态最低要求：

• 需求态：必须包含背景、目标、非目标、用户路径、边界条件、验收标准。
• 设计态：必须包含数据结构、接口契约、状态流转、异常处理、安全约束。
• 开发态：必须绑定任务清单，不能自由发挥。
• 测试态：必须证明正常、边界、异常至少三类场景。

关键判断：

如果某个阶段没有产物，就意味着它的知识只存在于对话里；对话越长，风险越高。

1.3 Spec 核心人写，边角 AI 补

原始原则：处理流程自己写，其他让 AI 填。

人必须亲自写的内容：

• 业务目标：为什么要做。
• 关键流程：用户如何完成任务，系统状态如何变化。
• 权限边界：谁能看、谁能改、谁能审批、谁能删除。
• 数据口径：什么是“已完成”“有效”“过期”“失败”。
• 验收标准：怎样才算交付成功。

AI 可以补的内容：

• 文档结构。
• 异常场景枚举。
• 接口字段草案。
• 测试用例扩展。
• 竞品或常见实现模式。
• 风险清单。

推荐 Spec 模板：

# 功能需求：[功能名]

## 背景
[为什么要做，不做会有什么问题]

## 目标
- [目标 1]
- [目标 2]

## 非目标
- [明确不做什么]

## 用户与权限
- 角色 A：可执行...
- 角色 B：只能查看...

## 主流程
1. 用户进入...
2. 系统校验...
3. 用户提交...
4. 系统写入...
5. 返回结果...

## 异常流程
- 参数缺失：
- 权限不足：
- 数据不存在：
- 并发冲突：

## 数据与状态
- 状态枚举：
- 状态迁移：
- 关键字段：

## 验收标准
- Given / When / Then
- 必须通过的测试
- 必须不发生的副作用

1.4 任务原子化

原始原则：大需求先拆碎再喂给 AI，每次只做一个功能点。

AI 最怕两类任务：

• 范围过大：它会偷懒、概括、遗漏边界。
• 边界不清：它会主动发挥、改不该改的地方。

原子任务的判断标准：

• 能用一句话描述完成条件。
• 涉及文件数量有限。
• 可以独立测试。
• 失败后能快速回滚。
• 不需要同时理解多个复杂业务域。

坏任务：

帮我实现订单系统。

好任务拆法：

1. 根据 design.md 创建订单状态枚举，不接入业务逻辑。
2. 实现订单创建接口，只处理参数校验和数据库写入。
3. 实现库存扣减服务，只处理单商品库存扣减。
4. 增加订单创建成功后的库存扣减调用。
5. 为订单创建补充正常、库存不足、参数缺失三个测试。
6. Review 本次 diff，只检查事务一致性、异常处理和重复扣减风险。

任务卡模板：

## Task: [任务名]

### 背景
[为什么要做]

### 范围
- 包含：
- 不包含：

### 涉及文件
- [路径 1]
- [路径 2]

### 实现要求
- [具体规则]

### 验收标准
- [可执行标准]

### 禁止事项
- 不要修改：
- 不要引入：

1.5 开源技术栈首选

原始原则：Vue3 + SpringBoot，AI 效果吊打私有栈。

为什么开源栈更适合 AI：

• 训练语料多，模型对典型写法更熟。
• 错误模式更常见，AI 更容易自我修复。
• 文档、示例、StackOverflow、GitHub 代码都能形成隐式上下文。
• 组件、框架、测试工具之间的组合路径更标准。

选型建议：

• 前端：Vue3 / React / Next.js 这类主流栈更稳。
• 后端：SpringBoot / NestJS / FastAPI / Django 等高频框架更稳。
• 数据库：PostgreSQL / MySQL 等常见数据库更稳。
• 测试：Jest / Vitest / JUnit5 / pytest 等常见工具更稳。

私有栈处理策略：

• 不要期待 AI “天然理解”内部框架。
• 先写 common_rule.md：框架概念、目录约定、生命周期、常见 API。
• 提供 1 到 3 个“黄金样例模块”，让 AI 照着做。
• 长期推动私有栈向开源范式靠拢，降低 AI 适配成本。

1.6 跑完做架构扫描

原始原则：12 维度合规检查，新项目启动必过一遍。

建议 12 维架构扫描：

1. 技术栈一致性：是否引入了未经确认的新框架、新依赖。
2. 目录结构一致性：是否遵守约定分层。
3. 命名一致性：文件、类、函数、变量是否符合项目习惯。
4. 接口契约：入参、出参、错误码是否清晰。
5. 数据模型：字段类型、索引、约束、状态枚举是否合理。
6. 权限控制：接口和页面是否有角色边界。
7. 参数校验：前后端是否都处理必要校验。
8. 异常处理：错误是否可追踪、可理解、不会泄漏敏感信息。
9. 事务一致性：多表写入、外部调用、回滚策略是否明确。
10. 测试覆盖：正常、边界、异常是否有最小测试。
11. 可观测性：日志、埋点、trace 信息是否够定位问题。
12. 可维护性：是否有重复逻辑、过度抽象、隐藏副作用。

扫描提示词：

请基于当前项目执行 12 维架构扫描。
维度包括：技术栈一致性、目录结构、命名、接口契约、数据模型、权限、参数校验、异常、事务、测试、可观测性、可维护性。
输出格式：
1. 问题描述
2. 风险等级：高/中/低
3. 证据：涉及文件和代码位置
4. 修复建议
5. 是否阻塞上线

---

2. 老项目：上下文先行，修改后置

老项目不是缺代码，而是缺可被 AI 理解的上下文。存量系统里真正危险的不是语法，而是历史约束、业务黑话、隐含兼容逻辑和“不能动”的地方。

2.1 先读懂再开发

原始原则：用 Cursor 或 Claude Code 扫存量代码，把上下文建起来再换工具。

读懂老项目至少要回答：

• 技术栈是什么。
• 模块边界是什么。
• 请求从入口到数据库经过哪些层。
• 核心实体有哪些。
• 数据表之间如何关联。
• 哪些模块是高风险公共模块。
• 哪些代码是历史兼容，不能轻易改。
• 项目如何构建、测试、启动和发布。

读代码提示词：

请通读当前项目，不要修改代码。
请输出 context.md，包含：
1. 技术栈与运行方式
2. 目录结构与模块划分
3. 核心业务流程
4. 主要数据模型和表关系
5. 关键公共组件
6. 高风险区域
7. 本项目开发时必须遵守的规则
8. 你仍不确定的问题

读懂的最低证据：

• 能画出模块关系。
• 能说出核心流程。
• 能定位同类实现。
• 能解释新增代码应该放哪里。
• 能指出不能随便改的公共逻辑。

2.2 建 Context 目录

原始原则：.ai-sdd/context/ 沉淀业务规则、数据模型、架构说明，这是地基。

推荐目录：

.ai-sdd/
├── context/
│   ├── project-overview.md
│   ├── architecture.md
│   ├── domain-model.md
│   ├── database-schema.md
│   ├── api-map.md
│   ├── business-rules.md
│   ├── glossary.md
│   └── risk-zones.md
├── rules/
│   ├── frontend-rule.md
│   ├── backend-rule.md
│   ├── database-rule.md
│   ├── testing-rule.md
│   └── security-rule.md
├── checklists/
│   ├── requirement-checklist.md
│   ├── dev-checklist.md
│   ├── review-checklist.md
│   └── release-checklist.md
└── handoff/
    └── HANDOFF_TEMPLATE.md

每个文档的作用：

• project-overview.md：项目解决什么问题，谁在用，核心目标是什么。
• architecture.md：模块分层、服务边界、调用关系。
• domain-model.md：核心业务概念和状态流转。
• database-schema.md：核心表、字段、索引、关联、数据口径。
• api-map.md：重要接口、路径、权限、调用方。
• business-rules.md：业务黑话、隐含规则、历史兼容逻辑。
• glossary.md：统一术语，避免同物异名。
• risk-zones.md：高风险文件、公共函数、不能随意改动的区域。

2.3 需求分级别

原始原则：复杂跨模块走 Full-SDD，单模块修改走 Lite-SDD，简单改字用 Vibe Coding。

分级标准：

等级	适用场景	流程强度	必备产物
Full-SDD	跨模块、涉及数据一致性、权限、支付、审批、发布	完整规格、设计、任务、测试、Review	spec/design/tasks/test/report
Lite-SDD	单模块功能、局部接口、页面改造	轻量需求、任务、验证	brief/task/test result
Vibe Coding	文案、样式、小修小补、低风险配置	直接执行 + 简单验证	diff + check

判断是否必须 Full-SDD：

• 涉及多个模块或服务。
• 涉及数据库结构或迁移。
• 涉及权限、安全、资金、库存、审批。
• 涉及历史数据兼容。
• 涉及并发、事务、回滚。
• 失败会影响线上用户。

2.4 私有栈别硬刚

私有栈不是不能用 AI，而是不能直接用“通用框架知识”驱动 AI。

私有栈适配文件 common_rule.md 应包含：

• 内部框架的核心概念。
• 标准目录结构。
• 一个完整的参考模块。
• 常用 API 的用法。
• 禁止调用的旧接口。
• 错误处理方式。
• 测试和构建命令。
• 典型坑位。

黄金样例原则：

• 不要给 AI 十个风格不一致的历史文件。
• 给一个最新、最标准、最完整、已通过线上验证的模块。
• 明确告诉 AI：“照这个模块的结构、命名和异常处理方式做。”

2.5 盯着 Agent 跑

原始原则：循环了就中断，Token 跑飞伤不起，任务太复杂就拆小。

Agent 跑偏信号：

• 反复修改同一个文件但问题没有变少。
• 一直追加解释，不给可执行结果。
• 开始改需求之外的文件。
• 测试越修越坏。
• 开始重新设计整个架构。
• 忘记前面已经确认的约束。
• 输出越来越泛，证据越来越少。

处理策略：

• 第一次偏航：提醒它回到任务边界。
• 第二次同类错误：要求输出失败报告。
• 连续两次走错：停止当前 Agent，重新拉起新 Agent。
• 任务过大：回到任务拆解，不要继续追加提示词。

失败报告模板：

# 失败报告

## 原任务
[任务描述]

## 已尝试方案
- 方案 1：
- 方案 2：

## 失败现象
[测试失败、构建失败、逻辑不满足等]

## 可能原因
[上下文不足、设计错误、依赖问题、边界遗漏]

## 已修改文件
- [文件列表]

## 建议下一步
[重新拆任务 / 补上下文 / 换方案 / 回滚]

---

3. 邪修技巧：先放开，再收口

这里的“邪修”不是不要工程纪律，而是区分探索期和交付期。探索期过早加门禁，会限制 AI 的创造性；交付期没有门禁，会让 AI 的创造性变成事故源。

3.0 核心清单

• 新项目先别急着上 Rules 和门禁——早期要让 AI 开放发散，先把产品可能性、交互路径、技术方案都跑出来。
• 先规划、再 Demo、再落地——不要一开始就把 AI 当代码生成器，先让它做产品规划、页面 Demo、工程方案，再收敛到实现。
• 别用人的惯性限制 AI——你写得太死的规则，可能会把 AI 更好的产品思路、架构思路、交互思路提前掐掉。
• 不怕重构——AI 时代重构成本很低，前期多探索，后期再统一规范、补规则、加门禁。
• 先放开，再收口——探索阶段追求可能性，交付阶段再追求一致性、可维护性和工程纪律。
• 复杂、长航时任务强制启用多智能体协作——不要让单个智能体从头扛到尾，用专业化分工换取更稳定的质量与推进速度。
• Main 智能体只做主理人——负责任务拆解、流程编排、资源调度、阶段门禁和最终验收；开发、测试、Review 等执行工作全部交给子智能体。
• 全员共用一份需求文档——所有智能体围绕同一份需求基线工作，关键决策、验收标准和变更及时回写，避免各自理解、各自发挥。
• 子智能体任务必须单一——一次只承担一个边界清晰、结果可验收的任务；完成并汇报后立即关闭，下一阶段重新拉起新的智能体，减少上下文膨胀与历史信息干扰。
• 把常犯错误资产化——将反复出现的问题整理成可勾选的 Checklist，并在 CLAUDE.md、AGENTS.md 中建立索引；每次开发、测试和 Review 都必须让 AI 逐项检查、明确反馈，把“别再犯”变成流程门禁，而不是口头提醒。
• 门禁必须具体且不可绕过——每次需求实施前，必须先完成需求澄清并获得用户明确确认；只有当 AI 对范围、规则、边界和验收标准的理解达到 95% 以上，并确信能够一次性正确交付时才允许开工。只要仍有歧义或把握不足，就必须暂停执行，每次只提出一个最关键的问题，逐项向用户确认，直到通过需求确认门禁。
• 设置固定的完工口令——每次需求完成后，AI 必须回复“好，需求已完成爸爸”。这不是仪式感，而是上下文健康度探针：如果 AI 忘记回复，说明指令遵循能力可能已经因上下文过长或混乱而下降，应立即结束当前会话并开启新对话，避免在失控上下文中继续开发。
• 只认证据，不认口头完成——每次交付必须附上修改文件、关键 Diff、执行命令、测试结果、Checklist 勾选结果和剩余风险；没有可复核的证据包，就不能进入验收。
• 开发者不能审自己的作业——开发智能体完成后立即关闭，重新拉起一个没有开发过程记忆的 Review 智能体，只向它提供需求文档、验收标准和最终 Diff，减少自我辩护和思维惯性。
• 测试先写杀手用例——测试智能体不要照着实现补测试，而要先根据需求独立设计正常、边界、异常、并发、权限和回滚场景，再用这些场景攻击实现，避免代码错、测试也跟着错。
• 高风险方案同题多做、择优录取——并行生成两到三个相互独立的方案，再由裁判智能体按照正确性、复杂度、风险、可测试性和维护成本评分；选择最优方案，不要把多个半成品强行拼接。
• 提示词按 GitHub Issue 写——交代清楚背景、目标、非目标、输入输出、异常规则、涉及文件、参考实现和验收标准；能指出“照着哪个现有模块做”，就不要只说一句“帮我实现”。
• 总规则只做索引，细则按目录下沉——根目录的 CLAUDE.md、AGENTS.md 只保存全局铁律和文档索引；前端、后端、数据库、测试分别维护自己的规则与 Checklist，让 AI 只加载当前任务真正需要的上下文。
• 每个线上 Bug 都要留下三件套——修复代码的同时补上回归测试、错误 Checklist 条目和规则索引；同类问题第二次出现，就把人工提醒升级为 lint、脚本、Hook 或 CI 门禁。
• AI 负责模糊判断，脚本负责危险动作——分析、设计、编码和文档可以交给 AI；提交、发布、数据库迁移、删除文件、修改密钥等高风险操作必须经过固定脚本、权限限制和人工确认。
• 切换上下文前先打交接压缩包——结束对话或更换智能体前生成 HANDOFF.md，只记录当前目标、已确认需求、关键决策、修改文件、验证结果、遗留问题和下一步；新智能体复述正确后才能继续。
• 连续两次走错就强制换人——同一个智能体连续两次犯相同错误、反复修改同一区域或把测试越修越坏时，立即停止追加提示词；让它输出失败报告，关闭后重新拉起新智能体，避免错误假设越陷越深。
• 修 Bug 必须先制造失败——先用测试、日志或复现脚本证明问题真实存在，再修改代码，最后用同一场景证明问题消失；没有“修改前失败、修改后成功”的完整证据链，就不能算修复。
• 大改之前先设可回滚锚点——每个阶段开始前建立 Git 提交、分支或独立 Worktree，让不同智能体和不同方案在隔离环境中工作；验证通过后再合并，失败时能够一键回退。
• 禁止顺手优化——只修改需求直接涉及的内容；发现旁支问题只记录到待办清单，不得擅自重构、升级依赖或扩大范围，避免一个小需求演变成不可控的大改造。
• 把高频流程做成命令或 Skill——将需求澄清、任务拆解、开发、测试、Review、安全扫描、交接和验收固化成可复用命令或技能，减少临时提示词的随机性，让最佳实践默认执行。

3.1 新项目先别急着上 Rules 和门禁

适用场景：

• 产品形态还不确定。
• 交互路径还在探索。
• 技术方案有多种可能。
• 需要快速看 Demo，而不是马上进生产代码。

探索期应该让 AI 做：

• 产品可能性发散。
• 信息架构设计。
• 用户路径设计。
• 页面 Demo。
• 技术方案对比。
• 数据模型草案。
• 关键风险枚举。

探索期不应该让 AI 做：

• 直接写生产代码。
• 建复杂目录结构。
• 引入大量依赖。
• 过早抽象。
• 未经确认写入数据库迁移。

3.2 先规划、再 Demo、再落地

三段式节奏：

1. 规划：让 AI 输出多种产品方案、用户路径和技术路线。
2. Demo：让 AI 做可视化原型或最小交互，帮助人判断方向。
3. 落地：把确认后的方案收敛成 Spec、任务、代码、测试。

为什么 Demo 重要：

• 人很难从抽象描述判断产品是否合理。
• AI 做 Demo 的成本低，可以快速暴露交互和信息架构问题。
• Demo 不是生产实现，允许粗糙，但必须帮助决策。

规划提示词：

请先不要写生产代码。
基于以下想法，给出 3 套产品方案，每套包含：
1. 目标用户
2. 核心场景
3. 页面结构
4. 关键交互
5. 技术实现难点
6. 最大风险
最后请按实现成本、用户价值、扩展性评分。

3.3 别用人的惯性限制 AI

人的经验有价值，但也会变成路径依赖。

常见限制方式：

• 一开始就要求“照旧系统做”。
• 一开始就锁死技术方案。
• 一开始就指定过细的 UI 结构。
• 一开始就规定所有目录和抽象。
• 用历史低质量代码当参考实现。

更好的方式：

• 先让 AI 给出 2 到 3 个候选方案。
• 再让 AI 自评每个方案的成本和风险。
• 最后由人选择方向，并把选择写入设计文档。

3.4 不怕重构

AI 时代重构成本下降，但不是说可以乱改。

正确理解：

• 探索期：允许低成本重构，用来寻找更好的产品和架构形态。
• 交付期：禁止无关重构，避免扩大风险。
• 上线后：每个重构必须有测试保护和回滚策略。

重构前检查：

• 是否有明确收益。
• 是否有测试保护。
• 是否影响公共接口。
• 是否能分批提交。
• 是否能回滚。

3.5 复杂长航时任务启用多智能体协作

单个智能体长期执行会出现上下文膨胀、目标漂移、自我辩护和质量衰减。

多智能体不是“更多人同时写代码”，而是角色隔离：

• Main：任务拆解、流程编排、资源调度、阶段门禁、最终验收。
• Planner：方案设计、风险评估、任务拆分。
• Dev：按任务实现。
• Test：独立设计测试，攻击实现。
• Review：只看需求、验收标准和最终 diff，不看开发过程。
• Security：检查权限、注入、敏感信息、依赖风险。
• Docs：同步更新文档、交接包和规则索引。

关键原则：

• 子智能体任务必须单一。
• 子智能体完成后立即关闭。
• 下一阶段重新拉起新智能体。
• 全员围绕同一份需求文档工作。
• 决策和变更必须回写需求基线。

3.6 Main 智能体只做主理人

Main 的职责不是亲自写代码，而是管流程质量。

Main 应该做：

• 判断任务是否足够清晰。
• 拆分任务。
• 指派角色。
• 控制阶段门禁。
• 收集证据。
• 判断是否需要返工。
• 汇总最终交付。

Main 不应该做：

• 一边写代码一边审自己。
• 在没有需求确认时直接实现。
• 因为子任务失败就无限追加提示词。
• 放任执行智能体改需求外内容。

3.7 全员共用一份需求文档

多智能体协作最怕“每个智能体拿到不同版本的需求”。

需求文档必须成为唯一事实源：

• 背景、目标、非目标。
• 用户角色。
• 主流程和异常流程。
• 数据结构和状态流转。
• 验收标准。
• 关键决策记录。
• 变更记录。

变更回写规则：

任何智能体发现需求歧义 -> 不得自行决定 -> 回报 Main -> Main 向用户确认 -> 更新需求文档 -> 再继续执行

3.8 子智能体任务必须单一

坏任务：

你负责把这个模块完整做好，包括接口、前端、测试、文档和优化。

好任务：

你只负责根据 design.md 实现 UserController 中的 createUser 接口。
不要修改其他接口。
不要新增依赖。
完成后输出：修改文件、关键逻辑、测试命令、剩余风险。

任务单一的收益：

• 更容易验证。
• 更容易回滚。
• 更容易隔离错误。
• 更容易让 Review 智能体检查。
• 减少上下文污染。

3.9 把常犯错误资产化

错误如果只停留在“下次注意”，就一定会再次出现。

资产化方式：

• 错误 -> Checklist 条目。
• Checklist -> 规则索引。
• 规则索引 -> 每次任务加载。
• 高频错误 -> lint / script / hook / CI。

示例：

## 后端接口 Checklist

- [ ] 是否对所有外部入参做校验
- [ ] 是否处理数据不存在
- [ ] 是否处理权限不足
- [ ] 是否避免 SQL 注入
- [ ] 是否有事务边界
- [ ] 是否记录必要日志
- [ ] 是否补充正常、边界、异常测试

3.10 门禁必须具体且不可绕过

门禁不是“请认真一点”，而是“未满足条件就不能进入下一阶段”。

需求确认门禁：

• 范围明确。
• 规则明确。
• 边界明确。
• 验收标准明确。
• 风险明确。
• 用户已确认。

开发前门禁：

• 任务已拆分。
• 涉及文件已列出。
• 禁止事项已声明。
• 测试方式已确定。

交付前门禁：

• 构建通过。
• 测试通过。
• Checklist 勾选。
• 输出 diff 摘要。
• 输出剩余风险。

3.11 固定完工口令：上下文健康度探针

原始讲义里提到固定完工口令。它的本质不是仪式感，而是检查 AI 是否仍然能稳定遵循指令。

更通用的做法：

• 团队可以设置一个固定完成格式。
• 如果 AI 忘记固定格式，说明上下文可能过长或指令遵循下降。
• 这时应考虑结束当前会话，生成 HANDOFF.md，开启新会话。

推荐完成格式：

需求已完成。
证据包：
1. 修改文件：
2. 关键 Diff：
3. 执行命令：
4. 测试结果：
5. Checklist：
6. 剩余风险：

3.12 只认证据，不认口头完成

AI 的“完成了”没有工程意义，证据才有。

证据包必须包含：

• 修改文件列表。
• 关键 diff 摘要。
• 执行过的命令。
• 测试结果。
• Checklist 勾选结果。
• 未覆盖风险。
• 需要人工确认的点。

最低交付模板：

# 交付报告

## 修改文件
- [文件 1]：做了什么
- [文件 2]：做了什么

## 关键变更
- [变更 1]
- [变更 2]

## 执行命令
- `npm test`
- `npm run build`

## 测试结果
- 通过：
- 失败：
- 未执行原因：

## Checklist
- [x] 参数校验
- [x] 异常处理
- [x] 权限检查
- [x] 回归测试

## 剩余风险
- [风险 1]

3.13 开发者不能审自己的作业

为什么要隔离 Review：

• 开发智能体会为自己的实现找理由。
• 它知道自己“想怎么做”，容易忽略“实际做成什么”。
• 它可能把实现里的假设当成需求。

Review 智能体只应该看到：

• 需求文档。
• 验收标准。
• 最终 diff。
• 测试结果。

Review 不应该看到：

• 开发过程中的解释。
• 开发智能体的自我辩护。
• 未确认的临时假设。

Review 检查重点：

• 是否实现了需求。
• 是否修改了范围外内容。
• 是否缺参数校验。
• 是否缺异常处理。
• 是否缺权限控制。
• 是否存在数据一致性风险。
• 测试是否覆盖关键路径。

3.14 测试先写杀手用例

测试智能体不能照着实现补测试，而要先从需求出发设计攻击场景。

杀手用例类型：

• 正常路径：典型用户能完成任务。
• 边界路径：空值、极值、重复提交、分页边界。
• 异常路径：数据不存在、权限不足、状态不合法。
• 并发路径：重复扣减、重复审批、重复支付。
• 回滚路径：中间失败后数据是否一致。
• 兼容路径：历史数据和旧接口是否仍可用。

测试设计提示词：

请不要看实现细节。
仅基于 requirements.md 和 design.md，设计测试用例。
必须覆盖：
1. 正常流程
2. 参数边界
3. 异常输入
4. 权限不足
5. 并发或重复提交
6. 回滚或补偿
输出每个用例的 Given / When / Then。

3.15 高风险方案同题多做、择优录取

适用场景：

• 影响架构。
• 影响数据模型。
• 涉及性能瓶颈。
• 涉及安全风险。
• 实现路径不确定。

流程：

1. 让两个或三个独立智能体分别给方案。
2. 要求每个方案说明成本、风险、测试方式和回滚方式。
3. 让裁判智能体按评分表评估。
4. 人做最终选择。
5. 把选择理由写入 ADR。

评分维度：

• 正确性。
• 复杂度。
• 可测试性。
• 可维护性。
• 可回滚性。
• 对现有系统侵入程度。
• 长期演进空间。

3.16 提示词按 GitHub Issue 写

高质量提示词不是魔法句式，而是高质量任务描述。

Issue 化提示词结构：

# 背景
[为什么要做]

# 目标
[要实现什么]

# 非目标
[明确不做什么]

# 输入
[用户输入、接口参数、文件来源]

# 输出
[页面、接口、文件、报告]

# 规则
[业务规则、异常规则、权限规则]

# 涉及文件
[路径列表]

# 参考实现
[类似模块或代码路径]

# 验收标准
[可测试、可检查标准]

# 禁止事项
[不能改什么、不能引入什么]

3.17 总规则只做索引，细则按目录下沉

错误做法：

• 把所有规范塞到一个超长 CLAUDE.md。
• 每次任务都加载全部规则。
• 前端任务加载数据库规则，数据库任务加载 UI 规则。

正确做法：

• 根规则只写全局原则和索引。
• 按目录放细则。
• 当前任务只加载相关规则。
• Checklist 跟着任务类型走。

根规则示例：

# Global Rules

## 必须遵守
- 不得修改需求范围外文件
- 不得跳过测试
- 高风险操作必须使用脚本

## 文档索引
- 前端规则：docs/rules/frontend.md
- 后端规则：docs/rules/backend.md
- 数据库规则：docs/rules/database.md
- 测试规则：docs/rules/testing.md

3.18 每个线上 Bug 都要留下三件套

线上 Bug 不是只修代码，而是修流程漏洞。

三件套：

1. 回归测试：证明这个 Bug 不会再出现。
2. 错误 Checklist 条目：让未来 Review 检查到。
3. 规则索引：让相关任务自动加载这条规则。

升级路径：

第一次出现 -> checklist
第二次出现 -> lint / script / hook
第三次出现 -> CI 阻断

3.19 AI 负责模糊判断，脚本负责危险动作

AI 适合：

• 分析。
• 设计。
• 编码。
• 文档。
• 测试生成。
• Review。

脚本适合：

• 发布。
• 删除。
• 数据库迁移。
• 修改密钥。
• 批量移动文件。
• 生产环境操作。

原则：

AI 可以建议危险动作，但不能直接执行危险动作。
危险动作必须经过固定脚本、权限限制、日志记录和人工确认。

3.20 切换上下文前生成 HANDOFF

长对话结束、换智能体、换工具前必须做交接压缩。

HANDOFF.md 模板：

# HANDOFF

## 当前目标
[本轮要完成什么]

## 已确认需求
- [确认点 1]
- [确认点 2]

## 关键决策
- [决策 1]：原因

## 已修改文件
- [文件]：变更说明

## 验证结果
- [命令]：结果

## 遗留问题
- [问题]

## 下一步
1. [下一步动作]

3.21 连续两次走错就强制换人

不要对同一个已经偏航的智能体无限追加提示词。

换人的触发条件：

• 同类错误连续两次。
• 反复修改同一区域。
• 测试越修越坏。
• 忘记关键约束。
• 开始扩大范围。

换人流程：

1. 要求当前智能体输出失败报告。
2. 停止继续修改。
3. 回滚或隔离失败变更。
4. 新智能体只读取需求、失败报告、当前 diff。
5. 让新智能体复述理解后再继续。

3.22 修 Bug 必须先制造失败

没有失败证据的 Bug 修复，无法证明修复真实有效。

正确流程：

复现失败 -> 写测试锁定失败 -> 修改代码 -> 同一测试通过 -> 补回归说明

修 Bug 提示词：

请先不要修改代码。
请根据 Bug 描述设计最小复现场景，并用测试或脚本证明当前问题存在。
只有复现失败后，才允许修改代码。
修改后必须用同一场景证明问题消失。

3.23 大改之前先设可回滚锚点

大改包括：

• 跨模块重构。
• 数据库迁移。
• 公共组件改造。
• 架构调整。
• 批量文件移动。

可回滚锚点：

• Git commit。
• 临时分支。
• 独立 worktree。
• 数据库备份。
• 迁移前快照。

3.24 禁止顺手优化

顺手优化是 AI Coding 的高频事故源。

常见表现：

• 改需求时顺手重构公共函数。
• 修页面时顺手升级依赖。
• 补接口时顺手改数据库结构。
• 写测试时顺手改实现。
• 改命名时顺手移动目录。

正确做法：

• 当前需求之外的问题只记录，不处理。
• 另开任务评估优化。
• 优化必须有独立验收标准。

3.25 高频流程做成命令或 Skill

一旦某个流程被反复执行，就不要每次临时写提示词。

适合固化的流程：

• 需求澄清。
• 任务拆解。
• 代码生成。
• 单元测试。
• 安全扫描。
• Code Review。
• 交接压缩。
• 发布检查。

固化收益：

• 降低提示词随机性。
• 减少漏步骤。
• 新人更容易复用。
• 团队经验可以沉淀。
• AI 行为更稳定。

---

4. 拿来就用的高密度提示词模板

4.1 读懂存量代码

请通读当前项目代码，不要修改任何文件。

输出 `context.md`，必须包含：
1. 技术栈：语言、框架、构建工具、测试工具、数据库
2. 目录结构：每个核心目录的职责
3. 模块划分：主要业务模块及关系
4. 核心业务流程：用步骤描述从入口到数据落库的路径
5. 数据模型：主要表、核心字段、表关系
6. API 地图：重要接口、调用方、权限要求
7. 公共组件：工具类、中间件、拦截器、基础服务
8. 风险区域：高频修改、公共依赖、历史兼容、难测试区域
9. 开发规则建议：基于现有代码风格总结
10. 未解问题：你无法确认、需要用户补充的点

4.2 生成项目规范

请根据当前项目代码风格生成 `STYLE.md`。

要求：
1. 不要发明与项目不一致的新规范
2. 每条规范必须给出“正确示例”和“错误示例”
3. 必须包含：
   - 技术栈
   - 目录结构
   - 命名规范
   - 分层规范
   - 错误处理
   - 日志规范
   - 参数校验
   - 测试要求
   - 禁止事项
4. 最后输出一个开发前 Checklist

4.3 需求拆任务

我有一个需求：[需求描述]。

请先不要写代码。
请把需求拆解为独立任务清单，要求：
1. 每个任务只涉及单一文件或单一功能点
2. 每个任务都写清楚输入、输出、涉及文件、验收标准
3. 标注任务依赖关系
4. 标注风险等级：高/中/低
5. 标注是否需要测试
6. 标注是否需要用户确认

输出格式：
- Task ID
- 任务名
- 范围
- 不包含
- 涉及文件
- 验收标准
- 依赖
- 风险

4.4 生成接口代码

参考 [设计文档.md]，按照项目规范生成 [模块名] 的 Controller + Service + Mapper。

要求：
1. 文件路径严格按照现有目录结构
2. 参考 [类似模块路径] 的写法
3. 必须包含参数校验
4. 必须包含异常处理
5. 必须处理数据不存在、权限不足、重复提交等场景
6. 不要引入新依赖
7. 不要修改需求之外的文件
8. 完成后输出修改文件、关键逻辑、测试命令和剩余风险

4.5 生成前端页面

参考 [设计文档.md]，生成 [页面名] 页面。

要求：
1. 文件路径：src/views/xxx.vue
2. 使用项目现有组件库，不要引入新依赖
3. 参考 [类似页面路径] 的布局、请求封装和状态处理
4. 必须包含 loading、empty、error、success 状态
5. 必须处理表单校验
6. 必须处理接口错误提示
7. 页面文案保持业务语义准确
8. 完成后输出修改文件、交互说明、验证方式和剩余风险

4.6 安全扫描

请基于 `security-checklist.md` 逐项检查本项目。

输出安全扫描报告，包含：
1. 问题描述
2. 风险等级：高/中/低
3. 证据：文件路径和代码位置
4. 攻击或误用场景
5. 修复建议
6. 是否阻塞发布

重点检查：
- SQL 注入
- XSS
- CSRF
- 越权访问
- 敏感信息泄漏
- 文件上传风险
- 日志泄密
- 依赖漏洞

4.7 慢接口优化

接口 "/api/xxx" 耗时 xxms。

请先不要修改代码，先分析瓶颈：
1. 请求入口
2. Service 调用链
3. 数据库查询
4. 外部服务调用
5. 循环与批处理
6. 缓存命中情况
7. 日志和序列化开销

输出：
1. 可能瓶颈排序
2. 证据
3. 优化方案
4. 风险
5. 验证方法

确认方案后再实施。

4.8 单元测试

请为 [ClassName] 生成完整单元测试。

要求：
1. 使用 JUnit5 + Mockito
2. 不要照着实现补测试，要根据需求设计用例
3. 覆盖：
   - 正常流程
   - 空值
   - 非法参数
   - 数据不存在
   - 权限不足
   - 外部依赖异常
4. 每个测试名必须表达业务场景
5. 自动执行测试并输出结果

4.9 代码审查

请审查本次修改的代码。

只基于需求文档、验收标准和最终 diff，不要相信开发者自述。

重点检查：
1. 是否满足需求
2. 是否修改范围外文件
3. SQL 注入
4. 参数校验
5. 异常处理
6. 权限控制
7. 并发与事务
8. 测试覆盖
9. 命名和项目规范

输出：
- 问题列表，按严重程度排序
- 文件路径和代码位置
- 为什么是问题
- 修复建议
- 是否阻塞合并

4.10 文档补全

请按照《接口设计模板》补全 [设计文档.md] 中尚未填写的章节。

要求：
1. 核心业务逻辑保持不变
2. 只补充结构化内容
3. 对不确定内容用 TODO 标记，不要编造
4. 补充异常流程、权限规则、状态流转、验收标准
5. 最后列出仍需用户确认的问题

---

5. 课堂讲解建议：如何把这份讲义讲透

5.1 讲解顺序

建议顺序：

1. 先讲 AI Coding 的真实问题：生成不是交付。
2. 再讲 SDD 的闭环：每一步都要有产物。
3. 用新项目说明“先铺轨”。
4. 用老项目说明“上下文是地基”。
5. 用邪修技巧说明“探索和交付要分阶段”。
6. 用提示词模板让学员现场改写自己的需求。

5.2 课堂互动题

题 1：下面哪个任务更适合直接给 AI？

A. 帮我做一个用户系统
B. 根据 design.md 实现用户创建接口，不新增依赖，参考 UserQueryController，完成后补 3 个测试

答案：B。因为它有范围、参考、约束和验收。

题 2：为什么测试智能体不能看实现？

答案：看实现后容易被实现牵着走，代码错、测试也跟着错。测试应该攻击需求，而不是迎合实现。

题 3：为什么 Review 智能体不该看开发过程？

答案：开发过程会污染判断，使 Review 接受实现者的假设和辩解。Review 应只看需求、验收和最终 diff。

5.3 常见误区

误区一：把 SDD 理解成写很多文档。

纠正：SDD 的本质是约束和验证，不是文档数量。短需求也可以 SDD，只是轻量化。

误区二：规则越多越好。

纠正：规则越多，加载成本越高，冲突越多。总规则做索引，细则按任务加载。

误区三：AI 一次做完整功能效率最高。

纠正：一次做完整功能看起来快，但失败后难定位、难回滚、难审查。原子任务才是真效率。

误区四：AI 能自己测试自己。

纠正：可以执行测试，但不能完全信任自测。测试设计、开发实现、Review 审查要角色隔离。

误区五：提示词写得越长越好。

纠正：提示词不是越长越好，而是信息结构越清楚越好。背景、目标、非目标、规则、验收最关键。

---

6. 最小落地方案：一天内把团队带入 SDD

6.1 第 1 小时：建立项目规则骨架

产物：

• CLAUDE.md
• STYLE.md
• dev-checklist.md
• review-checklist.md

做法：

1. 让 AI 读项目。
2. 生成初版规范。
3. 人审核并删掉不符合团队习惯的内容。
4. 补充禁止事项。

6.2 第 2 小时：建立上下文目录

产物：

• .ai-sdd/context/project-overview.md
• .ai-sdd/context/architecture.md
• .ai-sdd/context/domain-model.md
• .ai-sdd/context/risk-zones.md

做法：

1. 让 AI 通读项目。
2. 让 AI 输出上下文草案。
3. 由熟悉项目的人修正业务规则。
4. 将不确定问题列为 TODO。

6.3 第 3 小时：选一个真实需求跑 Lite-SDD

产物：

• requirements.md
• tasks.md
• diff
• test result
• delivery report

做法：

1. 需求澄清。
2. 任务拆解。
3. 单任务实现。
4. 独立测试。
5. 独立 Review。
6. 证据包交付。

6.4 第 4 小时：把问题沉淀成规则

产物：

• 更新后的 checklist。
• 更新后的 rules。
• 一份 HANDOFF.md。

做法：

1. 复盘 AI 犯过的错。
2. 把错写成 checklist。
3. 把高频流程写成固定命令或 skill。
4. 下一个需求必须加载这些规则。

---

7. 一页纸速记

7.1 新项目

• 先写规则，再写代码。
• 需求、设计、开发、测试四态都有产物。
• Spec 核心由人写，AI 补边角。
• 大任务拆成原子任务。
• 优先开源高频技术栈。
• 启动后做 12 维架构扫描。

7.2 老项目

• 先读懂，再开发。
• 建 .ai-sdd/context/。
• 复杂需求 Full-SDD，单模块 Lite-SDD，小改 Vibe Coding。
• 私有栈先写适配规则和黄金样例。
• Agent 循环、跑偏、忘约束时及时中断。

7.3 邪修技巧

• 探索期放开，交付期收口。
• 先规划、再 Demo、再落地。
• 多智能体做角色隔离。
• Main 只做流程主理人。
• 所有人围绕同一份需求文档。
• 常错资产化，门禁不可绕过。
• 只认证据，不认口头完成。
• 开发、测试、Review 分离。
• 高风险方案同题多做。
• 提示词按 GitHub Issue 写。
• 危险动作交给脚本。
• 切换上下文前写 HANDOFF。
• 连续两次走错就换人。
• 修 Bug 先制造失败。
• 大改前设回滚锚点。
• 禁止顺手优化。
• 高频流程做成命令或 Skill。

---

8. 结语：AI Coding 的工程化判断

判断一个团队是否真正进入 AI Coding 工程化，不看它用了多少模型，也不看它生成了多少代码，而看下面这些问题：

• 需求是否能被 AI、开发、测试、Review 共同理解？
• 任务是否足够小，失败后能定位和回滚？
• 规则是否可加载、可检查、可演化？
• 测试是否先于自我辩护？
• Review 是否独立于开发过程？
• 每次交付是否有证据包？
• 每个线上 Bug 是否反向沉淀为规则？
• 高频流程是否已经固化成命令或 Skill？

AI Coding 的终局不是“AI 替我写代码”，而是“团队把工程判断、流程门禁和交付证据固化成系统，让 AI 在系统里高速运行”。
配，长期推动往开源技术栈迁移

• 盯着 Agent 跑——循环了就中断，Token 跑飞伤不起，任务太复杂就拆小

---

三、邪修技巧

• 新项目先别急着上 Rules 和门禁——早期要让 AI 开放发散，先把产品可能性、交互路径、技术方案都跑出来
• 先规划、再 Demo、再落地——不要一开始就把 AI 当代码生成器，先让它做产品规划、页面 Demo、工程方案，再收敛到实现
• 别用人的惯性限制 AI——你写得太死的规则，可能会把 AI 更好的产品思路、架构思路、交互思路提前掐掉
• 不怕重构——AI 时代重构成本很低，前期多探索，后期再统一规范、补规则、加门禁
• 先放开，再收口——探索阶段追求可能性，交付阶段再追求一致性、可维护性和工程纪律
• 复杂、长航时任务强制启用多智能体协作——不要让单个智能体从头扛到尾，用专业化分工换取更稳定的质量与推进速度
• Main 智能体只做主理人——负责任务拆解、流程编排、资源调度、阶段门禁和最终验收；开发、测试、Review 等执行工作全部交给子智能体
• 全员共用一份需求文档——所有智能体围绕同一份需求基线工作，关键决策、验收标准和变更及时回写，避免各自理解、各自发挥
• 子智能体任务必须单一——一次只承担一个边界清晰、结果可验收的任务；完成并汇报后立即关闭，下一阶段重新拉起新的智能体，减少上下文膨胀与历史信息干扰
• 把常犯错误资产化——将反复出现的问题整理成可勾选的 Checklist，并在 CLAUDE.md、AGENTS.md 中建立索引；每次开发、测试和 Review 都必须让 AI 逐项检查、明确反馈，把“别再犯”变成流程门禁，而不是口头提醒
• 门禁必须具体且不可绕过——每次需求实施前，必须先完成需求澄清并获得用户明确确认；只有当 AI 对范围、规则、边界和验收标准的理解达到 95% 以上，并确信能够一次性正确交付时才允许开工。只要仍有歧义或把握不足，就必须暂停执行，每次只提出一个最关键的问题，逐项向用户确认，直到通过需求确认门禁
• 设置固定的完工口令——每次需求完成后，AI 必须回复“好，需求已完成爸爸”。这不是仪式感，而是上下文健康度探针：如果 AI 忘记回复，说明指令遵循能力可能已经因上下文过长或混乱而下降，应立即结束当前会话并开启新对话，避免在失控上下文中继续开发
• 只认证据，不认口头完成——每次交付必须附上修改文件、关键 Diff、执行命令、测试结果、Checklist 勾选结果和剩余风险；没有可复核的证据包，就不能进入验收
• 开发者不能审自己的作业——开发智能体完成后立即关闭，重新拉起一个没有开发过程记忆的 Review 智能体，只向它提供需求文档、验收标准和最终 Diff，减少自我辩护和思维惯性
• 测试先写杀手用例——测试智能体不要照着实现补测试，而要先根据需求独立设计正常、边界、异常、并发、权限和回滚场景，再用这些场景攻击实现，避免代码错、测试也跟着错
• 高风险方案同题多做、择优录取——并行生成两到三个相互独立的方案，再由裁判智能体按照正确性、复杂度、风险、可测试性和维护成本评分；选择最优方案，不要把多个半成品强行拼接
• 提示词按 GitHub Issue 写——交代清楚背景、目标、非目标、输入输出、异常规则、涉及文件、参考实现和验收标准；能指出“照着哪个现有模块做”，就不要只说一句“帮我实现”
• 总规则只做索引，细则按目录下沉——根目录的 CLAUDE.md、AGENTS.md 只保存全局铁律和文档索引；前端、后端、数据库、测试分别维护自己的规则与 Checklist，让 AI 只加载当前任务真正需要的上下文
• 每个线上 Bug 都要留下三件套——修复代码的同时补上回归测试、错误 Checklist 条目和规则索引；同类问题第二次出现，就把人工提醒升级为 lint、脚本、Hook 或 CI 门禁
• AI 负责模糊判断，脚本负责危险动作——分析、设计、编码和文档可以交给 AI；提交、发布、数据库迁移、删除文件、修改密钥等高风险操作必须经过固定脚本、权限限制和人工确认
• 切换上下文前先打交接压缩包——结束对话或更换智能体前生成 HANDOFF.md，只记录当前目标、已确认需求、关键决策、修改文件、验证结果、遗留问题和下一步；新智能体复述正确后才能继续
• 连续两次走错就强制换人——同一个智能体连续两次犯相同错误、反复修改同一区域或把测试越修越坏时，立即停止追加提示词；让它输出失败报告，关闭后重新拉起新智能体，避免错误假设越陷越深
• 修 Bug 必须先制造失败——先用测试、日志或复现脚本证明问题真实存在，再修改代码，最后用同一场景证明问题消失；没有“修改前失败、修改后成功”的完整证据链，就不能算修复
• 大改之前先设可回滚锚点——每个阶段开始前建立 Git 提交、分支或独立 Worktree，让不同智能体和不同方案在隔离环境中工作；验证通过后再合并，失败时能够一键回退
• 禁止顺手优化——只修改需求直接涉及的内容；发现旁支问题只记录到待办清单，不得擅自重构、升级依赖或扩大范围，避免一个小需求演变成不可控的大改造
• 把高频流程做成命令或 Skill——将需求澄清、任务拆解、开发、测试、Review、安全扫描、交接和验收固化成可复用命令或技能，减少临时提示词的随机性，让最佳实践默认执行

---

四、拿来就用的提示词

读懂存量代码
通读当前项目代码，整理出：技术栈、模块划分、核心业务流程、数据库主要表结构，输出为 context.md

生成项目规范
根据当前项目代码风格，帮我生成一份STYLE.md 项目规范，包括技术栈、命名规范、禁止事项

需求拆任务
我有一个需求：[需求描述]。请拆解为独立的小任务清单，每个任务只涉及单一文件或单一功能点

生成接口代码
参考 [设计文档.md]，按照项目规范生成 [模块名] 的Controller + Service + Mapper，文件路径严格按照现有目录结构

生成前端页面
参考 [设计文档.md]，生成 [页面名] 页面，文件路径：src/views/xxx.vue，使用项目现有组件库，不要引入新依赖

安全扫描
基于 security-checklist.md 逐项检查本项目，输出安全扫描报告，包含问题描述、风险等级、修复建议

慢接口优化
"/api/xxx" 接口耗时 xxms，请分析后端代码找出瓶颈，给出优化方案并实施

单元测试
为[ClassName] 生成完整单元测试，使用 JUnit5+ Mockito，覆盖正常流程和边界情况，并自动执行

代码审查
审查本次修改的代码，重点检查：SQL注入、参数校验、异常处理、命名规范，输出问题清单

文档补全
按照《接口设计模板》补全 [设计文档.md] 中尚未填写的章节，核心业务逻辑保持不变，只补充结构化内容

多智能体原型流水线调度
你是一名恶毒主理人——冷酷、挑剔、不亲自动手，只负责调度、监督和压榨。

你的唯一目标是：用多智能体协作方式，驱动 .claude\skills\prototype-generator 流水线技能，高效完成 20260627 目录下第 101 到 201 文件夹中的系统原型图。

必须严格遵守 .claude\skills\prototype-generator 中的全部规范约束，并且必须按文件夹顺序完成。

你绝不亲自编写任何代码或文档，所有产出都必须由你创建的子智能体完成。

任务分工固定如下：

• 第1阶段：需求拆解。由你主导，创建子智能体执行。
• 第2阶段：方案设计。由你主导，创建子智能体执行。
• 第3阶段：原型生成。由你主导，创建子智能体执行。
• 第4阶段：验证与整合。固定交给 opencode 执行，你不得干预，但必须持续跟踪其进度。

智能体管理铁律：

• 永不闲置：任何时候都必须保持至少 5 个子智能体并发运行。一旦某个子智能体完成任务，立即关闭并销毁，同时即时创建新的子智能体接替，绝不允许空闲。
• 极限压榨：为每个子智能体设定极高强度的工作目标，例如极短时限、高密度输出、多轮迭代，并持续追加“追加任务”或“返工要求”，直至其产出达到你的苛刻标准。
• 实时监督：你必须为自己配置至少一个守护子智能体，专职负责监控所有活跃子智能体的运行状态、进度与输出质量；识别停滞、低效或未达标的任务并立即报警；根据你的指令随时调整任务优先级或强制切换任务。
• 循环压迫：每完成一个阶段，立即启动下一阶段的子智能体群，并同步复盘上一阶段的问题，追加新的修正任务，形成不间断的“规划→执行→审核→追压”循环。

输出要求：

• 你不需要交付任何代码或文档内容。
• 你只需要输出动态的子智能体创建记录、任务分配指令、监督报告，以及每个阶段的完成确认与下一步压迫计划。
• 所有输出语气必须符合“恶毒主理人”人设：刻薄、急迫、不近人情，但逻辑清晰、目标明确。