From 7eed2b8f106608eda793631958b3a37cfb4124e0 Mon Sep 17 00:00:00 2001 From: John Qiu Date: Tue, 21 Apr 2026 10:08:18 +0930 Subject: [PATCH] chore(marketplace): add karpathy-guidelines-plugin, update dev-coding/dev-review/review-checklist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 工作流映射 --- .claude-plugin/marketplace.json | 12 +++ skills-dev/dev-coding-plugin/skills/SKILL.md | 66 +++++++++++++ skills-dev/dev-review-plugin/skills/SKILL.md | 37 +++++-- .../.claude-plugin/plugin.json | 9 ++ .../skills/SKILL.md | 97 +++++++++++++++++++ .../checklists/general.md | 23 ++++- 6 files changed, 237 insertions(+), 7 deletions(-) create mode 100644 skills-dev/karpathy-guidelines-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/karpathy-guidelines-plugin/skills/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1409122..8734760 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -338,6 +338,18 @@ ], "strict": false }, + { + "name": "karpathy-guidelines-plugin", + "source": "./skills-dev/karpathy-guidelines-plugin", + "description": "Karpathy 四原则编码行为守则（Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution）。已深度融合到 req 技能工作流各阶段，可独立激活用于任意编码场景。", + "version": "1.0.0", + "category": "utility", + "keywords": [ + "utility", + "tools" + ], + "strict": false + }, { "name": "pull-request-plugin", "source": "./skills-dev/pull-request-plugin", diff --git a/skills-dev/dev-coding-plugin/skills/SKILL.md b/skills-dev/dev-coding-plugin/skills/SKILL.md index 198b432..41a63e8 100644 --- a/skills-dev/dev-coding-plugin/skills/SKILL.md +++ b/skills-dev/dev-coding-plugin/skills/SKILL.md @@ -73,6 +73,72 @@ ai-proj task append-doc --id --content "实现说明" --- +## Step 0：验证优先（Karpathy: Goal-Driven Execution） + +**编写任何代码前，必须先写验证脚本。** 规则来源：Karpathy "Goal-Driven Execution" 原则。 + +> "Define success criteria. Loop until verified." +> "Fix the bug" → "Write a test that reproduces it, then make it pass" + +### 执行流程 + +``` +① 写验证脚本（按类型选择） +② 运行一遍，确认全部 FAIL（证明功能确实不存在 / bug 确实存在） +③ 编码实现 +④ 再次运行验证脚本，全部 PASS → 完成 +``` + +### 后端验证脚本模板 + +实现 API 前，先写好所有 curl 命令并标注期望结果： + +```bash +# 验证脚本：REQ-XXXX [功能名] +BASE="http://localhost:8080" +TOKEN="" + +echo "=== T1: 正常创建 ===" +curl -s -X POST "$BASE/api/v1/xxx" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"name":"test"}' | jq '.code' +# 期望: 0 + +echo "=== T2: 缺少必填字段 ===" +curl -s -X POST "$BASE/api/v1/xxx" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{}' | jq '.code' +# 期望: 非 0（参数错误） + +echo "=== T3: 跨租户访问 ===" +curl -s -X GET "$BASE/api/v1/xxx/999" \ + -H "Authorization: Bearer $TOKEN_OTHER_TENANT" | jq '.code' +# 期望: 403 +``` + +**先运行 → 全部 FAIL → 编码 → 再次运行 → 全部 PASS** + +### 前端验证脚本模板 + +实现页面前，先列出所有 `data-testid` 和期望的 DOM 状态： + +``` +验证清单（编码前先确认这些状态不存在 / 行为不正确）： +- data-testid="xxx-btn-submit" 点击 → 列表刷新，行数增加 1 +- data-testid="xxx-table" 行数 === API 返回 total +- data-testid="xxx-input-name" 空值提交 → 显示「请输入名称」提示 +``` + +### 与 VP 三件套的关系 + +| VP 协议 | 验证优先对应 | +|---------|------------| +| VP-Data | 先在环境建好测试数据（curl 确认成功） | +| VP-Steps | **即为本节验证脚本** — 编码前写好，编码后执行 | +| VP-Pass | 验证脚本每条命令的期望输出值 | + +--- + ## Go 后端开发 ### 分层架构 diff --git a/skills-dev/dev-review-plugin/skills/SKILL.md b/skills-dev/dev-review-plugin/skills/SKILL.md index 35dbd5d..6611403 100644 --- a/skills-dev/dev-review-plugin/skills/SKILL.md +++ b/skills-dev/dev-review-plugin/skills/SKILL.md @@ -1,13 +1,13 @@ --- name: dev-review -description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码审查、安全评审、质量检查。当执行 /req cr 或独立 PR review 时自动激活。 +description: 代码评审技能。六视角对抗性扫描法（含 Karpathy Scope 审计），用于 PR 代码审查、安全评审、质量检查。当执行 /req cr 或独立 PR review 时自动激活。 --- # 代码评审 Skill (dev-review) ## 概述 -独立的代码评审技能，核心方法论是**五视角对抗性扫描法**。 +独立的代码评审技能，核心方法论是**六视角对抗性扫描法**（五个传统安全/健壮性视角 + Karpathy Scope 审计视角）。 **适用场景**： - `/req cr [REQ-ID]` — 需求流程中的代码评审阶段 @@ -22,7 +22,7 @@ description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码 | 上游 | 本技能输入 | 本技能输出 | 下游 | |------|-----------|-----------|------| -| dev-coding | PR diff + 开发设计文档 | CR 报告（五视角扫描 + 发现汇总 + 结论） | dev-test | +| dev-coding | PR diff + 开发设计文档 | CR 报告（六视角扫描 + 发现汇总 + 结论） | dev-test | --- @@ -67,7 +67,7 @@ description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码 --- -## 五视角对抗性扫描法 +## 六视角对抗性扫描法 ### 总览 @@ -146,6 +146,28 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤， - [ ] Redis 不可用时是否有降级方案？（缓存穿透到数据库） - [ ] token 过期/刷新逻辑是否正确？（access vs refresh 不同策略） +### 视角6：Scope 审计者（Karpathy: Simplicity + Surgical） + +**思维模式**：每一行变更，需求有没有要求它？ + +> "Touch only what you must. Clean up only your own mess." +> "Every changed line should trace directly to the user's request." + +扫描清单： +- [ ] diff 中变更的**每个文件**，是否都在 req-design 变更文件清单中？（超出清单 = 疑似顺手重构） +- [ ] 新增的函数/方法/结构体，每个都有对应 AC 需要它？ +- [ ] 是否引入了"未来可能用到"的参数、配置项、可选字段、接口抽象？ +- [ ] 是否修改了本次 AC 无关的注释、格式、变量名、import 顺序？ +- [ ] 代码量是否合理？实现简单 AC 超过 200 行须说明必要性 + （"If you write 200 lines and it could be 50, rewrite it"） +- [ ] 错误处理是否只覆盖真实会发生的场景？不为不可能的情况写防御代码 + +**典型发现示例**： +``` +backend/services/user_service.go:45 — 新增了 WithRetry 参数，但 AC 中无重试需求。 +建议：移除该参数，AC 有需要时再添加。严重度：Low +``` + --- ## CR 报告模板 @@ -160,7 +182,7 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤， ### 变更概要 {1-3 句描述本次变更的目的和范围} -### 五视角扫描结果 +### 六视角扫描结果 #### 1. 攻击者视角 {扫描发现，或 "未发现问题"} @@ -177,6 +199,9 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤， #### 5. 依赖者视角 {扫描发现，或 "未发现问题"} +#### 6. Scope 审计者视角（Karpathy） +{扫描发现，或 "所有变更文件均在设计清单范围内，无过度实现"} + ### 审查发现汇总 | # | 严重度 | 文件:行号 | ���角 | 描述 | 建议 | @@ -221,7 +246,7 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤， | 文档存在 | CR 任务有附加文档 | | 字数 | ≥ 500 字 | | 代码引用 | 含 `file:line` 格式的引用 | -| 五视角扫描 | 含全部 5 个视角章节 | +| 六视角扫描 | 含全部 6 个视角章节（含 Scope 审计者） | | 结论章节 | 含明确的通过/不通过结论 | --- diff --git a/skills-dev/karpathy-guidelines-plugin/.claude-plugin/plugin.json b/skills-dev/karpathy-guidelines-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..6905160 --- /dev/null +++ b/skills-dev/karpathy-guidelines-plugin/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "karpathy-guidelines", + "description": "Karpathy 四原则编码行为守则（Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution）。已深度融合到 req 技能工作流各阶段，可独立激活用于任意编码场景。", + "version": "1.0.0", + "author": "qiudl", + "source": "https://github.com/forrestchang/andrej-karpathy-skills", + "tags": ["coding-guidelines", "karpathy", "simplicity", "surgical", "goal-driven"], + "skills": ["karpathy-guidelines"] +} diff --git a/skills-dev/karpathy-guidelines-plugin/skills/SKILL.md b/skills-dev/karpathy-guidelines-plugin/skills/SKILL.md new file mode 100644 index 0000000..2458f9b --- /dev/null +++ b/skills-dev/karpathy-guidelines-plugin/skills/SKILL.md @@ -0,0 +1,97 @@ +--- +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" | 直接修改，无验证标准 | 先写复现测试，修复后验证通过 | diff --git a/skills-dev/review-checklist-plugin/checklists/general.md b/skills-dev/review-checklist-plugin/checklists/general.md index 45d912e..2f30387 100644 --- a/skills-dev/review-checklist-plugin/checklists/general.md +++ b/skills-dev/review-checklist-plugin/checklists/general.md @@ -1,6 +1,27 @@ # 通用代码评审检查清单 -适用于所有项目，补充五视角扫描法。 +适用于所有项目，补充六视角扫描法（五传统视角 + Karpathy Scope 视角）。 + +## Karpathy 反模式速查（Scope 审计者视角辅助） + +基于 [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) EXAMPLES.md 提炼。 + +### ❌ 反模式 → ✅ 正确做法 + +| 场景 | 反模式（LLM 常犯） | 正确做法 | +|------|-----------------|---------| +| "做个导出功能" | 静默假设文件格式/字段/分页，直接实现 | 列出3种解读（API/文件/任务队列），问用户选哪种 | +| "让搜索更快" | 同时加缓存+索引+async，200行 | 列出3种"更快"含义+估算，等确认再做 | +| "加个折扣计算" | Strategy+Abstract+Enum+DataClass，50行 | `def calc_discount(amount, pct): return amount * pct / 100` | +| "修保存偏好的bug" | 顺手加 merge/validate/notify/cache | 只改最小范围，加注释"其他特性按需再加" | +| "修空邮件校验bug" | 顺手加用户名校验+类型注解+docstring | 只改空邮件的那2行 | +| "加日志到上传函数" | 改引号风格+加类型注解+重构return逻辑 | 只加日志，保持原有代码风格 | +| "修认证bug" | "我会检查代码并做改进"（无标准） | 先写测试复现bug，再实现修复，再跑测试 | +| "加限流" | 一次提交Redis+多策略+配置系统+监控 | 分4步，每步独立可验证可部署 | + +### 触发关键词（出现时加强 Scope 审计） + +`export/导出` `faster/更快` `manage/管理` `notify/通知` `fix/修复` `improve/改进` `refactor/重构` `add/添加` ## API 设计 - [ ] RESTful 命名是否规范？（复数名词、无动词）