# Creekmoon Lightcone Memory

> 项目业务图谱记忆系统——深挖跨模块业务逻辑、隐含依赖和业务不变量，以高信息密度文档建立可复用的项目记忆。Make sure to use this skill in ANY of these situations：(1) 当前项目存在 .light-cone/ 目录时必须触发，任何代码任务开始前先读 00-index.md；(2) 用户问"这个项目/模块/功能是干什么的"、"帮我梳理业务逻辑"、"这个类/方法/字段是做什么用的"、"为什么这里要这么设计"；(3) 用户刚接手项目、onboarding 或首次进入陌生模块；(4) 修改/新增功能前需要理解影响范围和跨模块依赖；(5) 用户提到"分析项目"、"建立记忆"、"更新记忆"、"了解项目"、"接手项目"、"深挖业务"、"项目文档"、"项目记忆"；(6) 故障排查或 code review 需要业务上下文时。If .light-cone/ exists, ALWAYS start from `00-index.md`.

- Skill: `creekmoon/creekmoon-lightcone-memory` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add creekmoon/creekmoon-lightcone-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/creekmoon/creekmoon-lightcone-memory/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-lightcone-memory

---


# LightCone 业务图谱记忆系统

> "解析项目万物，洞悉业务本质。"

**核心哲学**：业务逻辑 > 代码结构。Agent 必须先理解业务为什么这样运转，才能理解代码为什么这么写。

**信息密度原则**：单文档承载多层信息，拒绝碎片化。读一篇文档，获得过去需要读3-4篇才能获得的业务洞察。

**深度挖掘原则**：写模式必须发挥模型最大上下文能力，挖掘那些散落在各处的业务规则、跨模块约束、隐式依赖——这些才是代码的真正灵魂。

**证据优先原则**：结论强度不能超过证据强度。接口名、DTO 字段、注释、外部系统术语只能作为线索，不能单独证明项目定位、业务边界或系统归属。

**边界克制原则**：优先写「代码已证明什么」，再写「基于证据可推断什么」，最后单列「仍待验证什么」。高信息密度不等于高确定性。

**当前态原则**：记忆文档是系统现状地图，不是变更日志。更新记忆时必须把新证据改写成“现在系统如何工作”，不要记录“之前是什么、某天改成什么、已移除/新增了什么”这类变迁史。

**术语零发明原则**：记忆文档是术语的搬运工，不是发明者。所有专有名词只能来自代码标识符、项目文档或行业通语；三处都没有名字的概念，用大白话短语直述，禁止比喻造词（如“门闸”“护城河”）、数字打包命名（如“15 道门闸”“三大铁律”）、自创简称。详见文档规范 Section 6。

**业务结论原则**：记忆的价值单位是业务结论，不是代码事实罗列，更不是变更流水。合格的结论能回答“业务在什么条件下会发生什么、边界在哪里、越界会怎样”。把 git 日志或 diff 概要抄进文档不产生记忆；宁可探索成本高，也要把线索追到能下业务结论为止。

---

## 目录结构

```
.light-cone/
├── 00-index.md                 # 唯一入口：项目全景 + 快速导航
├── business/
│   ├── context.md              # 项目背景、核心术语、业务边界
│   ├── artifacts/              # 业务产物（高信息密度主文档）
│   │   └── {artifact}.md       # 产物全文档 = 概念 + 生命周期 + 关键代码 trace
│   └── flows/                  # 业务流程（跨产物端到端）
│       └── {flow}.md           # 流程全文档 = 场景 + 参与者 + 数据流转 + 失败传播
├── atlas/                      # 快速检索层（倒排索引）
│   ├── keyword.md              # 业务词/产物/角色 → 文档位置
│   ├── symbol.md               # 类/方法/表/API → 文档位置
│   └── symptom.md              # 故障现象/错误码 → 文档位置 + 根因
├── code/
│   └── modules.md              # 代码模块归属（单文件聚合）
└── schema/                     # 数据 Schema 层
    ├── overview.md             # 数据总览 + ER图
    ├── tables/                 # 单表/集合详情
    │   └── {table_name}.md     # 结构 = DDL + 字段含义 + 关联关系
    └── relations.md            # 数据关系矩阵（全局视图）
```

---

## Read Mode 读模式

### 场景 A：默认代码任务

```
1. 必读: 00-index.md
   └─ 获取项目全景 + 定位目标产物/流程

2. 按目标类型选择：
   ├─ 理解某业务产物 → business/artifacts/{artifact}.md
   ├─ 理解跨产物流程 → business/flows/{flow}.md
   └─ 代码符号定位 → atlas/symbol.md → 跳转对应产物

3. 够用就停。单篇产物文档已包含：
   ├─ Key Conclusions：3-7 条最关键的业务结论（先读这里）
   ├─ Why：为什么存在、业务目标
   ├─ Lifecycle：阶段划分、数据流、消费者
   ├─ Trace：关键调用链、事务边界、副作用顺序
   └─ Deep Business Rules：跨模块约束、隐含依赖、业务不变量
```

### 场景 B：Onboarding / 接手项目

```
1. 00-index.md（项目全景）
2. business/context.md（背景 + 术语 + 边界）
3. business/artifacts/ 下 2-3 个核心产物文档
4. business/flows/ 下 1-2 个主流程文档
```

### 场景 C：故障排查 / 症状检索

```
1. atlas/symptom.md → 按错误现象定位
2. 跳转至对应产物文档的「Failure & Degradation」章节
3. 阅读相关 Trace 章节了解调用链
```

### 场景 D：理解数据模型 / Schema

```
1. 必读: schema/overview.md
   └─ 获取数据全景 + ER图

2. 按目标选择：
   ├─ 理解单表/集合结构 → schema/tables/{table}.md
   ├─ 理解数据间关系 → schema/relations.md
   └─ 定位表归属 → atlas/symbol.md Tables 章节

3. 关联业务含义：
   └─ 表文档中的「业务产物归属」→ 跳转对应 artifact.md
```

### 场景 E：理解业务概念 / 实体与术语

```
1. 必读: atlas/entities.md
   └─ 获取业务实体全景 + 逻辑模型

2. 查找业务术语：
   ├─ 术语定义 → atlas/glossary.md
   ├─ 术语与字段映射 → schema/tables/{table}.md 字段血缘
   └─ 术语归属 → business/artifacts/{artifact}.md

3. 从物理数据反查业务含义：
   └─ 表文档中的「逻辑实体归属」→ 跳转 atlas/entities.md
```

---

## Write Mode 写模式

### 执行策略：主动拆分子代理

Write Mode 的扫描工作天然适合并行——**主 agent 应默认拆分子代理执行，而不是等用户要求**。原因：

1. **扫描维度彼此独立**：状态机追踪、副作用识别、数据关系挖掘等可以同时进行，互不阻塞
2. **深度换速度**：每个子代理聚焦一个子问题，能往更深走；串行执行时主 agent 上下文被全量代码占满，反而看不深
3. **更好的结论质量**：各子代理独立取证，再由主 agent 交叉审查，比单线程扫描更能发现矛盾与遗漏

**何时必须拆子代理：**

| 场景 | 拆法 |
|------|------|
| 初建记忆（全新项目） | 每个产物/流程一个子代理并行探查；主 agent 收口汇总 |
| 增量同步（代码变更后） | 变更涉及多个模块时，每个模块一个子代理；单模块变更可内联执行 |
| 深度更新（场景普查） | 对账出的每个新场景/失踪场景一个子代理走 Phase 1-4 深挖；存量抽查可合并为一个子代理 |
| Phase 1 扫描 | 将 20 项扫描维度按类分组（状态机/副作用/数据关系/时序依赖），至少拆 3-4 个并行子代理 |
| 同时需生成多篇文档 | 每篇文档一个子代理起草，主 agent 审查合并 |

**子代理分工模板（Phase 1 参考）：**

```
子代理 A — 业务核心流：状态机、调用链、事务边界（扫描项 1-6）
子代理 B — 数据层：DDL/ORM、数据关系、字段血缘、业务约束（扫描项 8-14）
子代理 C — 跨模块：隐式依赖、级联操作、时序敏感操作、疑点（扫描项 15-20）
主 agent — 收集三路报告 → 交叉审查矛盾 → 执行 Phase 2-5
```

> 如果当前环境不支持子代理（如纯对话场景），退化为串行执行 Phase 1，但须在开始前声明这一限制。

---

### 深度挖掘指令

写模式的目标是：**产出那些跨证据归纳、经得起反向审查的业务结论**。高信息密度不等于高确定性；越关键的结论，越要先过记忆审查。

#### 什么是合格的业务结论（一切写作的验收线）

一条合格的业务结论要说清四件事：**业务条件、系统行为、越界后果、证据锚点**。推荐句式（不强制，但四要素必须齐）：

> 当 {业务条件} 时，系统 {行为}；{条件不满足 / 越过边界} 时 {另一种行为或拒绝}。— 证据：`{ClassName}#{method}()`

落盘前过三道检验：

1. **可证伪**：能说出“什么证据出现就推翻它”。说不出的是感想，不是结论。
2. **可行动**：读者改代码、排障、评审时能直接引用它做判断。
3. **非复述**：把代码逐行翻译成中文不算结论。结论必须回答代码没有明说的问题——为什么这么做、边界在哪、谁依赖它。

典型的不合格产出（禁止落盘）：

| 反面模式 | 示例 | 病因 |
|---------|------|------|
| 变更流水式 | “本次提交优化了订单校验逻辑” | 抄 git 日志，没有业务含义 |
| 代码复述式 | “OrderService 新增 validateStock 方法，校验库存后抛异常” | 翻译代码，没回答业务上意味着什么 |
| 比喻包装式 | “订单要闯过 15 道门闸才能创建” | 自造词掩盖了规则本身，读者仍不知道拦什么、越界会怎样 |

同一个事实的合格写法：

> 库存不足的订单在创建阶段即被拒绝，用户不会进入支付页；拦截依据是实时库存查询而非缓存快照。— 证据：`OrderCreateValidator#checkStock(OrderCreateCmd)`

#### Phase 1: 全代码扫描（必须执行）

在创建任何文档前，必须完成：

```
┌─────────────────────────────────────────────────────────────────┐
│  SCAN PHASE - 撑爆上下文也值得                                   │
├─────────────────────────────────────────────────────────────────┤
│ 1. 全局搜索产物相关代码（类名、表名、状态枚举、关键字段）          │
│ 2. 识别所有生产者和消费者（谁创建？谁修改？谁读取？）              │
│ 3. 追踪数据流转（从入口到最终持久化的完整链路）                    │
│ 4. 找出状态机定义（所有可能的状态 + 转换条件 + 触发动作）          │
│ 5. 标记原子操作边界（哪些操作原子？哪些异步？哪些可能不一致？）     │
│ 6. 识别副作用（发送消息、调用外部 API、写缓存、发通知）            │
│ 7. 找出业务不变量（必须始终保持为真的规则）                        │
│ 8. 扫描数据结构定义（DDL、ORM 实体类、Schema 定义、迁移文件）      │
│ 9. 识别数据间关系（外键、隐式关联、关联查询模式）                  │
│ 10. 记录业务约束（非空、唯一、默认值背后的业务规则）               │
│ 11. 识别业务实体（从数据定义中找出逻辑实体及其物理分布）           │
│ 12. 分析字段血缘（原生字段 vs 计算字段 vs 冗余字段）               │
│ 13. 提取业务术语（建立术语到物理字段的映射）                       │
│ 14. 检查数据质量约束（主键、空值、一致性规则）                     │
│                                                                 │
│ 【数据关系深度挖掘 - 关键】                                        │
│ 15. 扫描业务逻辑层（不只是数据结构定义）：                         │
│     - 哪些方法/函数同时操作多张表/集合？                          │
│     - 原子操作边界内的跨表操作序列                                 │
│     - 关联查询模式（哪些表经常一起查，关联条件是什么）             │
│     - 代码中的 ID 传递（隐式引用，无物理约束但业务关联）           │
│ 16. 追踪级联操作：                                                │
│     - 创建 A 时必定创建哪些关联 B？                               │
│     - 状态变更会触发哪些关联数据更新？                             │
│     - 删除/作废的传播路径                                         │
│ 17. 识别时序敏感的数据操作：                                       │
│     - 操作 A 必须在操作 B 之前？顺序错误的影响？                    │
│     - 哪些是异步的，可能产生不一致窗口？                           │
│ 18. 区分证据类型：                                                 │
│     - 直接证据：调用链、状态机、核心表、事务边界、运行配置          │
│     - 辅助证据：命名、DTO 字段、注释、外部系统术语                  │
│ 19. 标记边界：                                                     │
│     - 哪些是本仓库直接拥有的能力？哪些只是对接/适配/消费外部系统？  │
│ 20. 记录疑点：                                                     │
│     - 哪些地方证据不足、证据冲突、或仍无法闭环？                    │
└─────────────────────────────────────────────────────────────────┘
```

#### Phase 2: 结论草稿（必须先做）

在写正文前，先列一份“候选结论清单”。候选结论一律按“合格业务结论”四要素书写（见上）；写不满四要素的，先回 Phase 1 补证据，或直接标记为待验证。清单至少覆盖以下字段：

| 候选结论 | 结论类型 | 证据锚点 | 当前判断 | 正文去向 |
|---------|----------|----------|----------|----------|
| `{结论}` | 事实 / 推断 / 待验证 | `{ClassName}#{method}()` / `{table}` / `{config}` | 证据充分 / 需降级 / 暂不下结论 | Why Exists / Boundary & Confidence / To Verify |

判定规则：

- **事实**：有直接证据支持，且可回指到调用链、状态机、数据流、核心表、配置或项目文档中的至少一个强锚点。
- **推断**：由多个证据共同指向，但仍带条件或解释空间；可以写，但必须注明依据和适用边界。
- **待验证**：只有命名、DTO、字段、注释、局部接口、单处术语，或证据互相冲突、无法闭环；不能冒充事实。

额外要求：

- 涉及**项目定位、业务边界、系统归属、某能力是否为“自有核心域”**的结论，必须至少有 2 个独立锚点，且至少 1 个来自真实行为证据（调用链 / 状态机 / 数据流 / 核心持久化 / 主流程）。
- 如果只看到 `Client`、`Adapter`、`OpenAPI`、回调接口、第三方字段映射等痕迹，默认只能得出“存在对接/适配/消费外部能力”的结论，不能顺手补全成本系统自有业务域。

#### Phase 3: 记忆审查（必须通过）

在候选结论进入文档前，逐条执行：

1. **事实审查**
   - 这个结论是否真的被代码、DDL、配置、项目文档直接证明？
   - 若去掉命名、注释、术语暗示，这个结论还站得住吗？

2. **边界审查**
   - 我写的是“本仓库直接拥有的能力”，还是“本仓库对接的外部能力”？
   - 我是不是把外部系统术语、回调协议、DTO 命名误写成了内部业务边界？

3. **反向否证**
   - 能否构造一个更保守但同样解释代码的说法？
   - 若两种解释都成立，必须选择更保守的一种，并把更强判断移入 `To Verify`。

4. **术语审查**
   - 文中每个专有名词，能否在代码、项目文档或行业通语中找到出处？
   - 是否出现比喻造词、数字打包命名、自创简称？命中即改写为出处术语或大白话直述（见文档规范 Section 6）。
   - 同一概念是否与已有记忆文档用词一致？不一致的收敛到 `atlas/glossary.md` 中的规范术语。

5. **降级改写**
   - 能证实的写进 `Why Exists` / `00-index` / `context.md`
   - 证据支持但仍需解释的写进 `Boundary & Confidence`
   - 证据不足的写进 `To Verify`

#### Phase 4: 深度挖掘清单（只对已过审结论展开）

每个产物文档必须深挖以下维度：

| 挖掘维度 | 必须回答的问题 | 参考示例 |
|---------|---------------|---------|
| **跨模块耦合** | 哪些其他模块隐式依赖此产物？ | 结算任务依赖主单终态，但状态刷新异步，可能漏处理 |
| **隐式状态规则** | 状态值之间有什么隐藏约束？ | `status=COMPLETED` 时必须有完成时间，但代码未统一校验 |
| **时序依赖** | 操作顺序错误会导致什么业务问题？ | 必须先落审计记录再改终态，否则无法追溯 |
| **数据一致性边界** | 哪些数据可能不一致？什么情况下？ | 主状态已更新但聚合视图未刷新，中间存在窗口期 |
| **失败级联** | 此产物失败会影响哪些看似无关的业务？ | 主单撤销后，需要同步反冲已生成的对账快照 |
| **业务兜底规则** | 极端情况下系统如何自保？ | 下游长时间无响应时转人工补偿，避免无限重试 |
| **人工介入点** | 哪些状态需要人工处理？触发条件？ | 异常状态超过阈值后转运营确认 |
| **实体边界** | 同一业务实体分散在哪些物理表？ | 实体分布在主表、扩展表、关系表 |
| **字段来源** | 字段是原生存储还是计算得出？ | `total_amount` 由多个原始字段计算而来 |
| **术语歧义** | 不同模块对同一概念的不同叫法？ | “申请单”在不同模块中也叫“任务单”或“主单” |

#### 边界探索清单（每个产物必须探到“代码尽头”）

“代码尽头”指：沿调用链一直追到链路离开本仓库（持久化、外部 API、消息中间件）为止；追不下去的要写明中断位置与原因，不许在中途停下就下结论。逐类探边：

| 边界类型 | 必答问题 | 典型证据 |
|---------|---------|---------|
| 拒绝边界 | 什么输入/状态/身份会被拒绝？拒绝时用户看到什么？ | 校验器、卫语句、权限注解、异常抛出点 |
| 数值边界 | 上限、批量大小、分页、重试次数、超时是多少？越界会怎样？ | 配置项、常量、限流器 |
| 时间边界 | 有效期、窗口期、冷却期是多久？过期后行为？ | 定时任务、TTL、时间比较逻辑 |
| 状态边界 | 哪些状态转换被禁止？终态之后还能做什么？ | 状态机校验、状态白名单 |
| 数据可见性边界 | 哪些数据被默认过滤掉、对谁不可见？ | 软删除标记、租户隔离、状态过滤条件 |
| 系统边界 | 链路在哪里离开本仓库？带走什么、带回什么？外部失败时本系统怎样？ | Client/Adapter、MQ 生产者、回调入口 |

**反例试探**：对每条“系统会 X”的结论，主动找“什么时候不 X”。找到反例，就把结论改写成带条件的精确版本；找不到反例但也无法证明不存在时，进 `To Verify`。边界探索的产出直接喂给 Key Conclusions 和 Deep Business Rules——最精辟的业务结论几乎都长在边界上。

#### Phase 5: 高信息密度写作

将以上发现写入 `{artifact}.md`，使用紧凑结构：

```markdown
# {artifact}.md 标准结构

## Frontmatter（机器可读元数据）

## Why Exists（只写已证实内容）
- 一句话定义
- 业务目标
- 失败影响范围
- 无影响范围

## Key Conclusions（核心结论）★ 先读章节
- 3-7 条按“合格业务结论”四要素写成的结论，按业务重要性排序
- 每条自带证据锚点；读者只读本节即可掌握该产物最关键的业务规律
- 凑不足 3 条说明挖掘深度不够，回 Phase 1/4 补挖，不许注水凑数

## Boundary & Confidence（边界与置信度）

### Confirmed Facts（已证实事实）
- `{结论}` — 证据：`{ClassName}#{method}()` / `{table_name}`

### Evidence-backed Inferences（证据支持的推断）
- `{结论}` — 基于 `{evidence}` 归纳；限制：`{limit}`

### To Verify（待验证事项）
- `{疑点}` — 当前缺失 `{missing_evidence}`

## Lifecycle（生命周期全景）

### Stages（阶段矩阵）
| Stage | Trigger | Actor | Input | Processing | Output | Persist | Next Consumer |
|-------|---------|-------|-------|------------|--------|---------|---------------|

### Data Flow（数据流矩阵）
| Data | Source | Transform | Stored | Exposed Via | Consumed By | Failure Impact |
|------|--------|-----------|--------|-------------|-------------|----------------|

### State Machine（状态机）
```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> PROCESSING : 提交
    PROCESSING --> COMPLETED : 成功回调
    PROCESSING --> FAILED : 异常/超时
```

## Deep Business Rules（深度业务规则）★ 核心章节

### Cross-Module Constraints（跨模块约束）
- `{模块A}` 隐式依赖 `{模块B}` 的 `{条件}`，当 `{场景}` 时可能不一致
- 约束示例：报表任务只处理 `status=COMPLETED` 的记录，但状态刷新和报表扫描异步，可能产生漏处理

### Implicit Dependencies（隐式依赖）
- `{实体}.{字段}` 实际由 `{代码位置}` 维护，但 `{其他代码}` 直接读取不做校验
- 依赖示例：`task.resultCode` 由回调更新，而查询接口默认其在终态后非空

### Business Invariants（业务不变量）
| Invariant | Enforced By | Violation Scenario | Impact |
|-----------|-------------|-------------------|--------|
| `status=PAID → paymentRecord != null` | PaymentService | 支付回调重复触发 | 重复扣款 |
| `status=COMPLETED → completedAt != null` | StatusUpdater | 手工改库 | 无法追溯完成时间 |

### Temporal Rules（时序规则）
| Order | Operation A | Operation B | Violation Impact |
|-------|-------------|-------------|------------------|
| 必须 | 记录审计日志 | 修改终态 | 先改终态后记日志，无法追溯 |
| 禁止 | 作废主单 | 推送下游后 | 下游已消耗数据，作废无效 |

## Trace（关键代码追踪）

### Core Call Chain（核心调用链）
```
Entry: Controller.method()
  → Service.entryMethod() [事务开始]
    → Service.subMethod1() [副作用: 发消息]
    → Service.subMethod2() [异步: 外部 API]
  → [事务提交]
  → AsyncHandler.callback() [事务外]
```

### Transaction & Async Boundaries（事务/异步边界）
- `{method}()`：在事务内，失败回滚
- `{method}()`：异步执行，失败不重试，丢入死信队列
- `{method}()`：外部 API 调用，超时=30s，不重试

### Dangerous Change Points（危险改动点）
| Location | Risk | Rule |
|----------|------|------|
| `{ClassName}#{method}({ParamTypes})` | 改动导致事务边界变化 | 必须与 {其他方法} 保持一致 |
| `{field}` 赋值位置 | 状态机漏状态 | 新增状态必须同步修改 {校验方法} |

## Failure & Degradation（失败与降级）

| Scenario | System Behavior | Business Impact | Recovery |
|----------|-----------------|-----------------|----------|
| {失败场景} | {系统如何反应} | {业务损失} | {如何恢复} |

## Evidence Anchors（证据锚点）
> **不记录行号**。用 `ClassName#method(ParamType)` 标准签名格式，Agent 可用搜索工具一步定位。行号在任何 Insert/Delete 后失效且无法自动检测，是「自信但错误」的锚点。

- 核心类：`{ClassName}` @ `{file}`
- 关键方法：`{ClassName}#{method}({ParamTypes})` — {一句话描述核心逻辑/副作用}
- 状态枚举：`{EnumName}` @ `{file}`
- 数据库表：`{table_name}`

## Related（相关文档，使用 Markdown 链接）

- **Flows**: [{flow-name}](business/flows/{flow-name}.md)
- **Related Artifacts**: [{other-artifact}](business/artifacts/{other-artifact}.md)
- **Schema**: [{table_name}](../../schema/tables/{table_name}.md)
```

写作约束：

- `Why Exists`、`00-index.md`、`business/context.md` 中的项目定位，只能使用 `Confirmed Facts` 已支持的结论。
- `Key Conclusions` 只收满足四要素、通过三道检验的结论；变更流水式、代码复述式条目一律不得进入。
- `Evidence-backed Inferences` 可以保留高信息量判断，但必须显式写出依据和限制，不能伪装成系统自我定位。
- `To Verify` 不是失败区，而是防止记忆文档把“线索”误写成“事实”的缓冲区。
- 所有专有名词遵守术语纪律（文档规范 Section 6）：可回指出处，无名概念用大白话直述。
- **所有跨文档引用路径必须使用 Markdown 链接语法 `[文字](路径.md)`，禁止裸路径**——裸路径不可点击，使记忆文档丧失快速跳转的导航能力（详见文档规范 Section 5）。

### 当前态写作规则（更新记忆时强制）

更新已有 `.light-cone/` 文档时，正文必须描述当前代码证据证明的现状，而不是本次改动过程。

**禁止写法**：
- `（2026-06-10：title 已移除，chat-bot 层 title=desc 兜底）`
- `原来/之前使用 A，现在改为 B`
- `新增了 X 字段`、`移除了 Y 逻辑`、`本次变更后...`

**推荐写法**：
- `小程序卡片消息输出节点使用 desc 作为卡片标题展示来源。`
- `chat-bot 层负责在组装卡片消息时补齐标题展示值。`
- `当前字段映射：title 展示值来源于 desc。`

如果用户明确要求复盘、迁移记录或 changelog，可以单独生成变更记录文档；不要把变更史混入 `00-index.md`、产物文档、流程文档、Schema 文档的业务记忆正文。

### 更新模式：增量同步与深度更新

更新记忆的头号禁令：**git diff 和 commit message 只是线索，不是素材**。禁止把变更流水改写成记忆正文；每条线索必须沿“线索 → 场景 → 结论”走完，才允许落盘。

#### 增量同步（代码变更后的跟随更新）

对每个 diff 回答三问。答不齐就继续挖，或标记 To Verify，不许直接落盘：

| 三问 | 追问方式 |
|------|---------|
| 这个变更服务哪个业务场景？ | 从改动点向上追到系统入口（API/定时任务/MQ/回调），确认触发者和业务意图 |
| 它改变了哪条业务规则或边界？ | 与记忆中已有结论比对：是新规则、修正了旧规则，还是仅实现细节变化 |
| 用户或下游可感知的行为差异是什么？ | 从改动点向下追到持久化、外部调用或响应，确认业务后果 |

只改实现细节、三问都答“无变化”的 diff，只更新证据锚点与 `last_verified`，不产生新结论——如实处理，不要为了显得有产出而硬造结论。

#### 深度更新（用户要求“深度更新记忆”，或记忆明显滞后时）

深度更新**不从 git diff 出发**——diff 只能看见改过的代码，永远看不见记忆从未覆盖的场景。以场景普查为主轴：

```
1. 入口普查：枚举当前代码的全部系统入口
   （HTTP/RPC 接口、定时任务、MQ 消费、回调/Webhook、CLI、事件监听——命令模式见 reference.md）
2. 场景对账：入口清单 vs 00-index/flows 已记载的场景，列出三类差异
   ├─ 新场景：入口存在、记忆没有 → 每个派一个子代理走 Phase 1-4 深挖
   ├─ 失踪场景：记忆有、入口已消失 → 按当前态原则重写或删除对应记忆
   └─ 口径漂移：两边都有但描述对不上 → 以代码为准重新取证改写
3. 存量抽查：随机抽 2-3 个“无差异”场景，验证其证据锚点与核心结论仍然成立（防记忆腐化）
4. 边界重探：对本次触达的每个场景执行边界探索清单，把新发现写入 Key Conclusions / Deep Business Rules
```

#### 结论清单收尾（两种更新都强制）

更新结束时必须向用户输出本次的业务结论清单：**新增了哪些结论、修正了哪些、作废了哪些**，每条附证据锚点。真的没有新结论时如实说明“本次仅同步事实细节，未产生新的业务结论”——宁可清单为空，不许把流水账包装成结论凑数。

---

## 文档规范

### 1. Frontmatter Schema（所有文档必填）

```yaml
---
type: artifact | flow | context | index | schema-overview | schema-table | schema-relations
name: {机器可读标识}
title: {人类可读标题}
coverage: complete | partial | stub
last_verified: YYYY-MM-DD
confidence: high | medium | low
---
```

### 2. 事实 / 推断 / 待验证分层

| 类型 | 允许写入的位置 | 证据要求 | 写法要求 |
|---------|----------------|----------|----------|
| **事实** | `Why Exists`、`00-index.md`、`business/context.md`、各章节主结论 | 至少一个强锚点 | 直接陈述，但必须可回指证据 |
| **推断** | `Boundary & Confidence`、章节备注 | 多个证据共同指向 | 明写“基于什么推断”以及“限制是什么” |
| **待验证** | `To Verify`、复盘清单 | 证据不足 / 证据冲突 | 只能提问或保守表述，不能写成定论 |

`confidence` 字段解释：

- `high`：关键结论都有直接证据，且边界判断基本闭环
- `medium`：核心流程可信，但部分边界或术语解释仍带推断
- `low`：仍以线索和待验证项为主，不能输出强定位结论

### 3. 信息密度规则

**禁止**：
- 只有方法名，没有业务目的说明
- 只有状态列表，没有转换规则
- 只有流程步骤，没有输入输出消费者
- 低价值的中间索引文件
- 仅凭命名、注释、DTO 字段、外部术语就下项目定位或业务边界结论
- 把 `To Verify` 中的疑点写进 `Why Exists`、项目简介、核心边界说明
- 把记忆更新写成变更日志，例如“某日期移除/新增/改为”“之前是 A 现在是 B”
- 把 diff/commit 概要当结论落盘（变更流水式记忆）
- 用自造比喻词、数字打包名、自创简称命名业务概念（见 Section 6）

**强制**：
- 产物/流程文档必须有 `Key Conclusions` 章节，每条满足四要素（业务条件/系统行为/越界后果/证据锚点）
- 每个 Stage 必须说明 Trigger + Input + Output + Consumer
- 每个状态转换必须说明条件 + 副作用
- 每个方法必须标注事务/异步边界
- 必须显式声明业务不变量和跨模块约束
- 每个关键结论必须能回指证据锚点
- 每个推断都要说明依据和适用边界
- 更新已有记忆时，先删除旧口径或变迁描述，再用当前代码事实重写为现状口径

### 4. 文档合并原则

| 场景 | 处理方式 | 说明 |
|---------|-----------|---------|
| 产物文档分散 | 合并为单文件 | `artifact-X.md` + `lifecycle.md` + `trace-Y.md` → `business/artifacts/X.md` |
| 中间索引文件 | 删除收拢 | 将中间索引层的功能收拢到 `00-index.md` |
| 模块文件过多 | 单文件聚合 | 多个 `module-X.md` → 单个 `code/modules.md` |

### 5. 跨文档链接规范（强制）

`.light-cone/` 内文档间的所有路径引用**必须使用 Markdown 原生超链接语法**，禁止只写裸路径。裸路径在渲染后不可点击，读者无法快速跳转，记忆文档的导航价值会大打折扣。

**格式**：`[链接文字](相对路径.md)` 或 `[链接文字](相对路径.md#section-anchor)`

| 正确 ✅ | 错误 ❌ |
|--------|--------|
| `[order](business/artifacts/order.md)` | `business/artifacts/order.md` |
| `[症状排查](atlas/symptom.md)` | `→ 查看 atlas/symptom.md` |
| `[pay-flow](../flows/pay-flow.md)` | `business/flows/pay-flow.md` |

**路径相对于当前文档位置计算：**

| 当前文档 | 引用目标 | 写法示例 |
|---------|---------|---------|
| `.light-cone/00-index.md` | artifact | `[order](business/artifacts/order.md)` |
| `.light-cone/atlas/symbol.md` | artifact | `[order](../business/artifacts/order.md)` |
| `.light-cone/business/flows/pay.md` | artifact | `[order](../artifacts/order.md)` |
| `.light-cone/schema/tables/orders.md` | artifact | `[order](../../business/artifacts/order.md)` |

**必须使用链接的场景（不得遗漏）：**
- `00-index.md` 核心产物表、核心流程表、快速导航区——每一个文件引用都要是可点击链接
- `atlas/` 所有倒排索引（keyword / symbol / symptom）的 Target 列
- 产物、流程文档末尾的 `Related Artifacts` / `Related Flows` 区域
- 任何 "→ 查看 xxx"、"→ 跳转 xxx"、"→ 见 xxx" 的导航指引
- `schema/overview.md` 核心表清单的 Schema 文档列

### 6. 术语纪律（强制）

记忆文档只搬运术语，不发明术语。写下任何一个专有名词前，先确认它的出处。表述风格用大白话打底：不用借喻包装抽象概念，不用修辞给普通事实抬价。

**术语三来源（按优先级取用）**：

| 优先级 | 来源 | 示例 |
|--------|------|------|
| 1 | 项目原生：代码标识符、DDL、配置、项目文档、注释中已有的叫法 | 类名 `OrderCreateValidator`、表名 `t_order`、注释里的“预售单” |
| 2 | 业务方惯用语：需求文档、UI 文案、用户/运营的实际叫法 | 界面上的“待接单”、运营口中的“补录” |
| 3 | 行业通语：有公认含义、无需解释的技术/业务词 | 幂等、灰度、对账、熔断、冲正 |

三处都找不到名字的概念，**不命名**，用大白话短语直述：写“下单前的参数与库存校验”，不发明一个“门闸”。

**禁止清单**：

| 禁止 | 反例 | 正确写法 |
|------|------|---------|
| 比喻/意象造词 | “15 道门闸”、“业务大脑”、“护城河规则” | “下单前置校验（`OrderCreateValidator`，共 15 项）” |
| 数字+名词打包命名 | “三大铁律”、“五层防线” | 直接列出规则本身；数量写在正文里，不进名字 |
| 自创缩写/简称 | 把“库存预留”缩写成“库预” | 用全称，或用代码里的原名 |
| 修辞拔高 | “灵魂字段”、“命脉链路” | “核心字段”、“主链路”，并说明为什么关键 |

**确需简称时**（同一概念反复出现且全称过长），必须同时满足三条：

1. 用平实、能望文生义的词（“下单校验链”可以，“门闸”不行）
2. 首次出现处给出定义和全称
3. 登记进 `atlas/glossary.md` 的「记忆用语登记」区，标注“记忆文档用语，非项目原生”

**全库一致性**：

- 同一概念全库只用一个词；`atlas/glossary.md` 是术语唯一注册表，写新文档前先查
- 更新时发现同义漂移（同一概念在不同记忆文档里叫法不同），收敛到规范术语，并在 glossary 记录曾用名
- 代码里本来就存在多个叫法的（如“申请单”在不同模块叫“任务单”），不是收敛对象，如实记入术语歧义对照表

**落笔前自检三问**：

1. 这个词能在代码或项目文档里搜到吗？
2. 新同事第一次读、不靠上下文，能猜出它指什么吗？
3. 半年后代码变了，这个词还成立吗？（“15 道门闸”在第 16 项校验加入时就作废了）

---

## Growth Rules

### 何时创建产物文档

满足任一：
1. 有独立业务目标（解决特定问题）
2. 有明确生命周期（>1 个状态）
3. 有多个消费者
4. 失败会影响其他业务

### 何时创建流程文档

满足任一：
1. 跨 2+ 个产物
2. 端到端数据流转复杂
3. 失败传播路径非直观

### 何时更新文档

1. **代码变更后**：走增量同步三问（见更新模式），确认变更已落代码后同步对应产物/流程文档
2. **发现隐式依赖**：任何新发现的跨模块耦合必须立即记录
3. **故障复盘后**：将根因和症状写入 `atlas/symptom.md` 和对应产物文档
4. **深度更新触发**：用户要求“深度更新记忆”、`00-index.md` 记载的场景与实际系统入口明显对不上、或记忆长期只做过增量同步时，执行深度更新（场景普查），不要只沿 git diff 找活干

更新动作只影响 `last_verified`、证据锚点和当前事实描述。除非用户明确要求 changelog，否则不要新增“变更历史”“本次更新”“曾经逻辑”等章节或括注。无论哪种更新，结束时都要输出业务结论清单（见更新模式的结论清单收尾）。

### 何时创建 Schema 文档

#### 何时创建单表文档 (schema/tables/{table}.md)

满足任一：
1. 表有明确的业务归属（是某个 artifact 的持久化载体）
2. 表有 2+ 个外键关联（关系复杂）
3. 表被 3+ 个不同模块查询
4. 表包含业务关键状态字段

#### 何时创建 Schema 总览 (schema/overview.md)

满足任一：
1. 数据库表数量 > 10
2. 存在 N:M 关系或多对多关联表
3. 需要理解跨表业务约束

#### 何时创建 Schema 关系文档 (schema/relations.md)

满足任一：
1. 数据表/集合数量 > 5
2. 存在跨数据业务约束（如"审批通过必有账单"）
3. 需要理解数据关系背后的业务规则

**编写原则**：
- **不止于外键/引用**：必须包含代码层面的隐式关联（关联查询模式、应用层维护的 ID 关系）
- **关联业务产物**：引用对应 artifact.md 中的跨模块约束和时序规则
- **显式业务不变量**：哪些跨数据状态必须同时为真？违背的影响是什么？
- **时序敏感操作**：哪些跨数据操作有严格的先后顺序？

**质量检验**：
- [ ] 能回答"删除这行数据会影响哪些业务？"
- [ ] 能指出"哪些数据必须在同一原子操作内处理？"
- [ ] 能说明"数据关系背后的业务时序约束"

#### 何时更新 Schema 文档

1. **DDL 变更后**：发现新的 migration、实体类修改
2. **发现新的表关系**：代码中出现新的 JOIN 模式
3. **表结构解释业务问题**：字段含义帮助理解业务规则

### 行号禁用规则（重要）

- **禁止**在任何文档中写 `{file}:{line}` 或 `L{数字}` 格式
- 代码定位统一使用 `ClassName#method(ParamType)` 签名格式
- 若需指出「某段逻辑」，用关键字描述（如「`OrderService#deductOrder` 内 UNPAID 过滤循环」）而非行号

---

详细模板、示例和编写指南见 [reference.md](reference.md)。