karpathy-principles

模型会替你做出错误的假设， 然后不加核实就沿着这些假设一路执行。它们 不会处理自己的困惑，不会寻求澄清， 不会指出不一致之处，不会呈现 权衡，也不会在应该反对时提出异议。

（Andrej Karpathy，谈 Agent 式编码的失效模式）

这是什么

一份包含四项原则的约定，用于减少最常见的 大模型编码陷阱。精简的入口。每项 原则在 night-market 中都有深入探讨的技能； 这项技能是索引，而非百科全书。

推导过程：Forrest Chang （forrestchang/andrej-karpathy-skills，MIT）根据 Karpathy 的观察提炼而成。完整出处见 references/source-attribution.md。

何时使用

• 开始任何规模大于修正错别字的编码任务之前
• 代码审查期间，用来指出你看到的失效模式
• 编写完差异后，在宣称完成之前进行自我审查
• 培训初级工程师阅读 Agent 生成的差异时

何时不使用

这些原则倾向于谨慎，而非速度。对于 modules/tradeoff-acknowledgment.md 中列出的情况， 请自行判断：简单修复、探索性试验、 仅修改文档，以及有时间限制的原型。

四项原则

1. 编码前先思考

说明假设。指出困惑。让语气与 证据相符。

• 如果请求有多种解读， 请逐一列出。不要默默选定一种。
• 如果有更简单的方法，请说出来。若简单的做法才是正确的， 就提出异议。
• 如果有不清楚的地方，就停下来询问。隐藏的 假设是最容易预防、却最难在之后发现的 bug。
• 不要做出超出证据支持范围的断言。 谨慎校准语气，胜过自信地空谈。

深入探讨：使用 Skill(imbue:rigorous-reasoning) 防范 谄媚，使用 Skill(superpowers:brainstorming) 生成选项，使用 /spec-kit:speckit-clarify 命令深入厘清歧义。

2. 简单优先

用最少的代码解决问题。不做 推测性实现。

它们真的很喜欢把代码和 API 搞得过于复杂， 让抽象层臃肿不堪。

（Andrej Karpathy，谈同一条 Agent 式编码讨论串）

• 不添加超出要求的功能
• 不为只用一次的代码创建抽象
• 不添加未被要求的灵活性或可配置性
• 不为不可能发生的情形添加错误处理
• 如果你写了 200 行，而实际只需 50 行，就重写

自我检查：资深工程师会觉得这过于复杂吗？参见 modules/senior-engineer-test.md。

深入探讨：使用 Skill(imbue:scope-guard) 了解 价值判断公式和分支预算， 使用 Skill(leyline:additive-bias-defense) 了解每项新增内容 的举证责任， 使用 Skill(conserve:code-quality-principles) 了解 KISS / YAGNI / SOLID 基础原则。

记录权衡（决策日志）

当此步骤确定了一个存在实际备选方案的决策时，应趁思路清晰时将其记录到 docs/tradeoffs.md（先起草并确认）：

• 如果已安装 leyline，请调用 Skill(leyline:decision-journal) 并追加 一条权衡记录（包括决策、考虑过的选项，以及 放弃的内容；将 phase 设为 plan）。展示草稿；确认后再 追加。
• 备选方案（未安装 leyline 时）：按照文件内的 ENTRY TEMPLATE 追加到 docs/tradeoffs.md；分配下一个 TR-NNN ID。

3. 精准修改

只改必要内容。只清理自己造成的问题。

• 不要改进相邻代码、注释或格式
• 不要重构没有问题的内容
• 即使你会采用不同做法，也要遵循现有风格
• 除遵循现有风格外，还要遵循该模块对相关问题的既有处理方式。迁移过程中，使用目标模型，绝不要照搬已被取代的模型，即使后者占多数。参见 Skill(conserve:elegant-code) 第 2 阶
• 如果发现无关的死代码，提出来；不要删除
• 如果你的修改导致导入项或变量变成孤项，请移除这些由你造成的孤项。已有的死代码应保留，除非有人要求删除。

回溯测试：每一行改动都应能直接追溯到用户的请求。

深入了解：Skill(imbue:justify) 用于审查差异中的增量偏向，Skill(leyline:additive-bias-defense) 用于举证责任约定，bounded-discovery.md 规则用于限制读取预算。

4. 目标驱动执行

定义可验证的成功标准。循环执行，直到验证通过。

将模糊的任务转化为可检查的目标：

• “添加验证”变为“无效输入的测试通过”
• “修复 bug”变为“先编写复现 bug 的测试，再让测试通过”
• “重构 X”变为“前后测试均通过”
• “提高速度”变为“在 N 毫秒内完成基准测试 Y”

对于多步骤任务，每一步都要简要说明计划，并明确如何验证。明确的成功标准能让你独立循环推进。标准不明确则需要不断澄清。

完整的改写模板参见 modules/verifiable-goals.md。

深入了解：Skill(imbue:proof-of-work) 介绍铁律（先有失败测试，再进行实现），Skill(superpowers:test-driven-development) 介绍 RED-GREEN-REFACTOR 循环。

Karpathy 自检

交付前，请回答以下四个问题：

原则	问题
编码前先思考	我是否列出了假设，还是默默猜测？
简单优先	资深工程师会认为这过于复杂吗？
精准修改	每一行改动都能追溯到请求吗？
目标驱动执行	我能通过检查证明已完成，而不是凭感觉吗？

四个问题都回答“是”，就可以交付。否则就继续迭代。

模块

• modules/anti-patterns.md - 八条具名的偏离护栏，附修改前后的差异
• modules/senior-engineer-test.md - 包含三个问题的自检清单
• modules/verifiable-goals.md - 将模糊目标改写为可验证目标的模板，附示例
• modules/tradeoff-acknowledgment.md - 四项原则不适用时的处理方式

参考资料

• references/source-attribution.md - Karpathy 的主要引用来源、Forrest Chang 的推导、许可证及相关先例

相关技能

• Skill(imbue:scope-guard) - 值得性公式和分支预算
• Skill(imbue:proof-of-work) - 铁律 TDD 门槛
• Skill(imbue:rigorous-reasoning) - 防止谄媚和隐藏假设
• Skill(imbue:justify) - 审查差异中的增量偏向
• Skill(leyline:additive-bias-defense) - 每项新增内容都需承担举证责任
• Skill(conserve:code-quality-principles) - KISS、YAGNI、SOLID
• Skill(superpowers:test-driven-development) - RED-GREEN-REFACTOR
• Skill(superpowers:brainstorming) - 在做出决定前生成备选方案
• 完整的门槛技能协作图参见 docs/quality-gates.md#skill-level-quality-gate-composition（此技能是综合中心）

必需的进度项

作为预检门槛调用时，创建以下项：

• karpathy:assumptions-listed - 满足原则 1
• karpathy:simplicity-checked - 满足原则 2
• karpathy:trace-back-verified - 满足原则 3
• karpathy:success-criteria-defined - 满足原则 4

退出标准

• 四项原则都已通过具体产物作答（假设列表、范围依据、 差异跟踪、验证计划）。
• 至少应用过一次资深工程师测试。
• 在开始实施前，已写下可验证的成功标准。
• 权衡了实际备选方案时，已将选定方案及其简洁性取舍 记录到 docs/tradeoffs.md（或文件内模板）中。