如何为AI编写系统功能规格说明书：提升代码生成准确率

1. 为什么需要给AI写系统功能规格说明书

1.1 从“AI听不懂人话”说起

很多人第一次尝试让AI帮忙写代码或者做系统设计时，都会遇到一个很尴尬的情况：你觉得自己已经说得很清楚了，但AI给出的东西就是不对味。比如你说“帮我写一个用户管理模块”，AI可能会给你一个包含登录、注册、权限、日志、消息推送甚至积分系统的庞然大物，而你只是想要一个简单的增删改查。

问题出在哪里？不是AI不够聪明，而是你给的信息太少了。AI没有你的项目背景，不知道你的技术栈，不清楚你的代码规范，更不了解你的业务边界。它只能根据“用户管理模块”这五个字去猜，猜出来的东西自然和你的预期相差十万八千里。

这就引出了一个很实际的需求：我们需要一种专门写给AI看的系统功能规格说明书。它和传统写给人类看的规格说明书有本质区别。人类看的文档可以靠上下文、靠经验、靠默契来补全信息，但AI不行，AI需要的是显式的、结构化的、无歧义的输入。

1.2 写给AI的规格说明书和传统文档的区别

传统软件需求文档通常包含大量的背景描述、业务价值论证、流程图和原型图。这些东西对人来说很友好，但对AI来说效率很低。AI不需要你告诉它“这个功能能提升用户体验”，它需要你告诉它“输入是什么、输出是什么、边界条件是什么、异常怎么处理”。

我自己的经验是，写给AI的规格说明书应该具备以下几个特征：

• 结构化程度极高：用固定的模板和字段，减少自由发挥的空间
• 边界条件明确：每个功能都要说清楚什么情况下不做、什么情况下报错
• 技术约束前置：语言、框架、数据库、接口风格都要提前锁定
• 示例驱动：给出输入输出的具体样例，比长篇描述有效得多
• 可验证性：每一条规格都应该是可以被测试和验证的

这份文档的目标读者虽然是AI，但写文档的人还是你自己。所以它同时也要满足一个条件：你自己写起来不费劲，AI读起来不迷惑。

1.3 适合哪些人参考这套方法

这套方法特别适合以下几类人：

第一类是独立开发者或者小团队的技术负责人。你们没有专门的产品经理来写详细需求，很多时候就是自己脑子里想清楚了就直接让AI写代码。这种情况下，一份写给AI的规格说明书能帮你省下大量反复沟通和修改的时间。

第二类是正在尝试用AI辅助系统设计的架构师。你们需要AI帮你生成模块划分、接口定义、数据库表结构，但前提是你要把约束条件说清楚。

第三类是对AI编程感兴趣但总是得不到满意结果的初学者。你们可能还在摸索怎么和AI“说话”，这套方法能帮你建立一套有效的沟通框架。

不管你属于哪一类，核心逻辑都是一样的：把AI当成一个能力很强但完全不了解你项目的远程外包开发者，你需要用文档把所有的隐含信息显式化。

2. 规格说明书的核心结构拆解

2.1 项目上下文：让AI知道它在为什么而工作

很多人写规格说明书时习惯直接从功能列表开始，这是一个常见的误区。AI在没有上下文的情况下，很容易做出错误的假设。比如你写“实现一个搜索功能”，AI可能会默认这是一个Web应用的全局搜索，但实际上你只是想要在一个下拉列表里做本地过滤。

项目上下文这部分不需要很长，但必须包含以下几个关键信息：

• 项目类型：是Web应用、移动端App、桌面软件、CLI工具还是后端服务
• 核心目标：用一句话说清楚这个系统要解决什么问题
• 目标用户：谁会用这个系统，他们的技术水平如何
• 技术栈约束：前端框架、后端语言、数据库、部署环境
• 非功能性约束：性能要求、安全要求、兼容性要求

我通常会用一个表格来呈现这部分信息，因为表格的字段固定，AI解析起来不容易遗漏。比如下面这样：

字段	内容
项目类型	后端API服务
核心目标	为内部系统提供统一的用户认证和权限校验
目标用户	内部开发人员，通过SDK调用
后端语言	Python 3.11
框架	FastAPI
数据库	PostgreSQL 15
缓存	Redis 7
部署方式	Docker容器，Kubernetes编排
性能要求	单接口P99延迟低于50ms
安全要求	所有接口需要JWT鉴权，敏感操作需要二次验证

这张表看起来简单，但它能帮AI排除掉大量错误的实现方向。比如AI看到“FastAPI”就不会给你写Flask的代码，看到“PostgreSQL”就不会用MongoDB的语法。

2.2 功能模块划分：从粗到细的拆解逻辑

功能模块划分是规格说明书的主干部分。我的习惯是先做一级模块划分，再做二级功能拆解，最后对每个功能点做详细规格描述。这个从粗到细的过程很重要，因为它模拟了人类设计师的思维过程，AI在生成代码时也会按照这个层级来组织文件结构。

一级模块划分的原则是按业务领域来分，而不是按技术层次来分。比如一个电商系统，应该分为“商品管理”、“订单管理”、“用户管理”、“支付管理”这样的业务模块，而不是分为“Controller层”、“Service层”、“DAO层”。因为AI需要理解的是业务逻辑，技术分层是它自己会处理的事情。

二级功能拆解是把每个模块拆成具体的功能点。比如“订单管理”可以拆成“创建订单”、“查询订单”、“取消订单”、“订单状态流转”等功能点。每个功能点都应该是独立的、可测试的。

这里有一个我踩过的坑：功能点拆得太粗或太细都不好。太粗了AI会自己脑补很多你没要求的东西，太细了AI会陷入细节而忽略整体结构。我的经验是，一个功能点对应一个API接口或者一个页面操作，这个粒度刚刚好。

2.3 接口契约：AI最容易出错的地方

接口契约是规格说明书里最需要精确的部分。AI在生成接口代码时，最常见的错误就是参数类型不对、返回值结构不对、错误码不统一。要解决这个问题，最好的办法是在规格说明书里把接口契约写得非常明确。

我通常会用类似OpenAPI的格式来描述接口，但不一定用YAML，用表格也可以。关键是要包含以下信息：

• 接口路径和HTTP方法
• 请求参数（名称、类型、是否必填、约束条件）
• 请求体结构（如果是POST/PUT）
• 响应体结构（成功和失败两种情况）
• 错误码列表和含义
• 鉴权要求

举个例子，一个创建用户的接口可以这样描述：

项目	内容
路径	/api/v1/users
方法	POST
鉴权	需要，Bearer Token
请求体	{"username": "string, 3-20字符, 必填", "email": "string, 合法邮箱格式, 必填", "password": "string, 8-32字符, 必填", "role": "string, 枚举值: admin/user/guest, 默认user"}
成功响应	{"code": 0, "message": "success", "data": {"user_id": "string", "username": "string", "created_at": "ISO8601时间戳"}}
失败响应	{"code": 非0, "message": "错误描述", "data": null}
错误码	1001: 用户名已存在, 1002: 邮箱格式错误, 1003: 密码强度不足, 1004: 无权限创建管理员

这种程度的描述，AI基本不会理解错。我实测下来，用这种方式写规格说明书，AI生成接口代码的准确率能到90%以上，剩下的10%主要是业务逻辑的细节需要微调。

2.4 数据模型：让AI理解数据之间的关系

数据模型部分需要描述系统中涉及的所有实体、实体的字段、实体之间的关系。这部分内容AI非常依赖，因为它直接决定了数据库表结构和ORM代码的生成质量。

我通常会用ER描述的方式来做，但不画图，而是用文字和表格。每个实体一张表，字段名、类型、约束、说明都写清楚。实体之间的关系用单独的一节来描述，比如“一个用户可以有多个订单，一个订单属于一个用户，关系类型为一对多”。

这里有一个细节需要注意：字段的命名规范要提前约定好。是用snake_case还是camelCase，主键是用id还是用表名_id，时间戳是用created_at还是create_time，这些都要在规格说明书里明确。否则AI可能会在不同模块里用不同的命名风格，后期统一起来很麻烦。

2.5 业务规则：那些AI猜不到的隐含逻辑

业务规则是规格说明书里最容易被忽略但最重要的部分。这些规则往往是团队内部约定俗成的，人类开发者之间口口相传，但AI完全不知道。

比如“用户连续登录失败5次后锁定账号30分钟”、“订单金额超过1000元需要人工审核”、“商品库存低于10件时自动发送补货提醒”，这些都是业务规则。如果不写进规格说明书，AI生成的代码里就不会包含这些逻辑。

我的做法是把业务规则单独列一节，用编号的方式逐条列出。每条规则都要说清楚触发条件、执行动作、例外情况。比如：

• 规则R001：用户连续登录失败5次后，锁定账号30分钟。锁定期间即使密码正确也拒绝登录。30分钟后自动解锁，失败计数清零。
• 规则R002：订单金额超过1000元时，订单状态变为“待审核”，需要管理员手动审核通过后才能进入支付流程。
• 规则R003：商品库存低于10件时，向管理员发送补货提醒。同一商品24小时内只提醒一次。

这种写法AI很容易理解，生成代码时也会把这些规则实现进去。

3. 实操过程：从零写一份AI友好的规格说明书

3.1 第一步：确定文档模板和字段规范

在开始写具体内容之前，先要把文档模板定下来。模板的作用是约束你自己的写作范围，同时也是给AI一个稳定的解析结构。我常用的模板包含以下几个部分：

1. 项目上下文（表格形式）
2. 功能模块列表（树形结构）
3. 接口契约（每个接口一张表）
4. 数据模型（每个实体一张表）
5. 业务规则（编号列表）
6. 异常处理约定（表格形式）
7. 技术约束和编码规范（列表形式）

这个模板不是固定的，你可以根据项目类型调整。比如如果是前端项目，接口契约可以换成组件契约；如果是数据处理项目，可以增加数据流水线描述。

模板定好之后，建议先写一个空模板，把所有的字段名和格式确定下来，然后再往里填内容。这样做的好处是格式统一，AI解析时不会因为格式变化而困惑。

3.2 第二步：用AI能理解的语言描述需求

这一步是整个流程中最考验人的地方。你需要把脑子里的想法翻译成AI能精确理解的语言。我的经验是遵循以下几个原则：

原则一：用陈述句，不用疑问句或感叹句。“用户应该能够通过邮箱注册账号”比“用户能不能用邮箱注册呢”要好得多。AI对陈述句的理解准确率明显更高。

原则二：量化描述，避免模糊词汇。“快速响应”不如“P99延迟低于50ms”，“大量数据”不如“单次查询返回不超过1000条记录”。AI对数字和具体约束的理解远好于形容词。

原则三：显式列出所有假设。如果你假设用户已经登录，就写“此接口假设调用方已通过鉴权”。如果你假设数据库里已经有某个表，就写“此功能依赖users表，表结构见数据模型章节”。不要让AI去猜。

原则四：用示例代替解释。与其花一段话解释“用户名不能包含特殊字符”，不如直接写“合法用户名示例：zhangsan、li_si、wang123；非法用户名示例：张三、user@name、admin#”。

3.3 第三步：接口和数据的详细定义

接口和数据的定义是规格说明书里最耗时的部分，但也是最值得投入时间的部分。我的做法是先定义数据模型，再定义接口，因为接口的请求和响应结构往往依赖于数据模型。

定义数据模型时，我会用下面这种表格：

字段名	类型	约束	说明
id	UUID	主键，自动生成	用户唯一标识
username	VARCHAR(20)	非空，唯一	用户名，3-20字符
email	VARCHAR(255)	非空，唯一	邮箱，合法邮箱格式
password_hash	VARCHAR(255)	非空	密码哈希值，bcrypt算法
role	VARCHAR(10)	非空，默认'user'	角色，枚举值：admin/user/guest
status	SMALLINT	非空，默认1	状态，1正常 0禁用
created_at	TIMESTAMP	非空，自动生成	创建时间
updated_at	TIMESTAMP	非空，自动更新	更新时间

定义接口时，我会用下面这种表格：

项目	内容
接口名称	用户注册
路径	/api/v1/auth/register
方法	POST
鉴权	不需要
请求体	{"username": "string, 必填", "email": "string, 必填", "password": "string, 必填"}
成功响应	{"code": 0, "message": "注册成功", "data": {"user_id": "uuid", "username": "string"}}
失败响应	{"code": 非0, "message": "错误描述", "data": null}
错误码	2001: 用户名已存在, 2002: 邮箱已被注册, 2003: 密码强度不足
业务规则	注册成功后自动发送欢迎邮件；新用户默认角色为user

这种表格的好处是信息密度高，AI解析起来不容易遗漏。我试过用纯文字描述同样的内容，AI生成代码的准确率会下降大概20%左右。

3.4 第四步：异常和边界条件的补充

异常和边界条件是AI最容易忽略的部分。如果你不写，AI默认只处理正常流程，异常情况要么不处理，要么处理得很随意。所以这部分必须显式写出来。

我通常会把异常分为三类：

• 输入异常：参数缺失、格式错误、超出范围
• 业务异常：状态冲突、权限不足、资源不存在
• 系统异常：数据库连接失败、第三方服务超时、并发冲突

每一类异常都要定义清楚错误码、错误信息、HTTP状态码、以及客户端应该如何处理。比如：

错误码	错误信息	HTTP状态码	客户端处理建议
2001	用户名已存在	409	提示用户更换用户名
2002	邮箱已被注册	409	提示用户更换邮箱或找回密码
2003	密码强度不足	400	提示密码规则
2004	请求参数缺失	400	检查必填参数
5001	数据库连接失败	500	稍后重试
5002	第三方服务超时	503	稍后重试

边界条件也要写清楚。比如“用户名长度3-20字符”就是一个边界条件，AI需要知道小于3或大于20时应该报错。再比如“单次查询最多返回1000条记录”，AI需要知道超过1000条时应该分页或者截断。

3.5 第五步：验证和迭代

规格说明书写完初稿后，不要直接拿去让AI生成代码。先做一轮验证，看看有没有遗漏或者矛盾的地方。我的验证方法很简单：自己按照规格说明书的描述，在脑子里过一遍完整的业务流程，看看有没有卡住的地方。

比如用户注册流程：用户提交注册请求 -> 系统校验参数 -> 系统检查用户名是否已存在 -> 系统检查邮箱是否已被注册 -> 系统创建用户记录 -> 系统发送欢迎邮件 -> 返回成功响应。这个流程里每一步都需要有对应的规格描述，如果哪一步没有描述清楚，AI生成代码时就会在那里出问题。

验证通过后，把规格说明书交给AI，让它生成代码。生成完之后，对照规格说明书检查代码，看看有没有偏离。如果有偏离，说明规格说明书里对应的部分写得不够清楚，需要补充或修改。然后再次生成，再次检查，直到AI生成的代码基本符合预期。

这个迭代过程通常需要2-3轮，但相比反复用自然语言和AI沟通，效率还是高很多。

4. 常见问题与排查技巧实录

4.1 AI生成的代码偏离规格怎么办

这是最常见的问题。AI生成的代码和规格说明书对不上，通常有三种原因：

原因一：规格说明书本身有歧义。比如你写“用户年龄”，AI可能理解为整数，也可能理解为字符串。解决办法是把类型写清楚：“用户年龄，整数类型，范围0-150”。

原因二：规格说明书有遗漏。比如你定义了接口的请求参数，但没有定义响应结构。AI就会自己编一个响应结构，可能和你的预期不一致。解决办法是每个接口都要完整定义请求和响应。

原因三：AI的“自由发挥”。有时候AI会自作主张添加一些你没要求的功能，比如自动生成日志、自动添加缓存、自动实现限流。这些不一定是坏事，但如果你不需要，就要在规格说明书里明确写“不需要日志记录”、“不需要缓存”、“不需要限流”。

排查技巧：当发现AI生成的代码偏离规格时，先不要急着改代码，而是回到规格说明书，找到对应的部分，看看是不是写得不够清楚。把规格说明书改清楚，再让AI重新生成，通常就能解决问题。

4.2 规格说明书写多详细才算够

这是一个很实际的问题。写太粗了AI理解不了，写太细了你自己累得半死。我的经验是遵循“最小充分原则”：只写AI无法自己推断的信息，AI能自己推断的就不写。

比如“用户密码需要加密存储”，这个要写，因为AI不知道你用什么加密算法。但“用户密码不能明文存储”，这个可以不写，因为这是常识，AI默认就会加密。

再比如“接口返回JSON格式”，这个要写，因为AI可能返回XML。但“JSON的key要用双引号”，这个可以不写，因为这是JSON规范，AI不会搞错。

判断标准很简单：如果你不确定AI会不会做对，就写进去。如果你确定AI一定会做对，就不用写。随着你使用AI的经验增加，你会越来越清楚哪些信息是AI需要的，哪些是多余的。

4.3 多个AI协作时如何保持规格一致

有时候我们会用多个AI来分别生成前端和后端代码，或者用不同的AI来生成不同的模块。这时候规格说明书的一致性就很重要了。

我的做法是维护一份主规格说明书，所有AI都基于同一份文档工作。如果某个AI需要额外的信息，就在主文档里补充，而不是单独给那个AI开小灶。这样可以保证所有AI对系统的理解是一致的。

另外，接口契约部分要特别小心。前端AI和后端AI对接口的理解必须完全一致，否则联调时会出现各种问题。我的经验是，接口契约写完之后，先让前端AI和后端AI分别生成代码，然后对比两边的接口定义，看看有没有不一致的地方。如果有，就修改规格说明书，直到两边完全一致。

4.4 规格说明书的版本管理

规格说明书是活文档，会随着项目进展不断修改。如果没有版本管理，很容易出现“AI用的是旧版规格”的问题。

我的做法是用Git来管理规格说明书，每次修改都提交一次，写清楚修改了什么、为什么修改。给AI生成代码时，明确告诉AI用的是哪个版本的规格说明书。

另外，规格说明书的修改要遵循“向后兼容”原则。如果某个接口的请求参数发生了变化，要尽量保持旧参数仍然可用，或者至少给一个过渡期。否则已经生成的代码可能会因为规格变化而失效。

4.5 常见问题速查表

问题现象	可能原因	排查方法	解决方案
AI生成的接口参数类型不对	规格说明书未指定类型	检查接口契约中的参数定义	补充参数类型和约束条件
AI遗漏了业务规则	业务规则未写入规格	检查业务规则章节	补充业务规则并重新生成
前后端接口不一致	接口契约有歧义	对比前后端生成的接口定义	统一接口契约描述
AI生成了不需要的功能	规格说明书未明确排除	检查是否有“不需要”的说明	添加排除性描述
异常处理不符合预期	异常定义不完整	检查异常处理章节	补充异常码和处理逻辑
数据模型与代码不一致	数据模型描述不清晰	对比数据模型和生成的ORM代码	细化字段类型和约束

5. 进阶技巧：让规格说明书更高效

5.1 用模板减少重复劳动

如果你经常需要写规格说明书，建议积累一套自己的模板库。不同类型的项目用不同的模板，比如Web后端项目、移动端项目、数据处理项目各有一套模板。模板里预置好常用的字段和格式，写新项目时直接复制修改，能省下大量时间。

我的模板库里有一个“最小可用规格说明书”模板，只有一页纸，包含项目上下文、功能列表、接口契约三个部分。适合小项目或者快速原型。还有一个“完整规格说明书”模板，包含所有章节，适合中大型项目。

5.2 用示例驱动减少歧义

示例是消除歧义的最好工具。与其花时间解释“用户名不能包含特殊字符”，不如直接给几个合法和非法的示例。AI从示例中学习规则的能力很强，给3-5个示例通常就能让AI理解你的意图。

我在规格说明书里会专门留一个“示例”字段，每个接口、每个数据模型、每条业务规则都尽量配上示例。实测下来，有示例的规格说明书，AI生成代码的准确率能提高15%-20%。

5.3 用检查清单保证完整性

写完规格说明书后，用检查清单过一遍，确保没有遗漏。我的检查清单包含以下项目：

• 项目上下文是否完整（类型、目标、用户、技术栈、约束）
• 功能模块是否覆盖了所有需求
• 每个接口是否有完整的请求和响应定义
• 每个数据模型是否有完整的字段定义
• 业务规则是否全部列出
• 异常处理是否覆盖了输入异常、业务异常、系统异常
• 是否有示例说明
• 是否有版本号和修改记录

这个检查清单看起来简单，但能帮你避免80%的常见遗漏。

5.4 用AI反过来检查规格说明书

这是一个很有意思的技巧：把规格说明书交给AI，让它找出其中的矛盾、遗漏和歧义。AI在这方面其实挺擅长的，因为它没有先入为主的观念，能发现你自己忽略的问题。

我试过让AI检查一份规格说明书，它指出了好几个我没注意到的问题，比如“接口A的响应中包含了用户ID，但接口B的请求中用户ID的类型定义不一致”、“业务规则R003和R007在库存低于10件时的处理逻辑有冲突”。这些问题如果等到代码生成阶段才发现，修改成本会高很多。

5.5 规格说明书的持续维护

规格说明书不是写完就完了，它需要随着项目进展持续维护。每次需求变更、每次接口调整、每次数据模型修改，都要同步更新规格说明书。否则规格说明书很快就会过时，AI基于过时的规格生成的代码也会有问题。

我的做法是把规格说明书纳入版本控制，和代码一起管理。每次代码提交时，检查规格说明书是否需要同步更新。如果规格说明书和代码不一致，以规格说明书为准，因为它是AI生成代码的依据。

6. 一个完整的规格说明书片段示例

6.1 项目上下文示例

字段	内容
项目类型	后端API服务
核心目标	为内部系统提供统一的用户认证和权限校验
目标用户	内部开发人员，通过SDK调用
后端语言	Python 3.11
框架	FastAPI
数据库	PostgreSQL 15
缓存	Redis 7
部署方式	Docker容器，Kubernetes编排
性能要求	单接口P99延迟低于50ms
安全要求	所有接口需要JWT鉴权，敏感操作需要二次验证

6.2 接口契约示例

项目	内容
接口名称	用户登录
路径	/api/v1/auth/login
方法	POST
鉴权	不需要
请求体	{"username": "string, 必填", "password": "string, 必填"}
成功响应	{"code": 0, "message": "登录成功", "data": {"token": "string", "expires_in": 3600, "user_info": {"user_id": "uuid", "username": "string", "role": "string"}}}
失败响应	{"code": 非0, "message": "错误描述", "data": null}
错误码	3001: 用户名或密码错误, 3002: 账号已被锁定, 3003: 账号已被禁用
业务规则	登录成功后刷新Token有效期；连续失败5次锁定账号30分钟

6.3 业务规则示例

• 规则R001：用户连续登录失败5次后，锁定账号30分钟。锁定期间即使密码正确也拒绝登录。30分钟后自动解锁，失败计数清零。
• 规则R002：Token有效期为1小时，每次成功调用接口后自动续期。如果Token过期，需要重新登录。
• 规则R003：管理员角色的用户可以调用所有接口，普通用户只能调用权限范围内的接口。

6.4 异常处理示例

错误码	错误信息	HTTP状态码	客户端处理建议
3001	用户名或密码错误	401	提示用户重新输入
3002	账号已被锁定	423	提示用户稍后重试
3003	账号已被禁用	403	提示用户联系管理员
4001	Token无效或已过期	401	跳转到登录页面
4002	权限不足	403	提示用户无权限
5001	数据库连接失败	500	稍后重试
5002	缓存服务不可用	503	稍后重试

这套规格说明书的写法，我在多个项目中实际使用过。最直观的感受是，前期写文档确实要多花一两个小时，但后期和AI沟通的成本大幅降低。以前可能需要来回十几轮才能让AI生成满意的代码，现在基本两三轮就能搞定。而且因为规格说明书本身就是一份完整的项目文档，后续维护和交接也很方便。

还有一个意外的收获：写规格说明书的过程本身就是在梳理自己的思路。很多时候你以为自己想清楚了，但真正写下来才发现有很多模糊的地方。把这些模糊的地方写清楚，不仅AI受益，你自己的设计能力也在提升。