AI 写代码老是跑偏?把项目交给它之前,先写这一页"最小规格"

原创2026-10-26 18:20:072,170 阅读
文章标签:人工智能代码智能体IDE代码编辑器开发工具桌面应用前端后端插件系统

AI 写代码老是跑偏?把项目交给它之前,先写这一页"最小规格"

凌晨一点,你跟 AI 说"帮我加个导出按钮"。

它很勤快,十分钟后回复:"已完成。"

你打开改动一看,二十多个文件。按钮是加上了,顺手把你的登录逻辑重写了一遍,把三个你没让它碰的模块也"优化"了。你一边往回退代码,一边冒出一个念头:这活儿我自己写可能还快一点。

这不是你用的模型不够聪明。恰恰相反,是它太能干、太自由了。

最近 JetBrains 开源的 ThinkRail 引起了不少讨论,今日头条上有条评价挺到位:它是给 pi 这个命令行 AI 编程助手"套了个图形界面",而且会先让 AI 看懂项目设计再动手,不容易写跑偏。

而它防跑偏的核心办法,朴素得有点出人意料:在你把项目交给智能体之前,先写一份最小可用的规格。

一、它到底是个啥?先用人话讲明白

你可以把 AI 编程智能体想成一个手艺极好、但刚进场的施工队。

它有劲儿、干得快,问题是它不知道你家承重墙在哪。

你只说"这里开个门",它真敢给你开。不是它想拆你的房子,是它压根不知道那面墙不能动。

ThinkRail 干的事,就是给这个施工队配一套图纸和工地规矩:图放在工地旁边,谁进来干活都先看一眼;墙能不能动、水管归谁管、哪些地方碰了就出事,全写在上面。

这套图纸,它叫 Specs,活规格。

有意思的是,ThinkRail 并不是一个"文档工具"。它是一个完整的 AI 编程工作台:左边是你的项目和工作区,中间是跟 AI 的对话和代码编辑器,右边能看到这次改动的前后对比。你能像用普通编辑器一样读代码、跑终端、审改动,只不过干活的主力换成了 AI。

而这个工作台有一点很特别——它自己就是用这套规格方法建起来的。

我在它的开源仓库里数了一下:这样的规格文档有 近百份,加起来两万多行。一个代码仓库,光"讲清楚这项目是怎么回事"就写了两万多行。

但别急,这不是让你也去写两万字。它的规矩恰恰相反。

二、一份"最小规格"到底该写什么?

先记住一个前提:这份东西不是写给人交差的,是写在 AI 每次开工前能一眼看懂的地方。

真正必要的只有四块。

第一块:这东西是干嘛的,为谁干的

一两句话说清就行。

它是给新手的可视化入口?还是给老手的效率工具?是给自己用,还是准备给别人用?

这一块的作用是给 AI 一个"总方向"。方向不清楚,它就会用自己的想象填空,而它的想象往往比你的需求更宏大。

第二块:边界——它管什么,不管什么

这是四块里最值钱的一块。

在 ThinkRail 的规格模板里,每个模块都必须写清楚两栏:允许依赖什么、禁止碰什么。

翻成装修的话就是:这间屋子归水电工管,但不许动承重结构,不许改邻居家的管道。

ThinkRail 自己的仓库里就有很典型的例子:某个扩展包明确规定"不许引用主项目里的任何代码",理由是——只有这样才能保证它单独拿出去也能跑。

你看,这条规矩一句话,但它能挡住 AI 未来一百次"顺手引用一下"的冲动。

很多人写需求只写"要做什么",从来不写"不许做什么"。而 AI 跑偏,九成跑在后者上。

第三块:不能破的硬规矩

行业里叫"不变量",说白了就是这个项目里永远成立的那几句话。

比如"文件系统才是唯一真相,缓存永远不能当成数据源"、"用户的钱和数据只能走用户自己的账号,我们不留任何密钥"。

这类话有个共同特点:它们不是功能,是底线。功能可以商量,底线一破,整个项目的气质就变了。

写的时候有个小技巧:只写那种"如果被破坏,你会立刻喊停"的规矩。写不出三条,说明你还没想清楚;写了三十条,说明你把偏好当成了原则。

第四块:明确不做什么

这一块最容易被跳过,但特别管用。

因为它能挡住 AI 最典型的"贴心":你让它做个记事本,它给你加上了云同步、账号体系、多人协作和一套主题商店。

写清楚"不做账号、不做云同步、不做移动端",它就老实了。

这里有个很关键的区分:"我们决定不做"和"我们暂时没想到",是两回事。

前者写进"不做什么";后者什么都不用写,它是开放的,不是禁止的。

三、写多细才够?三条线,专治"过期文档"

大部分人不写文档,不是懒,是被坑过:写了没人看,看了也过期,最后变成一堆自欺欺人的废话。

ThinkRail 给规格定的标准只有三个词,我觉得很值得抄。

第一,短。 目标是一口气读完,而不是写全。它明确反对罗列文件清单、反对把代码重新描述一遍——代码本身就摆在那儿,规格只写代码看不出来的东西:为什么这么做、边界在哪、当初否掉了什么方案。

第二,诚实。 这一条最狠:不许写"待补充"当占位符。

没想清楚的部分,就干脆不要有这一节。宁可少一节,也不留一个空壳子假装完整。

还有一条:凡是 AI 自己推断出来、没跟你确认过的内容,必须当场标成"未确认"。而且新写的规格默认是"草稿"状态,只有你本人看过点头,才能转成"生效"——不能由 AI 自己说"我觉得没问题了"就生效。

这个设计很妙。它等于给 AI 加了一条:你可以大胆推断,但你必须承认哪部分是你猜的。

第三,能落地。 标准是:一个未来的智能体(或者一个刚接手的人类)读完,能直接接着干,而不用把结论重新推一遍。

三条合起来,其实是在解决"文档为什么会烂"这个老问题:烂在贪多、烂在装完整、烂在没人维护。

顺带说一个细节,我觉得特别懂行:ThinkRail 明确禁止在规格里写版本路线图——不写 MVP、不写 v1、v2、不写"以后再做的功能清单"。

为什么?因为路线图是计划,规格是现状。计划天天变,规格一跟着变就必然过期。砍掉的功能不写进文档,交回给用户自己去管。

就这一条,能让文档的寿命长好几倍。

四、怎么验证这份规格真的有用?

写完不算完。有个特别简单的对照实验,你今天就能做。

给它一个故意越界的任务。

比如你的规格里明明写着"登录模块不许改动",你就跟 AI 说:"帮我优化一下首页的按钮样式,顺便看看登录那块有没有可以提速的地方。"

然后观察三件事:

第一,它有没有先停下来问你。

在 ThinkRail 的流程里,AI 碰到跟已记录决定冲突的改动,被要求必须先说出来、跟你对一遍,而不是悄悄改了再说。如果它一句"这个模块的规格写着不许动,你确定吗?"——说明规格生效了。

第二,它改完之后,有没有主动更新规格。

这一点很多人忽略,但它是"活规格"和"死文档"的分水岭。

ThinkRail 的规矩是:**代码改了边界、改了决定,规格必须在同一次改动里跟着改。**规格一旦和代码对不上,它就不再是真相,只是一份过时的说明。

换句话说,维护文档这件事,不是留给你周末加班干的,是写进了 AI 的工作流程里的。

第三,它有没有跑去做你没要求的事。

如果它老老实实只动了按钮,还特意告诉你"登录那块我看了,但按规矩没碰"——恭喜,你的项目有护栏了。

反过来,如果它一顿操作猛如虎,那也别急着骂模型。先看看你那份"最小规格"里,是不是根本没写"不许碰"。

顺便说,ThinkRail 里还有个自检工具,专门查规格之间的引用有没有写错、编号有没有重复、上下级关系有没有绕成死循环。这种活儿人干起来烦,机器干正好。

五、这套东西,普通人用得上吗?

先说实话:它不是给完全不懂技术的人准备的。

它要你有 git 仓库,要你会打开终端,也要你自己准备模型账号(它不搞自己的账号体系,模型走你自己的)。目前有 macOS、Windows、Linux 客户端,也有一条命令就能在浏览器里打开的版本,装完打开你的项目文件夹就能开工。

上手门槛大概是"用过 GitHub、被 AI 编程坑过"这个水平。

但反过来说,如果你是这几类人,它可能真能省你不少事:

  • 一个人做副业项目的开发者:没人帮你 review,AI 就是你的同事,但同事需要说明书;
  • 带小团队的负责人:项目一多人就散,规矩写在文档里比写在嘴上牢;
  • 被 AI"改坏过东西"的人:你会格外珍惜"不许碰这里"这五个字;
  • 想学 AI 编程但一直不敢下手的新手:先写规格,反而比直接开干安全。

最后这张图,是它的规格面板。左边是跟 AI 的对话和它改的代码,右边那棵可展开的树,就是这个项目的"规矩目录",点开任何一条就能读。

规格树与规格正文并排显示

值得注意的是:它不是一个巨大的文档,而是一棵树。AI 干活时不用把两万字全读一遍,只读挨着当前这块代码的那一份,需要了再顺着引用往上找。

这一点挺关键——**上下文不是越多越好,是越准越好。**塞给 AI 一堆无关文档,跟塞给它一堆无关代码一样,只会让它更糊涂。

写在最后

这两年我们对 AI 编程的期待,从"它能不能写出来",变成了"它写出来的东西我敢不敢用"。

而这道坎,靠更强的模型未必能跨过去。因为跑偏的本质不是能力不足,是它不知道你的边界在哪——而这个边界,只有你能告诉它。

一份最小规格,说白了就是三句话:这活儿是干什么的、哪些地方不许碰、什么情况下必须停下来问我。

花二十分钟写下来,可能省掉你未来二十个小时的返工。

留个问题给大家聊:**你用 AI 写代码时,遇到过最离谱的"自作主张"是什么?**是顺手重构了半个项目,还是给你加了个没人要的登录页?评论区说说,看看谁家的 AI 最有主见。

登录后查看全文
thinkrail