写代码前先写文档？这才是把AI用对姿势

放假前最后一个工作日下午5点，你鼠标都摸好了，就等着准点开溜。产品经理走过来了："有个小需求，用户列表加个筛选和排序，很简单！老板说客户明天就要看。"你嘴上说着好的，心里已经演完了八百集血压拉满的内心剧。算了，反正看起来也不复杂。

你熟练地打开 Cursor，输入："帮我实现用户列表的筛选和排序功能。"三分钟，真的只用了三分钟，AI哗啦啦吐出两百行代码。你随手点了几个案例，居然都能跑通。那一瞬间，你内心的独白是：爽！这就是我+AI编程的魅力！下班！

然而，放假回来后，新需求来了："加个高级筛选吧。"你信心满满地打开当初那份代码，然后------愣住了。

data1、temp、result2... 这变量名是闭着眼睛取的吗？if-else 层层嵌套，像俄罗斯套娃，改筛选，排序崩了；修排序，分页挂了。你硬着头皮读了一小时，还是没搞懂所有分支逻辑。最后，你咬着牙做了一个决定：这坨代码，不能要了。

推倒重写，花了两天。

3分钟写完的代码，用了2天来偿还。

我们到底被AI偷走了什么？

第一，代码质量简直在开盲盒。

AI生成的代码是能跑，但为啥能跑？不知道。每次生成的结果都像抽卡，变量命名全凭AI心情，架构设计基本靠运气。前期确实爽，像吃外卖------香就完了，谁管后厨干不干净？问题是，技术债这玩意儿，利滚利起来，可比高利贷狠多了。

第二，我们成了"方向盘焦虑患者"。

简单任务全扔给AI，自己只负责Ctrl+C/V；复杂架构也想靠AI，但又不敢完全放手。你在"全权托管"和"亲力亲为"之间反复仰卧起坐，就是找不到那个该接管的瞬间。AI不像工具，倒像个不太靠谱的同事，永远不知道他下一步会挖个什么坑。

第三，我们正在丧失"架构手感"。

你有没有发现？现在接到需求，第一反应已经不是"我该怎么设计"，而是"我去问AI"。就像用惯了导航，没了它你连小区门口的路都认不全。我开始害怕，再这样下去，我们会不会从"工程师"退化成"AI的搬运工"？

那么问题来了：这些困扰，是因为AI不够聪明吗？

恰恰相反。是因为AI太强了，强到我们还没学会怎么和它相处。

记住，你才是那个"定义问题"的人

我们必须想清楚一件事：在AI时代，程序员的真正价值到底是什么？

AI是执行力超群的工具，但它不是决策者。我们能理解业务、判断价值、为结果负责------这才是我们不可替代的部分。所以正确的关系是：我们决定"做什么"和"为什么做"，AI负责"怎么做"。

而不是我们说一句"帮我做个筛选"，AI就自由发挥，我们被动接盘。

这听起来像是常识，但实际情况却是越来越少人这样做。你有没有发现？以前开发至少还会查阅官方文档、原型验证，现在AI一来，直接从模糊需求跳转到代码，"意图走样"得连亲妈都不认识。

根本原因就在于：我们缺了一份明确的"规格说明书"。

你好，Spec-Kit：把"图纸"交给AI

GitHub前不久推出了一个叫Spec-Kit的工具包，我试用后的最大感受是：跟AI结对编程有戏了。

它的理念非常直接：在写代码之前，先把规格说清楚。

就像装修房子，你不会直接跟工人说"帮我装一下"，而是先出设计图、定水电、标材质。Spec-Kit做的就是这件事：它不是要取代AI，而是让AI变得更有用。官方说法是，它能和GitHub Copilot、Cursor、Claude 这些工具无缝配合，让你输入得更准，AI输出得更稳。

Spec-Kit四步工作法，请你记好：

bash 复制代码

1️⃣ /specify ------ 别急着写代码，先说话
   用自然语言说清楚你要什么、边界在哪、未来可能怎么变
   AI 会帮你整理成结构化的规格文档

2️⃣ /plan ------ 让AI出方案，你来拍板
   AI 根据规格生成技术方案：数据模型、设计模式、测试用例...
   记住：你审核，你点头，不是你被动接受

3️⃣ /tasks ------ 拆任务，一步步来
   生成可执行的任务清单，谁做什么、先做啥后做啥，清清楚楚
   推荐 TDD：先写测试，再写实现

4️⃣ /implement ------ 带着镣铐跳舞
   AI 开始写代码，但必须在规格和方案的框架内
   你始终掌握主导权，AI 是执行者，不是设计师

这和vibe coding最大的区别在哪？

Vibe coding是："AI，帮我做个功能。"→ AI随意发挥 → 你祈祷别出bug。

Spec-Kit 是："我先想清楚我要什么。"→ AI按图纸施工 → 你全程监工。

关键在于：谁在定义问题？

一个真实故事：30小时 vs 9小时

来看一个我亲身经历的例子：用户权限管理系统。一开始只要两个角色：管理员和普通用户。但真实世界哪有这么简单？后续一定会迭代。

❌ 使用前：Vibe Coding模式

第一版（2小时）：对AI说"做个用户权限系统"，AI生成了一堆 if (role === 'admin')。测试通过，上线。
第一次迭代（4小时）：要加"审核员"角色。一看代码我傻了，8处硬编码！是该勉强改成 || 'reviewer'，还是重构？战战兢兢改完，生怕漏了一个地方。
第二次迭代（24小时，整整三天！）：产品说要支持"权限组"（一个用户多个角色）。结果发现之前的架构是 user.role（字符串），根本没法扩展成 user.roles（数组）。只能推倒重来。

累计时间：30 小时。心态？每次迭代都想离职。

✅ 使用后：Spec-Kit模式

第一步（2小时）：写规格 + 技术规划

markdown 复制代码

用户权限管理规格：
- 要支持灵活扩展，以后加角色是必然
- 用户可以有多个角色
- 权限检查不能写死，要可插拔
- 注意无权限、权限冲突的情况

AI据此给出方案：User、Role、Permission、UserRole 四张表，多对多关系，用策略模式做权限检查。我审核通过。

第二步（6小时）：按任务列表实现，AI辅助写代码。

初版花了 8 小时，比vibe coding慢 6 小时。

但精彩的来了：

第一次迭代（5分钟）：加"审核员"？在Role表里插一条数据就行，代码一行不用动。
第二次迭代（1小时）：加"权限组"？架构本来就是这样设计的，只需要加一张PermissionGroup表和相关关联。

累计时间：9.1 小时。心态平稳，甚至有点期待下一次需求。

数据不说话，但数据最震耳欲聋：

维度	Vibe Coding	Spec-Kit	差距
初版速度	2h	8h	慢 6h
第一次迭代	4h	0.1h	快 3.9h
第二次迭代	24h（重构）	1h	快 23h
累计时间	30h	9.1h	节省 20.9h
代码质量	债台高筑	架构清爽	天壤之别
我的心态	日常崩溃	从容自信	这才是人过的日子

你看，前期多花6小时，后期省下21小时。什么叫"慢就是快"？这就是。

那三个困扰，是怎么被解决掉的？

关于代码质量：

规格就是最好的蓝图。变量名不再随心所欲，逻辑结构有设计模式指引，边界条件有测试覆盖。AI就像一位严格按菜谱做菜的厨师，出品稳定，绝不翻车。

关于人机协作：

分工从没这么清晰过。我负责定义业务、审核方案、拍板决策；AI负责出方案、写代码、干脏活累活。我是导演，AI是摄影师。戏怎么演，我说了算。

关于架构能力：

不仅没退化，反而被锻炼得更强。因为每次写规格，都在逼我做需求分析；每次审核方案，都在训练我的架构判断；每次考虑扩展，都在培养我的前瞻思维。AI成了我的"架构陪练"，而不是"思考替代器"。

想试试？三步就能开始

▎第一步：安装，五分钟搞定

bash 复制代码

# 用 uv 装（推荐，快）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 或者 pip 也行
pip install git+https://github.com/github/spec-kit.git

装完初始化一下：

bash 复制代码

specify init --here --ai cursor
# 除了 cursor，也支持 claude / chatgpt / copilot

项目里会多一个 specs/ 文件夹，之后所有规格文档都会规规矩矩躺在这里。

▎第二步：从写第一个规格开始

不用追求完美，就像平时和同事沟通那样说人话就行：

bash 复制代码

/specify 我想做个用户筛选，能按注册时间、状态、角色来筛，条件可以组合，要分页。
以后很可能还要加别的筛选维度。

AI会帮你把这段话整理成结构化的规格文档。

▎第三步：让AI出方案，你来审核

输入 /plan，AI会基于规格给出技术方案。注意：这一步你一定要动脑子！ 审核它，挑战它，而不是闭着眼睛通过。

接着用 /tasks 拆解任务，最后用 /implement 让AI在框架内写代码。

我的实战建议：

别一上来就挑战超级复杂的功能，选个中等难度、以后可能会改的。
第一次用，不求完美，感受一下"先设计再编码"的节奏。
有兴趣的话，可以同一个功能用vibe coding和Spec-Kit各做一版，亲自体会一下那个巨大的心理落差。

当然，Spec-Kit不是银弹

下面这些情况，我劝你别用：

❌ 一次性脚本（用完就扔）
❌ 火烧眉毛的紧急修复（没时间给你写文档）
❌ 纯粹的学习实验（方向都不明确）
❌ 简单到几行代码就能搞定的功能

那什么时候该用？我送你三个判断问题：

这功能以后会改吗？→ 会，用。
别人要看懂这代码费劲吗？→ 费劲，用。
出问题了你能快速定位吗？→ 没把握，用。

想象一下，还是那个放假前的下午5点，产品经理还是那句"有个小需求"。

但这一次，你没有急着打开AI就开干。你花了20分钟，写下一段简单的规格：到底要什么？边界在哪？以后可能会怎么变？然后你才把这份"图纸"交给AI，让它出方案，你来审核。

初版是多花了一小时。但两周后产品要加新功能，你只用了十分钟就搞定。更重要的是，你始终握着方向盘，代码没有变成一座你不敢碰的屎山。

AI时代，比的不是谁让AI写代码更快，而是谁能把问题定义得更清楚。

Spec-Kit不是在让你"慢下来"，而是在帮你"想清楚"。而想清楚了再动手，往往是最近的路。

记住，在这场人机协作中，我们，必须是那个定义问题并且最终拍板的人。