Leroy
d3e9bd45bd
- SKILL.md 双工作流（创建/迭代）+ 两道门（验料/通用化）+ 三档位 - 7 篇方法论 references + 3 个纯标准库脚本（scaffold/validate/trigger_eval） - 自身触发用例 16 条 + 先例研究/创建/迭代证据报告 - 方法论吸收自 qiaomu-meta-skill 与 luban-skill，取舍见 reports/prior-art.md
75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
# 迭代工坊——改进已有 Skill
|
||
|
||
改一个 skill，比新建一个更容易翻车：它已经有用户（哪怕用户只有 Leroy 自己），改坏了触发就断了。迭代的核心纪律是**可回退、可比较、单面推进**。
|
||
|
||
## 第一步：冻结基线
|
||
|
||
动任何刨子之前：
|
||
|
||
- 有 git：开分支或记录当前 commit；
|
||
- 没 git：`cp -r <skill> <项目根>/.baseline/<skill>-<日期>/`。
|
||
|
||
两条纪律（实战教训）：
|
||
|
||
1. **基线必须放在发现路径之外。** 放进 `.agents/skills/` 或 `~/.claude/skills/` 里的基线副本会被 runtime 当成另一个 skill 发现，制造幽灵触发。
|
||
2. **复制完立即验证。** `head` 一下基线的 SKILL.md 确认是旧版本——有些执行环境里文件写入跨调用不可靠，没验证过的基线等于没有基线。
|
||
|
||
之后所有候选改动都与基线比。基线是裁判，不是怀旧品。
|
||
|
||
## 第二步：诊断三把尺
|
||
|
||
| 尺 | 量什么 | 怎么量 |
|
||
|---|---|---|
|
||
| 结构尺 | 写得清不清楚 | `python3 scripts/validate_skill.py <目录>`，FAIL/WARN 直接转差距条目 |
|
||
| 触发尺 | 该触发时触不触发、不该触发时误不误伤 | `python3 scripts/trigger_eval.py <目录>` + 真实对话原话抽测 |
|
||
| 活体尺 | 真实任务里跑不跑得出结果 | 拿 2–3 个真实任务实际用一遍。"看起来能触发"不等于"跑得出结果"——静默失败比文档烂致命 |
|
||
|
||
**活体尺最常被跳过，也最值钱。** 大部分真问题（输出格式其实不稳定、某个步骤总卡住、引用的脚本跑不通）只有真实运行才暴露。
|
||
|
||
## 第三步：六维评分，定位最该刨的面
|
||
|
||
每维 0–10 分，**每个分数必须给证据**（哪条用例、哪次运行、哪行源码），凭手感打分作废：
|
||
|
||
| 维度 | 权重 | 量什么 |
|
||
|---|---:|---|
|
||
| 触发与边界 | 25 | description 覆盖、负触发、误伤/漏触发记录 |
|
||
| 可执行具体性 | 20 | 步骤是否可直接照做、示例是否字面可用 |
|
||
| 工作流清晰度 | 15 | 分步结构、何时读哪个 reference |
|
||
| 失败模式与停手点 | 15 | 出错怎么办、何时问用户，有没有编码 |
|
||
| 实测表现 | 15 | 活体尺结果 |
|
||
| 资源纪律 | 10 | 有没有不承重的文件、悬空引用、超长正文 |
|
||
|
||
总分不是用来攀比的，是用来**排序**的：最低分且权重高的维度，就是本轮唯一要刨的面。
|
||
|
||
## 第四步：单面慢刨
|
||
|
||
- 一轮只改一个面（只修触发、或只重构工作流、或只补失败模式）。
|
||
- 用户批量授权（"都修了吧"）后，升级为**单面单提交**——每个改动独立过验证门，绝不把两个面塞进一次改动。
|
||
- 改动前先写下：本轮只刨 X；改动边界：只改 X，不动 Y；预期提升是什么。
|
||
|
||
## 第五步：验证门
|
||
|
||
候选改动**全部满足**才保留，否则回刀（恢复基线，重新想）：
|
||
|
||
1. 比基线**多通过**至少 2 条测试原话（触发用例或真实任务）；
|
||
2. 没有把 skill 写得更长但更难用——行数增加必须换来可执行性；
|
||
3. 没有引入私有路径、密钥、不可复现依赖；
|
||
4. 没有破坏原有通过项——基线能过而现在过不了的，是退化；
|
||
5. 通过 `validate_skill.py` 全绿。
|
||
|
||
验收时换**独立验收视角**：假装是第一次见到这个 skill 的陌生模型，只读交付物，不知道改动过程。刨子和尺子不能握在同一只手里。
|
||
|
||
## 第六步：交付与回炉
|
||
|
||
交付改动报告（改了哪个面、验证证据、行数变化），并留**回炉清单**：
|
||
|
||
- 本轮"不做"的事和理由（下一轮入口）；
|
||
- 已知边界损耗（哪些用例还是过不了）；
|
||
- 沉淀机会：这次手写的验证手段，值得固化成 `scripts/` 工具或 `evals/` 用例吗？值得就顺手沉淀——验证不是脚手架，是交付物的一部分。
|
||
|
||
## 迭代时机
|
||
|
||
- 用户带着"它又翻车了"的原话回来 → 先把原话收编成用例，再修。
|
||
- 隔了一个月没动 → 先跑三把尺再决定刨哪里，不要凭上次印象。
|
||
- 多次小修仍不稳 → 怀疑是定位问题（验料没做对），回到第一道门重新定位，而不是继续打补丁。
|