Addy Osmani（Google Chrome 工程团队）开源了一套东西，叫 agent-skills。24 个结构化的编码技能，专门给 AI 编程 Agent 用的。它名义上是写给 AI 的操作手册，但我越读越觉得——这东西真正该看的，是每一个在写代码的人。

---

一、看上去是Agnet编码说明书，实际上是工程心法

1.1 这到底是个什么东西 —— 一套"操作手册"，二十年工程经验

agent-skills 是一个开源项目。24 个 Skill，每个是一份 SKILL.md 文件，覆盖软件开发的六个阶段：Define（定义）、Plan（规划）、Build（构建）、Verify（验证）、Review（审查）、Ship（发布）。

它的直接用途是给 Claude Code、Cursor、Gemini CLI 这类 AI 编程工具加载——Agent 识别到你在做某个阶段的事，自动加载对应的 Skill，然后按 Skill 里写好的步骤来执行。

但这不是重点。重点是这些 Skill 里写的东西。

1.2 为什么值得读 —— 原则不是贴在墙上的，是嵌在工作流里的

市面上讲"软件工程最佳实践"的文章很多。大部分是这样写的：告诉你一个原则，解释一下为什么重要。你读完觉得有道理但是没有真正落地的方法和标准。agent-skills 的做法完全不同。它不是"告诉你一个道理"，而是把道理变成步骤。以想法精炼（idea-refine）为例——大多数人拿到一个想法，直接就打开编辑器开始写代码了。但这个 Skill 说：等一下。它不会只说"先想清楚再动手"。它会写：

1. 写下原始想法——你现在脑子里那个模糊的东西，落成文字
2. 用至少三种不同的视角重新审视它：反过来看（Inversion）、去掉限制看（Constraint Removal）、放大十倍看（10x Thinking）
3. 生成 5-8 个变体提案，每个不超过三句话
4. 用同一组标准对每个变体打分：可行性、影响范围、与目标的契合度
5. 挑出最好的那个，同时明确列出"这次不做什么"——因为聚焦的本质，是对好想法说不
6. 产出最终提案：一句话定位 + 核心功能列表 + 明确边界

这不是建议，这是一份工作流。AI 读到它，会逐条执行。人读到它，会知道"先想清楚"这四个字到底意味着做哪些动作。

1.3 读完能获得什么 —— 重新理解"什么叫好的软件工程"

如果你是一个写代码的人，读完这套 Skill 你能得到三样东西。

第一，一套工程纪律的操作系统。 每个 Skill 告诉你"这个阶段应该做什么"、“为什么不能跳过”、“跳过会怎样”、“怎么验证你做完了”。这不是知识，是判断框架。下次你再听到脑子里的声音说"我先跳过测试，等下补"——你会有明确的反驳语言。

第二，一套跨越技术栈的通用原则。 Vertical Slices 不管前端后端，Beyonce Rule 不管用什么测试框架，Code as Liability 不管什么语言。你在 React 里学到的东西，在 Go 里照样用。

第三，一套你可以直接用的格式。 你团队里缺代码审查流程？code-review-and-quality 的五轴审查可以直接抄。你项目没有发布检查清单？shipping-and-launch 的 pre-launch checklist 可以直接抄。这不是教科书，是模板库。

---

二、一个Skill的六层骨架是怎样搭起来的

在展开 24 个 Skill 的全景之前，有必要先看懂一份 Skill 长什么样。

2.1 六段结构 —— 从"何时触发"到"什么才算做完"

每个 SKILL.md 由六层构成，每一层有明确的职责：

层级	回答的问题	内容	设计意图
Frontmatter	什么时候该用它？	name+description含触发条件	Agent 根据任务描述自动匹配
Overview	这个 Skill 管什么？	一到两句话，说清目的和价值	快速判断"我来对地方了吗"
When to Use	什么场景适用？	正向触发条件 + 反向排除场景	知道什么时候不用和什么时候用
Process	具体怎么做？	分步骤的工作流	核心流程步骤动作、判断、产出物
Rationalizations + Red Flags	为什么不能跳过？	反借口表 + 违规信号清单	预判偷懒的念头
Verification	做完了怎么证明？	一份逐项打勾的证据清单	"Seems right"不算。每种证据对应一个勾

2.2 五个原则 —— 不是参考文档，是工作流引擎

整套 Skill 的设计哲学可以归结为五条原则，用于更结构化的描述内容：

原则	一句话	核心主张
Process over prose	流程胜于散文	不是参考文档，是可逐步刷写的任务清单
Anti-rationalization	反自我合理化	预判所有借口，在你开口之前写好反驳（见下一节）
Verification is non-negotiable	验证不可商量	"Seems right"不算做完，证据清单逐项打勾才算
Progressive disclosure	渐进式披露	主文件只放核心流程，参考材料按需加载
Token-conscious	珍惜上下文	每一段都必须挣得自己的存在权，删掉不影响行为就删

2.3 反借口表 —— 偷懒的念头还没冒出来，反驳已经写好了

每个 Skill 都内置了一张这样的表格，这个设计狠在：它在你开口之前，就把反驳写好了。

借口	现实
“这段代码能跑，别动它”	能跑但读不懂的代码，出问题的时候也改不动。
“我之后再补测试”	你不会的。事后补的测试测的是实现，不是行为。
“没人会利用这个漏洞”	自动化扫描器会找到它。模糊安全不是安全。
“周五下午了，先上线吧”	周五下午的部署冲动，是整个项目里被明确列出的红线。
“没人依赖那个未文档化的行为”	Hyrum’s Law：只要可观察，就有人依赖。不需要文档，它就是事实契约。

---

三、24份Skill，铺成一张完整的编码工程地图

3.1 三层架构 —— 做法、视角、时机，各归各的

agent-skills 不是 24 个 Skill 的平铺。它有三层，这东西本身就是一堂微型的系统架构课——分层、接口、职责、信息的汇合点。

层级	管什么	一个例子
Skills	怎么做——把一件事拆成步骤、检查点、退出标准	test-driven-development 不会只说"要写测试"，它会写 Red→Green→Refactor 三步循环，每步有可验证的动作
Personas	谁来做——给同一个流程叠加不同的视角和标准	code-reviewer 以 Staff Engineer 的尺度看代码；security-auditor 以攻击者视角看同一份代码。同一份 Skill，不同的判断框架
Commands	什么时候做——按开发阶段激活对应的 Skill 和 Persona	/ship 同时启动三个 Persona 并行审查，最后合并成一份 go/no-go 报告

3.2 一张地图 —— 六个阶段，24个节点

24 个 Skill 按六个阶段铺开。每个 Skill 回答两个问题：什么时候用它？它做什么？

阶段	Skill	什么时候用
Define	interview-me —— 需求访谈	需求模糊，不确定用户到底要什么
	idea-refine —— 想法精炼	有一个模糊概念，需要具体化
	spec-driven-development —— 规格驱动开发	启动新项目、新功能、重大变更
Plan	planning-and-task-breakdown —— 规划与任务拆解	spec 写好了，需要变成可执行的任务
Build	incremental-implementation —— 增量实现	改动涉及多个文件，一次写不完
	test-driven-development —— 测试驱动开发	写逻辑、修 Bug、改已有行为
	context-engineering —— 上下文工程	切换任务时、Agent 输出质量下降时
	source-driven-development —— 源码驱动开发	用不熟悉的框架或库
	doubt-driven-development —— 质疑驱动开发	高风险决策（生产环境、安全、不可逆）
	frontend-ui-engineering —— 前端界面工程	构建或修改用户界面
	api-and-interface-design —— API与接口设计	设计 API、模块边界、公共接口
Verify	browser-testing-with-devtools —— 浏览器DevTools测试	前端调试、确认 UI 行为
	debugging-and-error-recovery —— 调试与错误恢复	测试挂了、构建坏了、行为不符合预期
Review	code-review-and-quality —— 代码审查与质量	合并前审查任何变更
	code-simplification —— 代码简化	代码能跑但读起来费劲
	security-and-hardening —— 安全加固	处理用户输入、认证、数据存储
	performance-optimization —— 性能优化	有性能指标或怀疑存在退化
Ship	git-workflow-and-versioning —— Git工作流与版本管理	任何时候（每次代码变更）
	ci-cd-and-automation —— CI/CD与自动化	搭建或修改构建/部署流水线
	deprecation-and-migration —— 弃用与迁移	移除旧系统、API、功能
	documentation-and-adrs —— 文档与架构决策记录	做架构决策、改 API、发布功能
	observability-and-instrumentation —— 可观测性与仪表化	加遥测、准备上生产
	shipping-and-launch —— 发布与上线	准备部署到生产环境
Meta	using-agent-skills —— 技能调度（元技能）	开始会话、判断该用哪个 Skill

3.3 六条铁律 —— 贯穿所有 Skill 的核心行为准则

using-agent-skills 这份元技能里定义了一组规则。不管你在哪个阶段、在用什么 Skill，这些规则永远在线：

#	规则	一句话	为什么不可妥协
1	Surface Assumptions	暴露假设，不要默默填空	沉默的假设是最贵的Bug。两周后集成时返工成本十倍
2	Manage Confusion Actively	遇到不一致，停下来不要猜	主动叫停比默默选一个然后赌对了更便宜。赌错了呢？
3	Push Back When Warranted	不做yes man反对要说出来	诚实的技术反对比虚假的一致更有价值。
4	Enforce Simplicity	能100行搞定不要写1000行	能更短吗？值得这个复杂度吗？专家会怎么看？
5	Maintain Scope Discipline	做手术刀而不是装修队	不要加 spec 外的功能因为"好像有用"。
6	Verify, Don’t Assume	"看起来对"不算做完	每个Skill都有验证步骤。没有证据 = 没做完

你可能会跳过某个 Skill，但你逃不掉这六条所描述的那些失败模式——默默假设、混淆装懂、一味迎合、过度设计、顺手大改、自我安慰。

---

四、按阶段挑重点

4.1 Define —— 先定义问题，再解决它

Define 阶段三个 Skill 构成一条流水线：先挖出真实意图 → 再生成和评估方案 → 最后锁定成白纸黑字的 Spec。

interview-me —— 意图挖掘沟通

1）什么时候用？ 需求缺了关键信息：不知道为谁做、为什么做、成功长什么样。

2）为什么用？ 发现"你以为的"和"用户实际要的"之间差距的最低成本的纠正时刻。

3）核心过程：
步骤 1：提出假设，附带置信度数字。用一句话写下你当前对用户需求的最佳解读，加上一个诚实的置信度数字（0-100%）。
信心低于70%必须写明原因，什么导致你猜测不准；如果你写下了一个高数字但实际上无法预测用户对你接下来要问的三个问题的反应，那这个数字就是错的。
步骤 2：一次问一个问题，每个问题附带猜测。用户仔细思考的精力是有限的，等待用户反应后再问下一个问题。
步骤 3：聆听"想要 vs 应该想要"。最危险回答是用户说出了听起来应该是什么样的而不是他们真正想要什么。
与人云亦云的最佳实践（可扩展、干净架构、健壮）但没有具体细节；遵从惯例的回答（大多数应用的做法）

当你听到这些时，要问的问题是：如果你不需要向任何人解释你的选择，你真正想要的是什么？

步骤 4：用用户自己的语言重述意图。当置信度很高时，写回你认为用户现在想要什么，尽可能使用他们的语言并结构化表达。
步骤 5：确认——明确的"是"，而不是"你觉得怎么样就怎么样"。获取明确的"是"，如果他们纠正你，将纠正纳入并重新陈述。
不要含糊其辞（"听起来不错。），或 沉默应对（用户已经放弃了访谈，没有收敛）

4）输出结果？ 经用户明确说 yes 的意图陈述：

字段	含义	示例
Outcome	要达成什么结果	固件升级失败时设备自动回退到上一版本
User	谁受益	已发货到客户现场的嵌入式设备
Why now	什么发生了改变	3台设备升级失败变砖退货，成本已超研发投入
Success	怎么算成功	回滚成功率100%，设备仍能正常启动和通信
Constraint	绑定的限制	MCU Flash 512KB，固件镜像 ~200KB
Out of scope	明确不做的事	增量/差分升级；升级包加密；跨大版本迁移

5）结束条件：你能不能预测对方接下来的三个回答？

idea-refine —— 想法精炼

1）什么时候用？ 确认了意图，但"怎么做"还没定。方案不止一条路。

2）为什么用？ 大多数人想到第一个方案就冲进去了。切换到构建模式之前的最便宜分歧点——一旦代码开始写了，方案级的方向修正代价巨大。

3）核心过程：三个阶段，先扩后缩。

Phase 1 发散——把意图重述为 “How Might We” 问题陈述，然后用七种视角生成 5-8 个变体提案。每次选 3-4 个最触动的视角（不需要全用）：反过来看（Inversion）、去掉限制看（Constraint Removal）、受众切换（Audience Shift）、简化版本（Simplification）、10x 版本（10x Thinking）、专家视角（Expert Lens）等。
铁律：5-8 个就好，不要 20+。质量高于数量，每个变体要说清它为什么存在。

Phase 2 收敛——把变体聚成 2-3 个有实质差异的方向，用三维标准逐一打分：用户价值（止痛药还是维生素？）、可行性（最难的部分是什么？）、差异化（用户会为此切换现有方案吗？）。然后暴露隐藏假设：赌了什么？什么能杀死这个方向？选择了忽略什么？
贯穿全程的态度：不是 yes-machine。对弱想法具体、友善地说 no——“A good ideation partner is not a yes-machine。Push back with specificity and kindness。”

Phase 3 交付——产出一页纸。

4）输出结果？

字段	含义	示例
Problem Statement	How Might We 一句话问题陈述	“让已发货设备固件升级失败时自动回退，不需拆机、不需派人？”
Recommended Direction	选定的方向及理由，2-3 段	A/B 分区 + Bootloader 回滚标记 + 看门狗兜底
Key Assumptions	需验证的关键假设，每条附验证方式	MCU 支持两个 Flash 地址启动？单分区 ≥ 240KB？
MVP Scope	最小可行版本——什么在、什么不在	Bootloader 状态机 + App 升级流程 + 回滚触发
Not Doing	这次明确不做的事及原因	外挂 SPI Flash（BOM 增加）、升级包加密（缺安全存储）
Open Questions	开始构建前需要回答的开放问题	传输通道是串口还是 BLE？固件增长预期？

---

spec-driven-development —— 规格驱动开发

1）什么时候用？ 方案选定了，需要一份动手前所有人可以审查的白纸黑字。

2）为什么用？ Spec 的价值不在"文档"，在暴露沉默的假设。沉默的误解是最贵的 Bug——你以为用 JWT，对方以为用 session cookie，两周后联调才发现，代码写完了，信任也裂了。

3）核心过程：四阶段门控，每阶段必须人类审批才能进入下一阶段。

Phase 1 SPECIFY——在写任何 Spec 内容之前，先把所有假设列出来让对方纠正。然后覆盖六个核心领域：目标、命令、项目结构、代码风格、测试策略、边界。
把模糊需求翻译成可验证的成功标准。“让仪表盘更快"→"LCP < 2.5s，数据加载 < 500ms，CLS < 0.1”。

Phase 2 PLAN——识别主要组件及依赖、确定实现顺序（先建什么）、标注风险和缓解策略、定义验证检查点。

Phase 3 TASKS——把计划拆成离散可执行的任务，每个任务有明确验收标准、验证步骤、预计涉及的文件。

Phase 4 IMPLEMENT——按任务逐个执行。

4）输出结果？

部分	内容	示例
Objective	构建什么、为谁、成功长什么样	固件安全升级，已发货设备，回滚成功率 100%
Commands	完整的可执行命令（含参数）	west build && west flash，pytest tests/ota/
Structure	目录布局，源码/测试/文档各放哪	src/bootloader/、src/app/、tests/ota/
Code Style	一份真实代码片段 + 关键约定	MISRA C 子集，CRC32 用硬件模块非软件实现
Testing	框架、测试位置、覆盖预期、各层级分工	pytest 单元测试 + QEMU 仿真集成测试 + 真机回归
Boundaries	Always / Ask First / Never 三级权限	Always：升级后校验 CRC；Ask First：修改分区布局；Never：跳过校验直接标"已确认"

---

4.2 Build —— 稳定的接口，隐性的契约

api-and-interface-design —— API与接口设计

1）什么时候用？ 设计 API、定义模块边界、建立前后端接口。任何一段代码要"暴露给另一段代码用"的时候。

2）为什么用？ Hyrum’s Law：API 的所有可观察行为——包括 bug、时序、错误消息的措辞——只要用户能观察到，就一定有人依赖它。 你以为"不重要，文档里没写"。不重要，已经有人在依赖了。每次暴露一个新公开行为，你就在做一个隐性承诺——文档可以修订，事实契约不能单方面撤销。

3）核心过程：五条设计规则。

① Contract First——接口定义先于实现。把 Interface / Schema / OpenAPI Spec 写出来，再写代码。类型就是文档。

② Consistent Error Semantics——整个 API 用同一套错误结构。不要有些端点 throw、有些 return null、有些 return { error }。消费者无法预测的行为 = 一定出 bug。
REST 用 HTTP 状态码 + 结构化 body：400 无效数据、401 未认证、403 无权限、404 未找到、422 校验失败、500 服务端错误。

③ Validate at Boundaries——信任内部代码，在系统边缘设防。API route handler、form submit handler、第三方 API 响应解析——这些是设防点。第三方 API 响应和用户输入一样是不可信数据，先验证再使用。

④ Prefer Addition Over Modification——通过新增可选字段扩展接口，不修改已有字段类型、不删除已有字段。

⑤ Predictable Naming——REST 用复数名词（GET /api/tasks），query 参数用 camelCase（?sortBy=createdAt），布尔字段用 is/has/can 前缀（isComplete）。

4）输出结果？

部分	内容	示例
接口定义	类型化的 Input/Output Schema	CreateTaskInput { title, description?, priority? } → Task { id, title, status, createdAt }
错误格式	全 API 统一的错误结构	{ error: { code: "VALIDATION_ERROR", message: "...", details? } }
边界验证	系统入口处的校验逻辑	POST /api/tasks → Zod schema 校验 → 通过才进业务逻辑
分页约定	列表接口的分页规范	GET /api/tasks?page=1&pageSize=20 → { data, pagination: { page, pageSize, totalItems } }

---

4.3 Review —— 审查的硬杠杠

code-review-and-quality —— 代码审查与质量

1）什么时候用？ 任何变更合并之前。自己写的、另一个 Agent 写的、其他人写的——一律审查。

2）为什么用？ 审批标准不是"完美"：“Approve when it definitely improves overall code health, even if it isn’t perfect.” 批准是因为它让代码库比刚才更好。另一条硬杠：~100 行最优，超 1000 行必须拆分。 小变更容易审查、容易回滚、出问题容易定位。

3）核心过程：五轴审查，每次审查覆盖全部五个维度。

① Correctness（正确性）——是否匹配 spec？边界条件处理了吗？错误路径处理了吗？有没有 off-by-one、竞态、状态不一致？

② Readability & Simplicity（可读性）——另一个工程师不看解释能读懂吗？命名是否描述性？控制流是否直接？有没有不必要的"聪明"技巧？
能 100 行搞定的不要 1000 行。抽象在第三个使用场景出现之前不要引入。

③ Architecture（架构）——是否符合现有模式？模块边界是否清晰？依赖方向是否正确（无循环）？

④ Security（安全性）——用户输入是否校验？Secret 是否被排除？认证/授权是否到位？SQL 是否参数化？外部数据是否当不可信处理？

⑤ Performance（性能）——Measure First——先测量，再优化。 无数据调优是猜测。五步闭环：测量基线 → 定位真正瓶颈（不是你"觉得"的瓶颈）→ 修复 → 再测量确认 → 加监控防退化。

4）输出结果？

维度	审查要点	示例（以一次 PR 审查为例）
Correctness	逻辑正确、边界覆盖	deleteTask 未处理"任务已删除"的幂等场景 → 需补
Readability	命名清晰、控制流直接	process() 内嵌套三元 + reduce 链 → 建议拆为 guard clause
Architecture	模块边界、依赖方向	新增的 formatDate 放在 components/ 下 → 应移入 lib/
Security	输入校验、参数化查询	searchUsers(q) 直接拼接 LIKE → 改为参数化查询
Performance	N+1、缺失分页、同步阻塞	listTasks 无分页，1000 条全量返回 → 加 pageSize 上限
Sizing	~100 行最优，>1000 行拆分	PR 总计 850 行，跨 3 个模块 → 拆为 3 个独立 PR
Verdict	Approve / Request Changes	Request Changes：Correctness + Security 各一项需修复

---

4.4 Ship —— 代码需要解释

documentation-and-adrs —— 文档与架构决策记录

1）什么时候用？ 做架构决策、选框架、设计数据模型——任何未来有人会问"当初为什么这么选"的决策。别记录代码本身已经说清楚的东西（Don’t document obvious code）。

2）为什么用？ 代码展示 What，文档解释 Why。注释的最高价值不是解释"这段代码在做什么"，而是回答"当初为什么选 A 而不是 B"。这个信息代码表达不了，但它是未来任何人做相关决策时最关键的东西——包括六个月后的你。

3）核心过程：ADR 四个必填部分 + 生命周期管理。

① Context（背景）——当前面临什么问题？有哪些约束？为什么需要做这个决策？

② Decision（决策）——选了什么？理由是什么？用一两段话讲清楚。

③ Alternatives Considered（考虑过的替代方案）——哪些方案被拒绝了？为什么？每个方案写清 pros/cons 和拒绝原因。这部分最有价值——后来者不需要重新走过你已经评估过的路径。

④ Consequences（后果）——选择带来的正面和负面影响，好的坏的都写。

生命周期：PROPOSED → ACCEPTED → SUPERSEDED。被取代不是失败——是决策在演化。旧 ADR 保留在版本控制里，标注被哪个新 ADR 取代。

4）输出结果？

部分	内容	示例
Context	背景、约束、触发条件	任务管理应用需选主数据库，要求：关系型模型、ACID 事务、托管方案可用、团队无专职 DBA
Decision	选择及理由	PostgreSQL + Prisma ORM：关系型匹配数据模型，托管方案成熟，Prisma 提供类型安全 + 迁移管理
Alternatives	拒绝的方案及原因	MongoDB（数据关系型不适合文档存储）、SQLite（并发写受限，无生产托管）、MySQL（PG 的 JSON 和全文搜索更优）
Consequences	正面和负面影响	+ 全文本搜索免引入 Elasticsearch；- 团队需 PG 知识（常见技能，低风险）

---

五、工具总会换代，但这些原则不会

5.1 会写代码 ≠ 会做工程 —— 差的是判断力，不是语法

AI 可以写出语法完全正确的代码。但它不会替你想：这个 API 该加分页吗？这个功能需要 kill switch 吗？删除这段旧代码之前，搞清楚它当初为什么存在了吗？

这些问题需要的不是编码能力，是工程判断力。而这 24 个 Skill 在做的事，就是把一个工程师从"能写代码"到"能安全交付价值"之间那些说不清道不明的隐性知识，变成了可执行、可验证、可复现的工作流。

这些东西的共同点是：不依赖任何语言、框架或工具。 React 会换代，Vercel 会换代。但 Hyrum’s Law 在第一个 API 诞生的那一天起就成立，Beyonce Rule 在第一个 Bug 出现的那一天起就成立。

技术栈是浪，工程原则是海。

5.2 怎么用 —— 从三个层次渐进引入

这套东西不需要一次性全部用上。按三个层次来，每一层都能独立生效。

第一层：先读，不改任何工作流。 挑一个你在做的阶段——比如正在写一个新功能？读 incremental-implementation。刚修完一个 Bug？读 debugging-and-error-recovery。准备上线？读 shipping-and-launch。十分钟读完一份 Skill，对照你正在做的事，看它指出的红线你踩了几条。不改变任何习惯，只建立意识。

第二层：挑一个 Skill，完整用一次。 比如下一次启动新功能时，严格按 spec-driven-development 走——先写 PRD，划边界，列验收条件，再打开编辑器。只试一个 Skill，不是为了永久改变习惯，是为了体验一次"按流程走完"和"凭直觉做到哪算哪"的区别。

第三层：纳入团队模板。 你觉得某个 Skill 的 checklist 确实有用——比如 code-review-and-quality 的五轴审查，或 shipping-and-launch 的 pre-launch checklist——把它复制到团队的 PR 模板或发布流程里。不需要提"agent-skills"这个名字，只把步骤抄过去。好流程不需要品牌。

---

相关链接：agent-skills 开源仓库 · Software Engineering at Google · Google Engineering Practices