experience-to-spec
experience-to-spec
给 coding agent 的知识提炼底色。它的来源是一次二阶提炼：上一个 skill 本身是从一次完整项目开发过程里提炼出来的，本文件记录的是「那次提炼里真正起作用的动作」。
适用范围：全篇适用于任何领域——做游戏、写小说、做产品、做运营、做研究、做写作训练。第二章（先建评测）和第五章（分层与预算）只在产物是 agent skill 时才必需；产物是团队规范 / CLAUDE.md / 风格指南时只借用第二、五章的取舍思路。
优先级：可证 > 可复用 > 可读 > 完整。
边界：本 skill 管「从素材里提炼什么、升到哪一层、怎么证」——提炼方法与置信度。产物若是 Axis 仓库的 SKILL.md，其格式合规（frontmatter、目录结构、门禁、挂载）由 writing-skills 管；它管格式，不管提炼方法。
一、四种提炼手法
按信息密度排序。前两种是主力，后两种是补充——素材充足时不必凑齐四种。
1. 从否决里拿原则
为什么信息密度最高：做了什么只说明这条路走通了；用户推翻过什么、为什么推翻，暴露的是「看起来合理、实际是决策」的分歧点。这种分歧点是默认可信度最低的地方，也是新人 agent 最容易重犯的地方。
做法：素材里每条「改了 / 退了 / 不要这样 / 我说了要 X」都抽一条。每条问两次：这次改判动了哪一层（机制 / 取值 / 表述）？同一件事有没有被改判两次以上？
判据：每条通则能指出它是从哪一次否决来的；指不出的要么删掉，要么降级为「观察」并标注强度。
亲历：某项目里一个输入的默认值被两次改判，两次都没有重写机制层，只改了取值函数和三个常数。由此得到的通则是「默认值与阈值是可玩性问题，不是实现问题」——抽象掉项目名词之后它依然成立。
2. 反复计数
为什么：同一件事被反馈第 N 次，说明前几轮修在了错误的层次。这不是症状描述，是优先级信号。
做法：对每类问题数独立事件的次数。计数低于 2 的不立规——一次案例是巧合，两次是巧合，三次才可能是模式。
判据：文档里写明「第 N 次反馈 / 第 N 轮迭代」；计数为 1 的条目标「单例，降权」而不是删（见第三章）。
3. 从真实产物综合
会话记录之外的东西密度更高：交接文档、PR 评审意见、事故复盘、事故工单、git commit 消息、被回滚的补丁。回滚记录是最高价值的一手材料——它精确指出了某条路走不通。
做法：把这类材料当独立来源单独读，不要只读会话记录。
4. 联网对标
亲历结论必须尝试找公开一手材料交叉验证，三种结果各有不同处理：
| 结果 | 处理 |
|---|---|
| 被互证 | 升为主张，附引文 |
| 被补强 | 保留原判据，标注补强来源 |
| 被反转 | 按公开材料改写，并在正文标注为反直觉结论 |
被反转不是失败，是本 skill 最值钱的产出之一。
亲历：曾把「结构越线性越好」当通则，公开一手材料（工作室自述 + 它给出的机制解释）证明非线性枢纽布局增加焦虑、而更线性的续作该感受下降。已按公开材料改写。
抽一手素材的具体做法（多代理并行精读、统一三元组格式、从症状描述里分辨优先级信号、拒绝自造术语）在 references/from-transcripts.md。
二、先建评测，再写文档
为什么：文档写完再评测，你会为了让它通过而改评测；先建评测，改的是文档。评测集是唯一能证明 skill 有价值的证据，也是唯一能防止你把它写成一份没人读的 best practices 搬运的东西。
两套评测，最小形态
| 评测 | 回答 | 最小形态 | 通过线 |
|---|---|---|---|
| 触发率 | agent 会不会在该读它的时候读它 | 20 条查询（10 正 10 近似错配负），每条跑 3 次 | 正例触发率 > 0.5；负例 < 0.5 |
| 输出质量 | 读了它之后产出是否更好 | 8–10 个 case，with/without 各跑一遍，只差 skill 是否安装 | 看 skill lift（差值），不看绝对分 |
近似错配负例是触发率评测的全部价值。零概念重叠的弱负例（「写个斐波那契函数」）测不出任何东西。负例必须共享概念、需要的是别的事情。
正例里最有价值的是关联不明显的那些——用户没明说「提炼」这个动作，但诉求需要它。如果查询已经明说 skill 做什么，任何合格 description 都会触发。
断言必须分级：脚本可查的（条目数、字段齐全、禁用词为空）标 good，人工评审的（这条通则换一个项目还成立吗）标 weak_manual。标 UNMEASURED 的项不要编分数。
三个必须做的判读动作
- 删掉「两种配置下都总是 pass」的断言——它们抬高 with-skill 通过率却不反映价值。
- 查「两种配置下都总是 fail」的断言——要么断言写错了，要么 skill 缺内容。这是最值钱的发现。
- 研究「只有有 skill 才 pass」的断言——这才是 skill 创造价值的地方。报告分三类列，不给单一总分。
过约束警告
加规则后通过率不再上升，就是过度约束的信号。删掉一些再看是否保持或变好。更少但更好的指令常常胜过穷尽规则。
协议细节、防过拟合划分（train/validation 60-40）、harness 方差警告见 references/evals.md。
最小可勾选清单
- 20 条触发查询写完（10 正 10 近似负，正例含至少 3 条关联不明显的）
- 8–10 个输出 case 写完，每条断言标了 strength
- 每条至少跑 3 次（单次测量在 harness 方差面前没有意义）
- 断言本身被审查过一遍（三种坏断言：太容易 / 太难 / 不可验证）
- 判读时做了上面三个动作
- 某轮迭代加了规则后通过率不再上升 → 删规则再看
三、抽象层次
判定法只有一条：换一个项目还成立吗。
- 成立 → 通则，进 skill 正文。
- 不成立 → 项目文档，或下沉到 reference 的专项附录。
- 只在你的项目里成立，但可能有价值 → 标「单例，降权」，写清它在本项目为什么成立，别删。
亲历对照：「满充 11.9 秒」属于项目文档；「变化必须在 1.5–2 秒内出现在画面上」是通则——它不依赖具体项目且可判定。
什么是必须下沉的
- 具体数值、实测结果、行号、代码片段
- 被否决方案的实现细节（保留它暴露的分歧点）
- 推导链里的项目专有名词
- 只出现过一次的孤例
三条常见的抽象失败
- 抽象成了口号：「要重视一致性」——没有一个 agent 会因为它改变行为。
- 抽象到了错误的层：把一个取值问题升成机制问题，或反过来。
- 为了通用而丢掉了 why：抽掉了推导，原则就变成没人会照做的规则（见第六章）。
必须带判据。判据要能被写成断言，或能被人工过一遍。操作化方法、正例反例对照见 references/abstracting.md。
四、分层剥离
两层：通用层（为什么成立 + 判据）与专项附录（具体名词、版本行为、数值）。
判定标准要可 grep：正文出现技术栈名词即为泄漏。用一次 grep 验证，不要凭印象。
分层例外的三个合法位置（都只是名词出现，不带任何该栈的行为结论）：
description里——它是发现层，匹配对象是用户说的话，用户会说平台名和工具名。- 路由表里——它是分发层，职责就是把项目匹配到正确附录。
- reference 的来源小节里——URL 自带域名。
五、结构决策
按处境切分，不按主题切分
参考文件的分篇依据是**「agent 在什么处境下需要它」**，不是「这批知识属于哪个学科」。处境互斥时，路由表才能给出「触发条件 → 读这篇」的一对一映射。主题切分会产生「机制篇」「流程篇」这种每篇都被多处境同时需要的结构，路由表立刻退化成「详见参考」。
主文件预算
- 上限 500 行，社区警戒线 400。
- 逐条过正文判据：「没有这条，agent 会不会做错？」不会就删。
- 高价值坑必须留在主文件——agent 是在遇到情况之前读它的；拆到 reference 它不会意识到该去读。
每条引用自带触发条件
写「如果 X 则读 y.md」，不写「详见参考」。笼统的引用等于没有引用。
每条原则带判据
| 写法 | 判断 |
|---|---|
| 「旁白只说画面给不出的话」 | 没人会照做——这是口号 |
| 「删掉这句，玩家损失的是一个信息还是一次判断」 | 能被执行——这是判据 |
全部写成「原则 / 推导依据 / 判据」三段。
给默认，不给菜单
写清推荐路径与例外条件。列一串选项让 agent 自己选，等于没约束。
资产该放哪：能机械执行的一律进 scripts/；文档格式模板进 assets/；只有需要判断力的才进 references/。
详细结构设计（预算分配、反例表、术语表、目录写法）见 references/structure-and-routing.md。
六、置信度纪律
三类来源强度，逐条标注
| 强度 | 含义 |
|---|---|
| 亲历可指认 | 能指出具体哪一次事故；正文可不加限定语 |
| 公开来源有引文 | 出处见 reference 末尾；正文标注来源类型 |
| 自建框架 | 你自己搭的，没有外部依据；正文显式声明 |
自建框架不丢人，不声明才丢人——读者无法判断哪部分能挑战。
材料缺口显式列出
检索后确认没有高质量材料的方向，在正文对应位置标注，不要编造，也不要用弱来源硬撑。
未解决分歧保留，不强行合并
两条公开材料互相冲突时：并存写下，各自给判据，并在 CREATION-LOG 里列为留给后来者的收敛点。假装它们已经调和是本 skill 最该避免的失败。
亲历：四条分歧按并存 + 各自判据处理，其中两条至今未收敛。
七、GOTCHAS
- 反复反馈是优先级信号，不是在描述症状。 同一件事被反馈第 4 次，说明前几轮修在了错误的层次（多半是调参而不是测量）。文档里写明「第 N 次反馈」。
- 回声证据：先查素材有没有把自己的规则读进去。 会话素材常会读取提炼者自己的记忆/规范文件，于是既有纪律会以「本项目悟出的新道理」的面目重新出现。不剔除的后果不是多写几条重复规则，而是给已有纪律加上并不存在的外部证据，把「≥3 才立项」的门槛做成假的。做法：合并阶段拿每条候选原话回查本仓既有文件；命中即移出证据计数，但保留原则本身。两个项目各自应验一次是强度上调的信号——它要求防线落到执行路径（闸或不可用入口）上，而不是再写一遍文字。
- 引文可验不等于注释可信。 代理的逐字引文能通过回查，它计数表里的轮次编号、案例代号仍可能串到另一个项目去（本次实测：某段计数表引用了「第二十二轮」「122→66」，两个字符串在素材里 0 命中，而同名字段属于工作区里另一个项目的溯源表）。回查工具只管原话列，管不到注释。所以：合并时只取引文与行号，不取代理自填的编号与统计；需要引用规模数字时，自己跑一次命令取数。
- 交付物里的规模数字，写之前当场测一次。 「447,828 行」这类自述值会随口径变化（含不含代码围栏、按哪种换行）；写进文档的每一个都要能指一条命令。本 skill 自己的文档也受这条约束。
- 格式不统一的批件会静默丢证据。 并行精读若有人交出「原则+判据」而省掉原话列，那一批就失去可回查性：只能降级为佐证，不能当一手引文用。合并前先跑一次格式校验并报告不合规条数，不许默默跳过。
- 行号在不同口径下会漂移。 素材若含裸
\r（CI 日志常见），按通用换行数出的行号与按\n数出的能差近千行。判据必须绑逐字存在的原话，行号只作定位提示并由回查工具回填。 - 读一手素材，不读二手结论。 项目里已写好的复盘文档、交接文档、会话导出——已存在的「结论」会丢掉否决背后的理由，重新去读原始素材。
- 多代理并行精读必须统一输出格式（三元组：原话 → 抽象原则 → 判据）。格式不统一，六千行散料会在合并阶段丢信息。
- 分层泄漏是可 grep 的，不要靠印象判断。 正文出现技术栈名词即为泄漏；跑一次 grep。
- 高价值坑拆到 reference 等于删掉。 agent 读不到自己不知道存在的东西。
- PASS 必须给具体证据。 断言说「包含一份总结」而输出真有个叫 Summary 的标题、里面只有一句空话——那是 FAIL。label 在但 substance 不在，是 FAIL。
- 不要断言所有东西。 氛围、手感这类半主观项交给人工并标
UNMEASURED。编一个分数比留空更糟。 - 找不到根因时，如实说「我能证伪所有猜测但没定位到」，比假装修好有价值得多。
- 不要把失败用例里的具体关键词加进 description。 那是过拟合。要找的是这些用例代表的一般类别。
- 按 validation 通过率选最优，不是按 train，也不是按最后一版。
- 不可破的例外和真 bug 长得一模一样。 记录哪些「看似出错的地方」是设计好的破例。
- 不要解释模型已经知道的东西，也不要写泛泛的最佳实践（「妥善处理错误」「保持代码整洁」这类是官方点名的失败模式）。
八、references 路由表
每条引用自带触发条件。按需读，一次只读命中的那几篇。
| 触发条件 | 读这篇 |
|---|---|
| 素材是对话记录／工单／PR 评审／事故复盘／git 历史，要开始抽原则；判断某条反馈是症状还是优先级信号；派多个代理并行精读该怎么定格式 | references/from-transcripts.md |
| 拿不准一条经验该升成通则还是留在项目里；正在做保留／丢弃对照；想给抽象层次配正例反例；判断是不是抽象过头了 | references/abstracting.md |
| 决定参考文件分几篇、每篇按什么切；主文件超预算要裁；写路由表；写每条原则的「原则／推导／判据」三段式 | references/structure-and-routing.md |
| 句子已经铺开、正在逐句改写给 agent 的规范文本；检查每条判据是否可执行；查祈使句、给默认、不用全大写、错误信息带位置与下一步、自造术语有标注 | references/writing-rules.md |
| 在写或改评测集；设计触发率查询与负例；给输出 case 写断言；判读 with/without 结果；怀疑自己过度约束了 | references/evals.md |
九、随附脚本
并行精读的合并阶段必跑这两条，不靠手工抽查（抽查会漏，且不可复算）：
python3 scripts/normalize_items.py <交回条目> <归一后条目> # 吃掉格式偏离，不丢任何一行
python3 scripts/quote_check.py <素材> <归一后条目> # 逐字回查原话 + 回填真实行号
前者把「行号写在第一列」这类偏离归一到协议格式；后者要求每条原话逐字存在于素材（与换行口径无关），并打印格式不合规数与回查失败数。两者都有已知缺陷样本可用来自证：一条素材里不存在的引文必须判红，缺列的行必须报格式不合规。
术语表
- 二阶提炼：素材不是「项目的内容」，而是「提炼这个项目时的做法」。本 skill 就是二阶产物。
- 三元组：统一格式的抽取产物——「用户原话 → 抽象原则 → 判据」。格式统一是并行合并不丢信息的前提。
- 反复计数：对同一类问题的独立事件计数。≥3 才当模式，=1 标单例降权。
- 优先级信号：一条反馈的第 N 次出现，指示修错了层，而不是指示症状。
- 换个项目还成立吗：抽象层次的唯一判定法。
- 单例，降权：只在本次项目成立但可能有普遍性的条目。保留并标注强度，不升为主张。
- 分层泄漏：通用层正文里出现技术栈名词或具体数值。可 grep 检测。
- skill lift：同一任务 with/without skill 的断言通过率差值。skill 的真实价值指标。
- 强负例 / 近似错配：共享概念但需要别的事情的负例，是触发率评测唯一有信息量的负例。
- UNMEASURED：难以拆成 pass/fail 的半主观项，交人工评审且不编分数。
- 给默认不给菜单：写清推荐路径与例外条件，而不是列一串让 agent 自己选。
附：来源与可信度
- 全部通则的骨架来自一次完整的独立项目开发经验提炼（三份会话导出共约 178k 行、项目内文档 11 份约 1800 行、26 轮决策史）。这是二阶提炼：素材是「提炼过程的做法」，不是「那个项目的内容」，因此正文不含任何该项目的领域名词。
- 官方 skill 写作硬约束（frontmatter 字段、description 长度与祈使式、主文件行数、参考文件一层深、给默认不给菜单、避免全大写 MUST/NEVER）来自公开文档调研，作为正文约束的第二来源。
- skill 的评测方法学本身没有高质量一手材料：断言强弱分级、审查断言本身、三个判读动作、过约束警告均为自建框架，已在正文显式标注。这是本 skill 最需要后续补强的地方。