这是一套旨在将 AI 编程助手（如 Claude）的错误率从 41% 降至 3% 的 CLAUDE.md 指令规范。既保留了 Karpathy 提出的 4 条基础代码编写原则，又补充了 8 条面向 AI 代理协作的高级规则，并对每一条都给出可操作的说明。
一、Karpathy 的 4 条基础规则（针对代码编写）
这些规则从根本上改变“人给指令，AI 写代码”的模式，强调思考、克制、精准和目标导向。
规则 1：编码前先思考 (Think Before Coding)
不要急于生成代码，先把问题想清楚。
- 明确陈述假设：你依赖的环境、版本、业务前提要显式写出来，例如“假设用户已登录且 token 有效”。
- 不确定的地方要提问：遇到歧义需求时，主动列出模糊点并请人澄清，不要靠猜去填补空白。
- 提供多种解释：如果某个需求天然存在多种理解方式，列出 2~3 种可能，并说明各自的取舍。
- 反驳更简单的方法：如果你能想到一种明显更简单的实现路径，要主动提出并分析它是否可行，防止过度工程化。
规则 2：简约至上 (Simplicity First)
只解决问题本身，不要替未来做多余的决策。
- 只写能通过当前测试的最少代码，不添加任何“以后可能用到”的功能。
- 不写投机性功能：虽然某个扩展点以后可能有用，但今天没有明确需求就坚决不写。
- 不为单次使用的代码创建抽象：如果一个函数只被一个地方调用，且看不出复用的必然性，就不要提取成通用库。
规则 3：外科手术式修改 (Surgical Changes)
每一次变更都要像外科手术一样精准，只碰必须碰的部分。
- 只修改与任务直接相关的行、函数或模块。
- 不要顺手“优化”无关的代码、注释、格式；即便是明显的坏味道，如果不影响当前任务，也留在下一次专门的重构里。
- 即使发现有更优写法，只要原有代码仍在正常工作，就不要去修复“没坏的东西”。
- 严格匹配现有代码风格（缩进、命名、注释习惯），让 diff 干净到只能看到业务逻辑的变化。
规则 4：目标驱动执行 (Goal-Driven Execution)
告诉 AI “成功长什么样”，而不是手把手教它怎么走路。
- 为任务定义一个可验证的成功标准（例如“所有单测通过并且输出日志里不出现 ERROR”）。
- 不要给 Claude 逐步操作清单，而是说明最终状态，让它自己规划并迭代。
- 形成“尝试 → 验证 → 调整”的闭环，直到成功标准被满足。
二、新增的 8 条高级规则（针对 AI 代理协作）
当 AI 不再是简单的代码补全工具，而是以“代理”身份参与协作时，需要这 8 条规则防止它越界、忘掉上下文或隐藏风险。
规则 5：仅将模型用于判断 (Judgment Calls Only)
模型只做它擅长的事，确定性逻辑留给代码。
- 负责：分类、草稿撰写、摘要提炼、语义理解、模式识别等需要“判断”的任务。
- 代码负责：路由分发、重试机制、确定性数据转换、精确计算等需要 100% 准确和可预测的逻辑。
不要让模型去计算 2+3，也不要让它决定哪个微服务处理请求——这是代码层的职责。
规则 6：严格的 Token 预算 (Hard Token Budgets)
像管理金钱一样管理上下文窗口，避免注意力稀释。
- 单次任务消耗上限：4,000 tokens；单次会话总计上限：30,000 tokens。
- 当接近预算时，必须在当前任务完成后，对已完成工作进行摘要压缩，并开启一个新会话继续，让关键信息浓缩传递，而不是让上下文无限膨胀。
- 这一规则强制养成“定期总结、重新对齐”的习惯，极大降低长链推理丢失关键信息的风险。
规则 7：暴露冲突而非中庸化 (Surface Conflicts)
遇到代码库中的模式冲突，不要缝合，要亮出来。
- 如果发现同一概念有两种互斥的实现方式（例如同时存在
snake_case和camelCase的命名），选择其中一种作为本次任务的标准，并在注释或消息中明确标记另一种为“待统一”。 - 严禁为了表面和谐而把两种风格混合在一起（Blend），那会让后续维护者完全不知道应该遵循哪一套。
- 这种显式暴露冲突的做法，让技术债务可见、可控。
规则 8：先读后写 (Read Before You Write)
每一次新增代码之前，必须先理解现有的依赖和接口，杜绝重复造轮子。
- 阅读将被调用函数的导出签名、上游调用者的用法、以及已有的共享工具库。
- 在 CLADE.md 或注释中记录你的发现：“已检查 utils/helper.ts，其中 formatDate 可复用，无需新写”。
- 这直接防止 AI 因不了解现有代码而写出功能重复的冗余代码，是降低错误率的关键。
规则 9：测试验证意图而非行为 (Tests Verify Intent)
测试的锚点是“为什么这么做”，不是“怎么做”。
- 测试名和断言必须直接反映业务意图，比如
should not allow checkout with expired coupon，而不是should call validateCoupon with false。 - 如果只是重构实现却导致测试大面积失败，那测试就是无效的——它耦合了实现细节而不是接口契约。
- 这种测试即使逻辑改变也能保持稳定，反过来保护重构的安全。
规则 10：重要步骤后设置检查点 (Checkpoints)
在多步流程中主动插入“心跳”，防止偏离主线。
- 每完成一个关键步骤（例如：环境搭建、数据迁移、算法实现），就向协作方/日志输出一条总结：已完成×，下一步将执行 Y，当前状态符合预期/存在偏差。
- 如果在任何时刻感到“逻辑跟丢”，立即停止当前操作，重述已知事实和目标，请求对齐。
- 这能防止连锁错误，把排查成本控制在最小单元。
规则 11：惯例胜过新奇 (Convention Beats Novelty)
融入现有代码库的习惯，比引入个人偏好重要得多。
- 即使你认为自己的写法更优雅、更现代，也必须服从项目当前的命名、文件结构、架构模式等既定惯例。
- 例如项目使用
snake_case命名变量，那么即使你钟爱camelCase，也要坚持用snake_case。 - 代码库的一致性价值远超单点处的新奇写法，因为它直接降低所有人的认知负荷。
规则 12：失败必须显性化 (Fail Loud)
不确定的成功等同于隐藏的炸弹，必须让它发出声响。
- 如果任务不能 100% 确认成功（例如：部分数据因权限不足未处理、某些测试因环境问题跳过、边缘情况未覆盖），必须在返回结果中显式说明。
- 严禁给出看起来 OK、实际上悄悄吞掉了异常的输出。失败要“大声”到无法被忽视。
- 这确保人和系统可以在第一时间处理不完整信息，而不是在数步之后才暴露一个难以追踪的故障。
这 12 条规则组合在一起，构成了一个严谨的 AI 协作契约：它既要求人类思考清楚、设定边界，也要求 AI 在约束下交出可信、可控、低噪声的代码。实践表明，严格执行这份 CLAUDE.md，代码生成的错误率可以从 41% 大幅压降到 3% 左右，将 AI 编程从“能写”真正推向“敢用”。
