Karpathy Guidelines | 卡帕西编码规范 · 手术式修改原则

Karpathy Guidelines（卡帕西编码规范）是 Andrej Karpathy 在 AI 辅助编码实践中总结的一套手术式修改原则：让 Agent 像外科医生一样精准动刀，而不是推倒重来。它属于 AI 编码社区的方法论，适合作为 Cursor Rules、AGENTS.md 或项目级常驻约束，与具体编码 Agent（OpenCode、Cursor Agent 等）配合使用。

「优秀代码是精心雕刻出来的。」—— Andrej Karpathy

核心原则：手术式修改

原则	含义	实操要点
最小改动	只改解决问题所必需的代码	不动无关文件、不顺手「整理」邻近逻辑
明确假设	每次修改前说清楚「我认为问题是什么」	用一两句话写出根因假设，便于事后复盘
划定范围	声明本次改动覆盖与不覆盖的边界	例如「只改 `auth.ts`，不改路由层」
成功标准	改动完成的判定条件必须可验证	测试通过、lint 清零、特定 API 返回 200 等
风格一致	保持与周边代码相同的命名、结构与抽象层级	不引入新范式，除非任务明确要求
可度量	改动效果能用数字或检查项说明	性能提升 X%、覆盖率 +Y、复现步骤消失

典型工作流

读上下文 — 先理解现有实现与调用链，不急于生成补丁
写假设 — 「我判断 Bug 来自缓存未失效，范围限定在 UserCache」
手术式补丁 — 最小 diff，保持原有风格
验证 — 跑测试、手动复现、对照成功标准
记录 — 若假设错误，更新假设再切下一刀，而非堆叠猜测性修改

适用场景

维护现有项目：修 Bug、补测试、小功能迭代
代码审查：约束 Agent 或人工提交的 diff 粒度
生产环境热修：需要可回滚、可审计的精准改动
与 Superpowers 等流程叠加：作为常驻「编码纪律」，贯穿 TDD 与审查环节

不太适合

大面积架构重构：需要重新划分模块边界时，手术式原则会拖慢必要的大刀阔斧
探索性原型：0→1 验证想法时，过度约束会扼杀快速试错
一次性脚本：没有长期维护负担时，完整流程性价比低

与其他工具的关系

Karpathy Guidelines 是工作流层的编码规范，不替代具体 Agent。常与 Superpowers 的 TDD 流程、Skill Vetter 的安全审计、GStack 的产品化交付组合：规范负责「怎么改代码」，其他工具负责「改什么、何时交付、是否安全」。

下一步

将核心原则写入项目 AGENTS.md 或 Cursor Rules，作为 Agent 常驻约束
日常编码搭配 Superpowers 的 TDD 与审查 Skills
完整五工具组合见 AI 开发五大核心技能工具组合打法（playbook，待发布）