AI编程规格说明书：30行配置省五轮返工

为什么你的AI总在返工？

同样用AI写代码，有人一句话就能得到可直接使用的成果，而有人反复沟通六七轮，结果还不如第一版。问题不在AI，而在你给它的那句话。

当你说"帮我做个待办App"，AI需要自己决定至少25件事：要不要筛选功能？数据存哪里？刷新后还在不在？颜色用什么？文件怎么分？这些你没说的，它只能猜。

为什么AI会「猜」你的需求？ 大语言模型的工作原理决定了这一点。当输入信息不完整时，模型会基于训练数据中最常见的模式进行补全——这在统计学上叫做「最大似然估计」。对于「做个待办App」这类请求，模型会默认选择训练语料中出现频率最高的实现方式：白色背景、简单列表、无持久化存储。这不是AI的失误，而是它在信息缺失时的理性选择。猜对算运气，猜错你就得一轮轮返工。

解决方案是：把提示词升级为规格说明书。这不是什么野路子——Google Cloud的AI总监专门撰文阐述了这一方法论，被O'Reilly转载；GitHub官方也为此推出了开源工具SpecKit，上线大半年已有近十万人收藏。

三个案例看差距：模糊提示词 vs 规格说明书

案例一：待办App——外观与功能的天壤之别

用Claude Code做同一个待办App，两种方式的结果截然不同：

模糊版（一句话）："帮我做一个待办事项App。"结果：白底刺眼、没有筛选、没有计数、刷新数据丢失、所有代码塞在一个文件里。能跑，但至少还要改五六轮。

规格版（30行说明）：写清暗色主题、圆角卡片、五个核心功能、数据存本地刷新不丢、代码分成五个文件。结果：跑起来基本就是你要的样子。30行字，省了五六轮返工。

案例二：用户注册——不只是好看，是安全不安全

模糊版"做一个用户注册登录功能"可能埋下三个致命隐患：

1. 密码明文存储：你没说要加密，AI可能把密码原文存进数据库，一旦泄露全部裸奔。行业标准要求使用bcrypt、Argon2或PBKDF2等慢哈希算法对密码进行加盐哈希处理，而非直接存储原文或使用MD5/SHA1等快速哈希——后者早已被证明可在数秒内被彩虹表攻击破解。
2. 错误提示泄露信息：返回"该邮箱不存在"等于告诉攻击者哪些邮箱是真实的，拿去撞库即可。这属于用户枚举攻击（User Enumeration Attack），OWASP（开放式Web应用程序安全项目）将其列为常见安全风险，正确做法是统一返回模糊提示。
3. 没有频率限制：攻击者可以每秒尝试上千个密码，暴力破解毫无阻拦。频率限制（Rate Limiting）是防御暴力破解和撞库攻击的基础防线，通常结合IP封锁和账号锁定机制使用。

规格版则明确写清：密码至少8位含大小写和数字、必须加密存储、登录失败统一提示"邮箱或密码错误"、加上频率限制防攻击。这些漏洞不是AI故意的，是你没告诉它这些事情重要。

案例三：项目级规格——配置一次，管所有对话

前两个案例都是单任务规格。但如果你有一个持续开发的项目，每次都重写一份太累了。解决方案是：写一份项目级规格说明书，配置一次，后面每次对话AI都自动遵守。

以Claude Code为例，在项目根目录放一个claude.md文件，就是个普通文本文件，记事本就能编辑。Claude Code每次开工前会先读它，然后照着里面的规矩做事。

这背后的技术原理值得了解。 LLM没有跨对话的持久记忆，每次对话都从零开始。claude.md通过在每次会话启动时自动注入项目规范，人为构造了一个「持久化上下文」，弥补了模型记忆缺失的天然局限。类似机制在其他AI编程工具中也有体现：Cursor使用.cursorrules文件，GitHub Copilot支持.github/copilot-instructions.md，Windsurf使用.windsurfrules。这一设计模式正在成为AI辅助开发的行业惯例，本质上是将「系统提示词」工程化、版本化、团队共享化。

没有这份文件会怎样？今天你说用TypeScript，明天忘了说，它给你写JavaScript，两种混在一个项目里。你让它新建文件，它丢在根目录，而你的规范是放在组件目录下。文件到处乱放，项目越来越像垃圾场。

六要素框架：规格说明书的标准写法

这套框架来自对GitHub上2500多份AI编程配置文件的分析总结。一份好的规格说明书需要覆盖六个要素：

1. 命令

项目常用的操作命令——怎么启动、怎么打包、怎么检查代码。写清楚后，AI做完一步就知道怎么验证。

2. 测试

用什么测试工具？怎么跑？测试文件放哪？AI改完代码会自动跑测试，确认没搞坏东西。

3. 项目结构

文件放哪个目录？怎么命名？这条一写，AI新建文件就不会乱放。

4. 代码风格

缩进用几个空格、变量怎么命名、注释怎么写。不写的话，你跟AI的代码混在一起，风格不统一，维护成本飙升。

5. Git工作流

提交记录怎么写、分支怎么管。类似文档的历史版本功能，规矩不写清楚它会搞乱。

6. 边界（最重要）

这条最容易被忽略，却最有价值。边界就是告诉AI：哪些事可以直接做，哪些要先问你，哪些绝对不能碰。

边界三档：给AI划出安全区

边界设置分三档，这是整份规格说明书里最核心的设计：

🟢 绿灯——直接做，不用问。 比如跑测试、装依赖、新建文件。风险低，让它放手做，提升效率。

🟡 黄灯——先问我，再做。 比如改数据库结构、删文件、改配置。有一定风险，你想在它动手前先确认。

🔴 红灯——绝对不能做。 比如直接把代码推到线上、删测试文件、改密码配置。不管什么情况，碰都不能碰。

这个机制给AI划了一个安全区：区内随便干，出了区必须向你汇报。既保证了效率，又守住了底线。

三条铁律：写规格说明书的避坑指南

铁律一：精准比全面重要

规格说明书不是越长越好。塞给AI的指令越多，它遵守每一条的概率反而越低。社区经验是：项目级规格控制在100行左右，超过200行AI就开始"选择性遗忘"。

这一现象有其技术根源。研究表明，LLM在处理长上下文时存在「迷失在中间」（Lost in the Middle）效应——位于输入文本中间部分的信息，其被模型有效利用的概率显著低于开头和结尾的内容。斯坦福大学2023年的研究证实，随着上下文长度增加，模型对中间信息的注意力权重会系统性下降。这意味着一份500行的规格文件，其中间300行的指令实际上很可能被模型忽略。「控制在100行内」的社区经验，正是对这一技术限制的实践适配。

关键原则：AI已经会做的事不用写，只写那些你不说它就会猜错的。

铁律二：模块化拆分

别搞一个巨无霸文件。根目录放一份总的，前端目录放前端专用的，后端目录放后端专用的。AI进哪个目录就读哪份，不会被无关信息干扰。

铁律三：每条要求可验证

每条要求都要写成能检查的标准。这一原则与软件工程中的测试驱动开发（TDD）理念高度契合——TDD要求在写代码之前先写测试，本质上是把「成功标准」前置定义。规格说明书中的可验证要求扮演了同样的角色：它为AI提供了一个自检闭环，做完之后能跑测试验证，而不是依赖人工主观判断。当AI输出不符合预期时，你也能精确定位是哪条规格没被遵守，而不是面对一个模糊的「感觉不对」。

判断标准只有一个：AI做完后能不能自己检查有没有达标？

• ❌ "代码质量要好"——这是愿望
• ✅ "改完跑测试全部通过"——这是标准
• ❌ "错误处理要完善"——这是愿望
• ✅ "所有接口返回统一格式，出错用对应状态码"——这是标准

核心理念：你做决定，AI负责执行

从今天开始，记住三句话：

1. 你做决定，AI执行。 不是你提想法，AI替你做决定。
2. 精准的30行指令，比模糊的一句话管用得多。
3. 配一次项目规格，后面每次对话都受益。

实操建议：即使你不是程序员，也可以把规格说明书模板直接丢给AI，说"帮我根据我的项目把这份模板填好"。AI会分析你的项目结构，自动填充内容，你只需审核确认即可。

规格说明书的本质，是把你脑子里那些"理所当然"的要求，变成AI能读懂、能执行、能自检的明确指令。这30行字的投入，换来的是每次对话都不再从零开始的长期收益。

核心要点

• 将模糊的提示词升级为规格说明书，30行配置可省去5-6轮返工，显著提升AI编程效率
• 规格说明书需覆盖六要素：命令、测试、项目结构、代码风格、Git工作流和边界设定
• 边界三档机制（绿灯直接做、黄灯先确认、红灯绝不碰）是规格说明书中最有价值的设计
• 三条铁律：精准比全面重要（控制100行内）、模块化分目录管理、每条要求必须可验证
• 项目级规格文件（如claude.md）可一次配置、长期生效，避免每次对话重复说明需求