Compare commits
3 Commits
bcea648e3c
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| da57cccf96 | |||
| 7eed2b8f10 | |||
| 5a45916b2c |
@@ -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",
|
||||
|
||||
@@ -73,6 +73,72 @@ ai-proj task append-doc --id <taskId> --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="<JWT>"
|
||||
|
||||
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 后端开发
|
||||
|
||||
### 分层架构
|
||||
|
||||
@@ -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）
|
||||
{扫描发现，或 "所有变更文件均在设计清单范围内，无过度实现"}
|
||||
|
||||
### 审查发现汇总
|
||||
|
||||
| # | 严重度 | 文件:行号 | <20><><EFBFBD>角 | 描述 | 建议 |
|
||||
@@ -221,7 +246,7 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤，
|
||||
| 文档存在 | CR 任务有附加文档 |
|
||||
| 字数 | ≥ 500 字 |
|
||||
| 代码引用 | 含 `file:line` 格式的引用 |
|
||||
| 五视角扫描 | 含全部 5 个视角章节 |
|
||||
| 六视角扫描 | 含全部 6 个视角章节（含 Scope 审计者） |
|
||||
| 结论章节 | 含明确的通过/不通过结论 |
|
||||
|
||||
---
|
||||
|
||||
@@ -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"]
|
||||
}
|
||||
97
skills-dev/karpathy-guidelines-plugin/skills/SKILL.md
Normal file
97
skills-dev/karpathy-guidelines-plugin/skills/SKILL.md
Normal file
@@ -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" | 直接修改，无验证标准 | 先写复现测试，修复后验证通过 |
|
||||
@@ -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 命名是否规范？（复数名词、无动词）
|
||||
|
||||
@@ -23,10 +23,11 @@ description: 复盘总结。自动采集数据、计算质量评分、跨需求
|
||||
### 2. 质量评分（Quality Score）
|
||||
|
||||
```
|
||||
QS = lookback_pass_rate × 0.3
|
||||
+ audit_defect_score × 0.3
|
||||
+ cr_density_score × 0.2
|
||||
+ test_pass_rate × 0.2
|
||||
QS = lookback_pass_rate × 0.25
|
||||
+ audit_defect_score × 0.25
|
||||
+ cr_density_score × 0.15
|
||||
+ test_pass_rate × 0.15
|
||||
+ karpathy_score × 0.20 ← Karpathy 四原则执行质量
|
||||
|
||||
audit_defect_score:
|
||||
0 缺陷 = 100
|
||||
@@ -38,8 +39,26 @@ audit_defect_score:
|
||||
cr_density_score:
|
||||
100 - (发现数 / 变更行数 × 1000)
|
||||
下限 0，上限 100
|
||||
|
||||
karpathy_score（四原则执行质量，各 25 分，共 100）:
|
||||
Think Before PRD (25):
|
||||
PRD 无返工 → 25 | 因需求误解返工 1 次 → 15 | ≥2 次 → 0
|
||||
Simplicity (25):
|
||||
CR 第六视角无 Scope 违规 → 25 | 1 个 Low → 20 | ≥1 个 Medium+ → 10 | High+ → 0
|
||||
Surgical (25):
|
||||
check-surgical.sh PASS + CR 无顺手改 → 25 | 警告但未阻塞 → 15 | FAIL → 0
|
||||
Goal-Driven (25):
|
||||
dev-coding 有验证脚本记录（VP-Steps 先于代码执行）→ 25 | 事后补写 → 15 | 无 → 0
|
||||
```
|
||||
|
||||
**Karpathy 数据来源**（按优先级）：
|
||||
1. dev-coding 任务文档中是否有「验证脚本」节
|
||||
2. CR 报告第六视角的发现数和严重度
|
||||
3. `git log` 中是否有 check-surgical.sh baseline 更新提交（说明有过违规）
|
||||
4. PRD 任务文档的版本数（> 1 说明有返工）
|
||||
|
||||
**无数据时**：各维度默认 20 分（中性），在报告中标注 `(无记录，按中性计算)`
|
||||
|
||||
### 3. 历史趋势对比
|
||||
|
||||
读取 `memory/retro_metrics.md` 的明细数据：
|
||||
@@ -87,10 +106,12 @@ AI: "近 5 次需求中 3 次 audit 发现了 {缺陷类型}。
|
||||
|
||||
追加一行到明细：
|
||||
```
|
||||
| REQ-xxx | 2026-04-18 | 5h44m | 92 | 2 | 279 | 3 | frontend |
|
||||
| REQ-xxx | 2026-04-18 | 5h44m | 92 | 2 | 279 | 3 | frontend | 85 |
|
||||
```
|
||||
|
||||
更新汇总：重新计算近 10 次平均值和趋势箭头（↑↓→）。
|
||||
列说明：`REQ | date | time | QS | audit_defects | changed_lines | cr_findings | type | karpathy_score`
|
||||
|
||||
更新汇总：重新计算近 10 次平均值和趋势箭头（↑↓→），包含 karpathy_score 趋势。
|
||||
|
||||
超过 30 条明细 → 最早的移入 `retro_metrics_archive.md`。
|
||||
|
||||
@@ -116,10 +137,19 @@ AI: "近 5 次需求中 3 次 audit 发现了 {缺陷类型}。
|
||||
## 质量指标
|
||||
| 指标 | 本次 | 近10次均 | 对比 |
|
||||
|------|------|---------|------|
|
||||
| 质量分 | 92 | 85 | ↑ |
|
||||
| 质量分 (QS) | 92 | 85 | ↑ |
|
||||
| audit 缺陷 | 2(低) | 3.2 | ↓ |
|
||||
| CR 发现 | 0 | 1.5 | ↓ |
|
||||
| 测试通过率 | 100% | 95% | ↑ |
|
||||
| Karpathy 分 | 85 | 78 | ↑ |
|
||||
|
||||
## Karpathy 四原则评分
|
||||
| 原则 | 得分 | 说明 |
|
||||
|------|------|------|
|
||||
| Think Before PRD | 25/25 | PRD 无返工 |
|
||||
| Simplicity | 20/25 | CR 第六视角发现 1 个 Low |
|
||||
| Surgical | 25/25 | check-surgical.sh PASS |
|
||||
| Goal-Driven | 15/25 | 验证脚本为事后补写 |
|
||||
|
||||
## git 统计
|
||||
| 提交数 | 变更文件 | +行 | -行 |
|
||||
|
||||
@@ -87,12 +87,24 @@ done
|
||||
**报告格式**：
|
||||
```
|
||||
### 约定检查 (Gate 0B)
|
||||
| 脚本 | 结果 | 详情 |
|
||||
|------|------|------|
|
||||
| check-architecture.sh | ✅ PASS | 5 rules, all within baseline |
|
||||
| check-modal-safety.sh | ✅ PASS | 0 violations |
|
||||
| 脚本 | 类型 | 结果 | 详情 |
|
||||
|------|------|------|------|
|
||||
| check-architecture.sh | Ratchet | ✅ PASS | 5 rules, all within baseline |
|
||||
| check-modal-safety.sh | Hard wall | ✅ PASS | 0 violations |
|
||||
| check-surgical.sh | Ratchet | ✅ PASS | 0 format-only violations (baseline=0) |
|
||||
```
|
||||
|
||||
**本项目已建立的约定检查脚本**：
|
||||
|
||||
| 脚本 | 类型 | 检测内容 | 来源 |
|
||||
|------|------|---------|------|
|
||||
| `check-architecture.sh` | Ratchet | Handler 直接引用 database/ 层 | 分层架构规范 |
|
||||
| `check-modal-safety.sh` | Hard wall | Modal.success 后立即操作 UI | REQ-20260416 |
|
||||
| `check-surgical.sh` | Ratchet | PR diff 中疑似仅注释/格式变更的文件 | Karpathy Surgical（REQ-20260421-0003）|
|
||||
|
||||
> `check-surgical.sh` 使用 Ratchet 模式：`.surgical-baseline.json` 记录基线，违规数只能降不能升。
|
||||
> 首次无基线时仅告警，不阻塞。运行 `./scripts/check-surgical.sh baseline` 建立基线。
|
||||
|
||||
> 这样 Harness 建立的约定脚本会在每次 `/req test` 时自动运行，无需手动执行 `/harness report`。
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user