Expert Team

---
name: expert-team
description: 派多专家子 agent 并行深挖单个业务模块，产出"契约层（黑盒使用）+ 实现层（白盒技术）"两层资产的专家包（落 .module-experts/），大模块可拆子专家或专题。触发："掌握这个模块"、"深度分析 xxx 模块"、"梳理这个模块"、"建模块专家团"、"module expert team"。
---

# 模块专家团

## AI 说明层

**目的**：把单个业务模块深度消化成一个"业务专家"资产包（契约层 + 实现层），供后续设计 / 排查 / 重构 / **直接使用**时取用，避免每次重摸代码。大型模块可拆分为子专家，各司其职。超大模块可创建专题，形成三级结构。大模块支持分批创建。

**三层递进模型**（用→导航→确认）：
- **契约层（黑盒，根目录）**：`C0-使用总览.md`、`C1-能力契约.md`、`C2-使用流程.md`、`C3-代码示例-{topic}.md`、`C4-数据流向与消费.md`、`C5-关键决策.md` 直接放在专家根目录。回答"怎么用"——模块能干什么、公开类/方法的用途/参数（含行为语义）/返回/异常/约束、常见使用流程、**真实可运行代码示例**、数据的去向与消费用途、**关键决策及其成因**（C5）。使用者照此即可调用模块，**无需读实现代码**（类比前端调后端 API：看接口文档，不看后端实现）。用于"使用"。
- **实现层（白盒，implementation/ 子目录）**：`implementation/01-架构.md`~`07-运维.md` 收在子目录中。回答"代码怎么组织的"。用于"导航"——深入模块（诊断/改造）时先看架构全貌、数据流、依赖关系，知道该去哪读代码。是代码的"地图"，不替代代码但节省大量追踪时间。
- **源代码**：用于"确认"——实际修改代码时读具体文件确认细节，永远权威。

**子专家机制**：大型模块按功能分类拆分为子专家（仅一级，不可嵌套）。每个子专家有独立的契约层 + `implementation/`，父专家的 C0 含子专家导航。

**专题机制**：超大模块（如 > 500 源文件）且需要三级结构时创建专题。专题下挂多个专家，专家下可挂子专家，形成三级结构：专题 → 专家 → 子专家。专题含 `topic.md` 名片 + `T0-专题总览.md`（跨专家架构 + 专家导航），不产出实现层文档。专题不可嵌套。

**分批创建机制**：大模块/专题无法一次创建完成时，按功能子域/专家分批创建。专题/父专家的架构文档先行作为共享输入，后续批次可并行（最多 3 个）。INDEX.md 标注各批次进度，全部完成后更新为正常格式。

**功能**：创建前资格判断（领域专属 × 复杂度/规模；公共/横切知识不建专家、转存项目记忆）→ 模块范围扫描（AI 自行判断；**仓库已有 `.fe-index/` 索引时先经 `index-lookup` 复用模块边界与依赖**；含测试信息采集：测试位置/框架/运行命令/环境依赖/已知失败）→ 评估是否建专题/拆子专家 → 评估是否分批 → 输出创建计划预览（专家名自动派生 + 匹配关键词，用户确认后实施）→ 知识库优先查 → 派出多专家子 agent 并行产出实现层 Wiki 文档（`06-测试.md` 必出，含测试可执行性）→ 主 agent 提炼契约层（含真实代码示例）→ 合成专家入口（含测试状态）→ 校验 → auto-review 评估审核+优化 → 落盘到 `.module-experts/{中文业务专家名或专题名}/` → **回写代码索引（Step 7.5：有索引时重跑 provider，专家资产列自动出现）** → **必须构建专题记忆（Step 8：写一条 ki 路标，解决资产闲置）** → **记录接口信息（Step 8.3：识别暴露接口，按子功能写可检索原子）** → **记录数据流（Step 8.4：识别数据实体，写实体流向可检索原子）** → **记录模块间强关联（Step 8.5：调用 `strong-relation` skill，识别该模块与外部模块的强耦合写入 ki-search）** → **记录关键决策（Step 8.6：识别有证据支撑的关键决策，产出 `C5-关键决策.md` 并写决策记忆到 ki）**。

**使用场景**：
- 即将对某业务模块做重大设计 / 重构 / 迁移，需要先彻底掌握它
- 反复排查某业务模块问题，希望沉淀一份持久专家资产
- 新人 / 新 agent 接手某业务模块，需要快速建立全景认知
- 需要使用某模块能力但不想每次回读实现代码
- 模块过大，需要按功能拆分为多个子专家各司其职
- 模块超大，子专家不足以描述，需要专题 → 专家 → 子专家三级结构
- 模块规模大，一次无法完成，需要分批创建
- 用户说"掌握这个模块""深度分析 xxx 模块""梳理这个模块的来龙去脉"时

## 组织模型：业务专家

> `.module-experts/` 的**子目录 = 业务专家或专题**（按功能分类，中文业务名）。每个专家含 `agent.md` 名片 + 契约层文档（根目录）+ `implementation/`（实现层）。大型模块的专家可含 `sub-experts/`（子专家，仅一级）。**超大模块**可创建**专题**，专题下挂多个专家，专家下再挂子专家，形成三级结构：专题 → 专家 → 子专家。不维护 CHANGELOG——资产随项目版本控制，git 历史即变更记录。
>
> **`PROJECT.md` 是项目级共享资产**（非专家/专题）：位于 `.module-experts/PROJECT.md`，描述项目全局信息（项目信息/技术栈/架构形态/核心功能/核心服务清单/配套服务关系/架构图/数据流向图/运行环境），供**所有专家共享**。创建/使用专家时读取以获取项目全局上下文；缺失时提示优先创建。由 expert-team 与 expert-lookup 共同维护。

```
.module-experts/
├── INDEX.md
├── PROJECT.md                         # 项目全局共享资产（非专家：项目信息/技术栈/服务清单/架构图/运行环境）
├── 支付系统专题/                      # 专题 = 超大模块的功能域分组
│   ├── topic.md                       # 专题名片（职责 + 专家清单 + 专题就绪状态）
│   ├── T0-专题总览.md                 # 专题级总览（能力清单 + 边界 + 跨专家架构图 + 专家导航）
│   ├── T1-跨专家契约.md               # 专题级公开能力契约（按需，仅当专题有跨专家的公开能力时）
│   ├── 支付流程专家/                  # 专题下的专家（结构同普通专家）
│   │   ├── agent.md                   # 专家名片（含子专家清单 + 契约层就绪状态）
│   │   ├── C0-使用总览.md             # 能力清单 + 边界 + 已知坑 + 子专家导航（必出）
│   │   ├── C1-能力契约.md             # 类/方法契约 + 真实代码示例（必出）
│   │   ├── C2-使用流程.md             # 业务目标调用路径 + 真实代码示例（按需）
│   │   ├── C3-代码示例-{topic}.md     # 完整代码示例，内容多时分文件（按需）
│   │   ├── C4-数据流向与消费.md       # 数据去向 + 消费方 + 业务用途（有数据落地时必出）
│   │   ├── C5-关键决策.md             # 关键决策 + 被否决方案 + 重新评估触发条件（有决策线索时必出）
│   │   ├── implementation/            # 实现层（白盒，用于导航代码）
│   │   │   ├── 01-架构.md
│   │   │   ├── 02-实现.md
│   │   │   ├── 03-数据流转.md
│   │   │   ├── 04-模型.md
│   │   │   ├── 05-接口.md
│   │   │   ├── 06-测试.md             # 必出：测试位置 + 可执行性 + 已知失败
│   │   │   └── 07-运维.md
│   │   ├── test/                      # 测试状态（切面级）
│   │   │   └── known-failures.md      # 已知失败的单元测试清单（code-review 阶段8 与 expert-lookup 增量维护）
│   │   └── sub-experts/               # 子专家（仅一级，不可再嵌套）
│   │       ├── 下单子专家/
│   │       │   ├── agent.md
│   │       │   ├── C0-使用总览.md
│   │       │   ├── C1-能力契约.md
│   │       │   └── implementation/
│   │       │       └── ...
│   │       └── 渠道路由子专家/
│   │           └── ...
│   └── 退款专家/                      # 专题下的另一个专家
│       ├── agent.md
│       ├── C0-使用总览.md
│       ├── C1-能力契约.md
│       └── ...
├── 告警系统专家/                      # 普通专家（无专题），可有子专家
│   ├── agent.md
│   ├── C0-使用总览.md
│   ├── C1-能力契约.md
│   ├── implementation/
│   │   └── ...
│   └── sub-experts/                   # 子专家（仅一级）
│       ├── 告警规则管理专家/
│       │   └── ...
│       └── 告警通知专家/
│           └── ...
├── 日志查询专家/                      # 无子专家的普通专家
│   ├── agent.md
│   ├── C0-使用总览.md
│   ├── C1-能力契约.md
│   └── implementation/
│       └── ...
└── ...
```

### 三级结构说明

| 层级 | 概念 | 适用场景 | 目录 |
|------|------|----------|------|
| **专题** | 超大模块的功能域分组 | 模块超大（如 > 500 源文件），包含多个独立功能域，单专家+子专家不足以描述 | `.module-experts/{专题名}/` |
| **专家** | 业务功能域 | 模块中等规模，或专题下的功能域分组 | `.module-experts/{专家名}/` 或 `.module-experts/{专题名}/{专家名}/` |
| **子专家** | 功能子域 | 专家下再按功能子域拆分 | `{专家}/sub-experts/{子专家名}/` |

> **何时用专题 vs 普通专家+子专家**：
> - 模块小 → 单专家即可
> - 模块中等，有清晰功能子域 → 专家 + 子专家
> - 模块超大，功能域下还有功能子域（需要三级） → 专题 + 专家 + 子专家

### 文档说明

- **专家目录**：中文业务名，由模块的业务功能自动派生（Step 1.9 计划预览中确认）
- **agent.md（必出）**：专家职责摘要 + 契约层就绪状态 + 子专家清单（如有），**不套 Wiki 格式**
- **契约层文档（根目录，黑盒）**：不套 code-to-wiki 格式，用契约专有格式（CR1-CR9）
  - `C0-使用总览.md`（必出）：能力清单 + 边界 + 已知问题与常见坑 + 子专家导航（如有）
  - `C1-能力契约.md`（必出）：每个公开类/方法的 用途/参数/返回/异常/约束 + **真实可运行代码示例**
  - `C2-使用流程.md`（按需）：业务目标级 Recipe + **真实可运行代码示例**
  - `C3-代码示例-{topic}.md`（按需）：C1/C2 内联示例不够时，拆分完整代码示例到独立文件
  - `C4-数据流向与消费.md`（有数据落地时必出）：数据实体的来源接口 / 去向 / 消费方（模块级概括）/ 业务用途；纯计算型模块不产出
  - `C5-关键决策.md`（有决策线索时必出）：关键决策 + 背景约束 + 被否决方案及否决理由 + 重新评估触发条件 + 证据来源；**优先记有证据的决策，无证据但代码结构强烈暗示的须前置 `[推测]`，纯猜测不写**（详见 Step 8.6 证据门）
- **implementation/（实现层，白盒）**：`01-架构.md` ~ `07-运维.md`，每篇严格遵循 code-to-wiki 文档格式。用于**导航代码**——深入模块前先看地图
- **test/（测试状态，切面级）**：`test/known-failures.md`（有测试时必出）——记录已知失败的单元测试清单（切面级：子专家/功能域各自标注），格式见下文。由 code-review 阶段 8 与 expert-lookup 增量更新维护，是"该模块测试健康度"的黑盒入口
- **sub-experts/（按需，仅一级）**：子专家目录，每个子专家结构同父专家但**不可再含 sub-experts/**
- **不维护 CHANGELOG**：资产随项目版本控制，git 历史即变更记录；expert-lookup 增量更新直接改契约文档，疑似差异内联标注
- **资产基线 commit**：agent.md / topic.md 出处行与 INDEX.md 记录的 `git commit` 是**资产基线**——创建或全量更新（合并补全/重建）时资产所覆盖代码的 commit，不是"文档生成时刻"。过期检测公式：`git diff --name-only {基线}..HEAD -- {模块根}`，可直接定位"基线之后哪些代码文件变更过"，供 expert-lookup（Step 4.5 新鲜度检查）判断资产是否过期并定向核对，替代全量读代码。仅创建与全量更新时刷新；expert-lookup 增量更新**不刷新**（增量只核对本次遇到的差异，推进基线会掩盖其余未核对变更）

### 专题文档说明

- **topic.md（必出）**：专题名片，含一句话职责 + 专家清单 + 专题就绪状态，**不套 Wiki 格式**
- **T0-专题总览.md（必出）**：专题级总览——专题能力清单 + 专题边界 + 跨专家架构图（Mermaid）+ 专家导航（列出专题下所有专家及其职责）
- **T1-跨专家契约.md（按需）**：仅当专题级有跨专家的公开能力时产出（如专题对外暴露的统一 API），格式同 C1
- **专题不产出 implementation/**：专题是组织层而非实现层，具体实现由其下的专家的 `implementation/` 承载

### 测试状态（test/ 目录）

> 测试信息是专家资产的**切面级健康度标注**（黑盒入口）——告诉使用方"这个模块/子专家的测试在哪、能不能跑、哪些已知失败"，供 code-review 阶段 8 测试验证与 expert-lookup 排查直接取用，避免重复发现。

- **test/known-failures.md（有测试时必出）**：已知失败的单元测试清单，**切面级**——子专家/功能域各自标注（父专家的 test/ 汇总各子专家条目）
- **格式**：
```markdown
# 已知单元测试失败：{专家名}

## {切面/子专家名}

### {测试文件路径}:{测试函数名}

- **执行方式**：{运行该测试的完整命令，如 `uv run pytest tests/test_alerts.py::test_add_rule`（含环境要求，如依赖 DB 等）}
- **失败时间**：{date}
- **失败原因**：{断言错误摘要}
- **修复尝试**：{尝试了什么，为什么未修复}
- **影响**：{对使用/验证的影响}
- **来源**：code-review 阶段 8 测试验证 / expert-lookup 增量更新
```
- **维护者**：code-review 阶段 8（单元测试失败且无法低成本修复时写入）+ expert-lookup 增量更新（使用中发现测试问题时补充）；条目修复后由上述维护者移除
- **agent.md 引用**：agent.md 的"测试状态"字段引用本文件

### 子专家规则

- **何时拆**：专家有清晰的功能子域划分 + 单专家契约过大不实用时。模块小则不拆
- **拆分粒度**：按功能分类（如告警系统 = 规则管理 + 通知 + 查询），每个子专家覆盖一个功能子域
- **仅一级**：子专家下不可再有 sub-experts/。如果子域仍然太大，应考虑将专家升级为专题，而非继续嵌套
- **专家职责**（专题下或独立）：功能域级总览、跨子域架构、子专家导航。专家的契约层覆盖功能域级公开能力
- **子专家职责**：功能子域内的完整契约 + 实现。子专家的契约层覆盖该子域的公开能力

### 专题规则

- **何时建**：模块超大（如 > 500 源文件）且有多个独立功能域，每个功能域下还有功能子域——需要三级结构才能描述
- **专题不可嵌套**：专题下不可再有专题。如果专题仍然太大，说明模块边界划分有问题，应拆分为多个独立专题
- **专题职责**：专题级总览（跨专家架构 + 专家导航），不产出实现层文档
- **专题下直接挂专家**：专题 → 专家 → 子专家，不跳级
- **专题与普通专家共存**：`.module-experts/` 下可同时存在专题和普通专家

## 实现层文档格式规范（对齐 code-to-wiki，不跑工具）

> 实现层文档（`implementation/01-架构.md`~`07-运维.md`）**对齐** `code-to-wiki` skill 的**格式规范**，但为适配"按业务专家分包"的模型做了取舍：
> - **采纳**：`**本文引用的文件**` cite 块、中文锚点目录、`章节来源` / `图表来源`（`file://` 路径 + **关键符号**：类名 / 方法名 / 类.方法）、Mermaid 配图、深度要求、R1–R7 规则。
> - **不采纳**：code-to-wiki 的"单一 7 节页面骨架"。本 skill 把模块拆为多个业务切面文件，每篇**按本 skill 的切面调研清单组织章节**。
> - **不调用**：`codetowiki wiki-format` 校验工具；改为 AI 手动自检 R1–R7。

### 每篇实现层文档的骨架
```markdown
# {标题}
**本文引用的文件**
- [模块名](file://相对仓库根目录的路径)

## 目录
1. [简介](#简介)
2. [...](#...)
...

## 简介 ...
章节来源：[名称](file://相对路径)（关键符号：`类名` / `类.方法`）

## {切面核心章节，按 reference.md 调研清单组织} ...
章节来源：[名称](file://相对路径)（关键符号：`类名` / `类.方法`）

## 结论 ...
```

### 引用与来源规范（R 系列，AI 手动自检）
| 规则 | 要求 | 级别 |
|---|---|---|
| R1 | 标题下、目录前有 `**本文引用的文件**` cite 块 | error |
| R2 | `## 目录` 条目与 `##` 章节一一对应（锚点中文） | error |
| R3 | 每个 `##`/`###` 小节末尾有 `章节来源`（`file://` 路径 + 关键符号）；纯概念节可豁免 | warning |
| R4 | 每个 Mermaid 图后紧跟 `图表来源` | error |
| R5 | 所有引用路径均 `file://` 前缀 | error |
| R6 | 关键符号须真实存在于源码（类/方法/函数名可 grep 验证），每处标 1~3 个入口符号即可；无类/方法符号的内容（配置/SQL/脚本）可用表名/顶层键等可搜索标识替代，实在没有才只标文件路径 | warning |
| R7 | 详细分析 ≥2 设计维度；架构 / 流程 / 依赖等按需配 Mermaid 图 | warning（不可豁免） |

### 文件命名
| 切面 | 文件 | 默认 |
|---|---|---|
| architecture | `implementation/01-架构.md` | 必出 |
| implementation | `implementation/02-实现.md` | 必出 |
| data-flow | `implementation/03-数据流转.md` | 按需 |
| models | `implementation/04-模型.md` | 按需 |
| api | `implementation/05-接口.md` | 按需 |
| tests | `implementation/06-测试.md` | 必出 |
| ops | `implementation/07-运维.md` | 按需 |

> `agent.md` 不套 Wiki 格式，保持轻量。

## 契约层文档规范（黑盒使用文档，不套 code-to-wiki）

> 契约层文档是专家资产的**黑盒使用层**，放在专家根目录（与 `agent.md` 同级），目标是让使用者**不看实现代码即可使用模块**。类比前端调后端 API：看接口文档，不看后端实现。
>
> **核心原则**：只写"怎么用"，不写"怎么实现"。不出现算法描述、内部数据结构、私有方法、内部状态机、DB schema 细节、实现模式名称。约束（如"此方法不可在事务外调用"）可写，因为约束影响使用；但"为什么"不写，那是实现的职责。参数的**行为语义**（换个取值调用，使用者可观察到什么行为差异）属于"怎么用"，必须写；其背后的实现机制不写。
>
> **C5 是"为什么"的唯一例外**：`C5-关键决策.md` 承载"当初为什么这么选、砍掉了什么备选"——因为**设计成因直接影响使用者的使用判断**（如"为什么不支持 webhook"直接决定调用方能否依赖回调式集成；"为什么用轮询"决定调用方对实时性的预期）。除 C5 外，契约层一律遵守"不写为什么"。
>
> **代码示例要求**：必须是**真实可运行代码**——API 调用必须与实际签名一致（真实），但环境初始化可用注释占位（如 `// 假设已初始化 db 连接`）。是**使用方代码**（调用者写的），不是被调用方实现代码。

### 契约层格式自检规则（CR 系列）

| 规则 | 要求 | 级别 |
|------|------|------|
| CR1 | `C0-使用总览.md` 含能力清单 + 边界 + 已知问题与常见坑 + 子专家导航（如有子专家） | error |
| CR2 | `C1-能力契约.md` 每个公开类/方法必含：用途 / 参数（含类型与**行为语义**：枚举/开关/边界敏感参数逐值说明可观察行为差异，纯透传参数一行说明）/ 返回 / 异常 / 约束 / **真实代码示例** | error |
| CR3 | 契约文档中不出现实现细节（算法 / 私有方法 / 内部结构 / DB schema / 实现模式名） | error |
| CR4 | `C2-使用流程.md`（若产出）每条流程含：业务目标 / 调用顺序 / 事务边界 / 预期结果 / **真实代码示例** | error |
| CR5 | 每条契约标注"契约来源"（类名 / 方法签名，非行号） | warning |
| CR6 | 已知问题条目含：现象 / 触发条件 / 正确做法 | warning |
| CR7 | 代码示例为**真实可运行代码**（API 签名真实，环境可占位），是使用方代码而非被调用方实现代码 | error |
| CR8 | `C4-数据流向与消费.md`（若产出）每条数据实体含：来源接口 / 去向 / 消费方（模块或功能级概括，>3 个时归纳不逐列）/ 业务用途 | error |
| CR9 | C4 只写数据"用来干嘛"，不写消费方的处理逻辑与实现细节 | error |
| CR10 | `C5-关键决策.md`（若产出）每条决策含：**分类（必填单选，按决策性质）** / 动机（可选） / 决策 / 背景约束 / 被否决方案及否决理由 / **重新评估触发条件（须可观测判据，写不出写「无」）** / 证据来源；**纯猜测无结构支撑的决策不写入**，低置信度的须前置 `[推测]`；标 `避坑` 须写明具体坑（现象→后果） | error |

> CR 系列与实现层的 R1-R7 互不干扰，各自独立检查。
>
> **CR3 对 C5 不机械套用**：CR3（禁实现细节）在 C5 上以"是否服务于使用判断"为准——说明"为什么这么选"时可能需要最小限度的结构/模式信息（如"选策略模式以便扩展"），只要**服务于使用者的使用判断**即允许；但不得展开算法、内部状态机、DB schema 等实现细节。

### 契约层文档清单

| 文件 | 默认 | 内容 |
|------|------|------|
| `C0-使用总览.md` | 必出 | 能力清单 + 边界 + 已知坑 + 子专家导航 |
| `C1-能力契约.md` | 必出 | 类/方法契约 + 真实代码示例 |
| `C2-使用流程.md` | 按需 | 业务目标调用路径 + 真实代码示例 |
| `C3-代码示例-{topic}.md` | 按需 | C1/C2 内联示例不够时，拆分完整代码示例 |
| `C4-数据流向与消费.md` | 有数据落地时必出 | 数据实体 → 来源接口 → 去向 → 消费方（模块级）→ 业务用途 |
| `C5-关键决策.md` | 有决策线索时必出 | 决策 → 背景约束 → 被否决方案及理由 → 重新评估触发条件 → 证据来源 |

> 详细模板见 [reference.md](reference.md) 中「契约层文档模板」章节。

### 契约层与实现层的关系

- **三层递进**：契约层在根目录（用于"使用"）；implementation/ 用于"导航"代码（深入模块前先看地图）；源代码用于"确认"行为。三者递进不竞争
- **内容分离**：契约只写"怎么用"，实现只写"怎么实现"
- **不重复**：同一信息不在两层重复；实现层涉及公开接口处引用契约（`详见 C1-能力契约.md#AlertManager.addRule`）而非复述
- **C4 与 03-数据流转分工**：C4 是黑盒（数据去向 / 消费方 / 业务用途），`implementation/03-数据流转.md` 是白盒（内部生命周期 / 状态机 / 异步流），互不重复
- **独立可读**：契约层可脱离实现层独立读懂并据此使用模块

## 与相邻 skill 的边界

| skill | 关系 |
|---|---|
| code-survey | 轻量、按需、跨多维度、一次性；本 skill 是单业务模块深挖、持久落盘 |
| **index-lookup / frontend-index / backend-index** | **建专家前**：仓库已有代码索引（`.fe-index/`）时，先 `use_skill("index-lookup")` 拿该模块**边界与依赖/被依赖**（省一次全仓扫描，见 Step 1）；**专家落盘后**回写索引（见 Step 7.5），让「专家资产」列自动出现，解决"建了没人知道" |
| ki-search | 本 skill 可选地把知识原子写入 ki KB；专家文档存深度参考，KB 存可查询原子，互补 |
| solution-capture | 沉淀"问题解法"；本 skill 沉淀"业务模块全景知识"，复用其包 + INDEX 范式 |
| **code-to-wiki** | **本 skill 的实现层文档对齐其格式规范**，但**不套用其单一 7 节骨架**、不调用其校验工具。该 skill 不在本技能库中，所需格式规则已全部内嵌为 R1–R7，不依赖外部文档 |
| **expert-lookup** | **本 skill 生成专家资产（含契约层 + 实现层 + `test/known-failures.md`）和专题；expert-lookup 查找并复用，且可对契约层与测试信息做受限增量更新。专题的查找也由 expert-lookup 支持** |
| **expert-audit** | **本 skill 产出完成后自动调用其做使用者视角验收（Step 9）；它只审查不重建，内容级问题回流本 skill 修复** |
| **strong-relation** | **本 skill 落盘+专题记忆（Step 8）后自动调用其记录该模块与外部的强关联（Step 8.5），按功能模块分组（统一父分组「关联关系」+ 动态子分组，tags 统一为 `relation`）；它记录模块间耦合，本 skill 记录模块内部知识，互补** |
| **code-review** | **本 skill 产出的 `test/known-failures.md` 与 `06-测试.md` 供 code-review 阶段 8 测试验证取用（测试位置/可执行性/已知失败）；阶段 8 单测失败无法低成本修复时写入 known-failures，与本 skill 及 expert-lookup 共同维护** |

## 核心原则

1. **业务专家为轴**：`.module-experts/` 子目录是业务专家（中文名），不是技术切面
2. **单模块深挖**：一次只针对一个业务模块，不泛化到全项目
3. **三层递进**：契约层在根目录（用于"使用"）；实现层在 `implementation/`（用于"导航"代码）；源代码用于"确认"。三者递进：用 → 导航 → 确认
4. **按需切面**：根据模块性质选择产出哪些实现层 Wiki 文档，不硬凑空文档
5. **知识库优先**：先查 ki（项目记忆 → KB），已知不重复读
6. **并行专家**：实现层切面 ≥ 2 时用 task-dispatch 并行
7. **实现层格式对齐 code-to-wiki**：R1–R7 手动自检
8. **契约层格式独立**：CR1-CR9 自检，不引用实现代码行号
9. **真实代码示例**：契约层代码示例必须是真实可运行的使用方代码（API 签名真实，环境可占位），帮助 AI 直接理解如何使用
10. **子专家按需拆分**：大模块按功能拆子专家（仅一级），不强行一个专家兜全部
11. **专题按需创建**：超大模块（如 > 500 源文件）且需要三级结构时创建专题，专题不可嵌套；中等模块用专家+子专家即可，不强行升专题
12. **分批创建**：大模块/专题无法一次创建完成时，按功能子域分批，专题/父专家的架构文档先行作为共享输入，每批次完成后增量合并
13. **不编造**：无内容则标注「该模块无此项」，不凑话
14. **强依赖检测**：构建专家时若发现目标模块强依赖另一模块，自动评估适合创建子专家还是独立专家，后者需用户确认
15. **测试信息必采集**：模块有测试时必须采集测试信息（位置/框架/运行命令/环境依赖/已知失败），产出 `06-测试.md`（必出）与 `test/known-failures.md`（有测试时必出），切面级标注测试可执行性；**PROJECT.md 标注「❌ 无法运行 / 无测试」的服务按「测试不可运行跳过」规则不产出测试文档**
16. **专家资格判断**：只创建"领域专属且复杂度/规模达标"的模块专家；公共/横切知识（工具库、代码风格约定、通用封装、基础设施）不建专家，推荐存入项目记忆；简单模块不建专家，直接读代码或 module-teach 讲解
17. **专题记忆必写**：专家/专题落盘后必须写一条 ki 专题记忆（Step 8 的 8 字段路标），解决"资产闲置"——记忆存路标不存本体，让 AI 未加载专家前也能检索到关键入口
18. **模块间强关联必记**：专题记忆写入后调用 `strong-relation` skill（Step 8.5）识别该模块与外部模块的强关联（契约/业务耦合），写 ki 动作下沉到 `ki-memory-write` 强关联策略，解决 code review / 修改时"改了 A 不知道必须连带改 B"的风险
19. **接口信息按需记录**：专家模块是后端模块（暴露 API）或后台核心模块（数据接收/消费）时，Step 8.3 识别其暴露接口，调 `ki-memory-write` 接口信息策略写入 ki（按子功能聚合 + `tags="api"`，group=`接口信息/{功能模块名}`），供接口检索精确命中；纯内部无对外接口的模块跳过
20. **数据流按需记录**：专家模块有数据落地（DB/消息/缓存/文件）时，Step 8.4 识别其数据实体，调 `ki-memory-write` 数据流策略写入 ki（实体粒度 + `tags="data"`，group=`数据流/{功能模块名}`），供数据问题排查精确命中；纯计算型无数据落地的模块跳过
21. **关键决策按需记录且禁止臆造**：模块存在关键设计选择时，Step 3.5 产出 `C5-关键决策.md` 并由 Step 8.6 调 `ki-memory-write` 决策记忆策略写入 ki（group=`决策记录/{功能模块名}`、tags=`decision`），回答"当初为什么这么定"；**优先记有证据的决策**（文档明写 / commit 明说 / 注释明写，**且需主动挖掘**），无证据但代码结构强烈暗示的可记但须前置 `[推测]`，**纯猜测一律禁止**——臆造决策会污染 request-guard / code-review 的判断；纯 CRUD 或无线索模块跳过

## 执行流程

### 前置守门：沉淀路由检查

专家资产包是重载体（多子 agent 并行深挖 + 双层文档，成本高），创建前先检查 `loop-discovery` skill 是否可用：

1. **如果可用且本次创建未经过路由**：先用它完成三步检查（证据门 → 覆盖阶梯 → 载体选择）：
   - 证据门未过（仅一次性查阅需求，无重复使用/交接诉求）→ 不建专家包，直接回答或建议用 module-teach 讲解
   - 覆盖阶梯命中已有资产（`.module-experts/` 中已有相关专家）→ 走 expert-lookup 复用或本流程的「合并补全」，不重建
   - 路由结论为"新建专家包"时，继续下方 3 的**专家创建资格判断**
2. **如果不可用**：至少自检一次：该模块是否会被反复使用/排查/交接？若只是一次性理解需求，module-teach 或直接阅读更合适；自检通过（会被反复使用/排查/交接）→ 继续下方 3 的**专家创建资格判断**

3. **专家创建资格判断（领域专属 × 复杂度/规模）**：路由结论为"新建专家包"后，先确认该模块是否**够格**创建专家。专家资产包是重载体（多子 agent 深挖 + 双层文档），只应为"**领域专属且复杂度较高**"的模块创建：

   | 判定维度 | ✅ 符合（推荐创建专家） | ❌ 不符合（不创建专家） |
   |---------|----------------------|----------------------|
   | **领域专属性** | 专属于某业务功能领域（告警 / 支付 / 权限 / 日志查询等），有明确业务语义，仅服务特定业务 | 公共 / 横切知识：工具库（utils / helpers / commons）、通用封装、**代码风格约定**、通用算法、基础设施（第三方库 / 框架 / 标准库） |
   | **复杂度** | 逻辑复杂：多层调用链 / 状态机 / 并发异步 / 异常分支多 / 数据落地多方消费 | 逻辑简单：单文件、无复杂业务逻辑、纯配置 / 纯数据 |
   | **代码规模** | 代码量较大：源文件较多（如 ≥ 5 个）或实现行数多（相对项目整体规模判断） | 代码量小：少量文件、仅几个工具函数 |

   **边界指引**（处理判定维度交叉的中间案例）：
   - **规模小但逻辑显著复杂**（如 3 个文件含状态机 / 并发 / 长调用链）→ 可建专家，复杂度优先于规模
   - **规模大但纯样板代码**（CRUD 模板化 / 低知识密度）→ 不建全量专家，降级为子专家或仅轻量记录
   - **模块内的公共子包**（如告警模块内 `utils/`）→ 归入所属业务专家范围，不单独建专家；确属全项目横切的独立包才触发"公共知识"判定

   **判定结论**：
   - **领域专属 且（复杂度高 或 规模大）→ 推荐创建专家**，继续 Step 0
   - **公共 / 横切知识 → 不创建专家**，推荐存入**项目记忆**，向用户说明理由后停止创建流程
   - **领域专属但规模小 / 逻辑简单 → 不创建专家**，直接读代码或建议用 module-teach 讲解，向用户说明理由后停止创建流程
   - **用户坚持要建** → 提示资产成本与更轻替代（项目记忆 / module-teach）后按用户意愿执行

4. **项目全局资产检查**：检查 `.module-experts/PROJECT.md` 是否存在（项目级共享资产，见「项目全局资产（PROJECT.md）」）：
   - **不存在** → 提示用户「项目尚未创建 PROJECT.md 全局资产，是否优先创建？」用户确认后，先扫描项目根目录（README / 目录结构 / 各服务入口）生成 PROJECT.md 初稿（模板见 [templates/PROJECT.md.template](templates/PROJECT.md.template)，直接读取填充，无需扫描 reference.md），再继续本流程
   - **存在** → 读取 PROJECT.md 作为项目全局上下文，供 Step 1 扫描与后续子 agent 背景使用
   - 创建/扫描中发现新的全局信息（新服务/技术栈变更等）→ 更新 PROJECT.md（只补全局信息，不写单专家细节）
   - **测试可执行性预判**：PROJECT.md 中标注目标服务「❌ 无法运行 / 无测试」时，本次创建**跳过测试深挖**——不产出 `06-测试.md` 的深挖与 `test/known-failures.md`，在相应文档标注「该服务测试不可运行/无测试，跳过测试内容」；标注「✅ 可跑 / ⚠️ 依赖外部环境」时正常产出测试文档

### Step 0：确认模块边界与专家/专题名 + 子专家评估

- 必须有明确的模块根路径（目录或包名）；路径不明确时仅问一次
- **专家名自动派生**：由模块的业务功能自动派生**中文专家名或专题名**（如 `pkg/alert` → "告警处理专家"；`pkg/payment` → "支付系统专题"）。即使用户指定了名称（如"建一个告警专家"），也以扫描后从业务功能派生的名称为准，用户指定名仅作参考；名称不单独提问确认，统一在 Step 1.9 计划预览中确认
- 专家 = **业务功能域**，一个专家可覆盖同一域下的多个相关模块
- 若 `.module-experts/{中文名}/` **已存在**：确认「合并补全」还是「重建」，默认合并补全。**旧格式迁移**：若检测到旧格式（实现层文件在根目录而非 `implementation/` 下），自动将旧文件移入 `implementation/`，并补建契约层骨架
- **专题评估**：快速扫描模块规模，若模块超大（如 > 500 源文件）且有多个独立功能域 → 在计划中列入专题结构：
  - 专题名 + 专题下各专家的划分 + 各专家是否需要子专家
  - **专题不可嵌套**：专题下不可再有专题
  - 模块中等规模则不建专题，直接走专家+子专家
- **子专家评估**：若不建专题但模块较大且有清晰功能子域 → 在计划中列入子专家拆分：
  - 子专家名 + 各自覆盖的功能子域
  - **子专家仅一级**：子专家下不可再拆（若子域仍太大，应升级为专题）
  - 模块小则不拆，单专家即可
- 专家名或专题名即目录名：`.module-experts/{中文名}/`
- 以上结构判断（专题/子专家/合并重建）均**不在本步逐项提问**，统一汇入 Step 1.9 计划预览一次确认；仅模块根路径不明确时在本步提问

### Step 1：模块范围扫描（AI 自行判断）

**先查代码索引（省一次全仓摸底）**：仓库已有 `.fe-index/` 时，`use_skill("index-lookup")` 按模块路径匹配 → 后端拿 `modules/*.md`（模块边界 / 依赖与被依赖 / 数据表 / 入口），前端拿 `pages/*.md` 或 `apis/*.md`（页面范围 / 接口）——作为扫描起点与**依赖线索**（供 Step 1.5 强依赖检测参照）；**无索引 / 路径未命中 / `--check` 报过期 → 照常直读，不阻塞**。索引只给骨架（去哪看），本步要记录的信息（公开签名 / 测试信息 / 决策线索）仍须直读代码确认。

主 agent 用 `list_dir` / `search_file` 快速摸清模块根目录结构，自行判断：

- 文件清单与语言 / 框架 / 测试目录 / 入口点
- **实现层该产出哪些切面 Wiki 文档**（发现 DB → `04-模型.md`；router → `05-接口.md`；测试 → `06-测试.md`；配置 → `07-运维.md`）
- **契约层该产出哪些文档**：`C0` + `C1` 必出；有多方法协作 → `C2`；内联示例不够 → `C3`；有数据落地（DB/队列/文件/事件）→ `C4`；**发现关键决策证据**（设计文档/ADR、commit message、代码注释三类中任一明写）→ `C5`
- **子专家扫描**（如有子专家）：为每个子专家确定其模块范围、公开类/方法
- 模块规模：源文件过多（如 > 200）时改为采样，保证必读入口/主调用链/每子目录至少1个代表文件
- **记录关键文件路径与关键符号**（类/方法/函数名，供实现层 cite / 章节来源，不记行号）；**同时记录公开类/方法签名 + 真实调用代码**（供契约层提炼与代码示例）；**记录参数行为观察点**（测试用例 / 分支逻辑中不同取值的行为差异，供 C1 行为语义）；**记录数据落地点与消费方线索**（谁写入、谁读取，供 C4 提炼）；**记录关键决策证据线索**（设计文档/ADR 明写的决策、commit message 说明的选型理由、代码注释写明的"为什么不用 X"，供 C5 提炼——**只记明写的，不记反推的**）
- **记录测试信息（切面级）**：测试目录/文件、测试框架、运行命令、环境依赖（DB/MQ/Redis/外部服务）、已知失败（供 `06-测试.md` 与 `test/known-failures.md`）；模块有测试但无法确认可执行性时标注「测试可执行性未知」；**确认测试不可运行（环境缺失且无法补齐/命令根本跑不起来）时，在 PROJECT.md 服务清单将该服务「测试可执行性」标注为「❌ 无法运行」，并按「测试不可运行跳过」规则跳过测试深挖**

### Step 1.5：强依赖模块检测

在 Step 1 扫描过程中，若发现目标模块通过 `import`/`require` 等方式**强依赖**另一个模块（非标准库、非框架依赖），按以下流程处理：

**1. 依赖评估**：判断被依赖模块适合「子专家」还是「独立专家」：

| 评估维度 | 适合子专家 | 适合独立专家 |
|---------|-----------|-------------|
| 业务归属 | 与目标模块属于同一业务功能域 | 属于不同业务域或有独立业务价值 |
| 使用范围 | 仅被当前模块使用 | 被多个模块共享使用 |
| 规模 | 较小的功能子集 | 有完整的模块边界和公开 API |
| 独立性 | 脱离父模块无独立存在价值 | 可独立运作、可单独被其他模块依赖 |

> **评估优先级**（当四维出现交叉时）：**独立性 > 业务归属 > 使用范围 > 规模**。如依赖模块可独立运作（被多个模块使用、有完整 API），即使归属于同一业务域也应优先判定为独立专家。

**2. 处理决策**：
- **适合子专家**：纳入 Step 0 的子专家拆分方案，**无需额外用户确认**（已在 Step 0 确认过子专家机制）
- **适合独立专家**：暂停当前流程，向用户说明：
  - 发现的强依赖模块及其路径
  - 为什么更适合作为独立专家而非子专家（对照上述评估维度说明理由）
  - **询问用户**：是否先创建该依赖模块的独立专家？
    - **用户确认**：回到 Step 0 开始新专家的创建流程，完成后再继续当前专家的构建
    - **用户拒绝**：将该依赖标记在 `01-架构.md` 外部依赖清单中，标注 `⚠️ 未创建独立专家，依赖模块 `{module}` 的能力契约不完整`，然后继续当前专家的创建流程
- **检测到循环依赖**（如 A→B→C→A）：在涉及的模块中选一个最核心的作为当前专家，其余作为外部依赖记录到 `01-架构.md`，标注 `⚠️ 循环依赖：{涉及模块列表}`。不无限回退
- **不适合创建专家**（如第三方库、框架、标准库）：记录在 `01-架构.md` 的外部依赖清单中即可

### Step 1.6：分批评估与计划（大模块/专题时触发）

当 Step 0 确认了专题或 Step 1 扫描发现模块规模较大（如 > 100 源文件），一次任务无法完成全部专家/子专家的创建时，生成分批计划。

#### 触发条件

满足以下**任一**条件即触发：
- 创建了专题（专题下有多个专家，每个专家可能还有子专家）
- 模块源文件 > 100 个
- 子专家数量 > 3 个

#### 分批策略

**按功能子域/专家分批**——每批次产出一个专家或子专家的完整资产：

1. **先完成专题/父专家的架构文档**（`T0-专题总览.md` 或 `implementation/01-架构.md`），作为所有批次的共享输入
   - 专题：先产出 `topic.md` + `T0-专题总览.md`（含跨专家架构图 + 专家导航）
   - 父专家：先产出 `agent.md` + `C0-使用总览.md` + `implementation/01-架构.md`
2. **按专家/子专家划分批次**，每批次一个独立 task-dispatch 子任务：
   - 输入：专题/父专家的架构文档 + 该专家/子专家的模块范围
   - 产出：该专家/子专家的完整资产（agent.md + 契约层 + implementation/）
   - 完成后增量合并到 INDEX.md

#### 分批计划输出

分批计划不单独确认，作为 Step 1.9 创建计划预览的一部分一并确认：

```markdown
## 分批创建计划

**总批次**：{N} 批
**共享输入**：{专题总览 / 父专家架构文档}

| 批次 | 专家/子专家名 | 模块范围 | 预估文件数 | 状态 |
|------|--------------|----------|-----------|------|
| 0 | {专题/父专家} 架构先行 | {全模块架构} | - | 待执行 |
| 1 | {专家1名} | {模块路径} | {N} | 待执行 |
| 2 | {专家1名} → {子专家1名} | {子模块路径} | {N} | 待执行 |
| 3 | {专家2名} | {模块路径} | {N} | 待执行 |
| ... | ... | ... | ... | ... |

> 批次 0 必须先完成，后续批次可并行（最多 3 个并行）。
```

#### 进度跟踪

在 INDEX.md 中标注各批次进度：

```
## {专题名/专家名}  （分批创建中）
- 模块根：{path}
- 创建模式：分批创建（共 {N} 批）
- 进度：{已完成}/{总批次}
- 批次状态：
  - [x] 批次0：架构先行 ✅
  - [x] 批次1：{专家1} ✅
  - [ ] 批次2：{子专家1} ⏳
  - [ ] 批次3：{专家2} ⏳
```

全部批次完成后，更新 INDEX.md 为正常格式（移除分批进度标注）。

#### 批次间一致性保证

- 每批次开始前，读取已完成的专题/父专家架构文档作为上下文
- 每批次完成后，主 agent 检查新产出与已有资产的一致性（命名、架构描述、依赖关系）
- 若发现不一致，修正新产出（以先完成的架构文档为准）

### Step 1.9：创建计划预览（用户确认后实施）

扫描与评估完成后、派出任何子 agent 前，将 Step 0~1.6 的全部判断汇总为一份**创建计划**直接输出，用户确认后才实施。零散确认（名称、子专家、专题、分批）全部收敛到这一次确认中。

```markdown
## 专家创建计划

**专家名（自动派生）**：{中文专家名或专题名}（由 {模块根} 的业务功能派生）
**模块范围**：{模块根路径}，共 {N} 个源文件，{语言/框架}
**结构**：单专家 / 专家+子专家（{子专家清单+各自子域}）/ 专题（{专家划分}）
**已存在处理**（如命中）：合并补全 / 重建

**实现层切面**：{01-架构, 02-实现, 06-测试（必出）, ...（含选择理由，如"发现 DB 模型 → 04-模型"）}
**契约层文档**：{C0, C1, ...（含选择理由，如"有数据落地 → C4"、"发现设计文档明写的决策 → C5"）}
**测试状态**：{测试目录 + 测试可执行性（✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行 / 无测试）}
**匹配关键词（自动提取）**：{8~15 个，中英混合，将写入 INDEX.md 供 expert-lookup 匹配}
**项目全局资产**：{PROJECT.md 存在 / 缺失（缺失时计划首步为"创建 PROJECT.md"）}
**专题记忆**：落盘后将写一条 ki 专题记忆（Step 8 的 8 字段路标）
**接口信息**：若为后端/后台核心模块，落盘后将记录暴露接口（Step 8.3，按子功能聚合的可检索原子，tags=`api`）
**数据流**：若有数据落地，落盘后将记录数据实体流向（Step 8.4，实体级可检索原子，tags=`data`）
**模块间强关联**：落盘后将调用 strong-relation 记录该模块与外部的强关联（Step 8.5，写入 ki-search 关联关系分组）
**关键决策**：若发现关键设计选择，落盘后将产出 `C5-关键决策.md` 并写决策记忆（Step 8.6，tags=`decision`；优先记有证据的，结构暗示的须前置 `[推测]`，纯猜测不写）

**分批计划**（如触发 Step 1.6）：{批次表}

确认后开始创建；可直接修改计划中任意项（如专家名、子专家划分、关键词）。
```

**规则**：
- 计划只输出一次，用户确认即执行；用户修改计划项后按修改后的计划执行，不重新输出全量计划
- **关键词提取来源**：业务域名词、模块名/包名、核心公开类/方法的业务含义、功能子域名、常见问题词（如"告警不触发"中的"触发"）；中英混合，8~15 个
- 用户长时间未回应时不自行开始创建

### Step 2：知识库优先查（如 ki 可用）

按 ki-search 规则，对目标模块先查 ki（项目记忆索引 → KB），命中则复用、跳过部分代码阅读。无 ki 则跳过。

### Step 3：派出专家团——实现层（并行）

依据 Step 1 判断结果选择切面。切面 ≥ 2 时调用 task-dispatch 并行，每个切面一个子 agent。

- **task-name**：`module-expert-{专家名拼音或英文简称}`
- **子任务产出**：每个切面产出 `implementation/{NN-切面中文}.md`
- **子 agent prompt 要点**：给定模块根 + 中文专家名 + 切面调研清单（见 [reference.md](reference.md)）+ 同批切面清单；调研并记录文件路径与关键符号（类/方法/函数名）；严格遵循 cite / 目录 / 章节来源 / Mermaid 规范
- **子专家**（如有）：每个子专家的 implementation/ 独立产出，可与其他子专家并行

**切面定义**：

| 切面 | 文件 | 核心内容 |
|---|---|---|
| architecture | `implementation/01-架构.md` | 职责、边界、子模块、依赖图、分层；含子专家划分说明（如有）；兼作实现层入口 |
| implementation | `implementation/02-实现.md` | 核心算法、设计模式、热点路径、关键类 |
| data-flow | `implementation/03-数据流转.md` | 入口 → 出口生命周期、状态流转、异步流 |
| models | `implementation/04-模型.md` | 数据模型、DB schema、ORM 映射、迁移、校验 |
| api | `implementation/05-接口.md` | 公开入口、契约、错误码、版本策略 |
| tests | `implementation/06-测试.md` | 单测位置、覆盖、模式、如何跑、**测试可执行性**（运行命令/环境依赖/已知失败）、缺口（必出） |
| ops | `implementation/07-运维.md` | 配置、部署、feature flag、日志 / 监控 |

> `01-架构.md`、`02-实现.md`、`06-测试.md` 必出；其余按适用性。父专家的 `01-架构.md` 须含子专家划分说明与导航。

### Step 3.4：专题总览合成（仅当创建专题时）

若 Step 0 确认创建专题，在实现层产出后、契约层提炼前，主 agent 先合成专题级资产：

1. **产出 `topic.md`**：专题名片——一句话职责 + 专家清单 + 专题就绪状态
2. **产出 `T0-专题总览.md`**：
   - 专题能力清单：从各专家的架构分析中提炼专题级能力
   - 专题边界：专题做什么、不做什么
   - **跨专家架构图**（Mermaid）：展示专题下各专家的依赖关系、数据流转、调用链
   - 专家导航：列出专题下所有专家及其职责、契约层就绪状态
3. **按需产出 `T1-跨专家契约.md`**：仅当专题有跨专家的统一公开 API 时产出

> 专题不产出 `implementation/`——具体实现由其下专家的 `implementation/` 承载。

### Step 3.5：提炼契约层（主 agent，在实现层产出后）

实现层各切面文档产出后，**主 agent** 基于实现层分析结果提炼契约层。需跨切面综合判断哪些是公开能力，确保一致性和完整性。**子专家各自独立提炼契约层。**

1. **识别公开能力**：从 `implementation/02-实现.md`（关键类与函数）、`implementation/05-接口.md`（对外入口）中提取所有公开类/方法
2. **产出 `C0-使用总览.md`**：
   - 能力清单：从架构职责提炼"模块能干什么"
   - 能力边界：从架构分析提炼"不做什么"
   - 已知问题与常见坑：从实现层各切面的"风险点""边界条件"提炼，格式：现象/触发条件/正确做法
   - **子专家导航**（如有子专家）：列出子专家名 + 一句话职责 + 各自覆盖的功能子域
3. **产出 `C1-能力契约.md`**：
   - 每个公开类/方法：用途 / 参数（含类型与**行为语义**）/ 返回 / 异常 / 约束 / **真实可运行代码示例**
   - **参数行为语义分级**：枚举/开关/边界敏感参数逐值说明可观察行为差异（如 `mode=fast` 跳过重复校验）；数值参数标单位与边界值行为（如 `timeout=0` 表示永不超时）；纯透传参数一行说明即可，防止 C1 膨胀
   - 契约来源：标注类名/方法签名（非行号）
   - **严格黑盒**：不写算法、内部结构、私有方法、DB schema；约束可写但不解释"为什么"
   - **代码示例**：从代码库中找到真实的调用方代码（如测试文件中的调用、其他模块中的调用），或基于实际 API 编写可运行示例（API 签名真实，环境初始化可注释占位）。不是伪代码
   - **覆盖度声明**（超大模块采样时）：C1 头部标注"本次契约基于采样 X/N 文件，以下为已覆盖的公开方法。未采样文件中可能存在未记录的公开方法"
4. **按需产出 `C2-使用流程.md`**：
   - 识别需要多方法协作的常见业务目标
   - 每条：业务目标 / 调用顺序 / 事务边界 / 预期结果 / 错误处理 / **真实可运行代码示例**
   - 无多方法协作场景时不产出，在 C0 标注「暂无使用流程，参照 C1 直接调用」
5. **按需产出 `C3-代码示例-{topic}.md`**：
   - 当 C1/C2 中的内联示例不足以覆盖完整使用场景时，将完整、可运行的代码示例拆分到独立文件
   - 文件名用 topic 区分：`C3-代码示例-基础用法.md`、`C3-代码示例-高级场景.md` 等
   - 每个示例标注：目标 + 涉及的契约条目 + 完整代码 + 关键说明
6. **产出 `C4-数据流向与消费.md`**（有数据落地时必出）：
   - 从 Step 1 记录的数据落地点出发，每类核心数据实体一条：来源接口（本模块哪些公开方法产生/写入）/ 去向（表/队列/文件/事件，概括级）/ 消费方（反向查找谁读取，按模块或功能级概括，>3 个时归纳）/ 业务用途（一句话说清"用来干嘛"）
   - 模块外消费方基于引用扫描确定时标注 `[基于引用扫描，未深入验证]`；未发现消费方时标注「未发现模块内消费方，疑似供外部系统使用」，不编造
   - **黑盒边界**：只写数据用途，不写消费方的处理逻辑（CR9）
   - 纯计算型模块（无数据落地）不产出，在 C0 标注「无持久化数据，未产出 C4」
7. **产出 `C5-关键决策.md`**（有决策线索时必出）：
   - 每条决策含：决策（含关键参数/阈值）/ 背景约束 / 被否决方案及否决理由 / 重新评估触发条件（**须为可观测判据**，写不出写「无」）/ 关联代码 / **证据来源**
   - **证据门（硬约束）**：优先记有证据的决策——证据限三类：① 设计文档 / ADR 明写 ② commit message / PR 描述明说 ③ 代码注释 / docstring 明写
   - **先找再判**：三类证据需**主动挖掘**（查项目设计文档目录含 design-craft 的「关键决策点」表 → `git log -S{关键符号}` / PR 描述 → 关键实现处注释），不被动等待；老模块常三类全无，此时按下方 `[推测]` 分级处理，**不要直接放弃整条决策**
   - **`[推测]` 标注**（对齐 `debug` 既有约定）：无直接证据但**代码结构强烈暗示**的（如"明显是轮询实现且全模块无 webhook 代码"）→ 可记录，决策字段前置 `[推测]`，证据来源写「无直接证据，基于{具体结构}推断」；**纯猜测无任何结构支撑的禁止记录**
   - **红线**：字段空缺写「无」，**不因字段空缺而编造备选方案与否决理由**（标注"这是推测"允许，编造"曾考虑某方案但因 X 否决"禁止）
   - **被否决方案**：事后场景常拿不到备选，允许写「无」
   - 无任何线索（既无证据也无结构暗示）→ 不产出 C5，在 C0 标注「未发现可追溯的关键决策」
   - 证据已失效（设计文档已删、commit 被 squash）但决策可确认的 → 仍记录，证据来源注明失效情况
8. **模块无公开类/方法**（纯配置型/纯数据型）时：C1 转写配置契约，C0 标注模块性质

> 详细模板见 [reference.md](reference.md) 中「契约层文档模板」章节。

### Step 4：合成专家入口

主 agent 汇总各切面产出 + 契约层，写入 `agent.md`：

**`agent.md`（专家名片，必出，不套 Wiki 格式）**：
- 一句话职责：该专家负责的**业务领域**
- 负责的模块：模块根路径与一句话职责
- 何时找这个专家：列出典型使用场景
- 契约层就绪：`C0 + C1` 就绪 / `C0 + C1 + C2 + C3 + C4 + C5` 就绪（列出实际产出项）/ 暂无
- 所属专题（如有）：专题名 + T0 链接
- 子专家清单（如有）：子专家名 + 一句话职责 + 覆盖的功能子域
- 包含的资产：契约层文档清单 + 实现层文档清单
- 测试状态（切面级，有测试时）：测试目录位置 + 测试可执行性（✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行）+ known-failures 引用
- 出处行：生成日期 + git commit（资产基线，创建/全量更新时刷新）

**`topic.md`（专题名片，仅当创建专题时，必出，不套 Wiki 格式）**：
- 一句话职责：该专题覆盖的**超大模块/业务域**
- 专题范围：模块根路径与功能域划分
- 何时找这个专题：列出典型使用场景
- 专家清单：专家名 + 一句话职责 + 契约层就绪状态
- 专题就绪：`T0` 就绪 / `T0 + T1` 就绪 / 暂无
- 包含的资产：`T0-专题总览.md`（+ `T1-跨专家契约.md` 如有）+ 专家清单
- 出处行：生成日期 + git commit（资产基线，创建/全量更新时刷新）

**`implementation/01-架构.md`** 补充：
- 契约层索引：链接到 `C0-使用总览.md` 等（根目录，相对路径 `../C0-使用总览.md` 或直接 `../../C0-使用总览.md` 视专家目录结构）
- 实现层切面索引：链接到其他 `implementation/02-实现.md` 等
- 子专家划分说明（如有）：为何如此拆分、各子专家边界
- 关键发现 / 主要风险 / 常见坑（Top）
- 术语表
- 出处行

### Step 5：校验（含格式自检）

主 agent 自检产出，**实现层按 R1–R7、契约层按 CR1–CR9 逐篇手动检查**（`agent.md` 除外）：

内容完整性：
- `agent.md` 与 `C0-使用总览.md`、`C1-能力契约.md`、`implementation/01-架构.md`、`implementation/02-实现.md`、`implementation/06-测试.md` 必有且非空
- 契约层各文档非空、无纯占位符
- 实现层各切面文档非空、无纯占位符
- 无内容的切面标注「该模块无此项」而非留空
- `implementation/01-架构.md` 含契约层索引 + 实现层切面索引
- `C0-使用总览.md` 含能力清单 + 边界 + 已知问题 + 子专家导航（如有）
- `C4-数据流向与消费.md`（若产出）每条数据实体含来源接口 / 去向 / 消费方 / 业务用途，消费方为模块级概括
- **代码示例为真实可运行代码**（CR7），非伪代码、非占位符
- 子专家（如有）各有完整 `agent.md` + 契约层文档 + `implementation/`
- **专题（如有）**：`topic.md` 与 `T0-专题总览.md` 必有且非空；`T0` 含专题能力清单 + 边界 + 跨专家架构图 + 专家导航；专题不含 `implementation/`

实现层格式自检（R1–R7）：同前

契约层格式自检（CR1–CR9）：
- **CR1** C0 含能力清单 + 边界 + 已知问题 + 子专家导航（如有）
- **CR2** C1 每个公开类/方法含：用途/参数（含行为语义，分级要求）/返回/异常/约束/真实代码示例
- **CR3** 契约文档不出现实现细节
- **CR4** C2（若产出）每条流程含：业务目标/调用顺序/事务边界/预期结果/真实代码示例
- **CR5** 每条契约标注契约来源（类名/方法签名）
- **CR6** 已知问题条目含：现象/触发条件/正确做法
- **CR7** 代码示例为真实可运行代码（API 签名真实，环境可占位），是使用方代码而非被调用方实现代码
- **CR8** C4（若产出）每条数据实体含来源接口/去向/消费方（模块级概括）/业务用途
- **CR9** C4 只写数据用途，不写消费方处理逻辑

不合格 → 补全 / 修正后重检。

### Step 6：Auto-Review 评估审核

Step 5 自检通过后，调用 `use_skill("auto-review")` 对全部专家资产（含子专家）进行质量审查与优化闭环。**auto-review 重点审查 Step 5 不覆盖的维度**（逻辑一致性、可读性、内容质量、引用完整性），格式自检已在 Step 5 完成，不在此重复。

1. **审查范围**：专家根目录下所有文件，包括：
   - `agent.md`（专家名片）
   - `C0-使用总览.md`、`C1-能力契约.md`、`C2-使用流程.md`、`C3-代码示例-*.md`、`C4-数据流向与消费.md`（契约层）
   - `implementation/` 下所有实现层文档
2. **子专家**：每个子专家各自独立审查
3. **修复闭环**：auto-review 发现的问题**必须修复**后才能进入 Step 7
4. **复杂场景**：若 auto-review 判断属于复杂场景并调用了 challenger skill，必须等 challenger 的质疑结果出来后一并处理
5. **达上限兜底**：若 auto-review 达到 3 轮修复上限仍不通过，将未解决的 auto-review 问题追加到 `C0-使用总览.md` 的"已知问题"章节，标注 `⚠️ auto-review 未通过的遗留项`，然后继续进入 Step 7，不阻塞专家落盘

### Step 7：更新索引

在 `.module-experts/INDEX.md`（不存在则建）按专家/专题追加 / 更新。每条记录必含**匹配关键词**行（Step 1.9 计划中确认的关键词），供 expert-lookup 匹配：

```
# 模块专家包索引
> 由 expert-team 自动维护

## 项目全局（共享资产）
- 资产：PROJECT.md（项目信息/技术栈/核心服务清单/配套服务关系/架构图/数据流向图/运行环境）
- 说明：所有专家共享的项目全局上下文，创建/使用专家前建议先读
- 维护：expert-team 首次创建/发现全局信息时更新；expert-lookup 使用中发现变化时受限更新

## {中文专题名}（专题）
- 模块根：{path}
- 生成日期：{date}  git commit：{hash}（资产基线，创建/全量更新时刷新）
- 匹配关键词：{关键词1}, {关键词2}, ...（8~15 个，中英混合）
- 专题层：T0-专题总览, T1-跨专家契约（或「暂无」）
- 专家清单：
  - {专家1名}（{一句话职责}）
    - 匹配关键词：{该专家的关键词}
    - 契约层：C0-使用总览, C1-能力契约, ...
    - 实现层：implementation/01-架构, 02-实现, ...
    - 子专家（如有）：{子专家1名}（{职责}）, {子专家2名}（{职责}）
  - {专家2名}（{一句话职责}）
    - 匹配关键词：{该专家的关键词}
    - 契约层：C0-使用总览, C1-能力契约, ...
    - 实现层：implementation/01-架构, 02-实现, ...

## {中文专家名}（普通专家，职责摘要见 agent.md）
- 模块根：{path}
- 生成日期：{date}  git commit：{hash}（资产基线，创建/全量更新时刷新）
- 匹配关键词：{关键词1}, {关键词2}, ...（8~15 个，中英混合）
- 契约层：C0-使用总览, C1-能力契约, C2-使用流程, C3-代码示例-xxx, C4-数据流向与消费（或「暂无」）
- 实现层：implementation/01-架构, 02-实现, 03-数据流转, ...
- 测试状态：{✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行 / 无测试}（与 PROJECT.md 服务清单标注一致；「❌ 无法运行 / 无测试」表示已跳过测试内容）
- 子专家（如有）：
  - {子专家1名}（{一句话职责}），匹配关键词：{...}
  - {子专家2名}（{一句话职责}），匹配关键词：{...}
```

> 不初始化 CHANGELOG.md——资产变更不单独记录，git 历史即变更记录。关键词后续由 expert-lookup 自动追加更新（只增不删）。
>
> **资产基线刷新**：创建与合并补全/重建完成时，将 INDEX.md 与 agent.md/topic.md 的 git commit 刷新为**当前最新 commit**（资产基线 = 资产覆盖的代码基线，语义见「文档说明·资产基线 commit」）。合并补全流程含全模块重扫（Step 1），刷新基线合法；本步覆盖创建与合并补全两条路径的共同落点，更新后无需另行记录变更日志；expert-lookup 增量更新不刷新基线。

### Step 7.5：回写代码索引（如存在）

专家包落盘后，若仓库已有代码索引（`.fe-index/`，即 Step 1 经 `index-lookup` 用到的那个），**重建对应端索引**让「专家资产」列自动出现——索引成为专家包的发现入口（解决"建了没人知道"）：

- **后端**：重跑 `backend-index` 的 `--emit-tree`（一条命令，秒级）——`{slug}/index.md` 的模块总表「专家资产」列与模块卡（`modules/*.md`）的「专家资产」章节会因 `.module-experts/` 目录存在而出现；专家目录为中文业务名、脚本机械匹配不上时，按 `backend-index` 的「专家关联确认」人工指认到模块卡
- **前端**：`frontend-index` 产物暂无专家探测，跳过（前端专家的发现靠 Step 8 的 ki 专题记忆）；该 skill 增加同款探测后可回写
- **分批创建时**：每批次落盘后即可执行（幂等，重建秒级）；也可全部完成后一次重建
- **无索引 / 索引已过期 / 用户不重建 / 重建后本模块仍不在索引范围**：跳过，不阻塞；可在对话小结中附一句"该模块已建专家，建索引后可自动关联"

> 回写的是**索引产物**（`frontend-index` / `backend-index` 的重建命令），不改变专家文档的快照属性；重建命令与口径以这两个 skill 的文档为准，本步不复制。

### Step 8：必须构建专题记忆（ki 路标）

专家/专题落盘后，**必须**写一条"专题记忆"到 ki 记忆，让 AI 在任何对话中**未加载专家资产前**也能快速检索到"有这个模块的知识 + 关键入口 + 去哪找详细"。这是解决"专家资产闲置"的关键——资产很全但只在 AI 主动查 `expert-lookup` 时被用上，专题记忆把资产从"被动待查"变为"主动可达"。

**专题记忆定位：路标 + 快查卡，绝不缩水复制专家资产**。只存"资产存在感 + 关键入口 + 极少数高频原子"，不存知识本体。全量复制会造成双源漂移（专题记忆与专家资产不一致），是生态系统评审判定的有害冗余（`内置 memory + ki 记忆 + 专家资产` 等量重复）。

**执行**：调用 `use_skill("ki-memory-write")` 的**专题记忆策略**，按该策略的 8 字段路标模板 + 维护规则写入 ki。ki 写入细节（8 字段模板、`ki_bulk_sync_relation` API、group/relation 约定、格式硬约束、维护规则）一律以 `ki-memory-write` 的 `reference-topic-memory.md` 为准，本步不重复声明。

**字段填充来源**：逐条从已产出的专家资产提炼，禁止编造；任一字段为空则写「无」不硬凑。

**ki 不可用降级**：ki 不可用时，**跳过写记忆并在 Step 9 验收报告标注**，不阻塞专家落盘（对齐 Step 2 的既有降级约定，避免"必须"阻塞流程）。

### Step 8.3：记录接口信息（暴露接口可检索原子）

专题记忆写入后，若专家模块是**后端模块**（暴露 API 给前端）或**后台核心模块**（数据接收/消费），**识别其暴露接口**并写入 ki 记忆，让 AI 查"某接口在哪定义 / 怎么调 / 谁提供"时直接命中。

**定位**：专题记忆（Step 8）记录"模块内部知识路标"（模块级）；接口信息记录"模块内子功能的接口集合"（子功能级）——粒度更细，供接口检索精确命中。两者互补，同存 ki。

**识别来源**：从契约层 `C1-能力契约.md` 提炼公开接口（API 路径 + 后端接口名 + 文件位置 + 职责）。

**执行**：调用 `use_skill("ki-memory-write")` 的**接口信息策略**，按该策略的子功能聚合模板 + `tags="api"` 约定写入 ki。ki 写入细节（group=`接口信息/{功能模块名}`、relation=子功能名、字段模板）一律以 `ki-memory-write` 的 `reference-api.md` 为准，本步不重复声明。

**降级**：ki 不可用时跳过（对齐 Step 8 降级约定）；接口清单在对话内输出，不阻塞专家落盘。模块无暴露接口（纯内部模块）时跳过本步，在 C0 标注「无对外接口，未记录接口信息」。

### Step 8.4：记录数据流（数据实体流向可检索原子）

专题记忆写入后，若专家模块有**数据落地**（DB 表 / 消息 / 缓存 / 文件），**识别其数据实体**并写入 ki 记忆，让 AI 查"某张表/字段/消息是哪个模块写的、被谁读、干什么用"时直接命中。

**定位**：专题记忆（Step 8）记录"模块内部知识路标"（模块级）；数据流记录"模块内数据实体的生产/消费流向"（实体级）——粒度更细，供数据问题排查精确命中。两者互补，同存 ki。

**识别来源**：从契约层 `C4-数据流向与消费.md` 提炼数据实体（表 / 消息主题 / 缓存 key / 数据结构 → 生产方 / 消费方 / 业务用途）。

**执行**：调用 `use_skill("ki-memory-write")` 的**数据流策略**，按该策略的实体流向模板 + `tags="data"` 约定写入 ki。ki 写入细节（group=`数据流/{功能模块名}`、relation=数据实体名、字段模板）一律以 `ki-memory-write` 的 `reference-data-flow.md` 为准，本步不重复声明。

**降级**：ki 不可用时跳过（对齐 Step 8 降级约定）；数据实体清单在对话内输出，不阻塞专家落盘。模块无数据落地（纯计算型模块）时跳过本步，在 C0 标注「无持久化数据，未记录数据流」。

### Step 8.5：记录模块间强关联（strong-relation）

专题记忆写入后，**调用 `strong-relation` skill** 识别并记录该模块与**外部模块**的强关联（契约耦合 + 业务耦合）。strong-relation 负责"识别关联 + 判定方向强度"，其写 ki 的动作下沉到 `ki-memory-write` 的强关联策略。

**定位**：专题记忆（Step 8）记录"模块内部知识路标"；`strong-relation` 记录"模块间强耦合"——解决 code review / 修改时改了 A 不知道必须连带改 B 的风险。两者互补，同存 ki。

**执行**：按 `strong-relation` 的流程执行（环境检测 → 定位模块 → GitNexus+源码识别关联 → 判定方向强度 → 调 `ki-memory-write` 强关联策略写 ki → 校验）。

**降级**：ki 不可用时跳过（对齐 Step 8 降级约定）；关联识别在对话内输出清单，不阻塞专家落盘。

### Step 8.6：记录关键决策（决策记忆）

若 Step 3.5 产出了 `C5-关键决策.md`，将其中决策同步写入 ki 记忆，让 AI 在**未加载专家资产前**也能检索到"当初为什么这么定"——git log 只告诉你改了什么，不告诉你为什么。

**定位**：其余五类 ki 记忆答"模块有什么 / 接口在哪 / 数据怎么流 / 和谁耦合 / 报错怎么解"，决策记忆答**"为什么"**。与 GitNexus 互补——GitNexus 答"代码现在长什么样"，决策记忆答"当初为什么这样"，两者叠加才是完整的影响分析。

**执行**：调用 `use_skill("ki-memory-write")` 的**决策记忆策略**写入 ki。ki 写入细节（group=`决策记录/{功能模块名}`、relation=决策主题、tags=`decision`、字段模板、证据门、格式硬约束）一律以 `ki-memory-write` 的 `reference-decision.md` 为准，本步不重复声明。

**字段填充来源**：从 Step 3.5 产出的 `C5-关键决策.md` 逐条提炼，一一对应；禁止新增 C5 中没有的决策。

**证据门（继承 C5，硬约束）**：优先写**有证据支撑**的决策；无直接证据但代码结构强烈暗示的，按 C5 的 `[推测]` 标注记录（决策字段前置 `[推测]`），由查询侧降级使用。**纯猜测的一律不写**——臆造的决策比没有更糟，它会污染 `request-guard` / `code-review` 的判断。

**跳过条件**：
- 模块无明显非显然设计选择（纯 CRUD）→ 跳过，在 C0 标注「无关键决策，未记录决策记忆」
- 无任何证据支撑的决策（C5 未产出）→ 跳过，**不写空记录**

**降级**：ki 不可用时跳过（对齐 Step 8 降级约定）；决策清单在对话内输出，不阻塞专家落盘。

### Step 9：使用者视角验收（expert-audit）

专家/专题创建或合并补全完成后，自动调用 `expert-audit` skill 对本次产出的专家做独立验收（冷读测试 + 格式合规）：

- 报告中的 **P0 问题必须当场处理**（回到对应 Step 补调研/重写）后才算交付；P1/P2 随报告呈现由用户决定
- 与 Step 5/6 的关系：Step 5/6 是生成者自检，Step 9 是使用者视角独立验收，不可互相替代
- 分批创建时，每批次完成后对该批次产出验收一次，全部完成后不重复全量验收

## 验证（测试方式）

1. **契约自足性**（核心）：仅凭 `C0-使用总览.md` + `C1-能力契约.md` 能否脱离代码使用模块的核心能力
2. **代码示例真实性**：C1/C2/C3 中的代码示例是否为真实可运行代码（API 签名真实，环境可占位）
3. 抽查：`implementation/01-架构.md` 能否脱离代码独立读懂该业务模块的实现
4. 实现层各切面是否遵循 code-to-wiki 格式（R1-R7）
5. 契约层各文档是否遵循契约格式（CR1-CR9），无实现细节侵入
6. 无内容的切面是否标注「该模块无此项」而非编造
7. 核心切面（`C0` + `C1` + `implementation/01-架构.md` + `implementation/02-实现.md` + `implementation/06-测试.md`）是否必出且非空
8. 子专家（如有）是否各有完整结构，且无二级嵌套
9. 专题（如有）是否含 `topic.md` + `T0-专题总览.md`，且不含 `implementation/`
10. 专题下是否直接挂专家（不跳级），专家下可挂子专家（仅一级）
11. 分批创建时，INDEX.md 是否标注进度，全部完成后是否更新为正常格式
11.5. 模块有测试时，`06-测试.md` 是否必出且含测试可执行性（运行命令/环境依赖/已知失败）；`test/known-failures.md` 是否产出且切面级标注、每条含**执行方式**（运行命令）；**PROJECT.md 标注「❌ 无法运行 / 无测试」的服务跳过测试产出，不强制必出**
12. C1 参数行为语义：枚举/开关/边界敏感参数是否逐值说明可观察行为差异，纯透传参数是否保持简洁不膨胀
13. C4（如有数据落地）是否产出，消费方是否模块级概括、是否只写用途不写处理逻辑
14. 格式自检 R1–R7 + CR1–CR9 是否全部通过
15. 项目全局资产（如已创建 PROJECT.md）：是否包含项目信息/技术栈/架构形态/核心功能/核心服务清单（含代码位置/**测试可执行性**）/配套服务关系/架构图/数据流向图/运行环境
16. 创建前资格判断：目标模块是否领域专属且复杂度/规模达标；公共/横切知识是否被正确引导转存项目记忆而非建专家
17. 专题记忆（Step 8）：专家/专题落盘后是否必须写入一条 ki 专题记忆；是否 8 字段齐全、极简（≤200 字）、只存路标不复制专家本体
18. 模块间强关联（Step 8.5）：是否调用 strong-relation 识别并记录该模块与外部模块的强关联；写入 ki-search 时是否按功能模块分组（统一父分组「关联关系」+ 动态子分组）、`relation` 名称是否用 `-` 连接不含特殊字符、tags 是否统一为 `relation`
19. 接口信息（Step 8.3）：后端/后台核心模块是否识别暴露接口并调 ki-memory-write 接口信息策略写入；是否按子功能聚合（group=`接口信息/{功能模块名}`、relation=子功能名）、tags 是否统一为 `api`；纯内部模块是否跳过并在 C0 标注
20. 数据流（Step 8.4）：有数据落地的模块是否识别数据实体并调 ki-memory-write 数据流策略写入；是否实体粒度（group=`数据流/{功能模块名}`、relation=数据实体名）、tags 是否统一为 `data`；纯计算型模块是否跳过并在 C0 标注
21. 资产基线（Step 7）：INDEX.md 与 agent.md/topic.md 是否记录 git commit 基线；合并补全/重建后是否刷新为最新 commit（语义 = 资产覆盖的代码基线；expert-lookup 增量更新不刷新）
22. 关键决策（Step 8.6 + C5）：有证据支撑的决策是否产出 `C5-关键决策.md` 并调 ki-memory-write 决策记忆策略写入（group=`决策记录/{功能模块名}`、tags=`decision`）；每条决策是否含**证据来源**、**纯猜测内容是否已排除**、**低置信度的是否已前置 `[推测]`**、触发条件是否为可观测判据；是否**主动挖掘过**三类证据（设计文档 / git log / 注释）而非被动放弃；纯 CRUD / 无线索模块是否跳过并在 C0 标注
23. 代码索引回写（Step 7.5）：仓库有 `.fe-index/` 时是否重建对应端索引（后端 `backend-index --emit-tree`）使「专家资产」列出现；无索引 / 过期 / 前端（暂无探测）时是否跳过不阻塞；中文业务名未被脚本自动关联时是否人工指认

## 行为边界

- **创建前资格判断**：只创建"领域专属且复杂度/规模达标"的模块专家；公共/横切知识（工具库、代码风格约定、通用封装、基础设施）不建专家，推荐存入项目记忆；简单模块不建专家，直接读代码或 module-teach 讲解
- **ki 记忆格式硬约束**：写入 ki-search 的记忆内容（专题记忆、接口信息、数据流、决策记忆、强关联等）禁用 yaml 元数据（`---` frontmatter）和 `##`/`###` 等 md 标题、`|` 表格；统一纯文本 + `-` 列表，保证 ki-search 向量检索效率
- **决策不臆造**：`C5-关键决策.md` 与决策记忆优先记录有证据支撑的决策（文档明写 / commit 明说 / 注释明写）；无直接证据但**代码结构强烈暗示**的可记录，但决策字段须前置 `[推测]`（查询侧降级使用）；**纯猜测一律禁止**——臆造的决策进 ki 后会污染 request-guard / code-review 的判断，比没有更糟
- 一次一个业务模块，不批量；发现强依赖需先创建依赖专家时，按序逐一完成，不并行
- **强依赖检测**：扫描阶段自动发现强依赖模块；适合子专家则纳入拆分方案（无需确认），适合独立专家则暂停并询问用户是否先创建该依赖专家
- 专家目录用中文业务名；契约层文档在专家根目录用 C 前缀（`C0-使用总览.md` 等）；实现层文档在 `implementation/` 下用数字前缀；子专家在 `sub-experts/` 下；专题层文档用 T 前缀（`T0-专题总览.md` 等）+ `topic.md` 名片
- **三层递进**：契约层用于"使用"（根目录）；implementation/ 用于"导航"代码（子目录）；源代码用于"确认"。三者递进不竞争
- **子专家仅一级**：`sub-experts/` 下的专家不可再含 `sub-experts/`。若子域仍太大，应升级为专题
- **专题不可嵌套**：专题目录下不可再有专题目录。专题下直接挂专家，专家下可挂子专家
- **专题不产出 implementation/**：专题是组织层，具体实现由其下专家的 `implementation/` 承载
- **分批创建**：大模块/专题可分批创建，但必须先完成专题/父专家的架构文档作为共享输入；每批次完成后增量合并到 INDEX.md；全部完成后更新 INDEX.md 为正常格式
- **代码示例必须真实可运行**：API 签名真实，环境可占位；是使用方代码，不是被调用方实现代码，不是伪代码
- **参数行为语义分级**：行为敏感参数（枚举/开关/边界敏感）必写行为语义（判据：换个取值调用，使用者能观察到什么不同），纯透传参数一行说明，防契约膨胀
- **C4 黑盒消费视角**：只写数据去向、消费方（模块级概括）与业务用途，不写消费处理逻辑；消费方 >3 个时归纳；模块外消费方标注 `[基于引用扫描，未深入验证]`
- **旧格式迁移**：expert-team 合并补全时检测旧格式（实现层文件在根目录），自动移入 `implementation/`，并补建契约层骨架
- 不内置过期同步 / 重跑机制；文档为生成时快照；expert-lookup 可对契约层做受限增量更新；**Step 7.5 回写的是索引产物（`backend-index` 等的重建命令），不属于专家文档的同步机制**
- **资产基线 commit 只在创建与全量更新时刷新**：INDEX.md / agent.md / topic.md 记录的 git commit 为资产基线；合并补全/重建完成后刷新为最新 commit；expert-lookup 增量更新不刷新（防止掩盖未核对的代码变更）；过期检测由 expert-lookup 通过 diff 基线执行（Step 4.5）
- 章节来源以关键符号（类/方法/函数名）标注，不写行号；符号因重命名失效时由使用方回退全文搜索——属已知权衡；存量旧文档的行号标注不做迁移，重建时自然切换
- 不调用 `codetowiki` 格式校验工具；格式合规由 AI 按 R1–R7 + CR1–CR9 手动自检
- 不替代 code-survey 的设计前轻量调研
- **专题记忆必写**：专家/专题落盘后必须写一条"专题记忆"到 ki 记忆（Step 8 的 8 字段路标，非内置 memory、非知识本体）；**专家资产本体内容不写 memory**——避免与记忆、规则形成等量重复（双源漂移）
- **KB 原子可选**：详细知识原子按 ki-search 8 类白名单写 ki KB（本体，供 query 命中）；与 Step 8 专题记忆（路标）互补不重复
- **测试信息切面级标注**：测试可执行性按子专家/功能域各自标注（父专家汇总），不混级；模块无测试时在 `06-测试.md` 标注「该模块无测试」，不产出 `test/known-failures.md`
- **known-failures 只增不改历史**：已知失败条目由 code-review 阶段 8 / expert-lookup 追加与移除，不做历史归档；修复后移除对应条目；每条必含**执行方式**（运行该测试的完整命令），不可只有失败结论而无复现路径
- **测试不可运行跳过**：PROJECT.md 中标注目标服务「❌ 无法运行 / 无测试」时，跳过该服务的测试深挖（不产出 `06-测试.md` 深挖与 `test/known-failures.md`），在对应文档标注跳过原因，不在测试内容上死磕
- **PROJECT.md 是项目级共享资产**：粒度止于"服务 → 代码位置 → 一句话职责"，不写契约/实现细节（归各专家资产）；创建/使用专家时读取，发现全局信息变化时更新；由 expert-team 与 expert-lookup 共同维护

## 更多资源

- 各切面调研清单与 code-to-wiki 格式产出模板 + 契约层文档模板（C0/C1/C2/C3/C4）+ 子专家创建指引，参见 [reference.md](reference.md)
- 项目全局资产（PROJECT.md）模板**独立存储**，参见 [templates/PROJECT.md.template](templates/PROJECT.md.template)（创建时直接读取该文件，避免扫描 reference.md）
- 实现层格式源自 `code-to-wiki` skill 的规范（该 skill 不在本技能库中）；本 skill 已将所需规则完整内嵌为 R1–R7，自检不依赖外部文档与工具
- 查找并复用本 skill 生成的专家资产（含多专家加载 + 增量更新），参见 `use_skill("expert-lookup")`
- 记录本 skill 产出模块与外部的强关联（Step 8.5），调用 `use_skill("strong-relation")`
- 写专题记忆（Step 8）、接口信息（Step 8.3）、数据流（Step 8.4）与强关联（Step 8.5）的 ki 写入动作，统一走 `use_skill("ki-memory-write")`