AI 编程实践

别让 AI 把 100 行代码
写成 1000 行

Karpathy 启发的四条编码准则：从“会写代码”到“可靠交付”

一篇面向 Claude Code、Cursor 与其他 AI 编程助手的实战指南

核心观点 真正高质量的 AI 编程，不是让模型写得更多，而是让它更少误解、更少过度设计、更少误伤无关代码，并且能用明确标准证明任务已经完成。

适合发布平台：CSDN / 技术公众号 / 团队工程博客

关键词：AI 编程、Claude Code、Cursor、Prompt Engineering、工程实践

摘要

大模型已经能够快速生成代码，但“能生成”不等于“能可靠交付”。在真实项目中，AI 编程助手常见的问题不是语法不会写，而是未经确认便替用户做假设、把简单需求复杂化、顺手修改无关代码，以及缺少可验证的完成标准。本文解析一个名为 andrej-karpathy-skills 的轻量级开源仓库。该仓库把 Andrej Karpathy 对 LLM 编码缺陷的观察提炼为四条工程准则，并分别适配 Claude Code、Cursor 和可复用 Skill。本文不仅解释这四条准则，还给出安装方式、提示词模板、实战案例及团队落地建议。

一、这个项目解决的不是“代码能力”，而是“工程判断”

打开仓库后，你不会看到常规项目里的 src、package.json、测试目录或构建脚本。它本质上是一套 AI 编程行为规范：通过少量 Markdown 和配置文件，改变编码智能体在理解需求、设计方案、修改代码和验证结果时的行为。

项目非常小，但瞄准的问题很关键。如今大模型通常能写出局部正确的代码，真正昂贵的错误往往发生在更高一层：模型理解错目标，却自信地继续实现；为了“通用性”提前引入抽象；修复一个 Bug 时顺便重构半个模块；最后只说“已经修复”，却没有测试或证据。

一句话理解 这个仓库不是教 AI 如何写某种语言，而是教 AI 如何像一名克制、可信、可协作的工程师那样工作。

二、仓库结构：同一套规则，适配三种使用方式

andrej-karpathy-skills-main/

├── .claude-plugin/

│   ├── plugin.json

│   └── marketplace.json

├── .cursor/rules/

│   └── karpathy-guidelines.mdc

├── skills/karpathy-guidelines/

│   └── SKILL.md

├── CLAUDE.md

├── CURSOR.md

├── EXAMPLES.md

├── README.md

└── README.zh.md

文件/目录	面向工具	作用
CLAUDE.md	Claude Code	项目级指令文件，放在项目根目录即可生效
.claude-plugin	Claude Code	插件清单与市场配置，支持全局安装
.cursor/rules	Cursor	alwaysApply 规则，打开项目后自动应用
SKILL.md	通用 Agent Skill	把规则包装为可复用、可发现的技能
EXAMPLES.md	所有读者	用正反案例展示准则的实际效果

三、四条核心准则详解

1. Think Before Coding：编码前先管理不确定性

模型最危险的习惯之一，是在需求存在歧义时默默选择一种解释，然后沿着这个解释高速前进。速度越快，偏离目标的代价反而越大。第一条准则要求 AI 显式说明假设、呈现不同解释、指出取舍，并在关键条件不清楚时先澄清。

• 明确说明自己依赖了哪些假设，而不是把假设伪装成事实。
• 当需求存在多种合理解释时，列出差异及其对实现的影响。
• 如果有明显更简单的方案，应主动提出，而不是机械执行复杂方案。
• 真正影响架构、数据安全或兼容性的歧义，应在编码前解决。

实践提醒 “主动澄清”不等于每件小事都提问。拼写修复、明确的一行改动可以直接完成；只有会显著改变结果的歧义，才值得暂停。

2. Simplicity First：用最少的代码解决当前问题

大模型倾向于展示能力，因此容易增加接口层、策略模式、配置项、未来扩展点和“不可能发生”的异常处理。这些内容看起来专业，却扩大了维护面。该准则强调：不实现未被要求的功能，不为一次性逻辑建立抽象，不为想象中的未来需求预留复杂结构。

判断标准非常直接：如果一名资深工程师看到方案后会问“为什么要这么复杂”，就应该继续简化。简洁不是代码越短越好，而是每一层复杂度都有当前需求作为理由。

3. Surgical Changes：每一处改动都能追溯到用户请求

修复某个功能时顺手整理格式、改变量名、删除旧注释，看似是在“提升代码质量”，实际上会扩大 Diff、提高审查成本，并可能破坏模型并未完全理解的逻辑。精准修改要求 AI 只触碰完成任务必须触碰的部分，同时匹配项目现有风格。

• 不重构没有损坏的邻近代码。
• 不随意修改与任务无关的注释、命名和格式。
• 如果本次改动导致导入、变量或函数失去用途，应清理这些“由本次改动产生”的孤儿。
• 发现原本就存在的死代码，可以报告，但不要未经授权删除。

4. Goal-Driven Execution：把命令改写成可验证目标

“修复 Bug”不是一个足够好的完成标准。更好的目标是：先写一个能够稳定复现 Bug 的测试，再修改实现，直到测试通过，同时确保原有测试不回归。这样，AI 才能围绕客观结果循环执行，而不是凭主观感觉宣布完成。

模糊指令	可验证目标
增加参数校验	为非法输入编写测试，然后让测试通过
修复登录 Bug	编写稳定复现问题的测试，修复后运行完整测试集
重构缓存模块	确认重构前后行为测试一致且性能没有明显退化

四、一个典型案例：AI 为什么会把小需求做大

假设用户提出：“给登录接口增加邮箱格式校验。”一个缺乏约束的 AI 可能新建通用验证框架、引入第三方 Schema 库、重构所有请求 DTO、统一错误码，并顺便改写原有注释。最终提交数百行代码，而真正需求可能只需要一个局部校验和两三个测试。

未经约束的执行方式

• 默认用户希望建立全项目统一验证体系。
• 增加未要求的可配置规则和扩展接口。
• 顺手格式化相关文件，导致 Diff 难以审查。
• 只展示实现代码，没有证明无效邮箱会被拒绝。

应用四条准则后的执行方式

1. 确认现有项目是否已经存在校验模式，并沿用该模式。
2. 添加无效邮箱被拒绝、有效邮箱保持兼容的测试。
3. 在最接近输入边界的位置加入最小校验逻辑。
4. 运行目标测试和相关回归测试，只提交必要 Diff。

结果 任务的价值并不取决于新增代码行数，而取决于需求是否被准确实现、风险是否被控制、结果是否可复现。

五、如何在 Claude Code 中使用

方式 A：通过插件安装

仓库提供了 Claude Code 插件市场配置。按照项目 README，可先添加市场，再安装插件：

/plugin marketplace add forrestchang/andrej-karpathy-skills

/plugin install andrej-karpathy-skills@karpathy-skills

插件方式适合希望在多个项目中复用同一套行为准则的用户。安装后，karpathy-guidelines 技能可以被 Claude Code 发现和加载。

方式 B：使用项目级 CLAUDE.md

如果只想在某个项目内应用规则，可以把仓库中的 CLAUDE.md 复制到目标项目根目录；如果项目已经存在同名文件，则把四条准则合并进去，并保留原有项目约束。

# 项目特定规则示例

 

- TypeScript 必须启用 strict 模式

- 所有 API 端点都必须有测试

- 错误处理沿用 src/utils/errors.ts 的现有模式

六、如何在 Cursor 中使用

仓库已经包含 .cursor/rules/karpathy-guidelines.mdc，并设置 alwaysApply: true。在 Cursor 中打开该仓库时，规则会自动应用。若要在其他项目复用，只需复制到对应项目的 .cursor/rules 目录。

your-project/

└── .cursor/

    └── rules/

        └── karpathy-guidelines.mdc

Cursor 默认不会读取 Claude Code 的插件配置，因此 .claude-plugin、CLAUDE.md 与 Cursor Rule 分别服务于不同的加载机制。项目作者用三份内容相近的文件换取了跨工具兼容性。

七、可以直接复用的 AI 编程提示词

如果暂时不安装插件，也可以把下面这段提示词放到项目规则或对话开头：

在修改代码前，请遵守以下规则：

1. 明确说明关键假设；如果歧义会显著影响结果，先澄清。

2. 只实现当前明确要求，不增加未要求的抽象、配置或扩展点。

3. 只修改完成任务所必需的文件和代码，避免顺手重构。

4. 在开始前给出可验证的成功标准；完成后运行相应测试或检查。

5. 最终说明修改了什么、如何验证，以及仍然存在的限制。

建议 团队规则应补充具体技术约束，例如测试命令、目录边界、错误处理方式和提交规范。通用原则负责约束行为，项目规则负责提供上下文。

八、如何判断这套规则是否真的生效

规范是否有效，不应该靠“感觉 AI 更聪明了”来判断，而应该观察工程产出。可以持续检查以下指标：

• Pull Request 的无关改动是否减少。
• 复杂方案被推倒重来的次数是否下降。
• 澄清问题是否出现在编码之前，而不是出错之后。
• Bug 修复是否附带稳定复现测试。
• AI 是否能明确说明验证命令及其结果。
• 每一行修改是否都能对应到用户需求或必要的连带清理。

九、项目的优点、局限与改进建议

优点

• 规则少而集中，容易理解，也容易与现有工程规范合并。
• 同时提供 Claude Code 插件、项目指令、Cursor Rule 和通用 Skill。
• 强调可验证结果，而不仅是提示模型“认真一点”。
• 精准修改原则对大型遗留项目尤其有价值。

局限

• 它是行为提示，不是强制执行器，不能替代测试、Lint、类型检查和代码审查。
• 三份核心规则存在重复，更新时需要人工保持同步。
• 仓库当前部分中文和特殊符号存在乱码，发布前应统一使用 UTF-8 编码检查。
• 规则偏向谨慎，对于极小改动应灵活处理，避免让流程本身成为负担。

建议的增强方向

• 增加自动同步脚本，从单一规则源生成 CLAUDE.md、MDC 和 SKILL.md。
• 增加最小示例项目，用真实 Diff 展示规则应用前后的差异。
• 为规则文件增加编码与一致性 CI 检查。
• 提供面向前端、后端、数据分析和基础设施项目的扩展示例。

十、团队落地：把“提示词”变成工程制度

如果只把这四条规则贴进对话，它们能改善单次输出；如果想长期稳定生效，则要与工程工具链结合。最实用的做法是建立三层约束：

1. 行为层：使用本文四条准则，约束 AI 如何思考与修改。
2. 项目层：在 CLAUDE.md 或 Cursor Rules 中写明目录边界、代码风格、测试命令和安全要求。
3. 自动化层：用测试、类型检查、Lint、CI 和代码审查验证结果，避免仅相信模型的文字声明。

关键结论 提示词适合指导决策，但不能替代自动化约束。最可靠的 AI 编程流程，是“清晰规则 + 最小修改 + 客观验证”。

结语

AI 编程的竞争正在从“谁能生成更多代码”，转向“谁能更稳定地交付正确改动”。andrej-karpathy-skills 的价值，就在于用四条简洁原则把模型从热衷展示能力的代码生成器，拉回到克制、透明、可验证的工程协作者。

当 AI 能够主动暴露假设、拒绝不必要的复杂度、只修改任务相关代码，并用测试证明完成结果时，我们得到的不只是更漂亮的代码，而是一套更低风险、更容易审查，也更适合团队协作的软件开发流程。

参考资料

• 项目仓库：forrestchang/andrej-karpathy-skills
• 核心来源：Andrej Karpathy 关于 LLM 编码常见陷阱的公开观察
• 仓库许可证：MIT License