规划式开发——AI 时代的工具开发方法论

许愿式开发的陷阱

AI 写代码的能力让很多人产生了一种错觉：好像对着对话框说一句话，工具就自动长出来了。日常画面是：敲一句模糊的需求 → AI 输出一堆代码 → 跑一下发现不对 → 补一句“不对，我是说……” → AI 又输出 → 还是不对 → 陷入循环。

这就是大许愿式开发——把 AI 当许愿池，扔一个愿望进去，等它吐出一个能用的东西。许愿越模糊，返工越多。

AI 把翻译成本归零了，但很多人理解错了这意味着什么。 翻译成本归零 ≠ 不需要思考。恰恰相反——翻译成本归零意味着思考从“怎么实现”解放出来，可以更专注地投入到“规划什么、怎么描述、如何验证”上。思考的总量没减少，它从编码层移到了规划层。

许愿 vs 规划：同一个任务，两种做法

任务：写一个批量重命名文件的工具。

许愿式：

“帮我写一个批量重命名文件的脚本。”

于是 AI 追问语言、规则、平台……你来回补了五轮，拿到一个勉强能跑的版本。时间没比自己写少，只是花在了不同的地方——以前花在查文档和调试上，现在花在和 AI 对齐需求上。但前者至少让你掌握了细节。

规划式：

在打开对话框之前，先用 5-10 分钟把问题想清楚：

1
2
3
4
5
6
7
目标：将目录下的 .jpg 按拍摄日期重命名为 YYYY-MM-DD_HHmmss.jpg输入：目录路径（必填），是否递归（可选，默认否），是否预览（可选，默认是）输出：重命名报告，列出 原名 → 新名，跳过项标注原因（无 EXIF / 目标名冲突）约束：纯 Python 标准库，不依赖 exiftool；冲突加序号后缀而非覆盖；      预览模式只输出不执行；UTF-8 路径兼容验收：给定测试目录，含 EXIF 的 A.jpg → 2024-03-15_142033.jpg，     无 EXIF 的 B.jpg → [跳过: 无EXIF]

这不是 prompt engineering，这是需求拆解和边界枚举。 5-10 分钟的规划，省掉的是后面 5-10 轮对话返工。

为什么工具开发尤其需要规划式

工具开发有三个天然适合规划驱动的特征：

• 输入输出明确。 重命名工具输入路径和规则，输出重命名结果。数据清洗脚本输入脏 CSV，输出干净 CSV。边界清晰，规划不费力。
• 可独立验证。 工具不需要用户行为数据来评判——跑一下就知道对不对。验收标准可以写成可执行的测试用例。
• 上下文可控。 不像产品需要理解整个业务领域，工具开发的上下文是技术性的、可以一次性组织好喂给 AI。

如果说产品开发里 AI 还是一个需要反复对齐的高级实习生，那工具开发里，只要做好了规划，AI 就是一个执行级的中级工程师。 差距就在于有没有那 5-10 分钟的规划。

规划的四个要素

1. 输入输出约定。 不说“帮我做一个日志处理工具”，说——

1
2
3
输入：目录路径，目录下 .log 文件，每行 [时间戳] [级别] [内容]输出：CSV，列 时间 | 级别 | 内容 | 文件名约束：跳过空行，时间戳 → ISO 8601，按时间升序

约定越精确，第一次输出越接近可用。

2. 边界条件。 AI 默认一切正常——文件存在、网络通畅、输入合法。你得自己枚举异常。文件不存在？格式不匹配？目标路径冲突？工具的质量 80% 体现在异常路径上，而异常路径是 AI 的盲区。

3. 技术约束。 指定语言、核心库、代码风格、单文件还是多文件。不是为了限制 AI，是为了自己能维护。AI 用了你没装过的库，和代码结构乱到你不想再看——本质一样，工具脱离了你掌控。

4. 验收标准。 给定输入 X，期望输出 Y。两个作用：AI 在心里跑一遍确认逻辑；你一拿到代码就能验证。

迭代节奏：先骨架，后血肉

规划做好了 ≠ 一次完美。拿到第一版后最致命的错误是在没跑通主路径之前开始改细节。

1. 第一轮： 只跑主路径。正常数据，输出对不对。不对就改规划，不碰代码。
2. 第二轮： 跑边界。脏数据、空文件、大文件，看行为是否符合预期。
3. 第三轮： 读代码。检查逻辑、安全、资源、隐藏假设。
4. 第四轮： 打磨体验。错误信息是否友好、有没有最小可运行示例。

自己改代码还是改规划让 AI 重来？ 逻辑层面（边界条件、分支行为）→ 改规划，重新生成。体验层面（文案、格式、颜色）→ 自己上手更快。

审查清单

• 命令注入和路径遍历： AI 特别喜欢 os.system(f"rm -rf {user_input}")。和 shell、文件系统交互的代码，逐字审。
• 错误处理： AI 要么吞异常 pass，要么不处理让它崩。两者都不对。
• 资源泄漏： 文件句柄、数据库连接、子进程。正常路径通常 OK，异常路径盯紧。
• 隐藏假设： 默认 UTF-8、默认文件不撑爆内存、默认本地时区。不查，生产环境替你查。
• 可维护性： 函数名和做的事对得上吗？关键逻辑有注释吗？有没有魔数？

反向测试：把文档喂给 AI

规划式开发的一个副产品是清晰的输入输出契约和验收标准，这些天然适合写成文档。有了文档，可以做一个测试——

把工具的 README 和帮助信息喂给 AI，让它试着用这个工具完成任务。 如果 AI 理解不了怎么用，说明文档不行。如果 AI 输出的命令和预期不一致，说明接口有歧义。

这放在两年前是脑洞，放在今天是实用建议：AI Agent 正在成为工具调用的新通道。你的工具不仅要对人友好，还要对 AI Agent 友好。 而规划式开发天然兼容这一点——你的输入输出契约，本身就是一个 AI Agent 的 tool description schema。

总结

翻译成本归零不意味着思考归零。它意味着思考从编码层移到了规划层。 认识到这一点，AI 才真正从一个时灵时不灵的许愿池，变成稳定可预期的工具。