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

发表于 更新于 分类于 本文字数： 4k 阅读时长 ≈ 4 分钟
本文探讨AI时代程序员如何正确与AI协作，提出Spec-Kit工作法——在写代码前先写规格说明文档。文章指出AI编程的三大痛点：代码质量开盲盒、方向盘焦虑、丧失架构手感，并提出正确的关系应该是人决定做什么和为什么做，AI负责怎么做。通过文档先行的方式，让人回归定义问题的核心角色，避免技术债积累。

AI 时代，程序员如何与 AI 相处：Spec-Kit 工作法详解

放假前最后一个工作日下午 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 四步工作法，你可以保存下来：

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 小时）：写规格 + 技术规划
1
2
3
4
5
用户权限管理规格：
- 要支持灵活扩展，以后加角色是必然
- 用户可以有多个角色
- 权限检查不能写死，要可插拔
- 注意无权限、权限冲突的情况

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
代码质量 债台高筑 架构清爽 天壤之别
我的心态 日常崩溃 从容自信 找回 coding 的乐趣

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

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

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

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

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

迫不及待了？三步就能搞定

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

1
2
3
4
5
# 用 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

装完初始化一下：

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

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

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

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

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

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

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

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

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

我的实战建议：

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

当然，Spec-Kit 不是银弹

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

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

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

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

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

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

初版是多花了一小时。但后期产品要加新功能，你只用了十分钟就搞定。更重要的是，你始终对此项目心中有数，代码没有变成一座你不敢碰的屎山。

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

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

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