背景

如果你用AI编程工具超过三个月，应该有这种感觉：代码是能跑，但PR没人愿意review，测试覆盖率惨不忍睹，边界情况全靠用户发现。

这不是工具的问题，是使用方式的问题。

上周看到Addy Osmani发了一个开源项目——Agent Skills（github.com/addyosmani/agent-skills，26K stars），核心思路是：把Git工程文化编码成AI agent可执行的skill，而不是给人类读的文档。

这个思路很有意思，拆解一下。

核心设计：Skill不是文档，是工作流定义

Agent Skills里的Skill，定义是一个带frontmatter的Markdown文件，但这个Markdown不是给人读的教程，是给agent执行的工作流定义。

---
name: improve-codebase-architecture
description: 改进代码库架构
trigger: 当代码库架构有问题需要系统性重构时
---

## 工作流

1. 分析当前架构
2. 识别问题点
3. 制定改进计划
4. 逐步执行
5. 验证改进效果

## 检查点
- [ ] 架构改进有文档记录
- [ ] 改动不影响现有功能
- [ ] 新架构可扩展

## 退出条件
- 所有检查点通过

关键点：过程大于文档。工作流是可执行的，不是只读的。

Anti-rationalization Tables：防止Agent自我合理化

LLM有个经典问题：被追问时，会生成听起来合理但偷工减料的解释。

比如：

• “这个任务太简单不需要spec” → 验收标准仍然适用
• “我之后再写测试” → 不存在"之后"
• “测试过了直接发版” → 通过的测试是证据不是证明

Anti-rationalization Tables把这些"常见借口+反驳"预置成对照表，让Agent在生成借口之前就被拦截。

## 反rationalization检查

| 借口 | 反驳 |
|------|------|
| 这个太简单不需要spec | 验收标准仍然适用，5行可以0行不行 |
| 我之后再写测试 | 不存在之后，测试是工作完成的必要条件 |
| 测试过了直接发版 | 通过的测试是证据不是证明，需要检查运行时行为 |

为什么这个设计重要？

因为你问AI"为什么没写测试"，它会说"太简单了没必要"。这个解释听起来很合理，但你追问"那边界情况呢"，它会说"不太可能出现"。

这些是典型的"在对话中自我合理化"。Anti-rationalization Tables把这个链条打断了。

渐进式披露：不是所有时候需要所有skill

Agent Skills不是上来就加载全部20个skill，而是用Meta-skill充当router，根据任务阶段激活对应skill。

为什么这样做？

5K token上下文限制下，全部加载会导致信号噪音太大。

更重要的是：不同阶段需要不同关注点。写代码时需要TDD skill，review时需要code review skill——但同时激活所有skill，等于没有优先级。

这个设计对应了人类工程师的真实工作方式：分阶段，而不是多任务并行。

五条不可协商原则

Agent Skills定义了5条不可协商原则，每一条都有具体的工程背景：

1. 动手前先暴露假设

沉默的错误假设是最常见失败模式。如果不主动说出来，reviewer需要花大量时间才能发现。

2. 需求冲突时停下来问

不要猜需求。猜对了是运气，猜错了浪费的是所有人的时间。

3. 有依据时敢于反驳

包括反驳人类。当你有数据或逻辑支撑时，应该坚持自己的判断。

4. 优先无聊的、显而易见的方案

聪明是有代价的。显而易见的方案通常更易维护、更少bug。

5. 只碰你被要求碰的东西

Scope discipline是可合并PR的最大决定因素。你把auth模块重构得很优雅，但reviewer分不清哪些改动是需求导致的、哪些是你自己加的。

Git工程文化的skill编码

Agent Skills把经典工程原则编码成了可执行的skill：

原则	编码位置	核心内容
Hyrum’s Law	API设计skill	公开API的一切都有人依赖，改变行为要有deprecation warning
Test Pyramid	TDD skill	~80/15/5的单位/集成/端到端测试比例
Beyoncé Rule	TDD skill	测试描述行为而非实现，像行为规范而不是代码注释
DAMP over DRY	测试code	测试的可读性优先于DRY
Chesterton’s Fence	代码简化skill	不理解为什么存在就不要删，先理解
Atomic Commits	git workflow skill	每个commit做一件事，可以单独revert

把原则编码成skill而不是文档，意味着什么？

文档需要主动查阅，skill在合适的阶段自动激活。你不需要记得"上次PR被拒是因为我没有先加deprecation warning"——skill会在你准备删代码之前提醒你。

适用场景和局限性

适合的场景：

• 团队有多人协作，需要统一的工程规范
• AI编程工具产出质量不稳定，PR review成本高
• 希望把高级工程师的"隐性知识"显性化

不适用的场景：

• 单人项目，快速迭代为主
• 一次性脚本，不需要长期维护
• 已有成熟CI/CD流程，AI工具只是辅助

总结

Agent Skills解决的核心问题是：让AI编程产出从"能跑就行"变成"可合并PR"。

不是让AI更聪明，是让AI遵循工程规范。

这个方向代表了一个正在发生的趋势：AI编程工具从"写代码"向"做工程"延伸。高级工程师那些不在diff里的工作——计划、review、检查、验证——正在变成可编码、可复制的skill。

如果你在团队里推广AI编程工具，建议先看看这个项目。不是要用它的全部skill，而是理解它的思路：把工程规范变成AI可执行的规则，而不是给人类读的文档。

---

你有使用AI编程工具的经历吗？遇到过什么问题？评论区聊聊。