想给孩子找点题做 都有什么网站知乎 淘宝网站建设

# 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}} | {{版本范围}} |

```