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 交叉审查，比单线程扫描更能发现矛盾与遗漏

何时必须拆子代理：

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

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

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

深度挖掘指令

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

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

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

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

落盘前过三道检验：

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

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

同一个事实的合格写法：

库存不足的订单在创建阶段即被拒绝，用户不会进入支付页；拦截依据是实时库存查询而非缓存快照。— 证据：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 补证据，或直接标记为待验证。清单至少覆盖以下字段：

判定规则：

• 事实：有直接证据支持，且可回指到调用链、状态机、数据流、核心表、配置或项目文档中的至少一个强锚点。
• 推断：由多个证据共同指向，但仍带条件或解释空间；可以写，但必须注明依据和适用边界。
• 待验证：只有命名、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: 深度挖掘清单（只对已过审结论展开）

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

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

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

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

Phase 5: 高信息密度写作

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

# {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（业务不变量）

Temporal Rules（时序规则）

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（危险改动点）

Failure & Degradation（失败与降级）

Evidence Anchors（证据锚点）

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

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

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

• Flows: {flow-name}
• Related Artifacts: {other-artifact}
• Schema: {table_name}

写作约束：

- `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. 事实 / 推断 / 待验证分层

confidence 字段解释：

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

3. 信息密度规则

禁止：

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

强制：

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

4. 文档合并原则

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

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

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

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

必须使用链接的场景（不得遗漏）：

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

6. 术语纪律（强制）

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

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

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

禁止清单：

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

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。