用技能文档固定 AI 编程交付标准
作者将反复向 Claude Code 解释的项目规则沉淀为 SKILL.md,覆盖站点结构、上线检查和常见集成任务。实践重点是通过规则、系统访问、任务拆分与审核安排,减少不同会话间的实现偏差。
AI 深度解读
Agent 写代码最让人头疼的,未必是写错,而是同一类任务每次换一种做法,项目规矩也得反复交代。作者使用 Claude Code 后,逐渐把工作重心转向四件事:固化规则、连接真实系统、拆分调查任务,以及持续审查。
他的结论是:稳定交付靠的是围绕 Agent 建立工作流程。这套做法值得参考,但文章提供的是个人项目经验,没有效率对照实验。哪些能直接借用,哪些依赖作者自己的技术底座,需要分开看。
反复交代的规矩,应该变成什么
Claude Code 的 skill 是包含 SKILL.md 的文件夹,任务匹配描述时,Agent 会加载相应说明。作者把需要重复解释的要求写进去,包括 Astro 站点结构、WordPress 上线检查、Figma-to-Bricks 实施步骤和 SaaS 起步规范。
关键不只是保存指令,还要写清验收条件和背后的原因。
下面这段要求解决的是「表单看起来正常,数据却没送到」的问题:
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.
要看最后一句:渲染正常不能算测试通过。前面还要求执行一次真实提交,检查成功提示、错误路径、必填校验和数据去向;如果会通知真实员工,需要先协调。
作者的 SaaS 规范更强:带登录的新应用必须从自己的多租户底座 fork,沿用 Postgres 行级安全(RLS)、工作空间、角色和审计日志。下面的清单用于阻止 Agent 重造已有能力:
- 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
第三条需要结合上下文理解:作者已经用 RLS 实现租户隔离,路由层补过滤可能掩盖策略失效。它不能直接推广成所有项目都该删除手工过滤。第二条的 10x 也是规范中的经验判断,文章没有成本测量。
这些规则来自实际踩坑。作者此前已有 5 个应用分别手写租户逻辑,因此明确要求不要再造第 6 套;否则 Agent 可能在前 5 分钟就开始创建 User 模型。
Figma-to-Bricks 手册也从小文件长到超过 6,000 词:SVG 因文件头而显示为 300×150,透明 PNG 转 JPEG 后变黑,重复元素 id 导致 500,都被写成检查项。作者估算,没看截图就猜区块名称,约 30% 会猜错,于是流程变成先截图再命名。
规则最有价值的来源,是已经发生过、下次还可能重演的错误。
接入真实系统,才能减少凭描述做决定
作者通过 MCP 给 Agent 接入 WordPress 管理服务、客户与项目 CRM,以及 Home Assistant。MCP 在这里承担的是工具连接:让 Agent 查询或操作实际系统。
WordPress 管理服务支持运行 PHP、WP-CLI,并在沙箱里读写文件。Agent 可以先看真实数据库,再制定计划。审计规范要求搜索自定义插件中的硬编码密钥、梳理外部 API 调用、检查 blog_public;上线检查则通过 PHP 查询各页面的构建器内容,寻找仍然指向 # 的占位链接。
这类检查的收益很具体:减少用户描述与实际安装状态之间的偏差。
但实际系统也可能和文档冲突。作者发现 lead-capture API 的集成文档路径过时,于是阅读后端源码,把正确的 ingest URL 和认证头写进 skill,并要求优先采用这张表。原文没有给出具体地址或认证字段,不能据此直接配置接口。
他的权限边界也很明确:写入前询问;重定向、分析统计、生产 API 密钥等对外生效的配置,不能悄悄修复,必须先确认。接入能力和授予自主修改权,是两个独立决定。
子 Agent 负责调查,人负责范围和取舍
作者把研究、审计按站点、服务器或资料来源拆给子 Agent,让它们阅读各自的文件与日志,再回传结论,避免主会话堆满原始输出。
例如,他正在建设面向巴基斯坦消费者的 which.pk,先从房产内容做起。一页可能需要十来项价格、费用、规则和机构职责信息。他让部分 Agent 调查,另一些用第二来源核实,再安排 Agent 寻找可用图片。回传结果保留来源,无法确认的事实会标记出来,最终由作者决定是否刊登。
这套分工的重点是交付可核查的信息,而不是用多个 Agent 的一致意见替代证据。
在 RepoCMS 中,非简单任务还有完整顺序:讨论方案、书面规格、书面计划、子 Agent 执行、逐任务检查规格与质量、运行完整测试套件,最后每个任务单独提交。计划文件留在仓库里,作者可以提前审查。
人工检查贯穿执行过程。作者阅读每个 diff,生产、支付和客户数据相关变更都要经过他。页面每完成一个区块,就检查桌面端和移动端截图,不等 3 个区块做完再一起看;失败截图、首次尝试错误、API 不匹配也必须如实汇报。
还要防止任务自行扩大。作者只要求检查一个页面的坏链接,Agent 却开始遍历超过 500 页的 sitemap。他及时叫停,把范围拉回单页。审查因此也包括观察正在做什么,而非只看最终代码。
我的判断
我认同这套流程把「做完」变成可检查条件:表单要验证数据落点,页面要看真实渲染,调查要保留来源。这些要求比「认真检查一下」更容易执行,也更容易追责。
但 skill 能约束行为,不能保证 Agent 每次都遵守。权限限制、测试和人工审查仍然需要独立存在。作者没有提供采用前后的缺陷率、耗时或 token 成本对照,因此还不能证明这套方法能给一般团队带来多少收益。
复用多租户底座也有前提:底座适合当前产品,而且 RLS 已正确配置并经过验证。「以后加多租户贵 10 倍」不能替代具体架构判断。子 Agent 同样会增加协调与复核工作,单页小修未必值得拆分。
相比不断扩写单次提示,skill 更适合稳定、重复的项目规范;相比让 Agent 自由探索,预先写计划更适合边界复杂的任务。两者都不宜变成机械仪式。
还有一个尚未补齐的环节:作者的 skills 当时只在本机,虽有定期云备份,却尚未进入 git。备份能恢复文件,版本历史与评审才能说明规则为什么改变。尤其是「以此表为准」的接口信息,也需要防止再次过期。
能拿来做什么
- 从最近一次真实返工开始,写一份约 10 行的 skill,说明触发条件、操作要求和验收证据。前端表单可以直接采用作者的检查思路,覆盖真实提交、错误路径、必填校验和数据落点。
- 给日常 AI 编程任务写清范围与完成条件,例如指定单个页面和需要验证的行为。执行中发现 Agent 扩展到全站扫描,就及时纠正。
- 只有任务包含相互独立的大量阅读时,再拆给子 Agent,并要求返回结论、来源和未确认项;最终决定仍由负责人作出。
- 把会影响 Agent 行为的规范纳入 git。接口信息保留核验依据,涉及生产、支付、客户数据的变更设置人工审查边界。