oh-my-claudecode 的 Karpathy 编码纪律规则：Think Before Coding、极简实现与外科手术式改动实战指南

本篇指南围绕 oh-my-claudecode 仓库中内置的规则模板 templates/rules/karpathy-guidelines.md 展开，系统讲解如何把 Andrej Karpathy 对 LLM 编程常见失误的观察，落地为可被 Claude Code 自动加载并持续约束 Agent 行为的编码纪律。读完你将掌握：四条核心纪律（先思考再编码、极简优先、外科手术式改动、目标驱动执行）的完整内涵，以及如何借助 oh-my-claudecode 的规则注入机制（Rules Injector Hook）将本模板部署到自己的项目中，让规则在 Agent 读写文件时自动进入上下文。

模板定位：一套面向 LLM 的行为纪律，而非普通代码规范

在 oh-my-claudecode 仓库中，templates/rules/ 目录是提供给使用者的一整套"规则模板集"，它与常见的代码风格模板（如 coding-style.md 的不可变性、文件组织约定）不同：

• 它约束的不是"代码长什么样"，而是"Agent 在动手之前和动手过程中如何思考、如何决策"；
• 它的全部出发点来自 Andrej Karpathy 对 LLM 编程常见失误的观察（例如急于动手、过度设计、顺手"改进"无关代码、缺乏验收标准等）；
• 它的核心倾向是宁可谨慎、不要图快（bias toward caution over speed），因此文档开篇就声明：对于琐碎任务，请用判断力权衡，不必机械套用（"for trivial tasks, use judgment"）。

在 oh-my-claudecode 的多 Agent 协作体系（如 agents/ 中的 executor、critic、qa-tester 等角色）中，这类行为纪律模板的价值在于：让每个子 Agent 在自主执行时保持统一的"工程判断力"，避免 LLM 最常见的四类失误被放大。

四条核心纪律逐条拆解

1. Think Before Coding：先思考再编码

原文核心主张是 "不要假设、不要隐藏困惑、把权衡摊开"（Don't assume. Don't hide confusion. Surface tradeoffs.），并给出四条前置动作：

• 明确陈述你的假设，不确定就问；
• 如果存在多种解读，把它们摆出来，而不是默默替你选一个；
• 如果存在更简单的做法，直接说出来，该反驳就反驳；
• 如果哪里不清楚，停下来，说出困惑点，然后提问。

这一条的工程价值在于：LLM 的默认行为是"尽快产出可运行结果"，而这恰恰是产生方向性返工的根源。把假设显式化、把歧义显式化，是把"隐性错误"转化为"显性讨论"的第一步，也是后续"简单优先"与"外科手术式改动"能够成立的前提。

2. Simplicity First：最小可用，杜绝投机代码

原文的核心主张是 "解决该问题所需的最少代码，不做任何投机性扩展"（Minimum code that solves the problem. Nothing speculative.），并列出一组"禁止清单"：

• 不做需求之外的功能；
• 不为单次使用的代码造抽象；
• 不做没被要求的"灵活性"或"可配置性"；
• 不为不可能发生的场景写错误处理；
• 如果你写了 200 行而 50 行就能解决，重写它。

原文还给出一个自检问题："一位资深工程师会不会认为这过于复杂？" 如果会，就简化。（Would a senior engineer say this is overcomplicated? If yes, simplify.）

从源码层面看，oh-my-claudecode 自身也贯彻了这一纪律：例如 src/hooks/rules-injector/constants.ts 中的 PROJECT_MARKERS 只保留了 .git、pyproject.toml、package.json、Cargo.toml、go.mod、.venv 六个最通用的项目根标记；TRACKED_TOOLS 也仅包含 read、write、edit、multiedit 四个真正触发规则注入的工具。这种"只覆盖必要的表面"的取舍，正是 Simplicity First 的代码级体现。

3. Surgical Changes：只动必须动的，只清理自己的烂摊子

原文核心主张是 "只触碰必须触碰的；只清理你自己造成的问题"（Touch only what you must. Clean up only your own mess.），适用于所有对既有代码的修改：

• 不要顺手"改进"相邻代码、注释或格式；
• 不要重构没有坏掉的东西；
• 匹配既有风格，哪怕你自己会写得不一样；
• 如果发现无关的死代码，提出来，但不要删。

当你的修改产生孤儿（orphan）时：

• 移除你自己改动导致不再被使用的 import、变量、函数；
• 不要删除预先存在的死代码，除非被明确要求。

原文给出的检验标准是一句话：每一处被改动的行，都应能直接追溯到用户的请求（Every changed line should trace directly to the user's request）。

这条纪律对多 Agent 协作尤其重要：在 oh-my-claudecode 的团队模式下，多个 Agent 可能先后触碰同一批文件，如果每个 Agent 都"顺手装修"一番，diff 将无法审计、冲突将急剧放大。Surgical Changes 让每次改动都可溯源、可回滚。

4. Goal-Driven Execution：定义成功标准，循环到验证通过

原文核心主张是 "定义成功标准，循环直至验证通过"（Define success criteria. Loop until verified.），并示范了如何把模糊任务改写成可验证目标：

• "加校验" → "为非法输入写测试，然后让它们通过"；
• "修 bug" → "写一个能复现它的测试，然后让它通过"；
• "重构 X" → "确保重构前后测试都通过"。

对于多步任务，原文要求先给出简短计划，每步都带验证点：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

原文最后一句是点睛之笔：强的成功标准让你可以独立地循环推进；弱的标准（"把它弄好"）只会让你不断回头找人确认。这与 oh-my-claudecode 仓库中 agents/qa-tester.ts 等验证型角色的设计意图一脉相承——把"期望结果"提前固化，Agent 才能自主验证而不是反复打断用户。

部署方式：如何让这套纪律真正进入 Agent 上下文

规则模板只有在被加载进 Agent 上下文时才有效。oh-my-claudecode 提供了两种互补的落地路径。

路径 A：复制到项目 .claude/rules/ 目录

按 templates/rules/README.md 的说明：

1. 在项目根目录创建 .claude/rules/；
2. 把想要的模板复制进去，例如 cp templates/rules/karpathy-guidelines.md .claude/rules/；
3. 按需定制；
4. 放置在 .claude/rules/*.md 中的规则会被自动发现并注入所有 Agent 的上下文。

同一份 README 还列出了全套可用模板：coding-style.md（代码风格）、testing.md（测试要求与覆盖率）、security.md（安全检查清单）、performance.md（性能与模型选择）、git-workflow.md（Git 提交与 PR 流程），以及本文主角 karpathy-guidelines.md。

路径 B：借助 Rules Injector Hook 实现按需注入

比起"全量塞进上下文"，oh-my-claudecode 更精细的机制是 src/hooks/rules-injector/index.ts 提供的规则注入 Hook。它不会把规则一股脑注入，而是在 Agent 实际访问文件时，按相关性挑选规则追加到输出中。核心调用链如下：

1. processToolExecution(toolName, filePath, sessionId) 先检查工具是否在 TRACKED_TOOLS（read/write/edit/multiedit）内，不在则直接返回（index.ts）；
2. processFilePathForRules 通过 findProjectRoot 沿目录向上查找项目根（依据 constants.ts 中的项目标记），再调用 findRuleFiles 收集候选规则；
3. 每个候选规则经 parser.ts 解析 YAML frontmatter，再用 matcher.ts 的 shouldApplyRule 判断是否命中当前文件；
4. 命中的规则按目录距离升序排列后，以 [Rule: 相对路径]、[Match: 原因] 的格式注入输出（index.ts）。

规则文件的匹配语法：让 karpathy-guidelines 只在需要时出现

若要精细控制"这套纪律什么时候生效"，可以给规则文件加 YAML frontmatter。根据 parser.ts 与 matcher.ts 的实现，支持以下字段：

• description：规则说明（字符串）；
• alwaysApply: true：无条件注入，绕过 glob 匹配；
• globs / paths / applyTo：三者等价，paths 是 Claude Code 兼容别名，会被自动合并进 globs（parser.ts），支持单字符串、行内数组 ["**/*.ts", "src/**/*.py"]、多行 - item 列表以及逗号分隔四种写法。

规则文件本身需以 .md 或 .mdc 结尾，支持 .github/instructions、.cursor/rules、.claude/rules 三套目录约定（constants.ts），同时兼容 .github/copilot-instructions.md 这种"永远生效"的单文件规则，以及用户级目录 [$CLAUDE_CONFIG_DIR|~/.claude]/rules 下的全局规则（finder.ts）。

一个可选的示例配置（假设你希望这套纪律对仓库内所有源码生效，但对文档目录豁免）：

---
description: Karpathy-style coding discipline for all agents
globs: ["**/*.{ts,js,py}", "!docs/**"]
---

对应的 shouldApplyRule 匹配逻辑会把 glob 转成正则：* 匹配除 / 外的任意字符，** 匹配任意层级（matcher.ts），并以项目根为基准的相对路径进行匹配。

去重与缓存：避免规则反复注入撑爆上下文

oh-my-claudecode 还对"规则注入本身"做了防膨胀设计，这与 Karpathy 纪律中"少即是多"的精神一致：

• 会话级去重缓存：getSessionCache 按 session 维护 contentHashes 与 realPaths 两个集合（index.ts），同一内容或同一真实路径（含符号链接去重）不会重复注入；
• 内容哈希：对规则正文计算 SHA-256 并截取前 16 位作为去重键（matcher.ts）；
• 会话清理：clearSession 在会话结束时删除缓存（index.ts）。

此外仓库在 src/tests/context-bloat-2577.test.ts 与 src/tests/post-tool-rules-injector.test.ts 中提供了针对规则注入相关行为的回归测试，可进一步印证该机制的实际行为。

本模板在 oh-my-claudecode 中的定位

在 oh-my-claudecode 的安装引导流程中，skills/omc-setup/phases/04-welcome.md 会把 karpathy-guidelines.md 作为可选规则模板推荐给使用者；templates/rules/README.md 中它的定位描述是 "Coding discipline — think before coding, simplicity, surgical changes"。也就是说，这套纪律被项目视为通用工程判断力的底座，与 performance.md 的模型选择策略、testing.md 的 TDD 流程等规则互补：前者约束"怎么想"，后者约束"怎么做、做到什么程度"。

落地建议小结

1. 全量启用：直接 cp templates/rules/karpathy-guidelines.md .claude/rules/，让每个 Agent 在会话初期就读到四条纪律——适合追求稳妥的团队项目；
2. 按域启用：通过 frontmatter 的 globs 让纪律只作用于核心源码目录，避免对琐碎脚本也强加流程成本，呼应原文 "for trivial tasks, use judgment"；
3. 与测试规则联动：将第 4 条 Goal-Driven Execution 的"先写测试再实现"与 testing.md 的 RED-GREEN-REFACTOR 流程配合使用，形成从目标定义到验证闭环的完整链路。

最终请记住这套模板的适用前提：它是行为纪律而非语法规范，其价值在于让 LLM Agent 在自主执行时保持"先想清楚、少做、只做该做的、做完要能验证"的工程本能——这正是 Karpathy 观察到的 LLM 编码失误的对症之药。