# Creekmoon Cerydra Codex

> 从现有代码中提炼某个维度的业务规律与稳定约定，生成指南性规范文件（中文名_rule.md）——以"推荐怎么写 + 背后规律 + 何时可偏离"为主体而非强制条文，并默认派发子代理做规律侦察与反例核查以保证事实质量。Make sure to use this skill whenever the user wants to整理某个模块的开发规范、抽取某类通用规则、把现有实现沉淀成 `.cursor/rules` 或 `xxx_rule.md`、为某个开发场景定义约定与推荐写法、或对齐新老实现方式。适用于模块级规则和横切规则。不要用于直接写业务代码、做系统架构设计、写分析报告或做代码 review。

- Skill: `creekmoon/creekmoon-cerydra-codex` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add creekmoon/creekmoon-cerydra-codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/creekmoon/creekmoon-cerydra-codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: creekmoon (https://skillmd.com/u/creekmoon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/creekmoon/creekmoon-cerydra-codex

---


# 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. 适用场景和范围
3. 样本代码位置在哪里
4. 规则文件保存位置在哪里

如有缺失，直接追问 1 到 2 个关键问题，拿到答案后再开始探索。

**追问优先级：**

1. 如果样本代码位置不清楚，优先问这个问题
2. 如果规则维度或使用场景模糊，再追问"这份规则到底约束什么、给谁用"
3. 保存位置若未指定，可直接采用默认值 `.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 负责。

对每条候选规律问三个问题：

1. **它想干什么？** 从文件名、包名、类名、变量名推断业务意图。
2. **现状和意图一致吗？** 当前的归类、命名、位置，是否真的匹配这个意图？还是只是"暂时这么放着"？
3. **会不会限制扩展？** 如果未来同类东西变多，现在这个安排还成立吗？

校验结果落到一个标签，直接影响后续档位：

- `契合`：命名 / 职责 / 位置与业务语义一致，扩展方向清晰
- `存疑`：命名暗示的职责与当前归类不一致，或当前写法可能限制扩展 → 最多写"可参考"，并记下更合理的安排
- `待判断`：信息不足，无法确认 → 不上推荐档

### 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` 不是一回事，前者最多"推荐（写明样本尚少）"。

**`[硬约束]` 不走上表，必须同时满足三个门槛：**

1. 违反会造成**可验证的实际损害**（编译失败、数据不一致、资损、安全漏洞、框架强制），且能写出具体后果
2. 反例核查结果为**零反例**，或所有反例均被确认是 bug
3. 业务语义**契合**

且每条硬约束必须写**突破路径**：如果现实业务确实要突破，应该先做什么（先改配套机制 / 先与某方对齐口径），不留死门。

### Phase 5：生成规则文件

完成 Phase 4 后，按下面的模板生成规则文件，保存为 `{中文规则名}_rule.md`。

**保存位置规则：**

1. 用户已指定目录时，保存到用户指定位置
2. 用户未指定时，默认保存到 `.cursor/rules/`
3. 如果仓库语境明显不是 Cursor 规则目录，再补问是否改存到其他文档目录

文件结构模板（按需裁剪，不要求所有章节都出现）：

```markdown
---
description: {一句话说明这份规范在什么场景下被参考}
globs:
  - {适用文件路径，例如 src/main/java/com/example/order/**/*}
alwaysApply: false
---

# {中文规则名}

本指南提炼 {维度} 在 {使用场景} 下的稳定规律与推荐做法，来自现有代码的实证核查。
条目以 [推荐] 为主体，每条说明背后规律与可偏离情形；[硬约束] 极少出现，仅用于违反会造成实际损害的场合；[可参考] 仅为现状参考，不构成背书。

一、适用范围

二、核心规律（这个维度最重要的 2-4 条业务规律，用连贯的话讲清"代码为什么长成这样"，让没读过代码的人先建立整体图景）

三、推荐做法（主体章节；模块级规则可按 结构 / 职责 / 命名 / 流程 分小节组织）

四、场景分支（同一问题在不同场景下的不同合理做法；无则省略）

五、已知偏离与例外（反例核查发现的真实偏离：哪些是合理例外、哪些是历史遗留不建议模仿）

六、待确认 / 可演进点（样本少、业务语义存疑或疑似 bug 的条目，连同更优方向写在这里）

七、参考实现 / 证据来源
```

条目示例（注意各要素的写法）：

```markdown
三、推荐做法

[推荐] 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 里；侦察和核查都要圈定范围

---

## 输出前检查清单

1. 规则名称和适用场景写清楚了
2. 走完了 规律侦察 → 反例核查 → 业务语义校验 → 证据归并 四个环节，没有跳步
3. 每条条目都标注了档位（推荐 / 场景 / 可参考 / 硬约束）
4. 每条 `[推荐]` 都写了"背后规律"和"何时可偏离"，且经过反例核查
5. 每条 `[硬约束]` 都满足三门槛，写了具体后果和突破路径
6. 反例都有去向：合理例外 → 场景分支；历史遗留 → 已知偏离；疑似 bug → 待确认
7. "二、核心规律"能让没读过代码的人建立整体图景
8. 业务语义存疑处已降档并写出更优方向
9. 横切规则有跨模块样本验证；模块级规则没有被错误泛化成全局
10. 文件命名格式为 `中文名_rule.md`

---

## 一句话原则

**这份技能产出的不是禁令清单，而是一份经过实证核查的业务规律指南：侦察铺开事实，反例核实一致率，语义校验把关合理性，最后写成"推荐怎么写、为什么、何时可偏离"——让后续的读者靠规律举一反三，而不是靠条文机械服从。**