我实际上是怎么用 AI agent 写软件的
大部分代码交给 Claude Code 后,救我的不是更会写提示词:把家规写成 skills、给 agent 接真系统、把读的活拆给子 agent,审查留给人。
我发布的代码,现在大部分是跟一个 agent(Claude Code)一起写的。早期一直撞上的问题,不是 agent 写的代码差,而是它每次写的代码都不一样——因为每次会话都从零开始,我得在每个提示词里把同一套家规重新解释一遍。
解决它的不是更好的提示词,而是在 agent 外面搭一个小系统:它遵守的规矩、它能触及的系统、活怎么拆、谁审什么。下面是这套东西今天在我机器上的样子。
家规写进 skills
Claude Code 有"skills":一个包含 SKILL.md 的文件夹,当任务匹配它的 description 时,agent 就会加载。凡是我本来要解释两遍的东西,我都用它。现在我有这些技能:我们的 Astro 静态站怎么组织结构、WordPress 上线前检查清单、接手别人 WordPress 站的审计、一份很长的 Figma→Bricks 操作手册、一个 SaaS 脚手架、把表单接到线索收集 API,以及一个可复用页面区块库。
关键在于:skill 不是提示词,它是一份写下来的标准,带着理由,agent 在每个项目上都一样地执行。比如这一段来自上线清单:
Every form gets ONE live test submission (coordinate with the client if it
emails/notifies real staff). Verify: success message, error path (temporarily
break the endpoint or submit invalid), required-field validation, and where the
data lands. A form that "renders fine" is not a tested form.
最后那句在那儿,是因为我发过"渲染正常、但哪儿都没送到"的表单。现在没有一次真实提交,agent 不能说一个站就绪。
SaaS 脚手架的技能更严。每个带登录的新应用都从我自己的多租户底座 fork 出来(Postgres 行级安全、workspace、角色、审计日志),技能里有一份"红旗,停"的清单:
- Writing a `User`, `Organization`, or `Role` model → it exists, fork the base
- "I'll add multi-tenancy later" → later costs 10x; it is free today
- Writing `WHERE workspace_id = ...` in a router → RLS already did it; a manual
filter hides a broken policy
这份清单的存在理由:在底座之前,我的五个应用各自手搓了一套租户隔离。技能里甚至点了它们的名,写着"不要加第六个"。放任不管的 agent,会在头五分钟里欢快地写一个 User 模型;加载了技能之后,它在写任何代码之前就会说:"这是一个应用,所以从 fork 开始。"
写这些技能,我学到两件事。
技能要装文档写错的事实。 线索收集技能里有一张对照表,给出 ingest URL 和鉴权头,紧跟着一句"信这张表,别信仓库文档"——因为项目自己的集成文档写的是过期路径。那是我读后端源码才发现的,我不想再发现一次。
技能应该从真项目里长出来。 Figma→Bricks 手册最初很小,现在超过 6,000 词,几乎全是我在做的时候踩的坑:SVG 导出因为文件头渲染成 300×150、透明 PNG 转 JPEG 变黑、重复的元素 id 导致 500。里面有一行写着:我猜的区块名"在我真去看之前大约 30% 的时候是错的",所以手册现在要求先截图每个区块,再给它命名。项目教会我什么,教训就进技能,下一个项目从那里开始。
现在这些技能只存在于我的机器上。所有东西都定期备份到云,所以丢了这台笔记本我能全部重建,但它们还不在 git 里。把它们和别的在做的项目搬进 git 仓库,是我清单上的下一件事。技能是改变 agent 行为的代码,所以它应该像别的代码一样有历史和评审。
真系统,而不是把上下文粘进对话
第二部分是让 agent 碰到真系统,而不是把上下文粘进聊天窗口。我配了 MCP server:一个 WordPress 管理服务器(能对站点跑 PHP 和 WP-CLI,在沙箱里读写文件)、一个我用来管客户和项目的 CRM,还有家里的 Home Assistant。
这改变了我能交出去的活的种类。在一个 WordPress 站上,agent 在做计划之前就能查真实数据库。审计技能让它:在自定义插件里 grep 硬编码的密钥、把每一处外部 API 调用画出来、检查 blog_public——全部对着正在运行的那套安装做。上线清单会对每一页的 builder 内容跑一条 PHP 查询,找出 # 占位链接。我不需要描述这个站,agent 自己看。
所有动作都过权限提示。agent 写之前要问,技能里也写明它不该自己做的事。比如上线清单说,不要偷偷修对外的东西——重定向、统计、生产的 API key——先跟我确认。
把调研和审计拆给子 agent
调研和审计,我把活摊给子 agent,一个站、一台服务器或一个来源一个。每个子 agent 读自己那一堆文件和日志,只回一个结论,所以我主会话不会被原始输出灌满。
最近一个例子是 which.pk,我给巴基斯坦做的一个消费咨询站,从房产开始。一页可能需要十几个事实:价格、税费、规定、哪个部门管什么。我把它拆给几个 agent:一些做调研,另一些回头拿第二个来源核对每个事实,还有一个去找我们真能用的图。回到我这里的是带来源的事实,核不了的那些会标出来。上不上页面我定。 对一个咨询站来说这就是重点:错的事实比缺的事实更糟。
在我自己的产品上,同一个思路是流程的一部分。RepoCMS 仓库的工作指引写着:非琐碎的工作走 头脑风暴 → 写下来的 spec → 写下来的 plan → 子 agent 执行(每个任务带 spec 与质量评审)→ 跑全套测试 → 每任务一次提交。plan 文件留在仓库里,所以我能在 agent 动手之前,读到它打算做什么。
子 agent 干读的活。我做决定,并把取舍写下来。
审查留给人
Agent 搭骨架、重构、试那些我手工没时间试的替代方案。每一份 diff 我都读。 任何碰到生产、支付或客户数据的东西都要过我,不只是过测试。
技能也在支撑这件事。Figma 手册里有一条"黄金规则:永不轻信,永远核实",它的意思是每做完一个区块,就要在桌面和手机两端截图真实渲染出来的页面——不是攒三个区块再一起看。它还要求 agent 诚实汇报:坏掉的截图、第一次做错的尝试、API 对不上,都写进总结。我宁愿读到"这个第一次没成",也不想自己后来发现。
审查也是关于掌舵,不只是读最终 diff。Agent 会走偏。我有一次问某一页上的一个死链,agent 就开始翻一个五百多页的 sitemap,去检查全站每一条链接。那不是我要的,而且会白白烧时间和 token。我把它停下,指到那一页。看着 agent 在干什么、早点打断,是这份工作的一部分。
我会怎么改
我会更早开始写技能。很长一段时间里,我把规矩留在脑子里和旧项目里,agent 一遍遍重新发现它们。技能的第一版可以只有十行。它只要比再解释一遍强就行。
我们的整理:四层各治什么病
原文的四个动作不是凑出来的架构:提示词管不住的,写进技能;技能看不到全局的,交给接口;接口也看不到全貌的,拆给子 agent;做完这些,改动还是只由人按 diff 放行。每一层都在堵上一层的漏洞。
| 层 | 原文做法 | 治的坏法 | 你可以先做的一步 |
|---|---|---|---|
| 规矩 | 家规写成 SKILL.md,带理由、带"红旗,停"清单 |
每次会话从零开始,同一套规矩重复解释 | 挑一条你解释过两遍的规矩,写成十行 |
| 接口 | 用 MCP 接 WordPress、CRM、Home Assistant | 上下文靠粘,agent 只能照着描述猜 | 挑一个你每天复制粘贴的系统,给它一条只读通道 |
| 拆活 | 一个来源一个子 agent,只回结论 | 原始输出灌满主会话,结论和证据糊在一起 | 把"读"和"决定"分开,读的活外包 |
| 闸门 | 每份 diff 人读,碰生产/支付/客户数据必经人 | agent 搭得快,但没人看得过来 | 写清楚哪几类改动永远不进自动流程 |
三条判据,照抄就能用:
- 一条规矩解释第二遍,就写下来。 判据不是"写得完整",而是"比再解释一遍强",所以十行也成立。
- 技能里最值钱的两段不是流程,是「文档写错的地方」和「红旗,停」。 前者省你重新读源码,后者拦下 agent 头五分钟的"我会自己加多租户"。
- 交给子 agent 的是读,留在自己身上的是决定和取舍。 这条一旦反了,你就在用 token 换自己不看证据。
最便宜的一次改进是那句"渲染正常不等于测试过"。它把一个模糊的"就绪"换成了一个可验证的动作(做一次真实提交、故意打断端点、看数据落在哪)。提示词写不出这个效果,因为提示词说的是"请认真测试",而技能说的是"证据长什么样"。
五条边界
一,这是一手经验帖,没有量化。 全文没有一个"效率提升 X%"的数字,也没有对照组;"大概 30% 的区块名猜错"是他自己的记忆。别把它当研究结论读,把它当一个有真实客户站点在跑的人、现在的工作台长什么样来读。
二,技能机制与 harness 强绑定。 SKILL.md 按 description 匹配加载,是 Claude Code 这套 harness 的实现。换个 harness,同样的内容要重新组织——按「能做什么 / 什么才是真的 / 接下来发生什么」这三层拆,见本站《你的 Agent 并不自主:你就是它的循环》。
三,作者自己承认的缺口最要命:技能只在本机、没进 git。 他在文中一边说"技能是改变 agent 行为的代码",一边承认这些代码没有版本历史、没有评审。这不是小事——一条写错的"红旗"清单会稳定地把 agent 带偏,而且没人能 diff 出是哪天改的。
四,文中的案例数字都是自述。 五个手搓租户的应用、五百多页的 sitemap、"十几个事实的页面",没有外部可核对的来源。这不影响他对机制的解释,但别把这些数字当行业数据引用。
五,"审查留给人"不等于"看懂每一行"。 原文的手法是"每份 diff 我都读"+"碰生产/支付/客户数据必经人",这是粒度问题而不是全能问题:你不需要读懂全部,但你要知道哪里必须停下来自己看。至于人真的读得过来多少,本站《AI 写的代码越多,审查越像盖章》和《Agent 写完的代码没人读过》讲的是这套做法的极限。
想接着看的三处
- 分清"技能"和"提示词"到底差在哪:《系统提示 vs 代理技能》、《智能体 vs 技能》
- 团队级的代码评审怎么排(七层防线):《Claude Code 团队怎么做代码评审》
- 更多 AI 编程与工程化实践:Vibe Coding 技术栈
来源
- Muazzam. How I actually build software with AI agents. dev.to,2026-11-20(原文约 1,350 词,6 分钟阅读)。https://dev.to/muazzami/how-i-actually-build-software-with-ai-agents-2f8m
- 作者主页:https://muazzam.dev
本文由 hubwiz 编译整理,转载请注明出处。
这是「AI 编程 / Vibe Coding」专题的一部分。完整地图见:AI 编程 / Vibe Coding 完全指南