AI 编程助手瘫痪了吗？Karpathy Skills 与 CLAUDE.md 如何用数学约束驯服 LLM 的混乱天性——从四大失败模式到生产级行为规则的完全指南
作者注：本文深度剖析 AI 编码助手从"玩具"到"生产基础设施"的演进路径，揭示 Andrej Karpathy 对 LLM 编码失败模式的底层观察，并通过完整的实战案例展示如何用 CLAUDE.md 行为约束体系构建可维护、可扩展、可协作的 AI 辅助开发流程。全文约 8500 字，阅读时间约 25 分钟。
目录
- 引言：当 AI 编程助手"失控"时发生了什么？
- Andrej Karpathy 是谁？为什么他的观察改变了一切
- AI 编码代理的四大核心失败模式深度解析
- 为什么提示工程（Prompt Engineering）不够用？
- Karpathy Skills 项目：用行为约束替代模糊提示
- 5.1 项目起源：从吐槽到工程规范
- 5.2 四大原则的技术实现
- CLAUDE.md 深度解析：AI Agent 的长期记忆系统
- 6.1 CLAUDE.md 的本质：永久系统指令
- 6.2 加载机制与优先级
- 6.3 规则分层架构
- 实战：从零构建生产级 CLAUDE.md
- 7.1 项目背景与技术栈约束
- 7.2 核心规则编写
- 7.3 验证标准前置定义
- 7.4 完整示例代码
- 团队协作：AGENTS.md 与 CLAUDE.md 的分工
- 性能优化：上下文窗口与 Token 成本管理
- 行业影响：Skills 生态 vs MCP 协议
- 总结与展望：AI 编程的下一个十年
1. 引言：当 AI 编程助手"失控"时发生了什么？
2026 年，AI 编程助手已经不再是新鲜事物。从 GitHub Copilot 到 Claude Code，从 Cursor 到 OpenClaw，开发者们每天都在与这些"智能体"协作。但一个尴尬的现实是：
大多数团队在使用 AI 编程助手时，仍然处于"碰运气"模式。
你可能有过这样的经历：
- 让 AI "添加一个登录功能"，它给你生成了一个包含 OAuth 2.0、JWT 刷新令牌、RBAC 权限控制的 400 行完整系统——而你只是想要一个原型项目的简单邮箱密码验证。
- 让 AI "修复这个日期格式化 bug"，它返回了一个包含建造者模式、六个辅助方法、完整异常处理的工具类——代码量从 30 行膨胀到 200 行。
- 让 AI "优化这段 SQL 查询"，它不仅重构了你指定的查询，还"顺手"修改了相邻的三个函数、重命名了五个变量、调整了代码格式——原本 4 行的 diff 变成了 40 行，代码审查成本成倍增加。
这些不是偶然事件。它们是 LLM 编码的系统性失败模式，根植于大语言模型的训练数据和推理机制中。
核心问题不是"AI 不够聪明"，而是"AI 不知道什么时候该停下来"。
要解决这个问题，我们需要的不再是"更好的提示词"，而是 行为约束体系——用数学规则、结构化配置、可验证的标准，把 AI 代理的"创造力"限制在工程可接受的边界内。
这就是 Andrej Karpathy（OpenAI 联合创始人、Tesla 前 AI 总监）的观察所揭示的真理，也是 andrej-karpathy-skills 项目在 GitHub 上爆火的根本原因。
2. Andrej Karpathy 是谁？为什么他的观察改变了一切
在深入技术细节之前，我们需要先理解：为什么 Andrej Karpathy 的观点具有如此大的影响力？
2.1 Karpathy 的技术履历
Andrej Karpathy 是 AI 领域最具传奇色彩的人物之一：
- OpenAI 创始成员：2015 年与 Sam Altman、Elon Musk 等人共同创立 OpenAI，是 GPT-3 和 ChatGPT 的核心贡献者之一。
- Tesla 前 AI 总监（2017-2022）：领导 Tesla Autopilot 视觉团队，构建了世界上规模最大的自动驾驶神经网络系统。
- "Vibe Coding" 之父：2025 年提出 "Vibe Coding" 概念——用自然语言描述意图，让 AI 完成编码实现，人类专注于架构设计和验证。
- 全球最有影响力的 AI 教育者：其 YouTube 课程 "Neural Networks: Zero to Hero" 累计观看量超过 500 万次。
2026 年 5 月 19 日，Karpathy 宣布加入 Anthropic 预训练团队，组建新团队用 Claude 加速预训练研究。这一人事变动被视为"AI 人才争夺战的标志性事件"。
2.2 Karpathy 对 AI 编程的观察
Karpathy 在使用 GPT-4、Claude、GitHub Copilot 等工具进行日常开发时，积累了大量"失败案例"。他没有选择沉默，而是在 X（Twitter）和 GitHub 上公开分享这些观察：
"The models make wrong assumptions on your behalf and just run with them. They over-engineer everything. They silently delete features they don't understand. This is not a intelligence problem — it's a discipline problem."
（模型会替你做出错误的假设，然后直接执行。它们会把所有东西都过度工程化。它们会静默地删除自己不理解的功能。这不是智力问题——这是纪律问题。）
这段话揭示了 AI 编程助手的核心矛盾：
- 高智商，低情商：LLM 能够生成复杂的算法和数据结构，但无法理解"什么时候应该问问题而不是做假设"。
- 训练数据偏见：AI 在大型企业级代码库上训练，习惯性采用高抽象度的设计模式，即使在小型项目中也默认采用复杂架构。
- 缺乏"工程味觉"：AI 不知道什么是"足够好"，什么是"过度设计"，什么是"需要人类确认的高风险操作"。
Karpathy 的贡献不是提供了新技术，而是把这些问题系统化、可操作化，转化为一组可以通过配置文件强制执行的行为规则。
3. AI 编码代理的四大核心失败模式深度解析
基于 Karpathy 的观察和社区的实践反馈，我们可以把 AI 编码代理的失败模式归纳为四大类。每一类都有其深层次的技术原因和可行的缓解策略。
3.1 问题一：静默假设（Silent Assumptions）
失败场景
当开发者提出模糊需求时，AI 代理不会主动询问具体需求，而是自行选择一种理解并开始实现。
典型案例：
# 开发者的需求（模糊）
"帮我添加一个用户认证功能"
# AI 的生成（过度复杂）
# 它假设你需要：
# - OAuth 2.0 集成（Google、GitHub、Microsoft）
# - JWT Token with 刷新令牌机制
# - RBAC 权限控制系统
# - 多因素认证（MFA）
# - 审计日志记录
# 结果：400 行代码，而你只是想要一个原型项目的简单邮箱+密码登录
技术根源
- 训练数据偏差：LLM 的训练语料中，"用户认证"通常关联着企业级实现（含 OAuth、JWT、RBAC）。
- 缺乏主动询问机制：AI 的优化目标是"最小化用户 friction"，而不是"最大化需求准确性"。
- 上下文窗口限制：AI 无法记住"我们之前讨论过这是一个原型项目"。
解决方案
在 CLAUDE.md 中添加 "先思考再编码" 规则：
# CLAUDE.md
## 核心规则
### 1. 静默假设禁止
- 遇到模糊需求时，**必须**先提出 2-3 个澄清问题，等待用户回答后再开始实现。
- 禁止自行假设技术栈、架构模式、第三方库。
- 示例：用户说"添加认证"，你应该问：
- "这是生产环境还是原型？"
- "需要支持第三方登录（OAuth）吗？"
- "需要 RBAC 权限控制吗？"
3.2 问题二：过度工程（Over-Engineering）
失败场景
AI 模型在大型企业级代码库上训练，习惯性采用高抽象度的设计模式。即使是简单的日期格式化函数，也可能返回包含建造者模式、六个方法、完整异常处理的工具类。
典型案例：
# 开发者的需求（简单）
"写一个函数，把 UTC 时间转换成北京时间"
# AI 的生成（过度工程）
class DateTimeConverter:
"""时间转换器（建造者模式）"""
def __init__(self):
self._timezone_registry = {}
self._cache = LRUCache(max_size=1000)
self._logger = logging.getLogger(__name__)
@staticmethod
def builder():
return DateTimeConverterBuilder()
def convert(self, utc_time: datetime, target_timezone: str) -> datetime:
"""转换时间（含缓存、日志、异常处理）"""
cache_key = f"{utc_time.isoformat()}_{target_timezone}"
if cache_key in self._cache:
self._logger.debug(f"Cache hit: {cache_key}")
return self._cache[cache_key]
try:
# ... 200 行实现
except Exception as e:
self._logger.error(f"Conversion failed: {e}")
raise DateTimeConversionError(e)
# ... 还有 5 个辅助方法
# 实际使用只需要：
def utc_to_beijing(utc_time: datetime) -> datetime:
return utc_time.astimezone(pytz.timezone('Asia/Shanghai'))
代码量从 30 行膨胀到 200 行，可读性反而下降。
技术根源
- 训练数据中的"最佳实践"偏见：LLM 的训练语料中，Java/C# 风格的企业级代码占主导，导致 AI 倾向于"过度抽象"。
- 缺乏"够用就好"的判断力：AI 无法评估"当前任务的复杂度"，一律采用"最安全"的高抽象度方案。
- 奖励模型的问题：RLHF 训练时，"完整性"和"鲁棒性"的权重过高，导致 AI 生成"防御性过强"的代码。
解决方案
在 CLAUDE.md 中添加 "最小实现优先" 规则：
### 2. 过度工程禁止
- **YAGNI 原则**（You Aren't Gonna Need It）：只实现当前需求，不提前引入未来可能用到的抽象。
- **KISS 原则**（Keep It Simple, Stupid）：优先选择最简单的实现，除非性能或可维护性有明确需求。
- **代码量预算**：单个函数的代码量不超过 50 行；单个类的代码量不超过 200 行。超过时必须先提出重构方案。
- 禁止使用：建造者模式（除非构造参数 > 4 个）、抽象工厂、依赖注入框架（除非项目已使用）。
3.3 问题三：范围蔓延（Scope Creep）
失败场景
要求 AI 修复单个函数的 bug，它不仅完成修复，还会"顺手"重构相邻函数、重命名变量、调整代码格式、清理注释。原本 4 行的 diff 变成 40 行，代码审查成本成倍增加。
典型案例：
# 开发者的需求
"修复 calculate_total() 里的整数溢出 bug"
# AI 的修改（范围蔓延）
@@ -12,7 +12,7 @@ def calculate_total(items):
total = 0
for item in items:
- total += item.price * item.quantity # 可能溢出
+ total = int(total + item.price * item.quantity) # 修复溢出
# AI "顺手"修改的其他内容（不在需求范围内）
@@ -20,15 +20,16 @@ def calculate_total(items):
-def format_price(price):
- return f"${price:.2f}"
+def format_price(price: float) -> str:
+ """格式化价格为货币字符串"""
+ return f"¥{price:.2f}" # 还顺手改了货币符号
-def process_order(order):
+def process_order_v2(order: Order) -> None:
"""处理订单（重命名为 v2，修改了函数签名）"""
# ... 完全重写了实现
# ... 还修改了 3 个不相关的测试文件
后果：
- 代码审查时间从 5 分钟变成 30 分钟。
- 引入了未经验证的功能变更。
- 其他开发者的本地分支产生冲突。
技术根源
- "有帮助的助手"偏见：AI 的 RLHF 训练鼓励"主动提供帮助"，导致它倾向于"额外工作"。
- 缺乏"任务边界"概念：AI 无法区分"修复 bug"和"改进代码质量"是两个独立的任务。
- 代码格式化工具的干扰：如果项目配置了 Black、Prettier 等格式化工具，AI 可能误以为"统一格式"是任务的一部分。
解决方案
在 CLAUDE.md 中添加 "任务边界严格隔离" 规则：
### 3. 范围蔓延禁止
- **单一职责原则**：每次任务只修改需求明确指定的代码区域。
- **diff 预算**：单次任务的代码变更（diff）不超过 20 行。超过时必须先拆分任务。
- **禁止顺手重构**：除非用户明确要求，否则禁止修改需求范围之外的代码（包括格式化、重命名、添加注释）。
- **Git 提交隔离**：每次任务对应一次 Git 提交，提交信息必须包含任务编号（如 `fix: #123`）。
3.4 问题四：缺乏验证（Lack of Verification）
失败场景
AI 生成表单验证代码后直接标记为"完成"，但从未测试空字符串、特殊字符、超长输入等边界情况。没有验证步骤，没有成功标准，只是机械地完成字面任务。
典型案例：
# 开发者的需求
"写一个邮箱验证函数"
# AI 的生成（缺乏边界情况验证）
import re
def validate_email(email: str) -> bool:
"""验证邮箱格式"""
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return re.match(pattern, email) is not None
# AI 标记为"完成"，但：
# 1. 没有测试空字符串：validate_email("") → False（正确，但没测试）
# 2. 没有测试超长输入：validate_email("a" * 1000 + "@example.com") → 可能 ReDoS 攻击
# 3. 没有测试特殊字符：validate_email("用户@例子.com") → False（Unicode 邮箱不支持）
# 4. 没有单元测试
技术根源
- "完成任务"而非"完成任务且验证"：AI 的优化目标是"生成看起来合理的代码"，而不是"生成经过测试的生产级代码"。
- 缺乏执行环境：AI 无法实际运行代码（除非配置了代码执行工具），因此无法自行验证。
- 训练数据中的"不完整示例"：许多开源代码库中的函数缺乏完整的边界情况测试，AI 从这些数据中学习到了"不完整的验证"。
解决方案
在 CLAUDE.md 中添加 "验证标准前置定义" 规则：
### 4. 缺乏验证禁止
- **测试驱动开发（TDD）**：生成任何功能代码之前，必须先编写单元测试。
- **边界情况清单**：必须测试的边界情况包括：
- 空输入（None、""、[]、{}）
- 超长输入（字符串 > 1000 字符，列表 > 1000 元素）
- 特殊字符（Unicode、emoji、SQL 注入、XSS）
- 数值边界（0、负数、MAX_INT、溢出）
- **验证证据**：任务完成时，必须提供测试运行结果（如 pytest 输出）。
4. 为什么提示工程（Prompt Engineering）不够用？
在引入行为约束体系之前，许多团队尝试通过"提示工程"来控制 AI 代理的行为。典型做法包括：
4.1 传统提示工程的方法
# 方法 1：在每次对话中重复指令
user: "写一个日期格式化函数。注意：保持简单，不要过度工程化。"
# 方法 2：使用系统提示词
system_prompt = """
你是一个谨慎的编程助手。
规则：
1. 遇到模糊需求时先提问
2. 保持代码简单
3. 不要修改需求范围外的代码
"""
# 方法 3：Few-shot 示例
user: "看看这个例子（好的实现 vs 坏的实现），然后写一个类似的简单函数..."
4.2 提示工程的三大缺陷
缺陷 1：无法持久化
- 问题：每次新对话，系统提示词都会丢失。你需要在每个新会话中重新输入规则。
- 后果：团队协作时，每个开发者都有自己的"提示词版本"，导致 AI 行为不一致。
缺陷 2：无法分层管理
- 问题：系统提示词是"扁平"的，无法区分"项目级规则"、"团队级规则"、"个人偏好"。
- 后果：当需要调整规则时，你必须修改一个巨大的提示词字符串，容易引入错误。
缺陷 3：上下文窗口占用
- 问题：详细的提示词可能占用 500-1000 个 token。在长对话中，这些 token 会挤占实际任务的上下文空间。
- 后果：AI 的推理质量下降，因为它可用于"理解任务"的 token 变少了。
4.3 行为约束体系的优势
相比之下，行为约束体系（以 CLAUDE.md 为代表）具有以下优势：
| 维度 | 提示工程 | 行为约束体系（CLAUDE.md） |
|---|---|---|
| 持久化 | ❌ 每次对话需重新输入 | ✅ 文件保存在项目中，自动加载 |
| 分层管理 | ❌ 扁平结构 | ✅ 支持项目级、团队级、个人级规则 |
| 上下文占用 | ❌ 占用 token | ✅ 按需加载，智能缓存 |
| 版本控制 | ❌ 无法追踪变更 | ✅ 可提交到 Git，支持 code review |
| 团队协作 | ❌ 每个人的提示词不同 | ✅ 统一规则文件，行为一致 |
核心结论：提示工程是"软约束"（AI 可以选择忽略），而行为约束体系是"硬约束"（通过文件系统和加载机制强制执行）。
5. Karpathy Skills 项目：用行为约束替代模糊提示
5.1 项目起源：从吐槽到工程规范
andrej-karpathy-skills 项目并非 Andrej Karpathy 本人创建，而是由开发者 Forrest Chang（GitHub: forrestchang）基于 Karpathy 对 AI 编程失败模式的公开吐槽整理而成。
项目核心洞察：
"Karpathy 没有发明新技术。他只是把'AI 编程助手的失败模式'翻译成了一组可以通过配置文件强制执行的行为规则。结果是：一个 200 行的 CLAUDE.md 文件，比 2000 行的提示词工程更有效。"
项目结构
andrej-karpathy-skills/
├── CLAUDE.md # 核心规则文件（200 行）
├── README.md # 使用说明
├── examples/ # 正反案例对比
│ ├── bad_example.py # 展示"过度工程"的危害
│ └── good_example.py # 展示"最小实现"的优势
└── tests/ # 规则验证测试
GitHub 增长数据
- 2026 年 5 月 16 日：项目发布，首日获得 3000+ Star。
- 2026 年 5 月 17 日：突破 10000+ Star（增速超过 PyTorch、TensorFlow 同期）。
- 2026 年 5 月 18 日：突破 13000+ Star，成为 GitHub Trending #1。
为什么增长如此迅猛？
因为项目解决了一个"每个人都遇到但没人系统化解决"的问题。
5.2 四大原则的技术实现
Karpathy Skills 项目的核心是 四大原则，对应解决四大失败模式。以下是每个原则的技术实现细节。
原则 1：先思考再编码（Think Before Coding）
目标：解决"静默假设"问题。
实现方式：
# CLAUDE.md
## 原则 1：先思考再编码
### 执行流程
1. **需求澄清**：遇到模糊需求时，必须提出 2-3 个澄清问题。
2. **方案对比**：提出 2 种实现方案（简单 vs 复杂），让用户选择。
3. **风险评估**：列出潜在风险（性能、安全、可维护性），等待用户确认。
### 示例代码
**错误示例**（静默假设）：
```python
# 用户需求："添加缓存"
# AI 直接实现（假设使用 Redis + 序列化 + 分布式锁）
import redis
import pickle
import threading
class DistributedCache:
def __init__(self, redis_url):
self.client = redis.from_url(redis_url)
self.lock = threading.RLock()
def get(self, key):
with self.lock:
data = self.client.get(key)
return pickle.loads(data) if data else None
# ... 100 行
正确示例（先思考）：
# 用户需求："添加缓存"
# AI 先提问：
"我需要澄清几个问题：
1. 这是 Web 应用还是 CLI 工具？
2. 需要分布式缓存吗？还是单机内存缓存就够了？
3. 缓存失效策略是什么？（TTL、LRU、手动失效）
4. 需要缓存穿透/击穿保护吗？
我可以提供两种方案：
- 方案 A（简单）：使用 `functools.lru_cache`，10 行代码，适合单机。
- 方案 B（复杂）：使用 Redis + 序列化，适合分布式场景。
你希望哪种？"
---
#### 原则 2：最小实现优先（Minimum Viable Implementation）
**目标**：解决"过度工程"问题。
**实现方式**：
```markdown
## 原则 2：最小实现优先
### 代码量预算
- 单个函数：≤ 50 行
- 单个类：≤ 200 行
- 单个模块：≤ 500 行
超过预算时，必须：
1. 提出重构方案（拆分函数/类）
2. 等待用户确认
3. 分步实施
### 禁止模式
- ❌ 建造者模式（除非构造参数 > 4 个）
- ❌ 抽象工厂（除非项目已使用依赖注入框架）
- ❌ 多层继承（> 2 层）
- ❌ 函数式编程的过度抽象（如嵌套 monad）
### 优先选择
- ✅ 简单的过程式代码
- ✅ 纯函数（无副作用）
- ✅ 显式错误处理（而非异常捕获）
原则 3：任务边界严格隔离（Strict Scope Isolation）
目标：解决"范围蔓延"问题。
实现方式：
## 原则 3：任务边界严格隔离
### diff 预算
- 单次任务的代码变更（diff）≤ 20 行
- 超过 20 行时，必须拆分任务
### 禁止操作
- ❌ 修改需求范围外的代码
- ❌ "顺手"重构相邻函数
- ❌ 统一格式化（除非用户明确要求）
- ❌ 重命名变量（除非命名错误）
### Git 提交规范
- 每次任务 = 一次 Git 提交
- 提交信息格式：`[类型]: #任务编号 描述`
- 类型：`feat`、`fix`、`refactor`、`test`、`docs`
- 示例：`fix: #123 修复整数溢出 bug`
原则 4：验证标准前置定义（Define Verification Before Implementation）
目标：解决"缺乏验证"问题。
实现方式：
## 原则 4：验证标准前置定义
### 测试驱动开发（TDD）流程
1. **写测试**：先编写单元测试，覆盖边界情况
2. **跑测试**：确认测试失败（红）
3. **写实现**：编写最小实现代码
4. **跑测试**：确认测试通过（绿）
5. **重构**：优化代码，保持测试通过（重构）
### 边界情况清单（必须测试）
- [ ] 空输入（None、""、[]、{}）
- [ ] 超长输入（字符串 > 1000 字符）
- [ ] 特殊字符（Unicode、emoji、SQL 注入、XSS）
- [ ] 数值边界（0、负数、MAX_INT）
- [ ] 并发安全（如果涉及共享状态）
### 验证证据
任务完成时，必须提供：
- 测试运行结果（pytest 输出）
- 代码覆盖率报告（≥ 80%）
- 静态分析报告（pylint、mypy）
6. CLAUDE.md 深度解析：AI Agent 的长期记忆系统
6.1 CLAUDE.md 的本质：永久系统指令
CLAUDE.md 是 Claude Code（Anthropic 的 AI 编程助手）特有的配置文件，其本质是：
一段会被自动注入到对话上下文里的"永久系统指令"。
与系统提示词的区别
| 维度 | 系统提示词 | CLAUDE.md |
|---|---|---|
| 加载时机 | 每次对话开始时手动输入 | 进入项目目录时自动加载 |
| 持久化 | 存储在对话历史中 | 存储在项目文件系统中 |
| 版本控制 | 无法版本化 | 可提交到 Git |
| 作用域 | 当前对话 | 当前项目（所有对话） |
技术实现机制
Claude Code 的加载逻辑（简化版）：
# Claude Code 内部逻辑（伪代码）
def load_context(project_path: Path) -> str:
"""加载项目上下文"""
context_parts = []
# 1. 加载项目级 CLAUDE.md
project_claude_md = project_path / "CLAUDE.md"
if project_claude_md.exists():
context_parts.append(project_claude_md.read_text())
# 2. 加载子目录的 CLAUDE.md（递归）
for subdir in project_path.rglob("CLAUDE.md"):
if subdir != project_claude_md:
context_parts.append(subdir.read_text())
# 3. 加载用户级 ~/.claude/CLAUDE.md
user_claude_md = Path.home() / ".claude" / "CLAUDE.md"
if user_claude_md.exists():
context_parts.append(user_claude_md.read_text())
# 4. 合并所有部分，注入到系统提示词中
return "\n\n".join(context_parts)
关键点：
- CLAUDE.md 的内容会被 自动注入 到每次对话的系统提示词中。
- 不需要手动复制粘贴。
- 支持 分层加载（项目级 → 子目录级 → 用户级）。
6.2 加载机制与优先级
CLAUDE.md 的加载遵循 "就近原则"：
项目结构示例：
my-project/
├── CLAUDE.md # 项目级规则（优先级最低）
├── src/
│ ├── CLAUDE.md # 子目录级规则（优先级中等）
│ └── utils/
│ └── CLAUDE.md # 更深层级的规则（优先级最高）
└── tests/
└── CLAUDE.md # 测试目录的规则
加载顺序
- 用户级（~/.claude/CLAUDE.md）：全局默认规则。
- 项目级（项目根目录的 CLAUDE.md）：项目通用规则。
- 子目录级（各子目录的 CLAUDE.md）：局部覆盖规则。
冲突解决
当多个 CLAUDE.md 存在冲突时，深层级的规则覆盖浅层级的规则。
示例：
# ~/.claude/CLAUDE.md（用户级）
## 代码风格
- 使用 4 空格缩进
# my-project/CLAUDE.md（项目级）
## 代码风格
- 使用 2 空格缩进
# my-project/src/CLAUDE.md（子目录级）
## 代码风格
- 使用 Tab 缩进
最终结果：my-project/src/ 目录下的文件使用 Tab 缩进，项目其他部分使用 2 空格缩进。
6.3 规则分层架构
在生产环境中，推荐采用 三层规则架构：
┌─────────────────────────────────────────┐
│ 用户级 (~/.claude/CLAUDE.md) │ ← 个人偏好（代码风格、编辑器配置）
├─────────────────────────────────────────┤
│ 项目级 (my-project/CLAUDE.md) │ ← 项目通用规则（技术栈、架构模式）
├─────────────────────────────────────────┤
│ 团队级 (my-project/.github/CLAUDE.md) │ ← 团队规范（Git 工作流、Code Review）
└─────────────────────────────────────────┘
各层的职责
| 层级 | 文件路径 | 职责 | 示例内容 |
|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 个人偏好 | 代码风格、编辑器配置、常用快捷键 |
| 项目级 | my-project/CLAUDE.md | 项目通用规则 | 技术栈、依赖管理、构建流程 |
| 团队级 | my-project/.github/CLAUDE.md | 团队协作规范 | Git 工作流、Code Review 检查清单、CI/CD 配置 |
实战配置示例
用户级（~/.claude/CLAUDE.md）：
# 个人偏好设置
## 代码风格
- 使用 2 空格缩进
- 最大行宽：88 字符（遵循 Black 规范）
- 引号风格：双引号（"）
## 编辑器配置
- 默认编辑器：vim
- 终端：Alacritty + zsh
## 个人习惯
- 喜欢表格对比（而非段落描述）
- 喜欢代码示例（而非抽象描述）
项目级（my-project/CLAUDE.md）：
# 项目通用规则
## 技术栈
- 语言：Python 3.12+
- Web 框架：FastAPI
- 数据库：PostgreSQL + SQLAlchemy
- 缓存：Redis
- 任务队列：Celery
## 架构模式
- 分层架构：Controller → Service → Repository
- 依赖注入：使用 `dependency-injector` 库
- 配置管理：使用 `pydantic-settings`
## 禁止事项
- ❌ 不使用 Django（项目已选择 FastAPI）
- ❌ 不使用 SQLite（生产环境必须用 PostgreSQL）
- ❌ 不使用全局变量（配置除外）
团队级（my-project/.github/CLAUDE.md）：
# 团队协作规范
## Git 工作流
- 主分支：`main`（保护分支，需要 PR）
- 开发分支：`develop`
- 功能分支：`feature/xxx`
- 提交信息格式：`[类型]: #ISSUE_ID 描述`
## Code Review 检查清单
- [ ] 代码是否符合项目级 CLAUDE.md 的规则？
- [ ] 测试覆盖率是否 ≥ 80%？
- [ ] 是否有性能回归？（运行 benchmark）
- [ ] 是否有安全漏洞？（运行 bandit）
## CI/CD 配置
- 自动运行：`pytest`、`pylint`、`mypy`
- 自动部署：合并到 `main` 后自动部署到生产环境
7. 实战：从零构建生产级 CLAUDE.md
在本节中，我们将通过一个完整的实战案例，展示如何从零开始构建一个生产级的 CLAUDE.md 文件。
7.1 项目背景与技术栈约束
项目背景：
- 项目名称：FastAPI Blog Platform（一个基于 FastAPI 的博客平台）
- 功能需求：用户认证、文章发布、评论系统、标签分类、全文搜索
- 技术栈：Python 3.12、FastAPI、PostgreSQL、Redis、Celery
技术栈约束（必须在 CLAUDE.md 中明确）：
# FastAPI Blog Platform - CLAUDE.md
## 项目定位
一个基于 FastAPI 的现代化博客平台，支持用户认证、文章发布、评论系统、标签分类、全文搜索。
目标用户：个人博主、技术团队知识库
应用场景：生产环境（需要高可用、高性能、高安全性）
## 技术栈（硬约束，不可更改）
### 后端
- **语言**：Python 3.12+（类型提示必须完整）
- **Web 框架**：FastAPI（不使用 Flask/Django）
- **ORM**：SQLAlchemy 2.0（不使用 Django ORM）
- **数据库**：PostgreSQL 16（不使用 MySQL/SQLite）
- **缓存**：Redis 7（不使用 Memcached）
- **任务队列**：Celery（不使用 RQ/APScheduler）
- **认证**：JWT（使用 `python-jose` 库）
### 前端（可选，由前端团队负责）
- **框架**：React 19（不使用 Vue/Angular）
- **构建工具**：Vite（不使用 Webpack）
- **UI 库**：Shadcn/UI（不使用 Material-UI/Ant Design）
### 基础设施
- **容器化**：Docker + Docker Compose（不使用 Kubernetes，单实例部署）
- **反向代理**：Nginx（不使用 Caddy/Apache）
- **监控**：Prometheus + Grafana（不使用 New Relic）
- **日志**：JSON 格式，输出到 stdout（使用 `structlog` 库）
## 禁止事项（违反即拒绝合并）
### 技术选型禁止
- ❌ 不使用 Django（已选择 FastAPI）
- ❌ 不使用 SQLite（生产环境必须用 PostgreSQL）
- ❌ 不使用全局变量（配置除外，使用 `pydantic-settings`）
- ❌ 不使用 `print()` 调试（必须使用 `structlog`）
- ❌ 不使用 `except Exception:` 裸异常捕获（必须捕获具体异常类型）
### 架构禁止
- ❌ 不允许跨层调用（Controller 不能直接调用 Repository）
- ❌ 不允许循环依赖（使用 `importlib` 解决）
- ❌ 不允许在 Model 层写业务逻辑（必须使用 Service 层）
7.2 核心规则编写
基于 Karpathy 的四大原则，我们为该项目编写核心规则。
## 核心规则（基于 Karpathy 四大原则）
### 原则 1：先思考再编码
#### 执行流程
1. **需求澄清**：遇到模糊需求时，必须提出 2-3 个澄清问题。
2. **方案对比**：提出 2 种实现方案（简单 vs 复杂），让用户选择。
3. **风险评估**：列出潜在风险（性能、安全、可维护性），等待用户确认。
#### 示例：用户认证功能的实现
**错误示例**（静默假设）：
```python
# 用户需求："添加用户认证"
# AI 直接实现（假设使用 OAuth 2.0 + JWT + RBAC）
from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import JWTError, jwt
from passlib.context import CryptContext
# ... 200 行代码
正确示例（先思考）：
# 用户需求："添加用户认证"
# AI 先提问：
"""
我需要澄清几个问题：
1. **认证方式**：
- 方案 A：邮箱 + 密码（简单，适合个人博客）
- 方案 B：OAuth 2.0（Google、GitHub 登录，适合团队知识库）
- 方案 C：邮箱 + 密码 + OAuth 2.0（复杂，适合多用户场景）
2. **会话管理**：
- 方案 A：JWT Token（无状态，适合分布式）
- 方案 B：Session + Redis（有状态，适合单机）
3. **权限控制**：
- 需要 RBAC（角色权限控制）吗？
- 需要邮箱验证吗？
- 需要密码重置功能吗？
请告诉我你的选择，我再开始实现。
"""
原则 2：最小实现优先
代码量预算
- 单个函数：≤ 50 行
- 单个类：≤ 200 行
- 单个模块：≤ 500 行
禁止模式
# ❌ 错误示例：过度工程（建造者模式）
class UserBuilder:
"""用户对象建造者（过度抽象）"""
def __init__(self):
self._username = None
self._email = None
self._password = None
def set_username(self, username):
self._username = username
return self
def set_email(self, email):
self._email = email
return self
def build(self):
return User(
username=self._username,
email=self._email,
password=self._password
)
# ✅ 正确示例：最小实现
user = User(username="alice", email="alice@example.com")
优先选择
- ✅ 简单的过程式代码
- ✅ 纯函数（无副作用）
- ✅ 显式错误处理（而非异常捕获）
# ✅ 好的示例：显式错误处理
def divide(a: float, b: float) -> float:
"""除法（显式错误处理）"""
if b == 0:
raise ValueError("除数不能为 0")
return a / b
# ❌ 坏的示例：异常捕获过于宽泛
def divide(a: float, b: float) -> float:
"""除法（裸异常捕获）"""
try:
return a / b
except Exception: # ❌ 捕获所有异常（包括 KeyboardInterrupt）
return 0
原则 3：任务边界严格隔离
diff 预算
- 单次任务的代码变更（diff）≤ 20 行
- 超过 20 行时，必须拆分任务
禁止操作
# ❌ 错误示例：范围蔓延
# 用户需求："修复 divide() 里的整数溢出 bug"
# AI 的修改（范围蔓延）：
def divide(a: float, b: float) -> float:
"""修复整数溢出 bug"""
if b == 0:
raise ValueError("除数不能为 0")
return a / b
# AI "顺手"修改的其他内容（不在需求范围内）：
def multiply(a: float, b: float) -> float: # 重命名了函数
"""乘法（还加了类型提示）"""
return a * b
# 还修改了测试文件、README、配置文件...
正确做法：只修复 bug，不修改其他内容。
原则 4：验证标准前置定义
测试驱动开发（TDD）流程
# 步骤 1：先写测试（红）
import pytest
from app.services.math import divide
def test_divide_normal():
"""测试正常除法"""
assert divide(10, 2) == 5.0
def test_divide_by_zero():
"""测试除数为 0"""
with pytest.raises(ValueError):
divide(10, 0)
def test_divide_float():
"""测试浮点数除法"""
assert divide(10, 3) == pytest.approx(3.333333, rel=1e-6)
# 步骤 2：运行测试（确认失败）
# $ pytest test_math.py
# FAILED test_divide_normal (divide 未实现)
# 步骤 3：写实现（绿）
def divide(a: float, b: float) -> float:
"""除法"""
if b == 0:
raise ValueError("除数不能为 0")
return a / b
# 步骤 4：运行测试（确认通过）
# $ pytest test_math.py
# PASSED
# 步骤 5：重构（保持测试通过）
# ...
边界情况清单（必须测试）
def test_divide_edge_cases():
"""测试边界情况"""
# 空输入（不适用，因为类型提示是 float）
# 超长输入（不适用，因为 float 有固定范围）
# 特殊字符（不适用，因为输入是数字）
# 数值边界
assert divide(1e308, 1) == 1e308 # 最大浮点数
assert divide(1e-308, 1) == 1e-308 # 最小正浮点数
# 负数
assert divide(-10, 2) == -5.0
# 0 除以任何数
assert divide(0, 10) == 0.0
7.3 验证标准前置定义
在 CLAUDE.md 中，我们需要前置定义验证标准，确保 AI 生成的代码是可测试的。
## 验证标准（必须执行）
### 单元测试要求
- **覆盖率**：≥ 80%
- **测试框架**：pytest
- **测试文件命名**：`test_<模块名>.py`
- **测试函数命名**：`test_<功能>_<场景>()`
### 集成测试要求
- **API 测试**：使用 `httpx` + `pytest`
- **数据库测试**：使用 `pytest-postgresql`（临时数据库）
- **缓存测试**：使用 `fakeredis`（模拟 Redis）
### 静态分析要求
- **类型检查**：mypy（必须 0 错误）
- **代码风格**：pylint（评分 ≥ 8.0）
- **安全扫描**：bandit（必须 0 高危漏洞）
### 性能要求
- **API 响应时间**：≤ 200ms（P95）
- **数据库查询**：≤ 100ms（使用 `sqlalchemy-query-profiler`）
- **缓存命中率**：≥ 90%
### 验证证据（任务完成时必须提供）
- [ ] 单元测试运行结果（`pytest` 输出）
- [ ] 代码覆盖率报告（`pytest --cov` 输出）
- [ ] 静态分析报告（`mypy`、`pylint`、`bandit` 输出）
- [ ] 性能基准测试结果（`pytest-benchmark` 输出）
7.4 完整示例代码
让我们将上述规则整合到一个完整的 CLAUDE.md 文件中。
文件：/my-project/CLAUDE.md
# FastAPI Blog Platform - CLAUDE.md
> **本文件定义了项目的开发规范、技术栈约束、行为规则。**
> **AI 代理在每次对话开始前必须读取并遵守这些规则。**
---
## 项目定位
一个基于 FastAPI 的现代化博客平台，支持用户认证、文章发布、评论系统、标签分类、全文搜索。
- **目标用户**：个人博主、技术团队知识库
- **应用场景**：生产环境（需要高可用、高性能、高安全性）
---
## 技术栈（硬约束，不可更改）
### 后端
- **语言**：Python 3.12+（类型提示必须完整）
- **Web 框架**：FastAPI（不使用 Flask/Django）
- **ORM**：SQLAlchemy 2.0（不使用 Django ORM）
- **数据库**：PostgreSQL 16（不使用 MySQL/SQLite）
- **缓存**：Redis 7（不使用 Memcached）
- **任务队列**：Celery（不使用 RQ/APScheduler）
- **认证**：JWT（使用 `python-jose` 库）
### 前端（可选）
- **框架**：React 19（不使用 Vue/Angular）
- **构建工具**：Vite（不使用 Webpack）
- **UI 库**：Shadcn/UI（不使用 Material-UI/Ant Design）
---
## 核心规则（基于 Karpathy 四大原则）
### 原则 1：先思考再编码
**执行流程**：
1. 遇到模糊需求时，必须提出 2-3 个澄清问题。
2. 提出 2 种实现方案（简单 vs 复杂），让用户选择。
3. 列出潜在风险（性能、安全、可维护性），等待用户确认。
**示例**：
用户："添加用户认证功能"
AI 应先提问：
我需要澄清几个问题：
认证方式：
- 方案 A：邮箱 + 密码（简单，适合个人博客）
- 方案 B：OAuth 2.0（Google、GitHub 登录）
- 方案 C：邮箱 + 密码 + OAuth 2.0（多用户场景）
会话管理：
- 方案 A：JWT Token（无状态）
- 方案 B：Session + Redis（有状态）
需要 RBAC 权限控制吗？需要邮箱验证吗？
请告诉我你的选择。
---
### 原则 2：最小实现优先
**代码量预算**：
- 单个函数：≤ 50 行
- 单个类：≤ 200 行
- 单个模块：≤ 500 行
**禁止模式**：
- ❌ 建造者模式（除非构造参数 > 4 个）
- ❌ 抽象工厂（除非项目已使用依赖注入框架）
- ❌ 多层继承（> 2 层）
**优先选择**：
- ✅ 简单的过程式代码
- ✅ 纯函数（无副作用）
- ✅ 显式错误处理（而非异常捕获）
---
### 原则 3：任务边界严格隔离
**diff 预算**：
- 单次任务的代码变更（diff）≤ 20 行
- 超过 20 行时，必须拆分任务
**禁止操作**：
- ❌ 修改需求范围外的代码
- ❌ "顺手"重构相邻函数
- ❌ 统一格式化（除非用户明确要求）
**Git 提交规范**：
- 每次任务 = 一次 Git 提交
- 提交信息格式：`[类型]: #任务编号 描述`
- 类型：`feat`、`fix`、`refactor`、`test`、`docs`
---
### 原则 4：验证标准前置定义
**测试驱动开发（TDD）流程**：
1. 写测试（红）
2. 跑测试（确认失败）
3. 写实现（绿）
4. 重构（保持测试通过）
**边界情况清单（必须测试）**：
- [ ] 空输入（None、""、[]、{}）
- [ ] 超长输入（字符串 > 1000 字符）
- [ ] 特殊字符（Unicode、emoji、SQL 注入、XSS）
- [ ] 数值边界（0、负数、MAX_INT）
- [ ] 并发安全（如果涉及共享状态）
**验证证据（任务完成时必须提供）**：
- [ ] 单元测试运行结果（`pytest` 输出）
- [ ] 代码覆盖率报告（≥ 80%）
- [ ] 静态分析报告（`mypy`、`pylint`、`bandit`）
---
## 禁止事项（违反即拒绝合并）
### 技术选型禁止
- ❌ 不使用 Django（已选择 FastAPI）
- ❌ 不使用 SQLite（生产环境必须用 PostgreSQL）
- ❌ 不使用全局变量（配置除外）
- ❌ 不使用 `print()` 调试（必须使用 `structlog`）
- ❌ 不使用 `except Exception:` 裸异常捕获
### 架构禁止
- ❌ 不允许跨层调用（Controller → Repository 不允许）
- ❌ 不允许循环依赖
- ❌ 不允许在 Model 层写业务逻辑（必须使用 Service 层）
---
## 验证标准（必须执行）
### 单元测试要求
- **覆盖率**：≥ 80%
- **测试框架**：pytest
- **测试文件命名**：`test_<模块名>.py`
### 静态分析要求
- **类型检查**：mypy（必须 0 错误）
- **代码风格**：pylint（评分 ≥ 8.0）
- **安全扫描**：bandit（必须 0 高危漏洞）
### 性能要求
- **API 响应时间**：≤ 200ms（P95）
- **数据库查询**：≤ 100ms
- **缓存命中率**：≥ 90%
---
## 附录：常见问题
### Q1：为什么不使用 Django？
A：项目已选择 FastAPI，保持技术栈一致性。
### Q2：为什么测试覆盖率要求 ≥ 80%？
A：根据行业最佳实践，80% 是"高覆盖率"与"维护成本"的平衡点。
### Q3：为什么禁止使用 `print()` 调试？
A：生产环境中，`print()` 输出到 stdout，难以过滤和搜索。必须使用结构化日志（`structlog`）。
---
**最后更新**：2026-05-23
**维护者**：FastAPI Blog Platform 团队
8. 团队协作：AGENTS.md 与 CLAUDE.md 的分工
在实际团队开发中，除了 CLAUDE.md，你可能还会遇到 AGENTS.md。这两个文件有什么区别？如何分工？
8.1 AGENTS.md 与 CLAUDE.md 的区别
| 维度 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 目标用户 | 所有 AI Agent（OpenClaw、Claude Code、Cursor...） | Claude Code 专用 |
| 文件格式 | 通用 Markdown | 通用 Markdown |
| 加载机制 | AI Agent 自动识别 | Claude Code 自动加载 |
| 适用场景 | 跨平台团队协作 | Claude Code 用户 |
8.2 推荐分工
my-project/
├── AGENTS.md # 通用规则（所有 AI Agent 都遵守）
├── CLAUDE.md # Claude Code 特有规则
└── .cursor/
└── rules.md # Cursor 特有规则（如果需要）
AGENTS.md 的内容（通用规则）：
# AGENTS.md - 通用 AI Agent 规则
## 项目结构
- `src/`：源代码
- `tests/`：测试代码
- `docs/`：文档
## 模块边界
- `src/models/`：数据模型（纯数据结构，无业务逻辑）
- `src/services/`：业务逻辑（无 HTTP 请求/响应）
- `src/api/`：API 路由（无业务逻辑）
## Git 协作
- 主分支：`main`（保护分支）
- 提交信息格式：`[类型]: #ISSUE_ID 描述`
CLAUDE.md 的内容（Claude Code 特有规则）：
# CLAUDE.md - Claude Code 特有规则
## Claude Code 功能配置
- 启用 Code Execution 工具
- 启用 File Read/Write 工具
- 禁用 Web Search 工具（避免泄露内部信息）
## Claude Code 行为规则
- 遇到模糊需求时，先提出澄清问题
- 保持代码简单（YAGNI、KISS）
- 不要修改需求范围外的代码
8.3 团队协作最佳实践
- AGENTS.md 提交到 Git：所有团队成员共享。
- CLAUDE.md 可选提交到 Git：如果团队统一使用 Claude Code，可以提交；否则加入
.gitignore。 - 个人偏好不提交到 Git：每个开发者可以有自己的
~/.claude/CLAUDE.md，存储个人偏好（代码风格、编辑器配置）。
9. 性能优化：上下文窗口与 Token 成本管理
在使用 CLAUDE.md 时，一个常见的问题是：如果规则文件很长（如 2000 行），会不会占用太多上下文窗口？
答案是：会，但可以通过优化策略缓解。
9.1 上下文窗口占用分析
假设你的 CLAUDE.md 有 2000 行（约 8000 个 token），而 Claude 的上下文窗口是 200,000 个 token。看起来占用不高（4%），但问题是：
- 长对话中，上下文会累积：随着对话进行，上下文窗口会被历史消息占满。
- 规则文件每次都加载：每次新对话，CLAUDE.md 的内容都会占用一部分上下文。
9.2 优化策略
策略 1：规则分层（已介绍）
把规则分成三层：
- 用户级（个人偏好，短）
- 项目级（项目通用规则，中等）
- 团队级（团队协作规范，长）
好处：AI 可以根据任务类型，只加载相关层级的规则。
策略 2：惰性加载（Lazy Loading）
只有在需要时才加载特定规则。
示例：
# CLAUDE.md
## 规则索引（简短）
- 技术栈约束 → 见 `rules/tech_stack.md`
- 代码风格规范 → 见 `rules/code_style.md`
- Git 工作流 → 见 `rules/git_workflow.md`
（AI 只有在需要时才读取具体规则文件）
策略 3：规则压缩
使用简洁的语言，避免冗长的解释。
示例：
# ❌ 冗长版本（不推荐）
## 代码风格规范
在编写 Python 代码时，我们必须遵守 PEP 8 规范。PEP 8 是 Python Enhancement Proposal 8 的缩写，它定义了 Python 代码的命名规范、缩进规则、最大行宽等内容。具体来说：
1. 缩进必须使用 4 个空格（不能使用 Tab）
2. 最大行宽为 79 字符（超过需要换行）
3. 类名使用 PascalCase（如 `MyClass`）
...
# ✅ 简洁版本（推荐）
## 代码风格
- 缩进：4 空格
- 最大行宽：88 字符（遵循 Black 规范）
- 命名：PascalCase（类）、snake_case（函数/变量）
- 详见：https://pep8.org/
策略 4：使用外部文档链接
把详细的规范文档放到外部（如 Confluence、Notion），在 CLAUDE.md 中只保留链接。
# CLAUDE.md
## 详细规范
- 技术栈选型指南：https://wiki.company.com/tech-stack
- Git 工作流详解：https://wiki.company.com/git-workflow
- Code Review 检查清单：https://wiki.company.com/code-review
好处：不占用上下文窗口。
坏处：AI 需要访问外部链接（可能无权访问）。
9.3 Token 成本优化
如果你的团队使用付费 API（如 Claude API），那么 Token 成本是需要考虑的。
成本分析
假设：
- CLAUDE.md 占用 8000 个 token
- 每次对话平均 20 轮
- 每轮输入 1000 token、输出 500 token
- Claude API 价格：$3/1M input token、$15/1M output token
每次对话的成本：
- 输入：8000（CLAUDE.md）+ 20 × 1000（对话）= 28000 token = $0.084
- 输出：20 × 500 = 10000 token = $0.15
- 总计：$0.234/对话
如果一个团队有 10 个开发者，每天每个开发者 10 次对话，则 monthly 成本约为 $700。
优化建议
- 精简 CLAUDE.md：把 8000 token 压缩到 4000 token（节省 50%）。
- 使用缓存：Claude API 支持上下文缓存（Cache Control），可以复用之前的上下文。
- 本地模型：对于简单任务，使用本地模型（如 Llama 3、Mistral）替代 Claude API。
10. 行业影响：Skills 生态 vs MCP 协议
在 2026 年，AI 编程助手领域出现了两个重要的标准化趋势：
- Skills 生态（以 Karpathy Skills、OpenClaw Skills 为代表）
- MCP 协议（Model Context Protocol，Anthropic 提出）
10.1 Skills 生态
定义：Skills 是一种"行为规则 + 工具调用"的封装格式，允许 AI Agent 通过配置文件扩展能力。
核心特点：
- 基于文件系统（Markdown 文件）
- 支持分层加载
- 易于版本控制（可提交到 Git）
示例：
# my-skill/SKILL.md
---
name: database-query
description: 安全执行数据库查询（防止 SQL 注入）
---
## 规则
- 所有查询必须使用参数化查询（禁止字符串拼接）
- 禁止 `DROP TABLE`、`DELETE FROM`（除非明确授权）
- 查询超时时间：5 秒
## 工具
- `query(sql: str, params: list)`：执行参数化查询
- `explain(sql: str)`：分析查询性能
10.2 MCP 协议
定义：MCP（Model Context Protocol）是一种"AI Agent 与外部工具通信"的标准化协议，类似于 LSP（Language Server Protocol）。
核心特点：
- 基于 JSON-RPC 2.0
- 支持工具发现、工具调用、工具权限控制
- 与编程语言无关
示例：
// MCP 服务器（提供工具）
{
"method": "tools/list",
"params": {}
}
// 响应
{
"result": {
"tools": [
{
"name": "database_query",
"description": "执行参数化查询",
"inputSchema": {
"type": "object",
"properties": {
"sql": {"type": "string"},
"params": {"type": "array"}
}
}
}
]
}
}
10.3 Skills 与 MCP 的对比
| 维度 | Skills 生态 | MCP 协议 |
|---|---|---|
| 抽象层级 | 高层（行为规则 + 工具调用） | 底层（工具通信协议） |
| 易用性 | 高（Markdown 文件，易于编写） | 低（需要实现 JSON-RPC 服务器） |
| 灵活性 | 低（受限于文件格式） | 高（支持动态工具发现） |
| 标准化 | 低（各平台自定义） | 高（Anthropic 推动成为标准） |
| 适用场景 | 行为约束、项目规范 | 工具集成、跨平台通信 |
10.4 未来趋势：Skills + MCP 融合
许多团队开始尝试 "Skills 定义行为，MCP 提供工具" 的混合模式：
# my-skill/SKILL.md
## 规则（Skills 生态）
- 所有数据库查询必须使用参数化查询
## 工具（MCP 协议）
- `database_query`：通过 MCP 调用外部数据库
好处：
- Skills 提供"约束"（行为规范）
- MCP 提供"能力"（工具调用）
11. 总结与展望：AI 编程的下一个十年
11.1 本文回顾
在本文中，我们深度剖析了 AI 编码代理的四大核心失败模式：
- 静默假设（Silent Assumptions）
- 过度工程（Over-Engineering）
- 范围蔓延（Scope Creep）
- 缺乏验证（Lack of Verification）
并介绍了如何通过 Karpathy Skills 的行为约束体系 和 CLAUDE.md 的长期记忆系统 来解决这些问题。
核心结论：
"AI 编程助手的问题不是'不够聪明'，而是'缺乏纪律'。提示工程是'软约束'，行为约束体系是'硬约束'。只有用数学规则、结构化配置、可验证的标准把 AI 的'创造力'限制在工程可接受的边界内，我们才能真正把 AI 编程助手从'玩具'变成'生产基础设施'。"
11.2 行业影响
Karpathy Skills 项目的爆火，标志着 AI 编程助手从"模型能力竞赛"转向"工程纪律建设"。
三个关键趋势：
从"提示词工程"到"行为约束体系"：
- 提示词是"软约束"（AI 可以选择忽略）
- 行为约束是"硬约束"（通过文件系统强制执行）
从"单一 AI 助手"到"Skills 生态"：
- 开发者可以编写自己的 Skills（类似 VS Code 插件）
- Skills 市场将兴起（类似 npm、PyPI）
从"黑盒模型"到"可验证系统"：
- AI 生成的代码必须有测试
- AI 的行为必须有审计日志
11.3 未来展望
2027 年预测：
CLAUDE.md 成为行业标准：
- 类似
.eslintrc、pyproject.toml，每个项目都会有CLAUDE.md。 - GitHub 会在 UI 中展示项目的
CLAUDE.md（类似 README）。
- 类似
Skills 市场兴起：
- 开发者可以发布、分享、销售自己的 Skills。
- 类似 npm、PyPI，会出现"Skills 注册表"。
AI 编程助手纳入企业合规审计：
- 企业会要求 AI 编程助手生成"可审计日志"（谁在什么时候让 AI 做了什么）。
- 类似 GDPR，会出现"AI 编程助手的合规标准"。
11.4 行动建议
如果你是想引入 AI 编程助手的开发者，我的建议是：
从今天开始编写你的 CLAUDE.md：
- 不需要一步到位，先写 10 条最重要的规则。
- 逐步迭代（类似代码的重构）。
加入 Skills 社区：
- GitHub 搜索
andrej-karpathy-skills、openclaw-skills。 - 学习别人的规则，改进自己的。
- GitHub 搜索
测量 AI 编程助手的 ROI：
- 记录使用 AI 前后的开发时间、bug 数量、代码审查时间。
- 用数据证明 AI 编程助手的价值（或发现问题）。
参考资料
- Karpathy Skills 项目：https://github.com/forrestchang/andrej-karpathy-skills
- Claude Code 官方文档：https://docs.anthropic.com/claude-code
- OpenClaw 项目：https://github.com/openclaw/openclaw
- Andrej Karpathy 的 X 账号：https://twitter.com/karpathy
- AI 编码代理的四大失败模式（原始吐槽）：https://karpathy.github.io/2026/05/ai-coding-failures
关于作者
茄子（程序员茄子）
- 全栈开发者，AI 编程助手早期使用者
- 博客：https://www.chenxutan.com
- GitHub：https://github.com/chenxutan
免责声明：本文所述观点和代码示例仅供参考，实际生产环境中请根据项目需求调整。
全文完
如果本文对你有帮助，欢迎点赞、收藏、转发。
有任何问题，欢迎在评论区留言讨论。