expert-team

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

SKILL.md

GitHub

模块专家团

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/ 汇总各子专家条目)
  • 格式:
# 已知单元测试失败:{专家名}

## {切面/子专家名}

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

- **执行方式**:{运行该测试的完整命令,如 `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。

每篇实现层文档的骨架

# {标题}
**本文引用的文件**
- [模块名](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 中「契约层文档模板」章节。

契约层与实现层的关系

  • 三层递进:契约层在根目录(用于"使用");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,直接读取填充,无需扫描 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 创建计划预览的一部分一并确认:

## 分批创建计划

**总批次**:{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 的全部判断汇总为一份创建计划直接输出,用户确认后才实施。零散确认(名称、子专家、专题、分批)全部收敛到这一次确认中。

## 专家创建计划

**专家名(自动派生)**:{中文专家名或专题名}(由 {模块根} 的业务功能派生)
**模块范围**:{模块根路径},共 {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)+ 同批切面清单;调研并记录文件路径与关键符号(类/方法/函数名);严格遵循 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 中「契约层文档模板」章节。

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
  • 项目全局资产(PROJECT.md)模板独立存储,参见 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")