Vibe Coding 札记

一年后的 2026 年 2 月，Karpathy 又为工作中的用法起了另一个名字：“智能体工程（agentic engineering）”——99% 的代码不再自己写，而是指挥智能体去写，自己负责监督。之所以叫“工程”，是因为这里面有技术和专业性。实务中说“Vibe Coding”时，越来越多是指这种用法，本文也按这个意思来写。

为什么需要监督，数据也说明了问题。

AI 已经非常擅长写“能跑的代码”。但“是否符合正确的规格”“是否安全”“是否与之前的决定矛盾”，放任不管就没有保证。系统越大，这个差距越明显。

关键在于读取的时机不同。如果全塞进 AGENTS.md，每次都得全部读一遍，正如上期介绍的研究，效果反而会变差。

工具也逐渐齐备，下面列出有代表性的两个。

名字不同，内容几乎一样：把规格、计划、任务三份文档放进按功能划分的文件夹，每个阶段由人确认。尤其重要的是下面两点。

• 加入让 AI 提问的环节 ── 像 Spec Kit 的 clarify 那样，让 AI 读写到一半的规格，找出“还没定下来的事”。规格的漏洞，越晚发现代价越高
• 规格按功能拆开 ── Kiro 官方也建议不要写一个巨大的规格，而是按“认证”“商品列表”“购物车”等功能分开。每一份越小，AI 和人都越能读完

即使不装工具，手工建好同样结构的文件夹和 Markdown，任何智能体都能按同样方式推进。下一章的布局就是不依赖工具的形式。

举个例子：一个公司内部用的订单管理系统，约 30 个页面，有前端、API 和数据库，采购、销售、财务都会用。仓库这样划分：

放置的原则有五条：

• 每次都读的要薄，需要时才读的可以厚 ── AGENTS.md 只写入口和规矩。细节放进 docs/ 和 specs/，由 AGENTS.md 指明位置
• 规格按功能放进带编号的文件夹 ── 编上 012、013，顺序和历史一目了然，也容易和分支名、PR 对应
• 决定写进 ADR，连同理由 ── “为什么用 PostgreSQL”“为什么用状态迁移来管理审批”。当 AI 想擅自改设计时，它就是依据
• 分领域规则用路径限定 ── API 的规则只在碰 API 时读，不要每次都读
• 同一件事不写两处 ── 规则里引用 docs。复制过去，总有一份会过时

作为入口的 AGENTS.md 大致如下。和上期的例子不同，这里把“没有规格就不做”这种推进方式本身写成了规矩。

各工具的存放位置差异如下：

以给订单系统新增“采购审批流程”为例，从规格走到验证。一共 6 个阶段，其中 3 处由人批准。

STEP 1 写规格（spec.md）

目的和验收条件由人来写，因为了解业务情况的只有人。写好后让 AI 读，并请它“把没定下来的事问出来”。

验收条件要写成可以直接变成测试的样子。不写“要好用”，而写“50 万日元以上就进入待审批”。条件和结果一句对一句，到 STEP 5 时 AI 和人都能判断。

STEP 2 定计划（plan.md 与 ADR）

计划让 AI 写，由人判断。要看的是“有没有破坏现有结构”“是否与已定的事矛盾”。像状态怎么管理这类日后难改的决定，要写进 ADR。

STEP 3 拆任务（tasks.md）

一个任务的大小，要一次对话就能做完，而且做完能确认。诀窍是把写测试的任务放在实现之前。

STEP 4–6 实现・验证・关闭规格

• 实现 ── 按 tasks.md 从上往下一个一个做。一个任务一次提交，出问题时回退点很清楚。大范围的调查（比如梳理影响范围）交给子智能体，不让主对话变乱
• 验证 ── 以“测试・类型・E2E 通过”为完成条件，并在 CI 里必跑。人的评审先对照验收条件，再看差异。权限检查遗漏、XSS 这类安全问题要专门看（如第一章的数据，放任不管就有近一半漏过去）
• 关闭规格 ── 把实现过程中定下来的事（比如不需要代理审批）写回 spec.md，让规格与代码一致后再结束。偏离的规格，会在下一个功能里把 AI 带偏

规则只是“请求”。必须遵守的事，要交给钩子或 CI。Claude Code 官方文档也写道：“写上‘不要编辑 .env’只是请求，不是保证。每次都必须遵守的，就做成钩子。”比如，每次改写文件都跑一次 lint 的钩子如下：

此表参考了 Claude Code 官方“逐步完善配置”的建议。不必一开始就全部备齐。

反过来，也列出三件应当避免的事：

• 让 AI 一口气写出巨大的规格书 ── 读不完的规格，就是没人确认过的规格
• 不读就提交 AI 写的文档 ── 正如上期的研究，原样放入的自动生成指示反而会拉低效果
• 页面上能跑就当完成 ── “能跑”和“正确”“安全”是两回事

工具和名称今后还会变化。这里列出的，是 Spec Kit、Kiro、Claude Code、Cursor 官方文档中共通的思路，整理成了不依赖工具的形式。