creekmoon Cerydra Codex - 代码规律提炼器
技能定位
这个技能只做一件事：从现有代码中提炼某个维度的稳定约定，输出为一份可复用的规则文件，帮助后续"解决同一类问题"时有据可依。
产出的定性是指南性规范：核心内容是"推荐怎么写、背后是什么业务规律、什么情况下可以偏离"，而不是一份"必须/禁止"清单。原因来自落地实践：强制条文总会被现实业务突破——计划赶不上变化，被突破过一次的"必须"从此失去公信力。真正能让后续的 LLM 和开发者写好代码的，是掌握这份代码背后的业务规律，从而在没见过的新情况下也能做出一致的判断。条文会过时，规律不会。
为质量投入 token 是值得的：一份好指南的地基是核实过的事实。本技能默认派发子代理完成规律侦察和反例核查两个环节——没有经过反例核查的做法，不允许写成"推荐"。
输出格式固定，文件命名固定（中文名_rule.md），内容偏向"规律与推荐做法的表达"，而不是"分析说明"。
核心原则（贯穿全流程）
下面五条优先级最高，与后续任何步骤冲突时以这五条为准。
原则一：指南优先，硬约束是稀缺品
默认档位是 [推荐]。[硬约束] 只留给"违反会造成可验证的实际损害"的极少数场合（编译失败、数据不一致、资损、安全漏洞、框架强制），且必须写清具体后果和突破路径。写 [硬约束] 之前先回答"违反它到底会坏什么"——答不出具体后果，就降为 [推荐]。
原则二：没有"为什么"的条目不配存在
每条推荐做法都要写出它承载的业务规律：这个做法在保护什么（隔离变化 / 收敛入口 / 统一口径 / 简化接入……）。读者靠规律举一反三，靠条文只能机械服从——遇到条文没覆盖的新情况就会失灵。写不出"为什么"的条目，要么继续核查，要么删掉。
原则三：反例是指南的一部分，不是噪音
反例核查找到的偏离样本必须有去向：合理例外沉淀为"场景分支"（它往往是另一条规律）；历史遗留写进"已知偏离"并点名不建议模仿；疑似 bug 进"待确认"。一份只有正面做法、看不到真实偏离的指南，遇到现实业务就会失效。
原则四：业务语义优先，先理解"想干什么"再下结论
不要照着现有目录/命名无脑固化。下结论前，先从文件名、包名、类名、变量名出发，推断这段代码"想表达什么业务意图"，再判断当前的归类、命名、位置是否和这个意图一致。
示例：
utils包下目前只有一个SysAdminConverter.java。
- 表面归纳：放进
utils包 → "推荐工具类放 utils"。- 业务语义校验：
Converter暗示这是业务兼容/模板代码，未来很可能扩展出多个 Converter；严格说它不是通用工具，更像converter包的成员。- 结论：当前归类存疑，不能写成"推荐"。最多写"可参考：现状放在
utils；从命名看更像converter包，未来扩展时可考虑迁移"。
原则五：现状可疑时，写出更优方向，而不是固化现状
当一条约定只能落到"可参考"档（样本稀少 / 业务语义存疑），且你从命名或业务语义看出了更合理的安排，必须把它写出来（"现状是 X；从命名看更像 Y；未来可考虑 Z"），不要假装现状就是答案。
调用前必须先确认
调用此技能前，必须先说清楚以下信息。信息不全时，先追问，不要直接开始归纳。
规则名称： 例如"承运商接入标准"、"通用CRUD规范"、"订单模块约定"
规则维度： 这份规则约束的是什么（见下方"规则类型"）
使用场景： 在哪些开发情况下需要参考这份规则
适用范围： 涉及哪些目录、文件、模块
样本代码位置：至少给出大概目录、模块或入口文件；如果用户说不清代表文件，技能再自行选样本
保存位置： 规则文件准备保存到哪里；如果用户未指定，默认保存到 `.cursor/rules/`
规则类型必须先判断：
模块级规则：针对某个具体模块的内部约定- 例如：订单模块、承运商接入模块、支付模块
- 归纳重点：目录结构、内部职责切分、命名、边界
横切规则：针对多个模块共用的实现套路- 例如：通用 CRUD、异常处理、DTO 转换、日志约定、SDK 集成
- 归纳重点：必须跨多个模块样本验证，不能把某一个模块的局部写法误当通用约定
如果用户说不清楚类型，默认先当模块级规则处理，归纳后再判断是否有更广泛适用性。
执行流程
固定五个环节，一个不跳：确认信息 → 规律侦察 → 反例核查 → 业务语义校验 → 证据归并与成文。其中侦察与核查默认派发子代理执行，提示词固定使用 agents/ 下的文件，不临场发明流程。
Phase 0：确认信息
收到调用请求后，先确认以下信息是否齐全：
- 规则名称和类型（模块级 / 横切）
- 适用场景和范围
- 样本代码位置在哪里
- 规则文件保存位置在哪里
如有缺失，直接追问 1 到 2 个关键问题，拿到答案后再开始探索。
追问优先级：
- 如果样本代码位置不清楚，优先问这个问题
- 如果规则维度或使用场景模糊，再追问"这份规则到底约束什么、给谁用"
- 保存位置若未指定，可直接采用默认值
.cursor/rules/，不必额外追问
Phase 1：规律侦察（子代理）
目标是铺开：这个维度下有哪些反复出现的稳定模式值得沉淀，样本分布如何，哪里还没覆盖。
- 派发子代理执行，提示词固定使用
agents/pattern-scout.md，并把 Phase 0 确认的信息（规则名称、维度、类型、范围、样本位置）作为输入交给它 - 模块级规则：派 1 个侦察代理
- 横切规则：按模块分片，并行派 2-3 个侦察代理，每个负责一个模块的取样——这是防止"单模块写法冒充全局约定"的结构性手段
- 交付物：候选规律清单（每条含规律描述、证据文件、出现次数、意图推测、疑点）+ 样本地图（适用文件全集口径、覆盖与未覆盖区域）
主 agent 收到交付后做一轮筛选：标注为"框架强制"的单独归类（见"特殊场景处理"）；只出现一次且无扩展迹象的降权；把值得核查的候选规律整理成清单，交给下一环节。
Phase 2：反例核查（子代理）
目标是拆穿：一条没有经过反例核查的"稳定约定"，很可能只是采样偏差。这一环节是整份指南质量的来源，多花 token 是值得的。
- 派发子代理执行，提示词固定使用
agents/counterexample-hunter.md，输入为 Phase 1 筛选后的候选规律清单和样本地图 - 候选规律较多时（> 6 条），按规律分组并行派发
- 交付物：每条候选规律的一致率（遵循数 / 适用全集总数，分母必须可交代）、反例清单（每个反例含文件、实际行为、定性）、适用边界修正建议
反例定性只有四种，每个反例必须落到其中之一：
| 定性 | 含义 | 在指南中的去向 |
|---|---|---|
| 合理例外 | 偏离有明确场景原因，且该场景下写法自身稳定 | 沉淀为"场景分支"条目 |
| 历史遗留 | 老代码未迁移，新代码已不这么写 | 写进"已知偏离"，点名不建议模仿 |
| 疑似 bug | 偏离看起来就是写错了 | 进"待确认"，单独提示用户 |
| 推翻规律 | 偏离广泛存在且无场景区隔 | 该候选规律不成立，不写或降为"可参考" |
铁律：没有经过本环节核查的候选规律，最多写 [可参考]。
Phase 3：业务语义校验（主 agent 必做）
拿到核查结果后、归并之前，主 agent 对每条准备写进规则的目录 / 包 / 类 / 命名做业务语义校验。这是把"照搬现状"和"提炼合理约定"区分开的关键步骤，子代理的意图推测只是输入，判断由主 agent 负责。
对每条候选规律问三个问题：
- 它想干什么？ 从文件名、包名、类名、变量名推断业务意图。
- 现状和意图一致吗？ 当前的归类、命名、位置，是否真的匹配这个意图？还是只是"暂时这么放着"？
- 会不会限制扩展？ 如果未来同类东西变多，现在这个安排还成立吗？
校验结果落到一个标签，直接影响后续档位：
契合：命名 / 职责 / 位置与业务语义一致，扩展方向清晰存疑：命名暗示的职责与当前归类不一致，或当前写法可能限制扩展 → 最多写"可参考"，并记下更合理的安排待判断：信息不足，无法确认 → 不上推荐档
Phase 4：证据归并与档位判定（Evidence Map）
在成文之前，先整理证据，不要一边看核查结果一边直接写条目。
Evidence Map 是内部工作草稿，默认不出现在最终规则文件中；最终规则文件只保留必要的"一致率""参考实现""证据来源"。
每条待写规律先填这张表：
| 规律点 | 证据文件 | 一致率 | 反例定性 | 业务契合度 | 落到哪一档 |
|---|---|---|---|---|---|
| Parser 只做字段映射，不写流程逻辑 | QuoteParser.java 等 15 处 |
14/15 | 1 个历史遗留 | 契合 | 推荐 |
| 状态更新走 StatusMachine 统一入口 | 12 处调用点 | 9/12 | 3 个属定时任务场景且写法一致 | 契合 | 推荐 + 场景分支 |
| Converter 放在 utils 包 | SysAdminConverter.java |
1/1 | 无适用面 | 存疑 | 可参考（附更优方向） |
档位判定（核心规则）：
| 证据强度 \ 业务契合度 | 契合 | 存疑 | 待判断 |
|---|---|---|---|
| 强（一致率高且样本充分，反例均已定性） | 推荐 | 可参考（写明存疑点 + 更优方向） | 可参考 |
| 中（有明确样本，覆盖面有限） | 推荐 / 场景 | 可参考 | 可参考 |
| 弱（≈1 个样本，或反例未定性） | 可参考 | 可参考（必须附更优方向） | 不写 |
一致率结合样本量看：3/3 和 27/30 不是一回事，前者最多"推荐（写明样本尚少）"。
[硬约束] 不走上表，必须同时满足三个门槛：
- 违反会造成可验证的实际损害（编译失败、数据不一致、资损、安全漏洞、框架强制），且能写出具体后果
- 反例核查结果为零反例，或所有反例均被确认是 bug
- 业务语义契合
且每条硬约束必须写突破路径：如果现实业务确实要突破，应该先做什么（先改配套机制 / 先与某方对齐口径），不留死门。
Phase 5：生成规则文件
完成 Phase 4 后，按下面的模板生成规则文件，保存为 {中文规则名}_rule.md。
保存位置规则：
- 用户已指定目录时，保存到用户指定位置
- 用户未指定时，默认保存到
.cursor/rules/ - 如果仓库语境明显不是 Cursor 规则目录，再补问是否改存到其他文档目录
文件结构模板（按需裁剪，不要求所有章节都出现）：
---
description: {一句话说明这份规范在什么场景下被参考}
globs:
- {适用文件路径，例如 src/main/java/com/example/order/**/*}
alwaysApply: false
---
# {中文规则名}
本指南提炼 {维度} 在 {使用场景} 下的稳定规律与推荐做法，来自现有代码的实证核查。
条目以 [推荐] 为主体，每条说明背后规律与可偏离情形；[硬约束] 极少出现，仅用于违反会造成实际损害的场合；[可参考] 仅为现状参考，不构成背书。
一、适用范围
二、核心规律（这个维度最重要的 2-4 条业务规律，用连贯的话讲清"代码为什么长成这样"，让没读过代码的人先建立整体图景）
三、推荐做法（主体章节；模块级规则可按 结构 / 职责 / 命名 / 流程 分小节组织）
四、场景分支（同一问题在不同场景下的不同合理做法；无则省略）
五、已知偏离与例外（反例核查发现的真实偏离：哪些是合理例外、哪些是历史遗留不建议模仿）
六、待确认 / 可演进点（样本少、业务语义存疑或疑似 bug 的条目，连同更优方向写在这里）
七、参考实现 / 证据来源
条目示例（注意各要素的写法）：
三、推荐做法
[推荐] Parser 只做字段映射，不写业务流程逻辑。
背后规律：本模块把"外部报文的形状差异"隔离在 Parser 层，流程编排统一收敛在 Service——
这样新接一家承运商只需要加 Parser，不用动流程。
何时可偏离：报文字段间存在强依赖、必须在映射时做上下文判断的场合，可在 Parser 内做局部裁决，
但裁决结果应以字段形式交给流程层，而不是在 Parser 里直接调用下游。
一致率：14/15（唯一偏离 LegacyQuoteParser 为历史遗留，见"五、已知偏离"）
参考实现：QuoteParser.java / BookingParser.java / TrackParser.java
[硬约束] 运单状态变更必须经 StatusMachine.transit() 统一入口，禁止直接 update 状态字段。
违反后果：绕过入口会跳过状态合法性校验与事件发布，下游对账依赖状态事件，直接改字段会造成对账数据错乱（已有事故案例）。
突破路径：如确需批量修数，走运维脚本通道并同步补发状态事件，先与对账方对齐口径。
一致率：12/12
参考实现：StatusMachine.java / OrderStatusService.java
[可参考] 转换类目前放在 utils 包（参考 SysAdminConverter.java）。
说明：仅 1 个样本。从命名看 Converter 更像业务兼容代码、未来可能扩展出多个，严格说不属于通用工具类。
更优方向：未来转换类增多时，可考虑独立的 converter 包，而非统一塞进 utils。
至少保留这些核心章节：
一、适用范围二、核心规律三、推荐做法七、参考实现 / 证据来源
如果某一章对当前规则维度不成立，直接省略，不要为了凑模板硬写。
规则文件写法要求
档位体系
| 档位 | 标注 | 含义 | 触发条件 |
|---|---|---|---|
| 推荐 | [推荐] |
默认做法：新代码默认这么写，有明确理由可偏离 | 一致率高 + 业务契合 + 反例均已定性 |
| 场景 | [场景] |
同一问题在特定场景下的另一种稳定做法 | 反例核查确认"偏离"自成场景且写法稳定 |
| 可参考 | [可参考] |
仅作为现状参考，不构成背书 | 样本稀少（≈1 个）/ 业务语义存疑 / 未经反例核查 |
| 硬约束 | [硬约束] |
违反会造成可验证的实际损害 | 三门槛同时满足（后果可写出 + 零反例 + 业务契合） |
选词纪律：
- 默认往低档写。拿不准就降一档，"可参考"永远比错误的"硬约束"安全。
推荐与可参考的区别：推荐是"这么做更好、值得跟，且经过反例核查"；可参考是"现状如此、给你个参照，但不保证它合理"。- 用"可参考"时，若看出更合理的安排，必须一并写出（见原则五）。
条目要素：
[推荐]条目必须含：推荐写法（一句话）、背后规律（为什么）、何时可偏离、参考实现；有核查数据时附一致率[硬约束]条目必须含：约束内容、违反后果（具体的）、突破路径、参考实现[场景]条目必须写清触发场景的判断条件，避免读者拿不准该走哪条分支[可参考]条目若有更优方向，必须写出来，不要只留一句"现状如此"
其它结构关键词（与档位无关，用于标注约定类型）：
| 关键词 | 适用场景 |
|---|---|
位置： |
文件或目录约定 |
命名： |
命名模式 |
职责： |
某个角色能做什么、不能做什么 |
语气与结构要求
- 规则正文偏"规律与做法的表达"，不要写成说明文、分析文或流水账
- "二、核心规律"用连贯的段落写，其余章节每条约定独立一行，不堆在段落里
- 每条条目前标注档位：
[推荐]/[场景]/[可参考]/[硬约束] - 如果某条规律依赖现有样本，注明"参考
{文件路径}"
规则类型差异
模块级规则写法重点
- 重点描述该模块内部的目录约定、职责边界、命名、配置
- 规则的适用范围限于该模块，不要泛化成全局
- 如果模块内部存在新旧两套风格，分开写，说明哪套是当前推荐
- "三、推荐做法"内通常按 结构 / 职责 / 命名 分小节组织
横切规则写法重点
- 必须说明这条规律在哪些模块中已验证（列出具体参考实现）
- 侦察阶段必须按模块分片并行取样（至少 2-3 个模块），核查阶段的适用全集必须跨模块
- 规律条目应抽象到"与具体模块无关"的表达
- 如果不同模块存在实质性差异，不要强行合并；分化为
[场景]条目或降为"可参考"
特殊场景处理
新旧风格并存
不要强行统一。分开描述，给出当前推荐方向和依据；旧风格样本归入"已知偏离与例外"，点名是否建议迁移。
框架强约束
区分"框架规定"和"团队自己选择"，重点写后者。框架强制项若有必要收录，标注"框架强制"，不占用团队约定的篇幅。
跨模块链路规则
如果规则本质上是一条跨模块调用链路，按"链路阶段"组织，每个阶段分别说明约定，不要按目录硬拆。
无法派发子代理的环境
若当前环境不支持子代理，由主 agent 亲自按 agents/pattern-scout.md 和 agents/counterexample-hunter.md 两份提示词逐份执行——省掉的只是并行度，侦察和核查环节一个不减。样本极小（有效文件 < 5 个）时同理，可由主 agent 直接执行两个环节，但规则文件中要标明"草案规则，待样本丰富后补齐"，条目整体落在"可参考"档。
禁止项
- 不要把行业最佳实践冒充成"项目当前实践"
- 不要写没有"背后规律"的条目——读者记不住也无法举一反三，这种条目宁可不写
- 不要轻易写
[硬约束]；答不出"违反它到底会坏什么"，就降为[推荐] - 不要跳过反例核查就把某个做法写成
[推荐]（未核查的最多[可参考]） - 不要把反例当噪音丢掉：合理例外要进"场景分支"，历史遗留要点名"不建议模仿"
- 不要因为看到
1个例子就上升为约定（最多"可参考"） - 不要跳过业务语义校验，照搬现有目录 / 命名就直接下结论
- 不要把业务语义存疑的现状写成"推荐"（应降到"可参考"并写出更优方向）
- 不要把模块局部写法写成全局通用规则
- 不要报一个分母不可交代的一致率——宁可写"未穷尽核查"降档处理
- 不要默认全仓扫描，尤其在 monorepo 里；侦察和核查都要圈定范围
输出前检查清单
- 规则名称和适用场景写清楚了
- 走完了 规律侦察 → 反例核查 → 业务语义校验 → 证据归并 四个环节，没有跳步
- 每条条目都标注了档位（推荐 / 场景 / 可参考 / 硬约束）
- 每条
[推荐]都写了"背后规律"和"何时可偏离"，且经过反例核查 - 每条
[硬约束]都满足三门槛，写了具体后果和突破路径 - 反例都有去向：合理例外 → 场景分支；历史遗留 → 已知偏离；疑似 bug → 待确认
- "二、核心规律"能让没读过代码的人建立整体图景
- 业务语义存疑处已降档并写出更优方向
- 横切规则有跨模块样本验证；模块级规则没有被错误泛化成全局
- 文件命名格式为
中文名_rule.md
一句话原则
这份技能产出的不是禁令清单，而是一份经过实证核查的业务规律指南：侦察铺开事实，反例核实一致率，语义校验把关合理性，最后写成"推荐怎么写、为什么、何时可偏离"——让后续的读者靠规律举一反三，而不是靠条文机械服从。