AI 编程时代,为什么你需要先写「四个文件」再动手?

多客科技

作者：微信文章
📖 预计阅读时间：14 分钟  |  ⚡ 速读：7 分钟



轻量级规范驱动开发（图片来源：本图片由 🍌 生成）

---

💡 在 AI 编程助手越来越强大的今天，「想清楚再动手」反而变得更重要了。本文介绍一套极简的任务规范方法论，帮你在混乱与过度工程之间找到平衡点。

NANO-SPEC 方法论（图片来源：本图片由 🍌 生成）

Part.01
你是不是也掉进过这个坑？
相信很多开发者都有过这样的经历：拿到 Claude、GPT-5 或 Gemini 这些 AI 编程助手后，兴奋地直接开干。「先写着看看呗」，心里这么想着。

前几轮对话确实很神奇。AI 刷刷地生成函数、组件，甚至整个模块。但接下来呢？需求开始发散，目标逐渐模糊，「等等，咱们到底在做什么来着？」三小时后，你手里有了一堆勉强能跑的代码，但它并没有真正解决最初的问题。

是不是很熟悉？



AI 编程的典型陷阱（图片来源：本图片由 🍌 生成）

---

Part.02
规范驱动的两难困境
解决方案似乎显而易见：先写规范文档。定义需求，设计系统，拆解任务。这正是 Kiro 的规范驱动开发[1]所倡导的，对于复杂功能和企业级项目来说绝对正确。

但问题来了：对于大多数任务，写完整规范的时间比写代码还长。

你打算加一个新的 API 接口，或者做一个简单的仪表盘功能。真的需要写这些吗？

一份 10 页的需求文档

多份设计文档

详细的任务拆解

架构图

等你把这些文档都写完，功能早就能上线了。所以你干脆跳过规范，结果又回到了混乱状态。

一定有个中间地带。

Part.03
nano-spec：刚刚好的结构化方法
nano-spec是一套为现代 AI 辅助开发设计的轻量级任务规范方法论。它提供结构，但不拖慢节奏。

核心理念：4 个简单文档，强制你想清楚，但不会让你淹没在流程里。
tasks/my-feature/
├── README.md # 背景：做什么，为什么做
├── todo.md # 计划：任务与验收标准
├── doc.md # 输出：决策与结论
└── log.md # 过程：每日进展
就这些。四个 Markdown 文件。不需要重型工具，不需要复杂模板，不需要项目管理软件。刚好回答四个关键问题：

我们在做什么，为什么？（README）

怎么判断做完了？（todo）

做了哪些决策？（doc）

一路上学到了什么？（log）

nano-spec 四文档架构（图片来源：本图片由 🍌 生成）

---

Part.04
四个文档详解●README.md：划定边界
在写第一行代码之前，回答这些问题：

背景：为什么有这个任务？我们在解决什么问题？

目标：想达成什么具体成果？

范围：哪些在范围内？更重要的是，哪些在范围外？

依赖：开始之前需要什么？

这不是冗长的需求文档，而是一个强制机制，确保你和 AI 助手对真正要做的事达成共识。

举个例子：
## 背景
用户希望通过聊天界面查询某政策数据，而不是在复杂的数据库表中导航。

## 目标- 支持用自然语言查询某数据库
- 返回结构化、可操作的结果
- 支持常见查询模式（药品覆盖、报销比例）

## 范围### 范围内- 某数据库的文本查询
- 与现有 OpenAI API 集成

### 范围外- 语音输入
- 多轮对话
- 历史政策版本
看到区别了吗？你还没写任何代码，但已经阻止了三个可能让项目跑偏的需求。
●todo.md：知道什么叫「做完了」
这是大多数开发者的软肋：开始做之前没定义什么叫「完成」。todo 文档把工作分成三个阶段：

调研：需要先了解什么？
- [ ] 梳理某数据库 schema
- [ ] 分析现有查询模式
- [ ] 评估 OpenAI function calling 能力
实现：分步骤的任务
- [ ] 创建数据库服务层
- [ ] 实现 OpenAI 函数定义
- [ ] 构建查询解析器
- [ ] 添加错误处理
验证：如何确认成功？
- [ ] 用 10 个样本查询测试
- [ ] 验证响应格式符合规范
- [ ] 检查边缘情况的错误处理
但最重要的是验收标准：
### 必须实现- [ ] 正确处理 80% 的常见查询模式
- [ ] 3 秒内返回结果
- [ ] 优雅处理格式错误的查询

### 最好有- [ ] 根据部分输入提供查询建议
- [ ] 缓存常见查询结果

### 不在范围内- 跨数据库查询
- 历史数据分析
这不只是清单，而是你跟自己签订的关于「交付」意味着什么的契约。



验收标准的三个层级（图片来源：本图片由 🍌 生成）

---

●doc.md：为未来的自己记录决策
在构建过程中，你会做出无数微决策。大多数都会被遗忘。doc.md 捕捉重要的那些：
## 关键决策### 决策：使用 OpenAI function calling 还是 RAG- **考虑的方案**：Function calling、基于 embedding 的 RAG、SQL 生成
- **选择**：Function calling
- **理由**：结构化数据查询需要精确的 SQL，而不是语义搜索。Function calling 让我们能控制查询生成，同时利用 GPT-5 的自然语言理解能力。

### 决策：直接访问数据库还是通过 API 层- **考虑的方案**：直接 TypeORM 查询、REST API、GraphQL
- **选择**：使用 TypeORM 的服务层
- **理由**：让数据库逻辑集中化，更容易测试，为将来暴露 API 做好准备。
六个月后，当有人问「为什么这样设计？」你会有答案。更重要的是，你会记得自己当时的推理过程。
●log.md：记录旅程
开发是混乱的。你会遇到阻塞，发现边缘情况，学到新模式。log.md 用简单的每日条目捕捉这些现实：
## 2025-01-15### 完成- 实现了基础的 OpenAI function 集成
- 创建了某查询的数据库服务

### 进行中- 正在处理查询结果格式化

### 阻塞- 需要确认是否包含已过期的政策（已询问产品团队）

### 备注- 发现 OpenAI function calling 的定义有 4096 token 限制
- 可能需要拆分成多个函数
- 在现有代码库中找到了有用的 TypeORM query builder 模式
这不是官僚主义，而是出声思考。当你和 AI 助手协作时，有这些上下文能让交接变得无缝。只要把最新的 log 条目粘贴到对话里，AI 就能立即理解你的进度。

Part.05
实战案例：某数据集成
让我展示一下这套方法在实际中如何运作。我最近做了一个自然语言查询某数据库的接口。

第 0 天：创建规范（15 分钟）

我创建了四个 nano-spec 文档。README 定义了范围：支持基于聊天的查询，集成 OpenAI，处理常见模式。明确排除：历史数据、多轮对话、语音输入。

todo 文档把工作拆成 12 个具体任务，带有清晰的验收标准：必须处理药品覆盖查询，必须在 3 秒内返回结果，必须优雅处理格式错误的输入。

第 1-3 天：开发

在构建过程中，doc.md 记录了关键决策：为什么选 function calling 而不是 RAG；如何组织数据库服务层；哪些 prompt 工程模式效果最好。

log.md 追踪每日进展和阻塞。当我在 OpenAI 函数定义的 token 限制上碰壁时，我记录了下来。当我发现一个有用的 TypeORM 模式时，我也记录了下来。

第 4 天：交接

产品经理想看进度。我不用手忙脚乱地回忆做了什么，直接分享 doc.md（决策）和 log.md（当前状态）。清晰、简洁、完整。

第 2 周：需求变更

「能加个语音输入吗？」不行，README.md 里明确写了不在范围内。省去了一周的范围蔓延讨论。

第 2 个月：排查 Bug

为什么有些查询失败？查看 doc.md，找到查询解析方案的决策理由，定位到我们遗漏的边缘情况。

维护规范的总开销：每天大概 20 分钟。产生的价值：无法估量。



nano-spec 实战时间线（图片来源：本图片由 🍌 生成）

---

Part.06
理念：文档不是目的
nano-spec不是什么：

不是思考的替代品

不是官僚流程

不是为了写文档而写文档

nano-spec 是一个碰巧会产出文档的思考框架。

真正的价值在于强迫你在写代码之前回答四个问题：

我们到底在做什么？

怎么知道做完了？

关键技术决策是什么？

过程中学到了什么？

如果你不写下来也能回答这些问题，很好。但大多数人做不到。我们的大脑不擅长在思考实现细节的同时，还记住范围边界和验收标准。

四个文档就是外部记忆。它们解放你的大脑，让你专注于解决问题，而不是记住问题是什么。

Part.07
找到平衡点
让我展示一下 nano-spec 的定位：

方法	文档数量	开销	适用场景
无规范	0	零	1 小时内的琐碎任务
nano-spec	4	低	大多数开发任务 ← 你在这里
完整规范	3+ 详细文档	高	复杂功能、企业级项目

「加个新 API 接口」的任务？用 nano-spec。

「做个新仪表盘」的功能？用 nano-spec。

「集成第三方服务」的项目？用 nano-spec。

构建涉及多团队依赖的新微服务架构？你可能需要更重的规范。但对于大多数开发者 80% 的工作来说，nano-spec 就是那个平衡点。



规范方法的光谱定位（图片来源：本图片由 🍌 生成）

---

Part.08
核心原则
四条原则指导 nano-spec：

边界优先

在写代码之前定义什么在范围内、什么在范围外。范围蔓延是交付的敌人。

验收标准

知道什么叫「完成」。「把它做好」不是交付条件。「90% 的查询在 2 秒内响应」才是。

决策留痕

未来的你会忘记为什么做这个选择。现在的你知道。写下来。

进度追踪

记录旅程，而不只是目的地。你遇到的阻塞和找到的解决方案都是宝贵知识。

Part.09
AI 时代，想清楚反而更重要了
AI 编程革命让一件事变得矛盾般地更加重要：思维的清晰度。

手动编码时，不清晰的需求会自然地拖慢你。不知道写什么就没法写代码。这种摩擦虽然烦人，但它强制你想清楚。

有了 AI 助手，你可以在不清晰的情况下生成代码。AI 会乐呵呵地为模糊的 prompt 写出函数、类和模块。感觉很有成效，但你只是在更快地制造技术债。

nano-spec 恢复了这个强制机制。

通过要求你预先定义范围、验收标准和决策，它确保你和 AI 助手在做正确的事。不只是把事情做对，而是做正确的事。

💡关键洞察：AI 越强大，「先想清楚」就越重要。nano-spec 不是要拖慢你，而是确保你和 AI 助手始终在同一个方向上努力。

Part.10
开始使用 nano-spec
入门门槛故意设得很低。三种方式：
●方式一：手动设置（30 秒）
git clone https://github.com/tao-hpu/nano-spec.git

cd nano-spec

cp -r template/ tasks/my-new-task/

编辑四个文件，开干。
●方式二：Claude Code 集成（即时）# 用户级别（所有项目可用）mkdir -p ~/.claude/commands/
cp .claude/commands/nano-spec.md ~/.claude/commands/

# 或项目级别（仅当前项目）mkdir -p /your-project/.claude/commands/
cp .claude/commands/nano-spec.md/your-project/.claude/commands/
然后在 Claude Code 中：

/nano-spec create my-feature "用自然语言描述你要做什么"

Claude 会根据你的描述生成全部四个文档，带有你可以细化的合理默认值。只需要命令文件，不需要 template 文件夹。
●方式三：其他 AI 工具
nano-spec 包含 OpenAI Codex CLI 和 Gemini CLI 的配置。复制相关配置文件即可使用。

Part.11
工作流程：从规范到交付
设置好 nano-spec 后，以下是整个开发周期中的使用方式：
●第一步：创建规范（编码前）

工具	命令
Claude Code	/nano-spec create auth-feature "OAuth2 用户认证功能"
Codex CLI	codex "Create a nano-spec for: OAuth2 用户认证功能"
Gemini CLI	gemini -p "Create a nano-spec for: OAuth2 用户认证功能"
手动	cp -r template/ tasks/auth-feature/ 然后编辑文件

●第二步：开发过程中
让 AI 助手保持同步，随时更新文档：

# 查看当前进度

"读一下 todo.md，告诉我还剩什么没做"

# 记录今日工作

"在 log.md 添加：实现了 OAuth2 回调，token 刷新还有问题"

# 记录决策

"在 doc.md 记录：选择 JWT 而不是 session，因为..."

# 更新任务状态

"把 todo.md 里的'实现登录接口'标记为完成"
●第三步：交接或评审
分享 4 个文件即可提供完整上下文：

# 快速了解状态

"根据 log.md 和 todo.md 总结一下当前进度"

# 新人上手

"读一下 tasks/auth-feature/ 的 4 个文件，解释一下这个项目"

# 范围确认

"有人问能不能加功能 X，看看 README.md 里是否在范围内？"
●常用提示词速查
Claude Code 斜杠命令：

场景	命令
新建任务	/nano-spec create my-task "任务描述"
查看进度	/nano-spec status my-task
更新规范	/nano-spec update my-task "要更新的内容"

自然语言（所有工具通用）：

场景	提示词
更新任务	把 todo.md 里的 [任务] 标记为完成
记录决策	在 doc.md 记录：我们选择 X 而不是 Y，因为...
每日日志	在 log.md 添加今天的记录：[做了什么]
范围问题	[功能] 在这个任务的范围内吗？
交接说明	给新同事总结一下 tasks/[名称]/

三步开始使用 nano-spec（图片来源：本图片由 🍌 生成）

---

Part.12
🇨🇳 发散思考：中国开发者的实践建议
对于国内开发者，nano-spec 可以结合一些本土工具和场景进行优化：

工具选择

如果团队使用飞书或钉钉，可以把四个文档整合到协作文档中

使用国产 AI 助手（如通义灵码、文心快码）时，同样适用

日志可以同步到团队的内部知识库

成本考量

调用国产大模型（如通义千问、DeepSeek）成本更低

对于敏感数据项目，私有化部署的模型更合规

团队协作

在 Code Review 时把 doc.md 作为必看文档

新人接手项目时，四个文档就是最好的上手指南

Part.13
从下一个任务开始
不要试图给整个代码库都加上 nano-spec。从下一个任务开始。一个功能，一个集成，一个 Bug 修复。

创建四个文档。诚实地填写。看看是否有帮助。

我敢打赌你会发现：

范围蔓延减少了

AI 交接更快了

决策追溯更容易了

后期调试更轻松了

如果对你不管用？没关系，你投入的不过是 30 分钟。但我怀疑你会像我一样发现，这种轻量级结构正是 AI 辅助开发所需要的。

Part.14
现在就试试
准备好尝试 nano-spec 了吗？

克隆仓库：git clone https://github.com/tao-hpu/nano-spec.git

把模板复制到你的下一个任务

在写代码之前填写四个文档

看看它是否改变了你的工作方式

模板故意设计得很精简。10 到 15 分钟就能填完。但这 15 分钟会帮你省下数小时的迷失和返工。

因为说到底，最好的代码是解决正确问题的代码。而如果你没定义清楚问题是什么，就没法解决正确的问题。

先想清楚再动手。即使有 AI，尤其是有 AI 的时候。

---

资源链接：

GitHub 仓库：https://github.com/tao-hpu/nano-spec

灵感来源 Kiro 的规范驱动开发：https://kiro.dev/docs/specs/

---

你试过在 AI 助手协作中使用规范驱动开发吗？你是怎么平衡结构和速度的？欢迎在评论区分享你的经验。

参考文献

[1]Kiro Spec-Driven Development:https://kiro.dev/docs/specs/

Part.15
关于作者安涛，悟智科技创始人，美国人工智能硕士。带领团队自主研发悟智AI平台，在智慧城市、司法服务、产业合规等领域服务多个省市级政府部门和央企国企。研究方向聚焦自然语言处理和知识图谱，致力于推动AI技术在政企场景真正落地。

版权所有，转载请联系 hi@fim.ai