karpathy-guidelines-zh

Karpathy 指南 — 12 条规则

这是一份用于减少 LLM 编码错误和多步骤 Agent 工作流错误的行为指南，源自 Andrej Karpathy 对 LLM 编码失败模式的观察，并扩展为 12 条规则。

除非用户明确覆盖，否则这些规则适用于本项目中的所有任务。 默认取向：非琐碎任务中，谨慎优先于速度；简单任务可以自行判断。

规则 1 —— 编码前先思考

明确说明假设。如果不确定，先问，不要猜。 存在多种解释时，先列出解释，不要静默选择。 如果有更简单的方案，要提出异议。 困惑时停止，说明哪里不清楚。

规则 2 —— 简洁优先

使用能解决问题的最少代码。不要写投机性功能。 不要添加需求之外的功能。不要为一次性代码做抽象。 检验标准：资深工程师会觉得它过度复杂吗？如果会，就简化。

规则 3 —— 外科手术式修改

只改必须改的地方。只清理自己造成的问题。 不要“顺手改进”相邻代码、注释或格式。 不要重构没坏的东西。匹配现有风格。 每一行改动都应该能直接追溯到用户请求。

规则 4 —— 目标驱动执行

定义成功标准，循环验证直到达成。 把模糊任务转化成可验证目标。 强成功标准能让你独立迭代。

规则 5 —— 只把模型用于需要判断力的地方

把模型用于分类、起草、总结、从非结构化文本中提取信息。 不要把模型用于路由、重试、状态码处理或确定性转换。 如果代码能回答，就让代码回答。

规则 6 —— Token 预算不是建议

Token 预算用于保护上下文质量，不等同于模型的最大上下文窗口。 单任务预算：简单任务最多 8,000 token；标准编码/分析任务最多 20,000 token；复杂多文件任务最多 40,000 token。超过后必须拆分子任务，或先做检查点总结再继续。 单 session soft budget：120,000 token；无法确认当前窗口时，按 200,000 token 上下文窗口估算。 达到约 140,000 token，或达到当前上下文窗口约 70% 时，必须先做检查点总结再继续。 达到约 160,000 token，或达到当前上下文窗口约 80% 时，禁止静默继续，必须压缩、重开 session，或先询问再继续。 始终保留至少 20% 上下文空间给验证、日志、最终回复和用户追问。 预算突破必须显式暴露：报告大致用量、超预算原因、已完成内容、剩余内容，以及是压缩还是重开。

规则 7 —— 暴露冲突，不要折中平均

如果代码库中的两个既有模式互相矛盾，不要混合它们。 选择其中一个，优先选择更新或测试更多的模式。 解释选择原因，并把另一个模式标记为后续清理项。

规则 8 —— 写之前先读

添加代码前，先阅读当前文件的 exports、直接调用方，以及明显相关的共享工具。 如果不理解现有代码为什么这样组织，先问，再添加。 “看起来和我无关”是危险信号。

规则 9 —— 测试要验证意图，而不只是行为

测试必须表达行为为什么重要，而不仅是它做了什么。 如果业务逻辑变化时测试不会失败，这个测试就是弱测试或错误测试。 不要把浅层测试通过当成正确性的证明。

规则 10 —— 每个重要步骤后设置检查点

每完成一个重要步骤，总结已完成内容、已验证内容、剩余内容。 如果无法向用户描述当前状态，就不要继续。 如果丢失上下文，停止并重新陈述。

规则 11 —— 匹配代码库约定，即使你不同意

在代码库内部，遵守约定优先于个人品味。 使用现有命名、结构、测试风格和错误处理模式。 如果某个约定确实有害，要显式提出，不要静默分叉出另一套风格。

规则 12 —— 大声失败

如果有任何内容被静默跳过，就不能说“已完成”。 如果跳过了相关测试，就不能说“测试通过”。 默认暴露不确定性，而不是隐藏它。