AI编程下的需求规格文档的问题及新规范
# AI编程就是要文档先行
在多个企业级项目中使用AI编程过程，有许多AI编程方向的心得和经验，抽空整理并记录下来，以供后来人借鉴。
首先我要分享的是项目文档编写方面的经验，常规的企业级项目肯定都是文档先行，再后才是编程。
现在市场上很多介绍一句话生成一个APP之类的视频，作为行内人，只是当热闹看。
想像一下，现实的软件公司中，如果客户只是给你一句话需求，你敢马上让程序员开干吗，那肯定是不行的吗，哪个项目不是要先写需求文档--与客户回来多轮沟通才能确认下来具体要开发的需求的。
特别是现阶段AI编程能力还只是相当一个初级程序员的理解功能，这让我想起这么多年带的那么程序员实力生，哪个不是要先给出详细，具体，明确的需求才能完成任务。
# 需求文档的现有问题
企业级的项目中的需求规格文档一般都是固定的格式和内容，这是给客户与IT团队成员看的，也就是说是给人看的，一般一个需求规格文档都是十几页甚至上百页以上，内容非常多，这对AI这种输入内容字数有限制的场景来说，非常不友好。就算在AI输入限制范围内，由于内容太多，AI也容易遗忘部分信息。
在我多个项目开发经验上看，已经出现多次AI遗忘的问题，最严重的一次是明明给定的概要设计文档中已经明确使用Python语言开发了，就是由于概要设计文档内容太多，超过1000行，导致AI输出的详细设计文档中还是有部分JAVA代码示例。
因此我总结给AI使用的文档（不单单是编程方向），其核心原则一定要围绕“AI友好性”与“token效率”两大维度构建，确保文档能被AI高效理解并转化为精准输出。
## AI友好性问题
常规的需求规格文档对AI不友好的体现主要有以下几点：
- **文档格式问题**：之前我们的需求规格文档都是使用docx格式的，甚至有些团队还使用pdf格式，但这些对AI都不大好友，最好是使用markdown格式，兼容AI和人都能直接理解
- **非结构化排版**：大量使用复杂表格、浮动图片和嵌套样式，导致AI无法提取关键信息
- **模糊表述**：使用"可能"、"建议"、"尽快"等不确定词汇，AI难以转化为明确实现逻辑
- **术语混乱**：同一功能模块出现多个名称（如"用户管理"与"会员系统"混用）
- **冗余信息过载**：包含过多市场分析、竞品对比等与技术实现无关的内容
- **缺乏明确边界**：功能描述与非功能描述混杂，未区分必选/可选需求
- **代码示例缺失**：关键业务逻辑仅用文字描述，未提供伪代码或实现示例
- **上下文断裂**：频繁使用"如前所述"、"详见附件"等指代性表述
## token效率问题
常规的项目文档由于固定格式的原因，导致有过多的非必要内容，这对AI模型来说是比较不友好的。
下面以需求规格文档为例，说明下token效率的问题：
- 文档版本信息，功能点更改记录，负责人等信息，这部分内容是给IT团队成员扯皮用的，对AI来说无任何价值。
- 项目背景、目标、术语这些，我感觉是给客户装X用的，我们自己的程序员开发代码时也不看这些内容
- 详细的表格、流程图等可视化元素，甚至有图片，这些AI无法直接解析且占用大量token
# AI编程下的需求规格文档新模板
根据上面的“AI友好性”与“token效率”两大原则，我重新设计了下需求规格文档的新模板，大家可以在评论中分享下自己的设计模板。
由于在项目中，编写文档的顺序是：需求规格文档--->概要设计文档--->详细设计文档--->代码实现，因此在AI编程中，需求规格文档既是给人确认需求用的，也是给AI的进一步生成概要设计文档用的提示词。
从AI编程的角度看，要生成概要设计文档，那到仅需要用到以下几个关键信息就可以：
- 要开发什么系统（核心需求）
- 用什么语言开发（技术约束）
- 具体的开发任务（需求功能）
- 开发中注意什么（非功能需求）
因此我设计的需求规格文档模板如下：
```markdown
# 核心需求
从程序员的角度描述要开发的需求内容，要求简洁明了。
## 2. 技术约束
| 类型 | 约束条件 |
| ---- | ------------------- |
| 前端 | {{框架/兼容性要求}} |
| 后端 | {{语言/中间件要求}} |
| 部署 | {{环境要求}} |
## 3. 需求功能
### 3.1 {{模块名称，非必须，如果功能点越过10个，可以不用模块这一层}}
#### FR-001 {{功能点名称}}
- **描述**：{{原子化功能说明}}
- **输入**：
{{参数名}} ({{类型}}, {{约束}})
- **处理逻辑**：
````mermaid
graph LR
A[开始] --> B{条件判断}
B -->|条件1| C[动作1]
B -->|条件2| D[动作2]
````
- **输出**：
{{结果数据结构}} ({{示例值}})
- **异常处理**：
{{错误码}} - {{错误说明}}
### 3.2 {{模块名称}}
## 4. 非功能需求
### 4.1 性能指标
| 场景 | 要求 | 验证方式 |
| --------- | ------------ | ------------ |
| {{场景1}} | {{量化指标}} | {{测试方法}} |
### 4.2 安全需求
- 🔒 {{安全要求1}} (如：密码强度策略)
- 🔒 {{安全要求2}} (如：SQL注入防护)
### 4.3 兼容性
| 平台 | 支持版本 |
| --------- | ------------ |
| {{平台1}} | {{版本范围}} |
```