政安晨的个人主页:************政安晨****************
欢迎 👍点赞✍评论⭐收藏
希望政安晨的博客能够对您有所裨益,如有不足之处,欢迎在评论区提出指正!
目录
[01 · 问题起源:AI Agent 为什么总是"过度热情"?](#01 · 问题起源:AI Agent 为什么总是"过度热情"?)
[01.1 一条推文引发的工程革命](#01.1 一条推文引发的工程革命)
[01.2 106k Star 背后的真实需求(截至博主发稿日/后续将继续增长)](#01.2 106k Star 背后的真实需求(截至博主发稿日/后续将继续增长))
[与传统 Prompt Engineering 的本质区别](#与传统 Prompt Engineering 的本质区别)
[在 OpenClaw 中的实际应用方案(政安晨建议)](#在 OpenClaw 中的实际应用方案(政安晨建议))
[CLAUDE.md 在多 Agent 系统中的扩展(政安晨建议)](#CLAUDE.md 在多 Agent 系统中的扩展(政安晨建议))
[02 · 核心技术:那个 CLAUDE.md 到底写了什么?](#02 · 核心技术:那个 CLAUDE.md 到底写了什么?)
[02.1 文件结构:只有 4 条原则,没有废话](#02.1 文件结构:只有 4 条原则,没有废话)
[02.2 原则一:Think Before Coding(编码前先思考)](#02.2 原则一:Think Before Coding(编码前先思考))
[02.3 原则二:Simplicity First(简单性优先)](#02.3 原则二:Simplicity First(简单性优先))
[02.4 原则三:Surgical Changes(精准手术式修改)](#02.4 原则三:Surgical Changes(精准手术式修改))
[02.5 原则四:Goal-Driven Execution(目标驱动执行)](#02.5 原则四:Goal-Driven Execution(目标驱动执行))
[03 · Agent Skills 标准:CLAUDE.md 的进化形态](#03 · Agent Skills 标准:CLAUDE.md 的进化形态)
[03.1 SKILL.md 是什么?](#03.1 SKILL.md 是什么?)
[03.2 SKILL.md 的跨平台生态](#03.2 SKILL.md 的跨平台生态)
[03.3 Agent Skills 生态规模(截至 2026-04)(不完全统计)](#03.3 Agent Skills 生态规模(截至 2026-04)(不完全统计))
[04 · 高级使用技巧与方案](#04 · 高级使用技巧与方案)
[04.1 技巧一:CLAUDE.md 分层策略(团队必备)](#04.1 技巧一:CLAUDE.md 分层策略(团队必备))
[04.2 技巧二:技能优先级与触发控制](#04.2 技巧二:技能优先级与触发控制)
[04.3 技巧三:多 Agent 系统的 CLAUDE.md 协同](#04.3 技巧三:多 Agent 系统的 CLAUDE.md 协同)
[04.4 技巧四:让 AI 自己验证自己的输出](#04.4 技巧四:让 AI 自己验证自己的输出)
[05 · 场景举例:三个真实场景的完整应用](#05 · 场景举例:三个真实场景的完整应用)
[05.1 场景一:新成员加入团队的代码规范落地](#05.1 场景一:新成员加入团队的代码规范落地)
[05.2 场景二:企业级代码审查工作流](#05.2 场景二:企业级代码审查工作流)
[05.3 场景三:长期 AI 辅助项目的记忆与一致性维护](#05.3 场景三:长期 AI 辅助项目的记忆与一致性维护)
[06 · 工程化实践:让约束真正落地](#06 · 工程化实践:让约束真正落地)
[06.1 为什么规则总是不起作用?](#06.1 为什么规则总是不起作用?)
[06.2 Git Hook 强制 CLAUDE.md 生效](#06.2 Git Hook 强制 CLAUDE.md 生效)
[06.3 衡量规则是否有效的指标](#06.3 衡量规则是否有效的指标)
[07 · 关键技术总结](#07 · 关键技术总结)
[08 · 测试验证方法](#08 · 测试验证方法)
[8.1 验证 CLAUDE.md 是否生效](#8.1 验证 CLAUDE.md 是否生效)
[8.2 验证 Simplicity First 原则](#8.2 验证 Simplicity First 原则)
[09 · 参考资源](#09 · 参考资源)
项目地址:https://github.com/forrestchang/andrej-karpathy-skills
该项目的Star : 100+K
01 · 问题起源:AI Agent 为什么总是"过度热情"?
01.1 一条推文引发的工程革命
2025年12月,Andrej Karpathy(OpenAI 联合创始人、特斯拉前 AI 负责人、"Vibe Coding"一词发明者)在 X 上发了一条简短总结:
"过去几周 Claude Coding 了很多项目。从 80% 手动+自动补全、20% Agent,切换到了 80% Agent 编程、20% 人工审核修改。确实快了很多------但也暴露了 AI Agent 编程的一系列致命陷阱。"
Karpathy 接着列举了 AI Agent 在编程时最常犯的错误:
❌ 静默假设(不确认就当"确定")
❌ 过度工程(为还不存在的问题写好未来扩展)
❌ 一次做太多(不做验证直接大改文件)
❌ 没有成功标准(改完了不知道对不对)
这四条总结迅速引爆开发者社区。华人开发者 Forrest Chang 将其提炼成一个 仅 2345 字节的 CLAUDE.md 文件 ,上传 GitHub 后 21 天内斩获 13,700 颗星,成为 2025-2026 年 GitHub 增长最快的 AI 开发规范项目之一。
01.2 106k Star 背后的真实需求(截至博主发稿日/后续将继续增长)
看数字可能感受不深,换个角度理解:
| 数据 | 含义 |
|---|---|
| ⭐ 106000 stars | 增长速度超过 99.9% 的 AI 相关仓库 |
| 🍴 10.5Kforks | 平均每 15 个 Star 就有 1 个 fork,说明开发者真的在用 |
| 📋 社区活跃 | 持续讨论边界场景 |
| 🌍 全球传播 | Reddit、LinkedIn、Medium、技术博客均有深度讨论 |
这说明什么?
全球开发者不只是在"点赞",而是真的把 Karpathy 这四条原则当作 工程纪律在团队里推广。
深度洞察:为什么这个项目如此重要?
核心技术创新点
该项目将 LLM 的能力从"概率性生成"转向 "确定性执行",核心创新在于提出"技能化(Skill-ification)"的架构:
它不再依赖于单一的长提示词,而是构建了一套 模块化的技能库,将复杂任务拆解为高度结构化的操作指令集。技术上,它引入了"约束驱动的任务执行"模式:通过定义严格的边界条件、标准操作程序(SOP)和自验证环节,强制模型在执行过程中遵循特定的算法逻辑,而非仅依赖权重概率。
一句话总结:约束驱动,而非概率驱动。
与传统 Prompt Engineering 的本质区别
| 维度 | 传统 Prompt Engineering | Karpathy Skills 体系 |
|---|---|---|
| 关注点 | 输入端优化 | 过程端规范 |
| 目标 | 诱导模型给正确答案 | 强制模型执行标准步骤 |
| 性质 | 艺术性调优 | 工程化协议 |
| 可预测性 | 低(黑盒博弈) | 高(确定性执行路径) |
| 可复用性 | 低(每次都要调) | 高(SKILL.md 模块化) |
在 OpenClaw 中的实际应用方案(政安晨建议)
第一步:OpenClaw skill_manage 工具
→ 将 Karpathy-skills 指令转换为 OpenClaw 规范的 .md 技能文件
→ 存储于 ~/.openclaw/skills/ 或 ~/.hermes/skills/
第二步:技能匹配机制
→ 当用户请求涉及复杂工程任务时
→ Agent 动态加载相关技能
→ 替代宽泛的系统提示词
第三步:delegate_task × SOP
→ 主 Agent 负责流程编排
→ 子 Agent 加载特定技能执行原子任务
→ 实现"对话式 AI" → "Agentic Workflow" 的升级
CLAUDE.md 在多 Agent 系统中的扩展(政安晨建议)
CLAUDE.md 从"个体说明书"可扩展为"集群全局政策文件(Global Policy File)":
02 · 核心技术:那个 CLAUDE.md 到底写了什么?
02.1 文件结构:只有 4 条原则,没有废话
CLAUDE.md(全文 2345 字节)
├── 1. Think Before Coding(编码前先思考)
├── 2. Simplicity First(简单性优先)
├── 3. Surgical Changes(精准修改)
└── 4. Goal-Driven Execution(目标驱动执行)
对比其他 AI 规范文档(动不动 300 行、50 个子规则),这个 CLAUDE.md 令人震惊地克制。但克制的背后,是精准的洞察。
02.2 原则一:Think Before Coding(编码前先思考)
核心理念:不假设、不隐藏困惑、主动暴露权衡。
小白解读:就像医生看病不问诊就直接开药。好的医生会先问"哪里不舒服""多久了""吃过什么药"------AI 也应该这样。
这一原则解决的根本问题:
-
减少"你以为你以为的不是你以为的"(需求理解偏差)
-
减少"改了三版才发现方向错了"(早期澄清节省 80% 重工)
02.3 原则二:Simplicity First(简单性优先)
核心理念:只写解决今天问题的代码,不写为明天准备的代码。
小白解读:就像装修房子,用户只要求刷墙,AI 不应该连家具布局图、水电改造方案、软装风格指南一起做了(除非用户明确要)。
判断标准:问自己------"高级工程师会觉得这太复杂了吗?"如果答案是"会",就简化。
02.4 原则三:Surgical Changes(精准手术式修改)
核心理念:只改必须改的,清理自己留下的垃圾,但不动原有的代码。
小白解读:就像做手术,医生应该在肿瘤位置精准切除,而不是顺便把旁边健康的器官也修整一下。
验证标准:每一行改动,都能追溯到用户的原始需求。如果改动的某行消失后,需求仍然能完成------那这行就不该改。
02.5 原则四:Goal-Driven Execution(目标驱动执行)
核心理念:把模糊任务转化为可验证目标,每步都有检查点。
小白解读:就像装修合同里的验收标准------"墙面刷漆"不是成功标准,"墙面平整无色差,光泽度误差不超过 5%"才是。
03 · Agent Skills 标准:CLAUDE.md 的进化形态
03.1 SKILL.md 是什么?
CLAUDE.md 解决了"AI 如何行为"的问题,但每个项目、每个团队有不同的专业领域需求。于是社区在 2025 年底到 2026 年初,将 CLAUDE.md 的理念扩展为可复用的技能包规范------SKILL.md。
基本结构:
---
name: 代码审查专家
description: 当用户要求审查代码时激活此技能。专注于性能、安全、可维护性。
---
# 代码审查技能
## 激活条件
当用户说"review""审查""检查代码"时激活
## 审查维度
1. 性能:O(n)复杂度、数据库 N+1 查询
2. 安全:SQL 注入、XSS、越权
3. 可维护性:函数长度、圈复杂度、命名
## 输出格式
每个问题按 [严重程度] 标注:
- [CRITICAL] 必须在合并前修复
- [WARNING] 建议修复
- [INFO] 参考建议
03.2 SKILL.md 的跨平台生态
这是 SKILL.md 最厉害的地方------一份文件,多个平台通用:
| 平台 | 路径格式 | 激活方式 |
|---|---|---|
| Claude Code | ~/.claude/skills/技能名/SKILL.md |
自动检测 + /技能名 斜杠命令 |
| OpenClaw | ~/.openclaw/skills/技能名/SKILL.md |
技能描述触发 |
| Codex CLI | ~/.codex/skills/技能名/SKILL.md |
自动检测 |
| Cursor | ~/.cursor/skills/技能名/SKILL.md |
斜杠命令 |
| 自定义 Agent | 任意指定路径 | API 加载 |
03.3 Agent Skills 生态规模(截至 2026-04)(不完全统计)
| 指标 | 数据 |
|---|---|
| 公开 SKILL.md 数量 | 2,636+ 个(持续增长) |
| 技能分类 | 前端设计、测试 QA、DevOps、API 开发、代码审查等 20+ 类 |
| OpenClaw 技能市场 | clawhub.ai(13,729 个技能,含大量 SKILL.md 规范) |
| SkillsBench 评估平台 | 专门评估 AI Agent 技能可靠性的基准测试 |
04 · 高级使用技巧与方案
04.1 技巧一:CLAUDE.md 分层策略(团队必备)
单一 CLAUDE.md 难以满足团队所有场景,推荐三层分层策略:
层次 1:~/.claude/CLAUDE.md(全局,适用所有项目)
├── 公司代码规范(命名规则、commit 格式)
├── 安全红线(绝不执行 rm -rf /、绝不提交明文密钥)
└── 通用工程原则(Karpathy 四原则在此)
层次 2:项目根目录/CLAUDE.md(项目级别)
├── 项目技术栈说明
├── 特定领域规则(如"本项目禁止使用 select * ")
└── 成功标准定义方式
层次 3:.claude/skills/技能名/SKILL.md(按需激活)
├── 代码审查技能
├── 测试生成技能
└── 文档撰写技能
04.2 技巧二:技能优先级与触发控制
通过 description 字段精确控制触发:
---
name: xxx学分析专家
description: >
当用户提到"xxx学"、"Dermatoglyphics"、"xxx分析"、
"xx报告"、"多指评估"时激活。
当用户提到"xxx"、"xxx2"、"xxx3"时激活。
当用户的任务是分析xxx数据或生成xxx学报告时激活。
---
触发精确度决定技能有效性 。模糊的 description 会导致技能被错误激活或完全不激活。
04.3 技巧三:多 Agent 系统的 CLAUDE.md 协同
在 OpenClaw 的多 Agent 架构中,每个 Agent 可以有独立的 CLAUDE.md:
# OpenClaw 多 Agent 场景下的 CLAUDE.md 协同
# 主 Agent(规划者)
# 角色:接收需求 → 拆解任务 → 分发给专家 Agent
# CLAUDE.md 主旨:理解需求、不要假设、拆解为可验证目标
researcher_agent = Agent(
name="研究专家",
instructions="你是专业的研究者...",
# 等效于 researcher/CLAUDE.md
)
reviewer_agent = Agent(
name="审核专家",
instructions="你是严格的代码审核专家...",
# 等效于 reviewer/CLAUDE.md
)
# 协同方式:Triage Agent(分诊台)
# 收到需求 → 路由给最合适的专家 Agent
# 分诊逻辑本身也要遵循"先确认再分发"原则
关键设计:主 Agent 的 CLAUDE.md 应该专注于"理解需求、拆解任务",专家 Agent 的 CLAUDE.md 专注于"在自己的领域做到极致"。
04.4 技巧四:让 AI 自己验证自己的输出
Karpathy 原则四的核心是"目标驱动",但实践中可以让 AI 在输出后自我审查:
<!-- 添加到 CLAUDE.md 的元规则 -->
## 自我验证清单(每项任务完成后检查)
- [ ] 改动的每一行都能追溯到用户原始需求吗?
- [ ] 有没有顺手"优化"了不在需求范围内的代码?
- [ ] 提交的信息描述了"做了什么"还是"为什么做"?
- [ ] 如果撤销这次改动,原始需求还能满足吗?
05 · 场景举例:三个真实场景的完整应用
05.1 场景一:新成员加入团队的代码规范落地
背景:团队有 5 名后端工程师,新来了一名 AI Coding 用户。历史代码风格不统一(有的用 tab,有的用 space;有的函数很长,有的遵循单一职责)。
Karpathy 方案应用:
在项目根目录创建 CLAUDE.md,包含:
## 本项目代码规范
### 1. Think Before Coding
新增功能前,必须确认:
- 是否符合现有 API 风格?(参考 src/api/)
- 是否有现成工具函数可用?(先搜索 src/utils/)
- 是否需要与现有模块交互?(先阅读模块文档)
### 2. Simplicity First
- 单个函数不超过 50 行
- 不引入新的外部依赖(先查现有依赖清单)
- 不写"为了以后扩展"的代码
### 3. Surgical Changes
- 每次 PR 不超过 3 个文件(除非重构)
- 每次提交必须关联 GitHub Issue
- 修改前先运行测试,确保不破坏现有功能
### 4. Goal-Driven Execution
- 每个任务必须有 GitHub Issue 描述
- 完成后必须运行测试套件
- PR 描述必须包含"如何测试这个功能"
效果:新成员第一次 Claude 启动时,AI 自动读取项目 CLAUDE.md,接下来的所有代码都遵循团队规范。
05.2 场景二:企业级代码审查工作流
背景:企业需要每周对所有 PR 做安全 + 性能审查,人工审查耗时且容易遗漏。
Karpathy + SKILL.md 方案应用:
<!-- 安全审查技能:security-reviewer/SKILL.md -->
---
name: 安全审查专家
description: >
当用户说"安全审查"、"security review"、
"检查漏洞"、"扫描依赖"时激活。
---
## 审查重点
### 1. Think Before Coding(审查前确认)
- 审查范围:只审查本 PR 改动的文件,还是全量?
- 风险等级:生产环境 / 测试环境(决定严格程度)
- 审查重点:已知的 OWASP Top 10 漏洞类型
### 2. Simplicity First(只报告真正的漏洞)
- 不报告"代码风格问题"(那是 lint 的职责)
- 不报告"可以但没必要改进"(那是重构的职责)
- 只报告真正影响安全的问题
### 3. Surgical Changes(精准定位)
- 每个漏洞必须包含:
- 文件路径 + 行号
- 漏洞类型(SQL注入 / XSS / 越权 / 敏感信息泄露)
- 严重程度 [CRITICAL / HIGH / MEDIUM / LOW]
- 修复建议(含代码示例)
### 4. Goal-Driven Execution(可验证结果)
- 每个漏洞必须有"验证测试":修复后能通过的安全测试
- 输出格式:结构化 JSON,供 CI/CD 集成
05.3 场景三:长期 AI 辅助项目的记忆与一致性维护
背景:用 Claude Code 开发一个持续迭代 3 个月的项目,每次新 session AI 都"失忆",需要重新解释项目上下文。
Karpathy 方案应用:
<!-- 项目 CLAUDE.md 补充:上下文维护规则 -->
## 项目上下文(长期维护)
### Think Before Coding(接手任务前必读)
1. 读 `docs/ARCHITECTURE.md` 了解系统架构
2. 读 `docs/API.md` 了解 API 规范
3. 读最近的 5 条 commit 了解当前开发进展
4. 问自己:"这个需求与现有架构一致吗?"
### 上下文传递规则
- 如果你修改了一个模块,在 commit 中说明原因
- 如果你发现架构问题,在 `docs/ARCHITECTURE.md` 中记录
- 如果你用了新的依赖,在 `docs/DEPENDENCIES.md` 中更新
### Goal-Driven Execution(季度维度的目标)
当前季度目标:Q2 性能优化
- 完成用户反馈的 3 个性能问题
- 不在本季度做大规模重构
- 所有性能优化必须有 before/after 基准测试
06 · 工程化实践:让约束真正落地
06.1 为什么规则总是不起作用?
很多团队引入了 CLAUDE.md,但 AI 还是"不听话"。常见原因:
| 问题 | 根因 | 解决方案 |
|---|---|---|
| AI 跳过 CLAUDE.md | 文件不在正确路径 | 确认 Claude Code 的 /CLAUDE.md 在项目根目录 |
| AI 理解了但不执行 | instruction 太长被截断 | CLAUDE.md 保持 500 行以内 |
| 团队成员不用 | 没有强制机制 | git hook 强制提交前检查 |
| 规则与实际冲突 | 规则太死板 | 规则本身要有"例外条款" |
06.2 Git Hook 强制 CLAUDE.md 生效
bash
#!/bin/bash
# .git/hooks/pre-commit
# 确保每次 commit 消息符合团队规范
COMMIT_MSG=$(cat "$1")
if ! echo "$COMMIT_MSG" | grep -qE '#[0-9]+'; then
echo "错误:commit 消息必须包含 GitHub Issue 编号(#123)"
echo "遵循 Goal-Driven Execution 原则"
exit 1
fi
06.3 衡量规则是否有效的指标
Karpathy 在 CLAUDE.md 末尾给出了自检标准:
bash
这些指南生效的标志:
✅ diff 中的不必要改动变少
✅ 因为过度复杂而重写的情况减少
✅ 澄清问题出现在实现之前,而非错误出现之后
可量化的团队指标:
PR 平均代码行数(是否在下降)
因"理解偏差"导致的返工次数(是否在下降)
AI 第一次给出的方案通过率(是否在上升)
07 · 关键技术总结
| 概念 | 说明 |
|---|---|
| CLAUDE.md | 行为约束文件,放在项目根目录,AI 每次启动自动读取 |
| SKILL.md | 可复用技能包,跨平台通用(OpenClaw/Claude Code/Codex/Cursor) |
| Think Before Coding | 编码前先确认假设,不懂就问,不假设就做 |
| Simplicity First | 只写解决今天问题的代码,不写为明天准备的代码 |
| Surgical Changes | 精准手术式修改,只改必须改的,不改顺眼但无关的 |
| Goal-Driven Execution | 每个任务有可验证的成功标准,每步有检查点 |
| Agent Skills 标准 | SKILL.md 跨平台互操作规范,2,636+ 技能已发布 |
| Harness Engineering | 将 AI 系统放到确定性轨道上(Stripe Minions 案例:每周处理 1,300 个 PR) |
| 约束驱动 vs 概率驱动 | 政安晨 核心洞察:这不是 Prompt Engineering,是工程化协议 |
08 · 测试验证方法
8.1 验证 CLAUDE.md 是否生效
bash
# 测试场景:故意提出模糊需求,看 AI 是否主动询问
$ claude
> "修一下那个 BUG"
(AI 应该):"您是指哪个 BUG?能否提供 GitHub Issue 链接或错误信息?"
(AI 不应该):"好的,我来修。" ← 这就是 CLAUDE.md 未生效
8.2 验证 Simplicity First 原则
bash
# 测试场景:要求写简单函数,看 AI 是否过度工程
$ claude
> "写一个函数判断闰年"
期望:def is_leap_year(year): return year % 4 == 0 ...
不期望:class DateValidator, AbstractRule, Strategy Pattern...
09 · 参考资源
| 资源 | 链接 |
|---|---|
| GitHub 仓库 | forrestchang/andrej-karpathy-skills |
| Karpathy 原始推文 | x.com/karpathy/status/2015883857489522876 |
| Stripe Minions(生产案例) | stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents |
| SkillsBench(技能评估) | skillsbench.ai |
| Agent Skills 标准 | agensi.io/learn/agent-skills-open-standard |
| CLAUDE.md 最佳实践 | Medium: CLAUDE.md Best Practices |
这是一篇很实用的文章,这篇文章的正确打开方式,其实是:让智能体来读!嘻嘻。
