Context Engineering on Kalend's Blog

从Vibe Coding到Agentic Engineering：2026开发者该升级的方法论

Tue, 28 Jul 2026 10:00:00 +0800

一、引子：Karpathy 的"落后感"

2026 年 4 月，红杉资本 AI Ascent 大会。

Andrei Karpathy 站在台上，说了一句让全场安静下来的话：

「我从没觉得自己如此落后过。」

14 个月前，正是他给一种编程方式起了名字——Vibe Coding。当时原话是「完全沉浸在氛围中，忘记代码，只管 accept」。那条推文引爆了整个开发者圈，所有人都在说：编程的门槛消失了。

14 个月后，同一个人站出来说：这套方法论，终结了。

不是 Vibe Coding 没用，而是它不够了。

Karpathy 用了个新词——Agentic Engineering。

从 Vibe Coding 到 Agentic Engineering，中间到底发生了什么？为什么连发明者自己都在升级方法论？

这篇文章拆解这个进化过程。三阶段、五大支柱、一份你现在就能用的落地清单。

二、Vibe Coding 是什么？为什么它曾经很香

先回顾一下定义。

2025 年 2 月，Karpathy 描述了这种工作方式：

1

prompt → accept → run → ship

你跟 AI 说「帮我写个登录页」，它吐出代码，你看一眼觉得行，accept，运行，部署。全程不仔细看代码细节，沉浸在「氛围」里。

这有错吗？没有。

它的本质是 floor-raising——提升下限。 以前不会编程的人，现在能造出原型。以前需要一周的功能，现在一天搞定。

Google 2026 年 5 月发布的《The New SDLC With Vibe Coding》白皮书给了数据：85% 的专业开发者在用 AI 编程智能体，51% 每天用，预估 41% 的新代码由 AI 生成。

不是少数极客在玩，是主流在用。

Vibe Coding 最香的场景：

场景	为什么适合	举例
原型开发	快速验证想法，质量要求低	Hackathon、内部 demo
个人项目	自己用，bug 自己修	个人工具、脚本
已知模式的模板代码	AI 擅长重复模式	CRUD、API 接口、配置文件
学习新技术栈	边生成边学，比看文档快	新框架上手

一个有意思的发现是：生产力提升最大的团队，不是那些让 AI 写所有代码的团队，而是知道「什么时候该用 Vibe Coding、什么时候不该」的团队。

关键词是「知道什么时候用」。

这就是天花板的起点。

三、天花板在哪？三个致命问题

Vibe Coding 的问题不是「不好用」，而是「用多了会出事」。

三个致命缺陷，一个比一个隐蔽。

问题一：没有 evals——你不知道 AI 产出的质量

你让 AI 写了一段代码，运行通过了。好。

但是：

边界条件覆盖了吗？
并发场景处理了吗？
安全漏洞有没有？
性能合不合格？

不知道。因为没有评估机制。

「能跑」和「质量达标」之间隔着一道鸿沟。 Vibe Coding 的默认状态是：跑通就算完成。这在原型阶段没问题，在生产环境是灾难。

问题二：没有 observability——agent 跑偏了你不知道

当你把越来越多的工作交给 AI，一个新问题出现了：你看不见它在干什么。

它改了哪些文件？为什么选这个方案而不是那个？中间做了几次重试？哪一步卡住了？

如果你不知道这些，你就是在盲开。

问题三：安全和可维护性无人负责

AI 生成的代码，谁对安全负责？

AI 生成的代码，三个月后谁来维护？

这两个问题在 Vibe Coding 的范式里没有答案。 因为 Vibe Coding 的核心动作是「accept」——接受产出，不做深度审查。安全和可维护性恰恰需要深度审查。

数据说话

一个普遍现象是：大多数团队能看到 agent 在干什么（observability），但只有一半左右的团队在系统性地评估产出质量（evals）。

这个差距就是 Vibe Coding 到 Agentic Engineering 的鸿沟。

能看见，但不能控制。能产出，但不能保证质量。

四、Agentic Engineering——Karpathy 的新范式

什么是 Agentic Engineering？

Karpathy 的核心定义是两个词：ceiling-preserving（保护上限）。

Vibe Coding 是 floor-raising——让更多人能参与。

Agentic Engineering 是 ceiling-preserving——确保质量不滑坡。

具体来说：

「我 99% 的时间不再直接写代码，而是在指挥智能体干活。但作为人类，我对最终质量负全责。」

关键词是「负全责」。

不是让 AI 随便搞。是工程化地管理 AI 写代码的过程。

三大支柱

Agentic Engineering 不是一个工具、一个框架，而是一套方法论。核心由三大支柱支撑：

支柱一：Spec（规范）

告诉 agent「做什么」和「不做什么」。这不是写 prompt，是写工程规格书。

具体形式就是 AGENTS.md、SOUL.md 这类规范文件——项目架构、编码规范、测试要求、禁止操作，全部写清楚。（怎么写，我在上一篇AGENTS.md 指南里详细拆过。）

支柱二：Evals（评估）

系统性地衡量 AI 产出的质量。不是「看起来行就行」，是「过了评估才算完成」。

可以是自动化测试，可以是 checklist，可以是 code review 流程——形式不重要，有没有才重要。

最简单的 eval：写一个 checklist，AI 每次产出后逐条打勾。

检查项	通过
功能符合需求	✅/❌
错误处理完整	✅/❌
无安全隐患	✅/❌
有测试覆盖	✅/❌
代码风格一致	✅/❌

5 条，5 分钟，但能把 80% 的问题拦在合并前。

支柱三：Observability（可观测性）

看得见 agent 在干什么。日志、trace、审计——知道每一步的输入输出，知道为什么做了这个选择。

不是为了监控，是为了事后复盘。出了问题能追溯，做得好能复用。

一张表看清区别

维度	Vibe Coding	Agentic Engineering
核心理念	提升下限（floor-raising）	保护上限（ceiling-preserving）
人的角色	accepter——接受产出	owner——对质量负责
代码审查	可选，甚至跳过	必须，有流程
产出质量	靠运气	靠工程
适用场景	原型、个人项目	生产环境、团队协作
核心动作	prompt → accept	spec → execute → evaluate → ship

五、三阶段进化全景

回头看，AI 编程方法论经历了三个清晰的阶段。

第一阶段：Vibe Coding（2025.02 —）

关键词：氛围编程，快但不可控。

Karpathy 定义，社区狂热。prompt → accept → ship。门槛降到地板，质量也跟着降到地板。

这一阶段的贡献是巨大的——它证明了 AI 可以写代码，而且写得还不错。它让整个行业开始认真对待 AI 编程。

但它也暴露了一个根本问题：快不等于对。

第二阶段：Context Coding / Harness Engineering（2025.06 —）

关键词：AGENTS.md + 规范约束，让 AI 在框架内工作。

2025 年中，社区开始使用 Context Engineering 这个概念，强调给 AI 提供完整的上下文而非简单 prompt。开发者开始写规范文件、定义规则、约束 AI 的行为边界。从「给 AI 一句话」变成「给 AI 一套规则」。

这一阶段的核心贡献是：把 AI 从「自由发挥」拉回到「有规矩地干活」。

我在之前的AGENTS.md 深度指南中详细拆过这一阶段的方法论。简单说：花 30 分钟写好规范文件，比花三天对比工具强十倍。

但 Context Coding 也有天花板：它管住了单个 AI 的行为，但管不住多个 AI 的协作，也没有系统性的质量验证机制。

第三阶段：Agentic Engineering（2026.04 —）

关键词：多 agent 协调 + evals + observability。

Karpathy 在 AI Ascent 大会上正式提出。不只是「给 AI 规则」，而是「工程化管理整个 AI 工作流」。

多个 agent 并行工作，人类定义目标和质量标准，evals 验证产出，observability 监控过程。

类比

阶段	类比	核心动作
Vibe Coding	手工作坊——一个人从头干到尾	accept
Context Coding	流水线——标准化流程	constrain
Agentic Engineering	智能工厂——多条线并行，人管质量	orchestrate

从「一个人干活」到「标准化流程」到「多条线并行」。

你现在在哪个阶段？大多数人停在 1.0 或 2.0。

六、你现在该怎么做？五条实操建议

不是理论，是现在就能做的事。

1. 不要抛弃 Vibe Coding，升级它

Vibe Coding 不是垃圾，是地基。

原型开发、学习新技术、探索性编码——这些场景仍然适用。问题不是 Vibe Coding 本身，而是把它当终点。

正确姿势：用 Vibe Coding 快速产出，然后用工程化手段验证。

2. 给你的 AI 工具加 evals

哪怕最简单的 checklist。

每次 AI 产出后，花 5 分钟逐条检查：

功能是否符合需求？
错误处理是否完整？
是否有安全隐患？
是否有测试覆盖？
代码风格是否一致？

不要觉得「看起来行就行」。「看起来」是最不靠谱的质量标准。

3. 学会写 AGENTS.md

Context Engineering 是 2026 年的必修课。

不管用什么工具——Claude Code、Cursor、Codex、Gemini CLI——底层逻辑都一样：AI 的产出质量，70% 取决于你给了它什么上下文。

30 分钟写一个 AGENTS.md，效果比换三个工具强十倍。不知道怎么写？参考 Codex CLI 的官方仓库——GitHub 超过 10 万 Star，它的 AGENTS.md 就是范本。

4. 建立 agent 可观测性

不需要复杂的基础设施。

最简单的方式：让 AI 在工作时输出日志——做了什么、为什么这么做、遇到了什么问题。

进阶方式：用专门的可观测性工具，记录每个 agent 的执行路径、决策过程、耗时分布。

能看到，才能改进。看不到，只能祈祷。

5. 从单 agent 到多 agent 协作

这是 2026 年真正拉开差距的地方。

一个人指挥一个 AI，是 Context Coding。

一个人指挥多个 AI 各司其职，是 Agentic Engineering。

具体怎么做：

1
2
3
4
5


一个 agent 负责写代码
一个 agent 负责 review
一个 agent 负责测试
一个 agent 负责部署
人类负责定义目标和验收标准

不需要一开始就搭完整的 pipeline。从「写代码 + review」两个角色开始，逐步扩展。

七、结论：地基之上，才是上层建筑

Vibe Coding 不是终结，是起点。

它证明了 AI 可以写代码，让整个行业开始认真对待 AI 编程。但「能写」和「写得好」之间，隔着 Agentic Engineering。

2026 年，「会用 AI」不够了。

要「会工程化管理 AI」。

三个核心转变：

1
2
3


从 accept 一切 → 只 accept 过了 eval 的
从看不到过程 → 每一步可观测
从单打独斗 → 多 agent 协作

Karpathy 说「从没觉得自己如此落后过」，然后用 14 个月定义了一套新方法论。

你呢？

不需要 14 个月。从今天开始做三件事：

写一个 AGENTS.md（30 分钟）
加一个 5 条 checklist 的 eval（5 分钟）
让 AI 输出工作日志（1 分钟）

36 分钟，你就能从 Vibe Coding 1.0 迈进 Agentic Engineering 的大门。

数据来源：Addy Osmani (Google)《The New Software Lifecycle》(2026.5)、Karpathy 红杉资本 AI Ascent 演讲(2026.4)

关注「varkm」，一起学习，一起成长。

Claude Code、Codex、OpenCode、ZCode 四款AI编程Agent怎么选：工具是方法论的载体

Sat, 11 Jul 2026 08:00:00 +0800

Claude Code 对应 Context Engineering 阶段，Codex 对应安全工程阶段，OpenCode 对应自由探索阶段，ZCode 对应可视化协作阶段。四款工具不是同一赛道的四匹马，而是四个方法论阶段的代表作。选工具之前，先搞清楚你想停在哪个阶段。

为什么"选工具=选阶段"

Vibe Coding → Context Coding → Agentic Engineering，这是 AI 编程方法论的三阶进化。我在之前的文章里详细拆过这三个阶段的演进逻辑，这里只说核心：每个阶段对"人机协作的信任边界"定义完全不同。

Vibe Coding 阶段，你把 AI 当高级自动补全，写一行说一行。Context Coding 阶段，你给 AI 写一份"施工图纸"，让它按图执行。Agentic Engineering 阶段，你给 AI 一个目标和约束，让它自己规划路径。

四款工具的设计哲学，恰好对应这四个坐标点。

Claude Code：Context Engineering 的代表作

Claude Code 的核心设计哲学是"先规划后执行"。

CLAUDE.md 文件是它的核心。在项目根目录放一个 CLAUDE.md，写清楚项目架构、编码规范、关键约束，Claude Code 在每次对话开始时自动加载。这不是一个配置文件，这是一份"工程合同"——你和 AI 之间的权责边界白纸黑字写在上面。

Permission mode 是另一个关键设计。开启 plan-first 模式后，Claude Code 在做多文件重构之前会先输出一份 Plan 文档，你审批通过后才动手。这不是多余的步骤，这是 Context Engineering 的核心：让 AI 先把思路亮出来，人类确认方向正确再执行。

Headless 模式支持无人值守，配合 Git worktrees 可以让 Claude Code 在独立分支上干活，不影响你的主分支。MCP 协议集成让它能连接外部工具链。

模型方面，Opus 4.8 是目前推理能力最强的编码模型，适合架构级决策。Sonnet 5 更快，适合日常编码。上下文策略是激进压缩——保留用户消息不动，压缩模型自己的历史输出。

定价：Pro $20/月，Max $200/月，或 API 按量付费。

适合场景：大型项目重构、架构级修改、需要深度推理的多文件协同变更。如果你的项目超过 5 万行代码，Claude Code 的 Context Engineering 能力是四款里最强的。

Codex CLI：安全优先的工程实践

Codex CLI 的设计哲学是"不信任但验证"。

三级审批模式是它的核心卖点。suggest 模式只给建议不改文件，auto-edit 模式可以自动修改代码但不执行命令，full-auto 才是完全自主执行。这三级模式不是可选的装饰，而是默认的安全策略。你不需要记住哪些操作需要审批，沙箱自动帮你隔离风险。

--ask-for-approval 参数控制审批粒度。你可以设置"修改文件前必须确认"，也可以设置"只在执行危险命令时确认"。粒度完全由你控制。

并行 Agent 能力是 Codex 的另一个优势。你可以同时启动多个 Agent 处理不同任务，它们各自在独立沙箱里运行，互不干扰。

模型方面，GPT-5.6 是 OpenAI 最新发布的模型家族，针对编码场景有专门优化。上下文策略是"用户消息一字不动，模型自己的全部可压"——和 Claude Code 的激进压缩有微妙但重要的区别。

定价包含在 ChatGPT Plus/Pro 订阅中，或 API 按量付费。CLI 本身开源。

适合场景：安全敏感的企业环境、需要并行执行多个编码任务、已经在 OpenAI 生态里的团队。

OpenCode：最大自由度的开源方案

OpenCode 的设计哲学是"你的模型，你的规则"。

BYOK（Bring Your Own Key）支持 75+ 个 LLM 提供商。你可以接 OpenAI、Anthropic、Google，也可以接国产模型——DeepSeek、Qwen、GLM 都行。这意味着你可以用同一个工具，在不同项目里用不同模型，成本完全可控。

它自带 Zen 模型精选，是社区维护的"针对编程优化过的模型推荐列表"。不知道选什么模型的时候，Zen 列表是个不错的起点。

Subagent 架构支持子代理并行。隐私优先设计保证数据不离开本地。桌面版目前在 Beta 阶段，降低了 CLI 的使用门槛。

上下文管理采用"可逆隐藏"策略——历史对话不会被真正删除，理论上可以恢复。这在需要回溯 AI 决策过程时很有价值。

180K+ GitHub Stars 说明社区认可度。免费开源，模型费用自付。接国产模型的话，日常编码成本可以压到接近零。

适合场景：预算敏感、想用国产模型、隐私优先、中等规模项目（1-2 万行）。但要注意：项目超过 5 万行或有复杂跨模块依赖时，OpenCode 的 orchestration 层不如 Claude Code 流畅。

ZCode 3.0：可视化的国产方案

ZCode 3.0 的设计哲学是"把开发流程塞进桌面应用"。

它是四款里唯一的桌面 ADE（Agentic Development Environment）。不想用 CLI？不想配环境变量？打开桌面应用就能开始写代码。这个定位对非终端用户非常友好。

GLM-5.2 是智谱自研的旗舰模型，1M 上下文窗口。作为原生适配的模型，ZCode 对 GLM-5.2 的调用效率和效果优化是其他工具接 API 做不到的。

多 Agent 协作和技能系统（Skills）是 ZCode 的差异化特性。需求理解 → 计划拆解 → 代码修改 → 验证，全流程在可视化界面里完成。

定价：首次 5 天免费，每天 300 万 token，之后走 GLM Coding Plan 订阅。

适合场景：不想用 CLI 的开发者、中文场景、想免费体验国产最强编程模型。

方法论适配度对比

维度	Claude Code	Codex CLI	OpenCode	ZCode
安全模型	Permission mode 审批制	三级审批模式隔离	本地优先不外传	桌面隔离
上下文策略	激进压缩，保留用户消息	保留用户消息，压缩模型输出	可逆隐藏，历史可恢复	桌面界面管理
模型灵活度	仅 Claude 系列	仅 GPT 系列	75+ 提供商自由切换	仅 GLM 系列
交互形态	终端优先	终端 + VSCode	终端 + 桌面(Beta) + IDE	桌面 ADE
并行能力	Headless + worktrees	并行 Agent	Subagent 架构	多 Agent 协作
学习曲线	中（需写 CLAUDE.md）	低	中	低（可视化）
开源	否	CLI 开源	完全开源	否
中文优化	一般	一般	一般	原生支持

决策树：四条路径，选哪条

你重视安全隔离吗？ 在企业环境里写代码，或者处理敏感数据，需要沙箱级别的权限隔离 → 选 Codex CLI。

你重视推理深度吗？ 项目规模大、架构复杂、需要 AI 先理解全局再动手，愿意花时间写 CLAUDE.md → 选 Claude Code。

你重视模型自由度和预算吗？ 想在不同项目里用不同模型，或者想接国产模型把成本压到接近零，项目规模中等 → 选 OpenCode。

你不想用 CLI / 要中文优化吗？ 不想配环境、不想记命令、想要可视化界面、中文场景优先 → 选 ZCode。

如果以上四条你都犹豫，说明你还在 Vibe Coding 阶段——用什么都行，先用起来再说。等你写够 5000 行 AI 辅助代码之后，自然知道自己需要什么。

结论

没有"最好的工具"，只有"最适合你阶段的工具"。Claude Code 的 CLAUDE.md 是工程纪律，Codex 的沙箱是安全底线，OpenCode 的 BYOK 是自由选择，ZCode 的可视化是降低门槛。这四款工具更新很快，但方法论的演进方向不会变：从"我说你做"到"你理解我的意图自己做"。

varkm

AI编程不是一句话搞定：任务拆解的粒度艺术

Fri, 10 Jul 2026 10:00:00 +0800

我见过太多人（包括我自己）踩同一个坑：把一个大需求直接丢给 AI，期待它一口气交付完整功能。

结果呢？前半段看起来不错，后半段开始离谱。你 accept 了前 200 行代码，到第 300 行发现逻辑对不上，回头一看——第一步的数据结构就埋了雷，后面全是连锁反应。

结论先说：AI 编程的核心技能不是 prompt 写得多好，而是任务拆得多细。

一、为什么"一句话搞定"是最大的陷阱

先说一个反直觉的事实：上下文窗口越大，你越容易高估 AI 的能力。

2026 年主流模型的上下文窗口已经到了 200K tokens，理论上能装下一个中型项目的全部代码。但问题是——能装下不等于能理解。模型在处理长上下文时，注意力会稀释。你丢进去 10 个文件让它同时改，它可能只精确处理了前 3 个，后面 7 个在"凭印象"写代码。

这引出一个核心概念：幻觉半径。任务越复杂，模型的"合理猜测"范围越大，犯错概率指数级增长。一个小功能的幻觉半径可能只有 2-3 行代码，一个完整模块的幻觉半径能覆盖整个文件。

更致命的是错误累积效应。第一步的数据类型选错，第五步的 API 就对不上，第十步的 UI 就要推倒重来。这不是 AI 笨——你让一个聪明人同时处理 10 个相互依赖的任务，他也会犯错。

类比一下：你不会让实习生第一天就独立交付整个支付模块。你会先让他改个按钮颜色，再写个工具函数，逐步加码。AI 编程也一样——不是因为它不聪明，而是因为复杂任务的本质就需要分步验证。

二、任务拆解的三层粒度模型

拆解不是随便切，有一个实用的分层框架：

层级	名称	时间粒度	例子
L1	功能级	10-30 分钟	“实现用户登录”
L2	步骤级	5-15 分钟	“创建登录表单组件”
L3	指令级	1-5 分钟	“在 LoginForm.tsx 中添加邮箱验证”

最佳实践：从 L1 开始规划，用 L3 实际执行。

什么意思？你在脑子里或文档里先拆出 L1 功能清单——“登录"是一个 L1，“评论系统"是一个 L1。然后每个 L1 拆成 3-5 个 L2 步骤。真正交给 AI 执行的是 L3：一个具体的、明确的、可以在几分钟内验证的小指令。

为什么要这样？因为每个 L3 指令都是一个可验证的检查点。做完了，跑一下，看看对不对。对了继续，错了立刻修。这比一口气做完 10 个功能再回头 debug 效率高一个数量级。

三、五种拆解策略

拆解有章法可循，不是凭感觉切。以下是五种我反复验证过的策略：

按文件拆

每个文件一次修改。不要让 AI 同时动 10 个文件——它会顾此失彼，改了 A 忘了 B 的 import 路径。

实操技巧：先问 AI “这个功能涉及哪些文件？"，然后一个一个来。

按层次拆

先数据层 → 再逻辑层 → 最后 UI 层。这是经典的分层架构思路，但很多人在 AI 编程时忘了它。

为什么要分层？因为数据模型是地基。你先让 AI 写 UI，回头发现数据结构不对，UI 就得全改。反过来，数据模型定好了，API 和 UI 怎么改都不伤根基。

按依赖拆

画一下依赖图，先实现被依赖的模块。工具函数比业务逻辑先写，公共组件比页面组件先写。

一个简单判断法：如果模块 A 的测试需要模块 B 的存在，那 B 就该先做。

按风险拆

高风险部分（支付、认证、数据迁移）单独审查，低风险部分（样式、文案、配置）可以批量处理。

这不是歧视低风险代码，而是把有限的审查精力集中在最可能出问题的地方。

按测试拆

每个拆分点都是一个可测试的里程碑。如果一个子任务你写不出测试用例，说明它太大了，需要继续拆。

1
2


好拆分：实现用户注册 API → 可以写测试验证返回 201 和正确的 user 对象
坏拆分：实现整个用户系统 → 测试用例写不出来，因为不知道从哪验证起

四、审查机制设计

拆解是骨架，审查是免疫系统。没有审查的拆解，只是把一个大错误切成了十个小错误。

Checkpoint 审查

每完成一个子任务，停下来 review。不需要逐行看代码，重点检查：

接口是否符合预期（输入输出类型对不对）
边界情况有没有处理
和上一步的衔接是否顺畅

自动验证

让 AI 自己跑测试、lint、类型检查。这是最高效的审查方式——不需要人肉看，机器告诉你对不对。

1
2
3


Prompt 示例：
"写完这个函数后，自己跑一下 pytest，确保所有测试通过。
如果有 lint 警告，也一并修复。"

回滚机制

git commit 要频繁。每完成一个 L3 指令就 commit 一次。这样出错时能精确回退到上一个正确的状态，而不是 git stash 整个进度。

渐进信任

这是核心原则：

阶段	信任级别	操作方式
小任务（L3）	Agent 自主	不审查，看结果
中任务（L2）	轻度审查	自动验证 + 快速扫一眼
大任务（L1）	人工审查	逐个 checkpoint 检查
关键任务	人工参与	每步确认再继续

信任是挣来的，不是给的。先让 AI 在小任务上证明自己，再逐步放权。

五、实战案例——一个真实功能的拆解过程

需求：“给博客系统加一个评论功能。”

这句话看起来简单，实际涉及至少 6 个独立模块。如果一把丢给 AI，大概率翻车。拆开看：

L1 拆解（6 个功能）：

1

① 数据模型 → ② API 端点 → ③ 前端组件 → ④ 前后端连接 → ⑤ 样式交互 → ⑥ 测试

L2/L3 拆解（以"数据模型"为例）：

1
2
3
4
5
6
7


L2-1: 定义 Comment schema（字段、类型、约束）
L2-2: 创建数据库迁移文件
L2-3: 写基础 CRUD 方法

L3-1: 在 schema 中添加 content: text, author: string, post_id: integer, created_at: timestamp
L3-2: 运行 migration，验证表创建成功
L3-3: 实现 create 方法，写一个测试验证能插入数据

关键点：每一步都是独立的、可验证的、可回滚的。

L3-1 做完，跑类型检查，确认 schema 没语法错误
L3-2 做完，查数据库，确认表结构正确
L3-3 做完，跑测试，确认 CRUD 正常

任何一步出错，只回退那一步，不影响其他部分。这就是拆解的价值——把不可逆的大失败变成可逆的小失败。

六、不同工具的拆解差异

不同工具对拆解粒度的要求不同：

工具	适合粒度	原因	注意事项
Cursor	L2-L3	Agent 模式可自动执行多步，但文件级操作仍需控制	单次改动不超过 3 个文件
Claude Code	L1-L2	长上下文能力强，可以一次处理更大范围	但仍需 checkpoint，不能盲目信任
OpenCode/Codex CLI	L2-L3	沙箱隔离，适合高风险操作的独立审查	适合"先在沙箱里试，确认后再合并”

通用原则：工具越强，粒度可以越粗，但不能不拆。

即使是最强的模型，面对"帮我重写整个认证系统"这种指令，也大概率会遗漏边界情况。能力上限不等于可靠性上限。

七、常见反模式

最后列四个我见过最多的反模式，每个都是血泪教训：

“一口气全做完”——丢一个大需求，期望一次交付。这是最常见也最致命的。你以为省了时间，实际在后面付出了 3 倍的 debug 时间。

“过度拆解”——拆到每行代码一个指令。走到另一个极端，效率为零。L3 是底线，再细就该自己写了。

“只拆不审”——拆了 10 个步骤，一口气全执行完，中间不检查。拆解的意义在于验证，不检查等于没拆。

“盲目信任”——AI 说"测试全通过"就信了。实际上它可能只跑了它自己写的测试，而那些测试恰好跳过了真正的 bug。验证要独立于被验证的对象。

写在最后

AI 编程的真正门槛不是 prompt engineering，是工程思维。

能用 AI 写代码的人越来越多，但能把 AI 编程用好的人——任务拆得清、审查做得实、质量守得住——依然是少数。

任务拆解听起来像管理话题，和技术无关。但做过大型项目的人都知道：最难的从来不是写代码，是决定先写什么、后写什么、什么不写。

AI 改变的是编码速度，没有改变软件工程的基本规律。小步快跑、持续验证、快速回滚——这些原则在 AI 时代比任何时候都重要。

varkm

写好 AGENTS.md，比选对 AI 编程工具重要 10 倍

Mon, 06 Jul 2026 08:00:00 +0800

先给结论

你花了三天对比 Codex CLI、Cursor、Claude Code、Gemini CLI，最后选了"最强"的那个。结果同一个需求，你同事用"最弱"的工具，产出质量甩你一条街。

区别不在工具。区别在他项目根目录有个 AGENTS.md，你没有。

我自己的项目，加了 AGENTS.md 之后，代码风格一致性问题基本消失，重构时的"误删"从每周两三次降到几乎为零。不是因为工具变强了，是因为工具终于知道我的项目长什么样。

工具只是载体，上下文才是底层逻辑

2023 年大家研究 Prompt Engineering——怎么把一句话写好。2025 年中 Shopify CEO Tobi Lütke 把概念推进到 Context Engineering——不是写好一句话，而是给工具建好一整个信息环境。到 2026 年，又有人提出 Harness Engineering，把上下文、架构约束、垃圾回收三层打包。

不管叫什么，核心逻辑没变：AI 编程工具的产出质量，70% 取决于你给了它什么上下文，20% 取决于工具本身的能力，10% 是运气。

很多人在 70% 的地方偷懒，却在 20% 的地方疯狂内卷——天天比哪个工具更强，却不肯花 30 分钟写个项目说明文件。

Karpathy 2025 年 2 月提出 Vibe Coding，意思是在氛围里沉浸编码，不仔细看生成的代码。到了 2026 年 4 月他自己承认"从没觉得自己这么落后过"。Vibe Coding 的前提是你对项目足够了解，能一眼看出问题。但如果你连项目规范都没写下来，你看不出问题，工具也猜不到规范。

AGENTS.md 是什么

一句话：项目根目录下的一个 Markdown 文件，告诉 AI 编程工具"这个项目怎么干活"。

它由 OpenAI Codex CLI 推动成为开放标准。Codex CLI 在 GitHub 上 9.5 万 Star，Gemini CLI 10.5 万——这两个最火的终端编程工具，都认这个文件。

各工具的上下文文件格式对比：

工具	配置文件	绑定工具	AGENTS.md 兼容
Codex CLI	AGENTS.md	否（标准本身）	原生支持
Cursor	.cursorrules / .cursor/rules	是	部分
Claude Code	CLAUDE.md	是	部分
Copilot	.github/copilot-instructions.md	是	部分
Gemini CLI	GEMINI.md	是	部分

问题很明显：如果你用 Cursor 写了 .cursorrules，切到 Claude Code 就得重写一遍。但如果用 AGENTS.md，一个文件适配所有——因为它是跨工具标准，其他工具要么原生支持，要么通过简单适配兼容。

怎么写：7 个核心 Section

OpenAI Codex 自己仓库的 AGENTS.md 是最好的范本（Codex CLI GitHub 9.5 万 Star）。我拆解了它的结构，提炼出 7 个核心 section：

1. 项目架构

告诉工具：这是什么项目、用了什么技术栈、核心模块在哪。不需要长篇大论，三五行足够。

1
2
3
4
5


## 项目结构
- 后端：Go + Gin，代码在 cmd/server/
- 前端：Next.js，代码在 web/
- 数据库：PostgreSQL，迁移文件在 migrations/
- 单体仓库，不要把前后端拆成独立项目

2. 编码规范

代码风格、命名约定、格式化工具。这一条直接决定生成代码的一致性。

1
2
3
4
5


## 编码规范
- Go 代码必须经过 gofmt 格式化
- 变量命名用驼峰，不用下划线
- 错误处理必须显式检查，不要忽略 err
- 提交前运行 golangci-lint

3. 测试要求

什么场景必须写测试、测试怎么跑、覆盖率要求。这是防止工具"自信地写出没有测试的代码"的关键。

1
2
3
4
5


## 测试
- 新增 API 必须有集成测试
- 运行测试：make test
- 不要用 --all-features，会增加构建时间
- 修改数据库逻辑后必须跑 migration 测试

4. 禁止操作

明确红线。不说工具就会"好心办坏事"——删文件、改配置、动数据库 schema。

1
2
3
4
5


## 禁止操作
- 不要修改 migrations/ 下已有文件，只新增
- 不要动 .env.example，它是模板
- 不要自动删除"看起来没用"的代码
- 不要升级 go.mod 里的依赖版本

5. 目录结构

比"项目架构"更细——哪些目录放什么，入口在哪。

1
2
3
4
5


## 目录约定
- cmd/ 放可执行入口，一个目录一个命令
- internal/ 放不对外暴露的业务逻辑
- pkg/ 放可被外部引用的库代码
- 测试文件和源文件放一起，不单独建 tests/ 目录

6. 部署流程

工具如果知道怎么部署，就能帮你验证改动是否打破构建。不知道就只能盲写。

1
2
3
4
5


## 部署
- 构建：docker build -t app .
- 测试：make test && make lint
- 部署前必须确认构建通过
- Dockerfile 不要用 latest 标签

7. 角色分工（多 Agent 场景）

这是进阶用法。当多个工具/角色协作时，不同角色读不同 section，减少上下文噪音。

1
2
3
4
5


## 角色
- 后端开发：读 internal/ 相关 section，关注 API 设计
- 前端开发：读 web/ 相关 section，关注组件和样式
- 测试工程师：读测试 section，关注覆盖率和集成测试
- 运维：读部署 section，关注 Dockerfile 和 CI 配置

有 vs 没有的差距

这不是玄学。同一个需求，有没有 AGENTS.md，产出质量差距肉眼可见：

维度	没有 AGENTS.md	有 AGENTS.md
代码风格	随机风格，每次生成不一样	符合项目既有规范
错误处理	忽略错误返回值，或用过度防御	遵循项目约定
重构安全性	经常误删"看起来没用"的代码	知道哪些不能碰
测试覆盖	写完功能不写测试，或写无意义测试	按项目要求补测试
上下文一致	每次对话重新解释项目背景	一劳永逸

我自己踩过最大的坑：工具"好心"帮我删了一段它认为没用的兼容代码，结果线上老接口全挂了。加了一条"不要自动删除任何看起来没用的代码"到 AGENTS.md 后，再没发生过。

常见错误

错误 1：写得像产品文档

AGENTS.md 不是给人看的 README，是给工具看的操作手册。别写"我们是一个创新驱动的敏捷团队"——写"后端用 Go，测试用 make test"。

错误 2：什么都往里塞

文件太长，工具反而抓不住重点。控制在 100 行以内，只放"不写就会出事"的规则。

错误 3：写完不更新

项目演进后规范变了，AGENTS.md 还停留在三个月前。规则：每次工具产出不符合预期时，第一反应不是换工具，而是检查 AGENTS.md 有没有覆盖这个场景。

错误 4：只放规范不放禁止操作

人记住"不能做什么"比记住"要做什么"更有效，工具也一样。禁止操作的优先级高于编码规范。

进阶：多角色协作

当项目复杂到一个 AGENTS.md 不够用时，可以利用工具的层级读取机制：

1
2
3
4
5
6
7
8


项目根目录/
├── AGENTS.md # 全局规范
├── backend/
│ └── AGENTS.md # 后端特定规范
├── frontend/
│ └── AGENTS.md # 前端特定规范
└── ops/
 └── AGENTS.md # 运维特定规范

这样不同角色进入不同目录时，只读到和自己相关的上下文。后端开发不会被前端配置干扰，运维不会被业务逻辑干扰。

这也是 Harness Engineering 的核心思想：上下文不仅要注入，还要清理。让工具在每个时刻只看到它需要的信息，而不是把整个项目扔给它。

结论

选工具是在选载体，写 AGENTS.md 是在设计信息环境。

载体可以换，环境设计的思路是通用的。今天最强的工具，半年后可能被超越；但你花时间搞清楚的 Context Engineering 方法论——怎么拆解项目规范、怎么定义禁止边界、怎么让工具理解你的上下文——这些不会过时。

先写好 AGENTS.md，再纠结用哪个工具。

如果还没有，这里有个最小可用模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# AGENTS.md

## 项目
（一句话描述项目）

## 目录结构
（核心目录及含义）

## 编码规范
（3-5 条最重要的规则）

## 测试
（怎么跑测试，什么时候必须写）

## 禁止操作
（3-5 条红线）

## 部署
（构建和验证命令）

30 分钟写完，受益远超你换三次工具。