派出多专家子 agent 并行深挖单个业务模块，产出含"契约层（黑盒使用文档）+ 实现层（白盒技术文档）"两层资产的"业务专家"包，供后续直接使用或导航代码。大型模块可按功能拆分为子专家，超大模块可创建专题（专题→专家→子专家三级结构），大模块支持分批创建。创建前输出计划预览（专家名由业务功能自动派生、含匹配关键词），用户确认后实施。落盘到 .module-experts/。触发短语："掌握这个模块"、"深度分析 xxx 模块"、"梳理这个模块"、"建模块专家团"、"module expert team"，或需要对某业务模块建立深度、持久、可复用的领域专家资产时。
Scanned 9/20/2026
Install to Claude Code
Skills Directorynpx -y skills add HACK-WU/skills --skill expert-team --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Expert Team?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/hack-wu-expert-team)More formats (shields.io, HTML) on the badges page.
---
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 自行判断，**含测试信息采集：测试位置/框架/运行命令/环境依赖/已知失败**）→ 评估是否建专题/拆子专家 → 评估是否分批 → 输出创建计划预览（专家名自动派生 + 匹配关键词，用户确认后实施）→ 知识库优先查 → 派出多专家子 agent 并行产出实现层 Wiki 文档（`06-测试.md` 必出，含测试可执行性）→ 主 agent 提炼契约层（含真实代码示例）→ 合成专家入口（含测试状态）→ 校验 → auto-review 评估审核+优化 → 落盘到 `.module-experts/{中文业务专家名或专题名}/` → **必须构建专题记忆（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 是单业务模块深挖、持久落盘 |
| 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 自行判断）
主 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 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 标注
## 行为边界
- **创建前资格判断**：只创建"领域专属且复杂度/规模达标"的模块专家；公共/横切知识（工具库、代码风格约定、通用封装、基础设施）不建专家，推荐存入项目记忆；简单模块不建专家，直接读代码或 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 可对契约层做受限增量更新
- **资产基线 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")`
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
