John Qiu
7eed2b8f10
Karpathy 四原则融合到 req 技能工作流 (REQ-20260421-0003): - dev-coding: 新增 Step 0「验证优先」(Goal-Driven Execution) - dev-review: 五视角 → 六视角，新增 Scope 审计者 (Simplicity + Surgical) - review-checklist/general: 新增 Karpathy 反模式速查表 - karpathy-guidelines-plugin: 新增独立插件，含四原则全文 + 与 req 工作流映射
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
---
|
||
name: karpathy-guidelines
|
||
description: Karpathy 四原则编码行为守则。减少 LLM 常见编码错误：过度实现、静默假设、顺手重构、无验证标准。在任意编码场景激活。
|
||
---
|
||
|
||
# Karpathy Guidelines Skill
|
||
|
||
> 来源：[andrej-karpathy-skills](https://github.com/forrestchang/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" | 直接修改，无验证标准 | 先写复现测试，修复后验证通过 |
|