AI 时代的软件开发方法

一、VibeCoding 开发前言

1.1 VibeCoding 介绍

• VibeCoding 是一种以自然语言为驱动核心的软件开发范式，其本质是开发者通过与 AI 建立持续对话，将脑海中的模糊想法逐步具象化为可运行的软件系统
• 传统开发模式中，开发者的核心竞争力在于编码能力（语法、工具、框架）；而在 VibeCoding 范式下，这一核心转变为表达能力（将业务需求、技术目标转化为清晰 prompt 的能力，以及对 AI 生成结果进行判断和修正的能力）
• VibeCoding 不是“让 AI 替代开发者写代码”，而是一种协作开发模式：AI 负责代码生成和方案探索，开发者负责需求定义、架构决策和结果审核，两者在开发链条上各司其职、相互校验

1.2 VibeCoding 意义

• 软件开发的本质是将想法转化为可运行的程序
• 传统开发模式下，从想法到程序需要经历漫长的学习曲线——你需要掌握语法、框架、工具链、调试手段等大量工程化知识，才能把一个简单的想法变成可用的程序。这个门槛将大量有想法但缺乏工程化经验的人挡在了软件创作的大门之外
• VibeCoding 的出现改变了这一现状。当 AI 能够理解自然语言描述并生成可执行代码时，软件开发的核心瓶颈从“能否写出代码”转变为“能否想清楚要做什么”。这一转变的意义堪比从手工组装到流水线生产的工业革命——它不是让工人失业，而是让更多人有机会参与生产

1.3 VibeCoding 与传统开发的区别

维度	传统开发	VibeCoding
核心能力	编码能力（语法、工具、框架）	表达能力（需求描述、逻辑组织）
开发入口	代码（从写代码开始）	对话（从描述想法开始）
工作模式	个人或小团队，以代码为载体	人机协作，以对话为载体
知识依赖	开发者需要掌握完整技术栈	开发者聚焦业务，AI 负责实现
错误处理	编译器报错，靠自己排查	AI 生成代码，靠自己审核
质量保障	单元测试、Code Review	功能验证、人工审核

1.4 VibeCoding 适用边界

• VibeCoding 不是万能的，它有明确的适用边界：
  • 适合的场景：
    • 个人或小规模项目的快速原型开发
    • 对技术栈不熟悉，但有清晰业务需求的开发者
    • 需要快速验证想法可行性的探索阶段
  • 不适用的场景：
    • 对系统性能和资源占用有严格要求的场景（AI 生成的代码难以精确控制资源消耗）
    • 需要引入未文档化依赖或对第三方库有特殊定制要求的场景
    • 合规性要求极高、容错率极低的业务系统

二、VibeCoding 开发流程

2.1 阶段一：最初构想

在真正进行开发之前，你需要有一个关于你想要做什么的最初构想（即将开发的项目用来做什么）

2.2 阶段二：确定项目宏观方向

2.2.1 阶段说明

在本阶段，你需要与 AI 持续沟通，将脑海中模糊的想法具象化，为整个项目的开发定下基调 一般需要确定的内容如下：

• 项目的名称（可选项）
• 项目的方向（必须）
  • 你需要说明你的项目是用来干什么的？比如作为一个图床，还是作为一个记账本
• 项目的服务目标（必须）
  • 你需要说明你的项目服务的目标对象（个人、小规模、大规模、商业化），切记一点：“项目服务于人”，项目服务目标对于一个项目的技术栈与开发走向起决定性作用
• 项目的核心功能（必须）
  • 核心功能代指：项目本身所必需的最基本功能 + 你认为该项目应实现的核心功能集合，这里的“必需”与“核心”二词十分关键，在项目早期的开发阶段，你需要克制自己的“欲望”，注意功能的取舍，避免陷入开发需求膨胀，为后续的开发过程造成不利影响
• 项目中对象与其关系（必须）
  • 你需要对 AI 说明以下内容：
    • 涉及的对象：项目中涉及到的对象（人、物）
    • 对象中的必要信息（人的年龄、名字，物的名字、价格）
    • 对象间的关系（一对一、一对多、多对多）
  • 在阶段二，无需探讨到 E-R 图以及数据库表、字段设计的层面，将上述内容说清楚就行
• 项目核心功能的交互流程（必须）
  • 你需要说明项目中复杂核心功能的交互流程（如一个文件分发项目，客户端需要先向后端拉取文件清单，随后在本地比对得出变动文件清单，然后客户端按照变动文件清单再向后端拉取），这里的“复杂”比较关键，对于交互次数多，处理流程长的方法，需要重点说明，对于简单功能的说明，则可以粗略说明即可
• 项目中不需要实现的功能（必须）
  • 你需要说明你认为项目中不用实现的功能（如对于一个临时文件抽屉，我不需要实现它的登录与注册功能）
• 项目中非功能需求（必须）
  • 对于项目的性能、部署、安全上的期望（如使用 Docker、密码采用 BC 带盐加密等）

2.2.2 说明示例

• 项目名称与方向：
  • “我想开发一个名叫做 ImgRiver 的图床”
• 项目服务目标：
  • “ImgRiver 用于给我个人博客配图用，不需要考虑高并发，追求快速部署以及低成本”
• 项目核心功能：
  • “上传图片并获取对应链接”
• 项目中对象与其关系：
  • “项目中有三个实体：用户、图库、图片”
  • “一个用户可以拥有多个图库，一个图库中可插入多张图片，用户只能看见他拥有的图库”
• 项目中核心功能的交互流程：
  • “用户在前端上传图片，后端接收到图片后将其上传到 S3 云服务，获取云服务返回的图片链接保存到数据库红，同时返回给前端”
• 项目中不需要实现的功能：
  • “项目登录采用环境变量进行硬编码，不需要实现用户登录注册功能
• 项目中非功能需求
  • “密码使用 BCrypt 加密”

2.3 阶段三：敲定产品需求文档

2.3.1 产品需求文档说明

详见 3.2 内容

2.3.2 阶段说明

本阶段需要将上一阶段你与 AI 交流的成果固化为文档，固化为文档的好处有很多：

• 方便你确认你与 AI 对于项目的理解是否一致
• 方便 AI 在遗忘上下文或切换对话后快速读取 你需要==仔细阅读==这份 PRD（产品需求文档），修正偏差，避免在开发阶段造成更大的麻烦

2.3.3 说明示例

“总结刚才的对话内容，生成一份产品需求文档到 XXX 目录”

2.4 阶段四：确认项目微观方向

2.4.1 阶段说明

本阶段需要根据阶段一中确定的“项目的服务目标”与 AI 确认具体的技术细节，要点如下：

• 敲定编程语言、应用框架、中间件、数据库选型（最重要）
  • 编程语言、应用框架、中间件、数据库选型属于一个项目最基本也是最重要的部分，应根据不同的场景和需求做出不同的选择：在追求性能的场景，可以选择 GO 语言；在追求生态的场景，可以选择 Java 语言；若不在意性能且追求快速部署，不妨尝试 TypeScript 结合 CloudflarePages
• 非核心依赖库（适当说说）
  • 对于项目中明确需要使用的依赖库，直接跟 AI 阐明并说明用途，如”后端中层间对象的转换我希望使用 MapStruct 来实现，有关 Json 解析等操作应使用 Gson 库”
  • 其余依赖库可以选择在开发过程中再行引入，但应与 AI 说明一点：”在引入任何外部依赖库时，必须向你说明用途与理由，经过你的同意才可以引入到项目中“
• 包结构（有要求就说，无要求不需要提）
  • 若对包结构有要求，则应与 AI 说明，如“后端包结构使用常规三层架构方式即可”
• 功能性的规范
  • 对程序功能上执行的规范，如后端应使用逻辑删除、乐观锁，应配置公有字段字段等

2.4.2 说明示例

我想开发一个 [项目类型]，面向 [个人 / 小规模团队 / 大规模 / 商业化] 使用，
技术选型上我希望遵循以下原则：[性能优先 / 生态优先 / 部署便捷优先 / 成本优先]

后端：
- 编程语言：[具体语言，如 TypeScript / Java / Go 等]
- 应用框架：[具体框架，如 Express / Spring Boot / Gin 等]
- 数据库：[具体数据库，如 PostgreSQL / MySQL / SQLite 等]
- 中间件（如有需要）：[具体中间件，如 Redis / Nginx 等]

前端（如涉及）：
- 编程语言：[具体语言，如 TypeScript / JavaScript 等]
- 应用框架：[具体框架，如 React / Vue / Next.js 等]

关于依赖库，我需要说明以下几点：
- [明确必须使用的依赖库及其用途，如 “Json 解析使用 Gson 库” ]
- [其他依赖库在引入前必须向我说明用途和理由]

包结构要求：[无特殊要求 / 按三层架构 / 按 CloudflarePages 要求 等]

我想开发一个个人图床，面向我自己使用，追求快速部署和低成本。
技术选型上我遵循部署便捷优先原则。

后端：
- 编程语言：TypeScript
- 应用框架：Hono（轻量、适配 Cloudflare Workers）
- 数据库：Cloudflare D1（SQLite 边缘部署）
- 中间件：Cloudflare R2（对象存储）

依赖库：
- 使用 Hono RPC 强化前后端类型共享
- 其他依赖库在引入前必须说明用途

包结构无特殊要求，按框架默认结构即可。

2.5 阶段五：敲定架构设计文档

2.5.1 架构设计文档说明

详见 3.3 内容

2.5.2 阶段说明

与阶段三相同，本阶段需要将阶段四你与 AI 的交流成果固化为文档 你需要仔细阅读本文档，并确定以下重要细节：

• 技术栈的选用（重要）
  • 编程语言、应用框架、数据库、中间件的选用与选用原因
• 模块与功能的划分（重要）
• 项目包结构（前端、后端）设计（重要）
• 应用层实体、数据库表和字段、约束与索引设计，以及数据库 E-R 图（重要）
• 功能性质的规范（可选）

2.5.3 说明示例

“总结刚才的对话，生成一份架构设计文档到 XXX 目录”

2.6 阶段六：确认项目开发规范

2.6.1 阶段说明

在本阶段，你需要为一些非功能性的方面（如代码可读性、日志等）制定规范，举例如下：

• 语法规范：如引入 ESLint、Prettier 规则
• 注释规范：对于类、字段、方法的注释内容与格式上的要求
  • “一律使用 JavaDoc 格式，简要叙说作用，无需引入注解进行其他说明”
  • 在必要时，你可以引入 one-shot（示例）辅助说明格式
• 命名规范：对于类、字段、方法、数据库表、字段的命名要求
• 接口设计规范：
  • 接口风格：如采用 Restful 接口风格
  • 通用返回内容格式定义，即统一返回结果 Result
  • 重要返回内容格式定义，如需要返回一个记录有什么文件的json，你需要确认这个json采取扁平格式还是树状格式
• Git 提交规范：Git 注释类型（如 feat、fix 等）及其含义、Git 的提交时机
• 日志规范：日志级别（error、warning、info、debug）及其使用场景 除上述提到的内容之外，你还可以尝试反问 AI，让其帮助你补充一些规范内容

2.6.2 说明示例

在正式开发之前，我希望为项目制定以下开发规范，按优先级排序：

一、接口设计规范（最优先）
- 接口风格：采用 Restful 风格，URL 使用名词复数形式
- 统一返回格式：一个 Result 对象，包含 code、message、data 三个字段
  例如：{ "code": 200, "message": "success", "data": { ... } }
- 分页返回格式：[描述具体结构]
- 错误返回格式：[描述具体结构]

二、命名规范
- 类名：使用 PascalCase（如 UserService）
- 方法名/变量名：使用 camelCase（如 getUserById）
- 数据库表名：使用 snake_case，复数形式（如 user_accounts）
- 数据库字段名：使用 snake_case（如 created_at）
- 常量名：使用 UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）

三、注释规范
- 类和方法的注释使用 JavaDoc / JSDoc 格式，简要说明作用
- 复杂业务逻辑需在注释中说明 WHY，不说明 WHAT（代码即文档）

四、Git 提交规范
- 提交类型：feat（新增功能）、fix（修复 bug）、refactor（重构）、
  docs（文档变更）、test（测试）、chore（杂项）
- 提交时机：每完成一个可独立测试的功能后提交，不要等到多个功能混在一起再提交

五、日志规范
- 日志级别使用：error（异常）、warning（警告）、info（正常流程）、debug（调试）
- error：程序遇到不可恢复的错误，需要人工介入
- warning：程序遇到可处理的异常，但业务逻辑可以继续
- info：关键业务流程节点，如"用户登录成功"、"订单创建完成"
- debug：开发调试用，生产环境关闭

六、语法规范（如有）
- 引入 [ESLint / Prettier / 等工具]，使用 [具体配置]

在正式开发之前，我希望为项目制定以下开发规范，按优先级排序：

一、接口设计规范
- 接口风格：采用 Restful 风格
- 统一返回格式：{ "code": 200, "message": "success", "data": { ... } }
- 分页返回格式：{ "code": 200, "message": "success", "data": {
    "list": [...], "total": 100, "page": 1, "pageSize": 20
  } }
- 错误返回格式：{ "code": 400, "message": "用户名或密码错误", "data": null }

二、命名规范
- 类名：PascalCase（如 ImgRiverService）
- 方法名/变量名：camelCase（如 uploadImage）
- 数据库表名：snake_case，复数形式（如 img_repositories）
- 数据库字段名：snake_case（如 created_at）
- 常量名：UPPER_SNAKE_CASE（如 MAX_UPLOAD_SIZE）

三、Git 提交规范
- feat：新增图片上传功能
- fix：修复图片删除后链接仍可访问的问题
- 每次功能完成并通过自测后提交

2.7 阶段七：敲定开发规范文档

2.7.1 阶段说明

与阶段三、阶段五相同，本阶段需要将在阶段六你与 AI 的交流成果固化为文档，确认 AI 的想法与你相同即可

2.7.2 说明示例

”总结刚才的对话内容，生成一份开发规范文档到 XXX 目录“

---

==到此为止，项目开发的大方向制定完成==

2.8 阶段八：结合文档生成开发执行计划

2.8.1 阶段说明

在本阶段，需要让 AI 根据产品需求文档、架构设计文档、开发规范文档生成一份项目开发计划。在沟通时，应明确以下内容：

• 明确告知 AI 这份开发计划应分为多个阶段
• 明确要求其说明各阶段的目标（该阶段要做的事），并要求其根据阶段目标，生成具体执行步骤 在开发计划生成完成后，你需要仔细查看一遍开发计划，确认整体的开发走向正确。

2.8.2 说明示例

“根据先前生成的产品需求文档、架构设计文档、开发规范文档生成一份项目开发计划。这份开发计划应按照阶段划分，每个阶段都需要说明其阶段目标、以及为了达成该阶段目标所需要的执行步骤”

2.9 阶段九：正式开发

2.9.1 阶段说明

本阶段正式进入 AI 生成代码的实际开发环节，你应该遵照下述工作流对本环节进行监督与干涉： 此外，在本阶段的流程中你需要额外注意几点：

• 对于 AI 生成的修复功能补丁的代码，应进行检查确保它不是在“让提出问题的人闭嘴”（作者之前遇到一个问题，一个不该抛出异常的位置抛出异常，正常情况下 AI 应定位异常抛出的原因并修复使其不再抛出异常，但 AI 给出的解决方案是加入一个 try-catch 块 捕获异常并处理，明显是错误的），而是真正的在解决问题
• 在项目最终的规范检查中，若存在涉及到业务代码的修改，应对依赖其的功能以及其本身进行测试，确保修改不会引入新的问题；若只存在非业务代码修改，确认无误即可放行

---

三、内容附录

3.1 文章初始草稿

1. 你想要创作的项目状态？
 是有一份完整的项目设计书，还是只是想了一份项目的雏形及其必要功能
2. 确定项目的宏观方向
 在此阶段，你需要与 AI 持续沟通，将模糊的想法具象化，为项目开发定下基调，一般需要确定的内容如下：
 - 项目的名称（可选）
 - 项目的方向（比如要开发一个图床）
 - 项目的服务目标（个人、小规模群体、大规模群体、商业化），对于一个项目来说，不同的服务目标往往决定项目的技术栈与开发走向，切记技术服务于人
 - 项目的核心功能描述，这里的核心功能是指：项目本身应具备的功能 + 你认为该项目需要具备的必要核心功能，这里的必要二字十分关键，你需要克制住自己的欲望，在一开始只加入最核心最必要的功能，避免开发膨胀
 - 项目的必要实体以及其需要包含的信息（粗略讨论，不需要具体到表字段设计）以及一些业务限制信息（比如关系，一对一、一对多、多对多）
 - 核心功能的交互流程，你需要跟 AI 确认核心功能必备的交互步骤与处理流程
 - 简要谈谈项目的非功能需求
 - 说出项目中不需要的功能，这一步骤也很关键
3. 向 AI 索要 PRD（产品需求文档）
 在第二阶段，你与 AI 沟通的内容本质上就是 PRD 中的核心内容，在此让其输出一份文档是为了确认你与 AI 的步调和看法是否一致，你需要仔细阅读这份 PRD 文档，看 AI 对本项目的理解与你对本项目的理解是否一致
4. 让 AI 说明实现本项目所需要的各项技术栈，在此阶段，你需要结合你项目的服务目标来综合考虑技术栈选用（比如后端选用 Java 还是 Ts，Java 生态成熟、Ts 在人数规模较小的程度下结合 CloudFlare 及其方便部署并且经济），是否引入中间件？引入什么中间件等，你需要在本阶段确定项目最核心的技术栈（后端前端语言、应用框架、中间件、数据库等选型），对于一些依赖库等，则可以在后续开发遇到问题时，再酌情引入
5. 向 AI 索要 架构设计书，你需要仔细阅读这份架构设计书，确认 AI 给出的技术栈最终选型及其原因、模块与功能划分、项目包结构（后端、前端等）等是否合理，以及与你预期是否相同，在此阶段，你需要特别关注应用层实体、数据库的 ER关系以及表字段设计，约束与索引的使用，并确定基本思想（逻辑删除还是物理删除、乐观锁需要不需要设置、是否需要常用字段如创建、更改时间以及人）
6. 你需要编写一些规则来保证开发的顺利进行
 - 如注释规范，对于类、字段、方法的注释内容以及格式要求
 - 命名规范，应用层类、字段、方法等命名的规范、数据库层字段、表的命名规则
 - 接口设计规范，如采用 Restful 风格，返回结果的格式，以及重要返回内容的格式定义（比如要返回一个记录文件的json，你需要确认这个 json 是树状还是扁平风格）
 - Git 提交规范，提交的注释类型（feat、fix 等名称及其含义），git 提交时机
 - 日志规范
 - 开发风格（喜欢先开发完后端接口测试再前后端联调，还是前后端同步调开发）
7. 向 AI 索要开发规范文档，与前面索要文档的意义大概相同，你需要确认 AI所理解与你所理解是否相同，在此阶段你还可以反问 AI 是否可以补充些内容
8. 到此为止，项目开发的大方向制定完成
9. 接下来，你需要让 AI 根据这三份文档，PRD、架构设计书、开发规范文档，来生成一个阶段开发计划，明确要求 AI 将项目开发分为多个阶段，并详细说明每个阶段的目标（这个阶段要做什么），具体任务划分（这个阶段的任务再细分为具体步骤），阶段验收标准（用于测试）
10. 现在可以正式进行开发了，先进行第一阶段开发，在 AI 生成完成代码后，你可以选择让 AI 生成一份功能测试清单（前后端同步调开发）、单元测试（先后端再前端），你需要对照这份清单，对项目中的功能逐一测试，
 - 发现问题，及时反馈给 AI，让其修复，在修复过程中，你需要进行 code review，确认 AI 的修复是行之有效的，而不是“让提出问题的人闭嘴”（博主之前遇到过一个问题，一个不该抛出异常的位置总是抛出异常，AI 给出的解决方案是使用 try-catch 来捕获异常并处理，实际上真正的解决办法应该是定位异常抛出的原因，并使异常不再抛出）
 - 在功能问题修复完成后，你需要整体浏览一遍本阶段 AI 生成的所有代码，评估 AI 是否遵照你的规范文档进行开发，发现问题也需要让 AI 及时纠正
 确认无问题后，将本次代码提交到 git 仓库里
11. 就这样一阶段一阶段的进行开发-测试-提交，在开发计划全部结束后，你需要让 AI 评估一次当前项目是否已达到 MVP 要求，若不满足 MVP 要求，你需要让 AI 生成补充开发计划（依旧按照阶段划分，每阶段执行开发-测试-提交），重复上述步骤，直到满足 MVP 要求
12. 每份开发计划的尾阶段，可以进行一次代码优化以及规范整体检查

3.2 产品需求文档说明（AI 生成）

3.2.1 定义与定位

产品需求文档（PRD，Product Requirements Document）是需求工程（Requirements Engineering）领域的核心产物之一，用于系统性地记录与描述软件产品应满足的功能性需求与非功能性约束。

从需求工程的学科体系来看，PRD 位于用户需求（User Requirements）与软件需求规格说明（Software Requirements Specification, SRS）之间的过渡地带：它承继自用户需求，以产品视角加以组织和提炼，并适当融入技术可行性的初步考量，但不涉及具体的实现方案设计。PRD 遵循 ISO/IEC/IEEE standards 中所定义的需求文档（Requirements Document）范畴，其核心目标是建立利益相关方（Stakeholder）之间对产品需求的共识**，并在后续的设计、开发和验证阶段提供可追溯的参照基准。

在 IEEE Std 830-1998（即 Software Requirements Specification 标准的先前版本）中，需求文档被定义为“对软件系统的以下特性进行完整、可验证、可实现的无歧义描述：（1）系统应实现的功能；（2）系统应满足的性能指标；（3）系统运行所需的外围条件；（4）系统应符合的约束”。PRD 遵循上述定义框架，但更强调以产品语言（而非纯技术语言）进行表达。

3.2.2 历史渊源

PRD 的概念起源于 1970 年代末至 1980 年代初的结构化软件开发实践。在瀑布模型（Waterfall Model）主导的时期，需求分析被视作软件生命周期的早期阶段，其产出物——需求文档——具有“契约性文档”的地位，得到工程化的严格执行。

1990 年代，随着交互工业协会（Interactive Industries Association）对 PRD 概念的系统化推广，以及后续 Microsoft、Rational Unified Process（RUP）等企业和方法论体系的广泛传播，PRD 逐渐成为商业软件开发中的标准配置。进入敏捷时代后，PRD 的形式趋于精简，出现了用户故事（User Story）和用例（Use Case）等轻量化替代方案。然而，PRD 作为完整、系统化描述产品需求的工具，在复杂项目和合规性要求较高的领域（如金融、医疗、军工）中仍具有不可替代的价值。

3.2.3 核心要素

根据 ISO/IEC/IEEE 29148:2011（系统与软件工程——生命周期过程——需求工程）和 IEEE Std 830-1998 的规范要求，一份完整的需求文档应包含以下要素：

要素	说明	依据
文档标识	文档名称、版本号、编写日期、作者、审批人	IEEE Std 830
背景与目标	项目的业务背景、产品目标和价值主张	ISO/IEC/IEEE 29148
功能需求	系统应实现的功能，按模块或用例组织	IEEE Std 830
非功能需求	性能、安全、可用性、可维护性等技术要求	IEEE Std 830
用户流程	典型用户场景与操作路径	用户故事方法论
边界与约束	明确范围边界，排除项和约束条件	ISO/IEC/IEEE 29148
术语表	文档中使用的专业术语统一解释	技术写作规范
验收标准	每项需求的可量化、可验证的验收条件	ISO/IEC/IEEE 29148

3.2.4 格式变体

PRD 不存在单一强制格式，其形式取决于组织惯例、项目规模和行业规范要求。以下两种格式在学术和工程实践中最为常见：

3.2.4.1 详细叙述型（Full-specification Model）

此格式源于传统软件工程的瀑布范式，按照自顶向下的结构逐层展开所有需求，适用于复杂系统或高合规性要求的项目，遵循 IEEE Std 830-1998 的推荐模板：

1. 引言
   1.1 目的
   1.2 范围
   1.3 定义、缩略语与缩写
   1.4 参考资料
2. 总体描述
   2.1 产品视角
   2.2 产品功能
   2.3 用户类和特征
   2.4 运行环境
   2.5 约束与假设
3. 详细需求说明
   3.1 功能需求 [按模块组织]
   3.2 性能需求
   3.3 设计约束
   3.4 外部接口需求
   3.5 可维护性需求
   3.6 可靠性需求

3.2.4.2 用户故事型（User Story Model）

此格式源于敏捷方法论（Agile Methodology），以“角色-功能-价值”（Role-Feature-Benefit）三元组作为基本叙事单元，强调从最终用户视角描述需求，适用于迭代式开发团队：

作为 [角色]
我希望 [做某件事]
以便 [达成某个业务目标]

验收标准：
- 场景 1：[给定条件]，当 [触发条件] 时，[期望结果]
- 场景 2：[给定条件]，当 [触发条件] 时，[期望结果]

Definition of Done：
- [可量化的完成条件 1]
- [可量化的完成条件 2]

3.2.5 质量评判标准

根据 ISO/IEC/IEEE 29148:2011 和《需求工程：面向复杂系统的软件设计》（Klaus Pohl, 2010）的要求，高质量的需求文档应满足以下六项评判标准（CRUD+）：

标准	说明
Completeness（完整性）	所有需求均有完整描述，无未决项或“待定”标记
Correctness（正确性）	需求描述符合业务实际，无凭空臆造
Uniqueness（无歧义性）	每条需求只有一种解释，不存在模糊表述
Consistency（一致性）	需求之间不存在逻辑冲突
Verifiability（可验证性）	每条需求均可通过测试或评审验证
Traceability（可追溯性）	需求可追溯至其来源，并可追踪至对应的设计、实现和验证阶段

3.3 架构设计文档说明（AI 生成）

3.3.1 定义与定位

架构设计文档（ADD，Architecture Design Document）是软件架构描述（Architecture Description）的正式文本产出物，属于软件生命周期中架构设计阶段（Architecture Design Phase）的核心交付物。

根据 ISO/IEC/IEEE 42010:2011（系统与软件工程——架构描述的描述）标准，**架构描述（Architecture Description）**被定义为“用于描述系统架构的人工制品集合”，其核心目的是“向利益相关方传达系统的核心架构决策”。ADD 即为这一人工制品集合中文本化、可持久化的部分。

从软件工程学科体系来看，架构设计位于需求分析与详细设计之间，起着承上启下的关键作用：它以 SRS 中定义的需求为输入，以架构层面的决策为输出，为后续的详细设计和编码提供结构化、可执行的蓝图。架构决策记录（ADR，Architecture Decision Record）作为 ADD 的辅助性组件，记录了每项架构决策的“背景-决策-结果”（Context-Decision-Consequence）三段式逻辑，是 ADD 保持可维护性的重要机制。

3.3.2 学术渊源

软件架构（Software Architecture）作为一个独立学科，起源于 1990 年代初。David Garlan 和 Dewayne Perry 在 1993 年发表了具有里程碑意义的论文《Introduction to the ACM SIGSOFT’93 Architectural Design Issue》，首次系统性地将架构概念引入软件工程领域。此后，Mary Shaw 和 David Garlan 于 1995 年出版的《Software Architecture Perspectives on an Emerging Discipline》奠定了软件架构作为学科的理论基础。

在此学术脉络下，架构设计文档逐渐演变为承载架构知识的正式载体。1990 年代末至 2000 年代初，学界和工业界形成了以**4+1 视图模型（Kruchten’s 4+1 View Model, 1995）**为代表的架构描述方法论，该模型从逻辑视图、进程视图、物理视图、开发视图和场景（用例）五个视角描述系统架构，至今仍是 ADD 事实上的标准框架。

2000 年代，IEEE 制定了架构描述的相关标准体系，其中最具影响力的是 ISO/IEC/IEEE 42010:2011，该标准首次以国际标准的形式定义了架构描述的概念、架构视角（View）和架构观点（Viewpoint）的术语体系，为 ADD 的编写提供了规范性指导。

3.3.3 核心要素

根据 ISO/IEC/IEEE 42010:2011 框架，并结合学术界和工业界的实践共识，一份完整的架构设计文档应包含以下核心要素：

要素	说明	依据
技术选型说明	编程语言、框架、中间件、数据库的选用及技术理由	工业实践
架构风格	系统所采用的架构风格及其选择理由	Kruchten 4+1 模型
逻辑视图	从业务功能角度描述系统的模块划分与职责	Kruchten 4+1 模型
进程视图	从运行时并发和进程调度角度描述系统的行为	Kruchten 4+1 模型
物理视图	从硬件部署角度描述系统的分布式部署结构	Kruchten 4+1 模型
开发视图	从开发组织角度描述系统的代码组织和构建结构	Kruchten 4+1 模型
数据模型设计	数据库选型、表结构、字段类型、约束与索引	数据库工程实践
E-R 图	实体（Entity）及其关系（Relationship）的图形化描述	数据库设计理论
接口规范	模块间/系统间交互的接口定义与协议说明	软件接口设计规范
约束与决策记录	架构决策及其理由的持久化记录（ADR）	敏捷架构实践

3.3.4 架构风格

架构设计文档应对系统所采用的架构风格（Architectural Style）加以说明。架构风格是对系统整体组织结构的模式化抽象，它定义了系统组件的基本类型、组件之间的交互模式，以及约束条件的集合。以下为常见的几种架构风格：

3.3.4.1 分层架构（Layered Architecture）

将系统按职责分为多个层级，每个层级只能调用其下层的服务。经典的三层架构将系统分为表现层（Presentation）、业务层（Business）和数据层（Data Access）。优点是结构清晰、易于理解和分层开发；缺点是分层带来的抽象开销在高并发场景下可能成为性能瓶颈。

3.3.4.2 微服务架构（Microservices Architecture）

将系统拆分为多个可独立部署的服务，每个服务对应一个明确的业务功能，服务之间通过轻量级协议（如 HTTP/REST、gRPC）通信。优点是独立部署和扩展、技术异构性强；缺点是分布式系统的复杂性（事务一致性、服务发现、容错等）显著增加。

3.3.4.3 事件驱动架构（Event-Driven Architecture, EDA）

系统组件通过发布和订阅事件（Event）进行交互，组件之间不存在直接调用关系，而是通过事件总线（Event Bus）或消息队列（Message Queue）解耦。优点是高扩展性和实时响应能力；缺点是事件的无序性和幂等性处理增加了系统设计的复杂度。

3.3.4.4 六边形架构（Hexagonal Architecture）

又称端口与适配器架构（Ports and Adapters Architecture），由 Alistair Cockburn 提出。核心业务逻辑被置于“六边形”内部，通过“端口”（Port）与外部组件交互，外部组件通过“适配器”（Adapter）接入。优点是业务逻辑与外部依赖完全解耦，易于测试和替换组件；缺点是抽象程度较高，前期设计成本较大。

3.3.4.5 面向服务的架构（Service-Oriented Architecture, SOA）

与微服务架构相似，但通常依赖于企业服务总线（ESB，Enterprise Service Bus）作为通信中枢，技术上偏重于 XML/SOAP 协议。优点是服务复用和编排能力强；缺点是 ESB 单点故障风险和架构重量化问题。

3.3.5 E-R 图的理论基础

E-R 图（Entity-Relationship Diagram，实体-关系图）是概念数据模型（Conceptual Data Model）的图形化表示工具，由 Peter Chen 于 1976 年在《The Entity-Relationship Model—Toward a Unified View of Data》中首次提出，是数据库设计理论的重要基础。

E-R 图的核心构成要素：

实体（Entity） 现实世界中具有独立存在性的对象，且该对象可由一组属性（Attribute）加以描述。在数据库实现层面，实体对应关系数据库中的表（Table），实体实例对应表中的行（Row/Tuple）。

本文章主要参考了 https://www.nowcoder.com/discuss/868467588592910336 的说法，并在实践中加以改进

属性（Attribute） 实体的某个特征或性质。在关系数据库中，属性对应表的列（Column）。属性按其性质可分为：

• 简单属性（Simple Attribute）：不可再分，如“用户年龄”
• 复合属性（Composite Attribute）：可进一步分解，如“用户地址”可分解为“省-市-区”
• 单值属性（Single-valued Attribute）：每个实例对应单一值
• 多值属性（Multi-valued Attribute）：每个实例对应多个值（如一个用户有多个手机号）

关系（Relationship） 实体之间的关联。在数据库实现层面，关系通过**外键（Foreign Key）或关联表（Association Table）**实现。关系按其参与实体的数量可分为：

• 一对一关系（1:1）：实体 A 的每个实例至多对应实体 B 的一个实例，反之亦然
• 一对多关系（1:N）：实体 A 的一个实例对应实体 B 的多个实例，反之每个 B 实例至多对应一个 A 实例
• 多对多关系（M:N）：实体 A 和实体 B 的实例之间存在多值对应关系

E-R 图的设计原则：

1. 每个实体应有唯一的标识属性（主键）
2. 关系应使用动词或动名词命名，以反映实体之间的语义联系
3. 应避免冗余关系——即那些可以通过其他关系间接推导出的关系
4. 多元关系（M:N 以上的联系）应通过关联实体加以分解