ai-proj-helper/skills-dev/karpathy-guidelines-plugin/skills/SKILL.md

name, description

name	description
karpathy-guidelines	Karpathy 四原则编码行为守则。减少 LLM 常见编码错误：过度实现、静默假设、顺手重构、无验证标准。在任意编码场景激活。

Karpathy Guidelines Skill

来源：andrej-karpathy-skills 在本项目中已深度融合到 req 技能工作流各阶段。

四原则

1. Think Before Coding（编前推理）

"Don't assume. Don't hide confusion. Surface tradeoffs."

在写第一行代码前：

• 显式列出本次实现的假设（数据格式、边界条件、依赖接口）
• 如存在多种解读，列出所有方案（附估算），不要静默选择
• 如有更简单的实现方式，说出来
• 遇到不清晰的地方，停下来，指出混乱点，提问

在 req 工作流中： → 已嵌入 req-prd 的「Phase 0 假设倾倒协议」

---

2. Simplicity First（简单优先）

"Minimum code that solves the problem. Nothing speculative."

禁止：

• 添加未被需求要求的功能
• 为单次使用的代码添加抽象
• 添加未被请求的"灵活性"或"可配置性"
• 为不可能发生的场景写错误处理
• 写了 200 行但 50 行就够的代码 → 重写

自检： "一个高级工程师看这段代码会觉得过度设计吗？" 如果是 → 简化

在 req 工作流中： → 已嵌入 req-design 过度设计检查 + dev-review 第六视角

---

3. Surgical Changes（手术式修改）

"Touch only what you must. Clean up only your own mess."

修改现有代码时：

• 不要"顺手改进"相邻代码、注释或格式
• 不要重构没有损坏的代码
• 匹配现有代码风格，即使你会做不同的选择
• 发现不相关的死代码 → 提及但不删除

你的变更造成的孤儿：

• 删除你的变更导致的无用 import/变量/函数
• 不要删除已存在的死代码（除非被要求）

铁律： diff 中每一行修改都应该可以追溯到用户的需求

在 req 工作流中： → 已嵌入 dev-review 第六视角 + check-surgical.sh Harness 脚本

---

4. Goal-Driven Execution（目标驱动执行）

"Define success criteria. Loop until verified."

将请求转化为可验证目标：

• "加验证" → "为无效输入写测试，然后让它通过"
• "修 bug" → "写一个复现 bug 的测试，然后让它通过"
• "重构 X" → "确保测试在重构前后都通过"

多步任务需要说明计划：

1. [步骤] → 验证: [检查项]
2. [步骤] → 验证: [检查项]
3. [步骤] → 验证: [检查项]

在 req 工作流中： → 已嵌入 dev-coding 的「Step 0 验证优先」+ VP 三件套协议

---

与 req 工作流的映射

原则	生效阶段	落地机制
Think Before Coding	req-prd 启动前	Phase 0 假设倾倒协议
Simplicity First	req-design + dev-review	过度设计检查 + 第六视角
Surgical Changes	dev-review + CI	第六视角 + check-surgical.sh
Goal-Driven Execution	dev-coding	Step 0 验证优先 + VP 三件套

反模式速查

场景	❌ LLM 常犯	✅ 正确做法
"做个导出功能"	静默假设格式/字段，直接实现	列出3种解读，等用户确认
"让搜索更快"	同时加缓存+索引+async	列出3种"更快"含义，确认再做
"加折扣计算"	Strategy+Abstract+Enum，50行	一个函数，3行
"修空邮件bug"	顺手加用户名校验+类型注解	只改空邮件的那2行
"修认证bug"	直接修改，无验证标准	先写复现测试，修复后验证通过