expert-team
派多专家子 agent 并行深挖单个业务模块,产出"契约层(黑盒使用)+ 实现层(白盒技术)"两层资产的专家包(落 .module-experts/),大模块可拆子专家或专题。触发:"掌握这个模块"、"深度分析 xxx 模块"、"梳理这个模块"、"建模块专家团"、"module expert team"。
SKILL.mdskills/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 共同维护 |
核心原则
- 业务专家为轴:
.module-experts/子目录是业务专家(中文名),不是技术切面 - 单模块深挖:一次只针对一个业务模块,不泛化到全项目
- 三层递进:契约层在根目录(用于"使用");实现层在
implementation/(用于"导航"代码);源代码用于"确认"。三者递进:用 → 导航 → 确认 - 按需切面:根据模块性质选择产出哪些实现层 Wiki 文档,不硬凑空文档
- 知识库优先:先查 ki(项目记忆 → KB),已知不重复读
- 并行专家:实现层切面 ≥ 2 时用 task-dispatch 并行
- 实现层格式对齐 code-to-wiki:R1–R7 手动自检
- 契约层格式独立:CR1-CR9 自检,不引用实现代码行号
- 真实代码示例:契约层代码示例必须是真实可运行的使用方代码(API 签名真实,环境可占位),帮助 AI 直接理解如何使用
- 子专家按需拆分:大模块按功能拆子专家(仅一级),不强行一个专家兜全部
- 专题按需创建:超大模块(如 > 500 源文件)且需要三级结构时创建专题,专题不可嵌套;中等模块用专家+子专家即可,不强行升专题
- 分批创建:大模块/专题无法一次创建完成时,按功能子域分批,专题/父专家的架构文档先行作为共享输入,每批次完成后增量合并
- 不编造:无内容则标注「该模块无此项」,不凑话
- 强依赖检测:构建专家时若发现目标模块强依赖另一模块,自动评估适合创建子专家还是独立专家,后者需用户确认
- 测试信息必采集:模块有测试时必须采集测试信息(位置/框架/运行命令/环境依赖/已知失败),产出
06-测试.md(必出)与test/known-failures.md(有测试时必出),切面级标注测试可执行性;PROJECT.md 标注「❌ 无法运行 / 无测试」的服务按「测试不可运行跳过」规则不产出测试文档 - 专家资格判断:只创建"领域专属且复杂度/规模达标"的模块专家;公共/横切知识(工具库、代码风格约定、通用封装、基础设施)不建专家,推荐存入项目记忆;简单模块不建专家,直接读代码或 module-teach 讲解
- 专题记忆必写:专家/专题落盘后必须写一条 ki 专题记忆(Step 8 的 8 字段路标),解决"资产闲置"——记忆存路标不存本体,让 AI 未加载专家前也能检索到关键入口
- 模块间强关联必记:专题记忆写入后调用
strong-relationskill(Step 8.5)识别该模块与外部模块的强关联(契约/业务耦合),写 ki 动作下沉到ki-memory-write强关联策略,解决 code review / 修改时"改了 A 不知道必须连带改 B"的风险 - 接口信息按需记录:专家模块是后端模块(暴露 API)或后台核心模块(数据接收/消费)时,Step 8.3 识别其暴露接口,调
ki-memory-write接口信息策略写入 ki(按子功能聚合 +tags="api",group=接口信息/{功能模块名}),供接口检索精确命中;纯内部无对外接口的模块跳过 - 数据流按需记录:专家模块有数据落地(DB/消息/缓存/文件)时,Step 8.4 识别其数据实体,调
ki-memory-write数据流策略写入 ki(实体粒度 +tags="data",group=数据流/{功能模块名}),供数据问题排查精确命中;纯计算型无数据落地的模块跳过 - 关键决策按需记录且禁止臆造:模块存在关键设计选择时,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 是否可用:
如果可用且本次创建未经过路由:先用它完成三步检查(证据门 → 覆盖阶梯 → 载体选择):
- 证据门未过(仅一次性查阅需求,无重复使用/交接诉求)→ 不建专家包,直接回答或建议用 module-teach 讲解
- 覆盖阶梯命中已有资产(
.module-experts/中已有相关专家)→ 走 expert-lookup 复用或本流程的「合并补全」,不重建 - 路由结论为"新建专家包"时,继续下方 3 的专家创建资格判断
如果不可用:至少自检一次:该模块是否会被反复使用/排查/交接?若只是一次性理解需求,module-teach 或直接阅读更合适;自检通过(会被反复使用/排查/交接)→ 继续下方 3 的专家创建资格判断
专家创建资格判断(领域专属 × 复杂度/规模):路由结论为"新建专家包"后,先确认该模块是否够格创建专家。专家资产包是重载体(多子 agent 深挖 + 双层文档),只应为"领域专属且复杂度较高"的模块创建:
判定维度 ✅ 符合(推荐创建专家) ❌ 不符合(不创建专家) 领域专属性 专属于某业务功能领域(告警 / 支付 / 权限 / 日志查询等),有明确业务语义,仅服务特定业务 公共 / 横切知识:工具库(utils / helpers / commons)、通用封装、代码风格约定、通用算法、基础设施(第三方库 / 框架 / 标准库) 复杂度 逻辑复杂:多层调用链 / 状态机 / 并发异步 / 异常分支多 / 数据落地多方消费 逻辑简单:单文件、无复杂业务逻辑、纯配置 / 纯数据 代码规模 代码量较大:源文件较多(如 ≥ 5 个)或实现行数多(相对项目整体规模判断) 代码量小:少量文件、仅几个工具函数 边界指引(处理判定维度交叉的中间案例):
- 规模小但逻辑显著复杂(如 3 个文件含状态机 / 并发 / 长调用链)→ 可建专家,复杂度优先于规模
- 规模大但纯样板代码(CRUD 模板化 / 低知识密度)→ 不建全量专家,降级为子专家或仅轻量记录
- 模块内的公共子包(如告警模块内
utils/)→ 归入所属业务专家范围,不单独建专家;确属全项目横切的独立包才触发"公共知识"判定
判定结论:
- 领域专属 且(复杂度高 或 规模大)→ 推荐创建专家,继续 Step 0
- 公共 / 横切知识 → 不创建专家,推荐存入项目记忆,向用户说明理由后停止创建流程
- 领域专属但规模小 / 逻辑简单 → 不创建专家,直接读代码或建议用 module-teach 讲解,向用户说明理由后停止创建流程
- 用户坚持要建 → 提示资产成本与更轻替代(项目记忆 / module-teach)后按用户意愿执行
项目全局资产检查:检查
.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 个
分批策略
按功能子域/专家分批——每批次产出一个专家或子专家的完整资产:
- 先完成专题/父专家的架构文档(
T0-专题总览.md或implementation/01-架构.md),作为所有批次的共享输入- 专题:先产出
topic.md+T0-专题总览.md(含跨专家架构图 + 专家导航) - 父专家:先产出
agent.md+C0-使用总览.md+implementation/01-架构.md
- 专题:先产出
- 按专家/子专家划分批次,每批次一个独立 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 先合成专题级资产:
- 产出
topic.md:专题名片——一句话职责 + 专家清单 + 专题就绪状态 - 产出
T0-专题总览.md:- 专题能力清单:从各专家的架构分析中提炼专题级能力
- 专题边界:专题做什么、不做什么
- 跨专家架构图(Mermaid):展示专题下各专家的依赖关系、数据流转、调用链
- 专家导航:列出专题下所有专家及其职责、契约层就绪状态
- 按需产出
T1-跨专家契约.md:仅当专题有跨专家的统一公开 API 时产出
专题不产出
implementation/——具体实现由其下专家的implementation/承载。
Step 3.5:提炼契约层(主 agent,在实现层产出后)
实现层各切面文档产出后,主 agent 基于实现层分析结果提炼契约层。需跨切面综合判断哪些是公开能力,确保一致性和完整性。子专家各自独立提炼契约层。
- 识别公开能力:从
implementation/02-实现.md(关键类与函数)、implementation/05-接口.md(对外入口)中提取所有公开类/方法 - 产出
C0-使用总览.md:- 能力清单:从架构职责提炼"模块能干什么"
- 能力边界:从架构分析提炼"不做什么"
- 已知问题与常见坑:从实现层各切面的"风险点""边界条件"提炼,格式:现象/触发条件/正确做法
- 子专家导航(如有子专家):列出子专家名 + 一句话职责 + 各自覆盖的功能子域
- 产出
C1-能力契约.md:- 每个公开类/方法:用途 / 参数(含类型与行为语义)/ 返回 / 异常 / 约束 / 真实可运行代码示例
- 参数行为语义分级:枚举/开关/边界敏感参数逐值说明可观察行为差异(如
mode=fast跳过重复校验);数值参数标单位与边界值行为(如timeout=0表示永不超时);纯透传参数一行说明即可,防止 C1 膨胀 - 契约来源:标注类名/方法签名(非行号)
- 严格黑盒:不写算法、内部结构、私有方法、DB schema;约束可写但不解释"为什么"
- 代码示例:从代码库中找到真实的调用方代码(如测试文件中的调用、其他模块中的调用),或基于实际 API 编写可运行示例(API 签名真实,环境初始化可注释占位)。不是伪代码
- 覆盖度声明(超大模块采样时):C1 头部标注"本次契约基于采样 X/N 文件,以下为已覆盖的公开方法。未采样文件中可能存在未记录的公开方法"
- 按需产出
C2-使用流程.md:- 识别需要多方法协作的常见业务目标
- 每条:业务目标 / 调用顺序 / 事务边界 / 预期结果 / 错误处理 / 真实可运行代码示例
- 无多方法协作场景时不产出,在 C0 标注「暂无使用流程,参照 C1 直接调用」
- 按需产出
C3-代码示例-{topic}.md:- 当 C1/C2 中的内联示例不足以覆盖完整使用场景时,将完整、可运行的代码示例拆分到独立文件
- 文件名用 topic 区分:
C3-代码示例-基础用法.md、C3-代码示例-高级场景.md等 - 每个示例标注:目标 + 涉及的契约条目 + 完整代码 + 关键说明
- 产出
C4-数据流向与消费.md(有数据落地时必出):- 从 Step 1 记录的数据落地点出发,每类核心数据实体一条:来源接口(本模块哪些公开方法产生/写入)/ 去向(表/队列/文件/事件,概括级)/ 消费方(反向查找谁读取,按模块或功能级概括,>3 个时归纳)/ 业务用途(一句话说清"用来干嘛")
- 模块外消费方基于引用扫描确定时标注
[基于引用扫描,未深入验证];未发现消费方时标注「未发现模块内消费方,疑似供外部系统使用」,不编造 - 黑盒边界:只写数据用途,不写消费方的处理逻辑(CR9)
- 纯计算型模块(无数据落地)不产出,在 C0 标注「无持久化数据,未产出 C4」
- 产出
C5-关键决策.md(有决策线索时必出):- 每条决策含:决策(含关键参数/阈值)/ 背景约束 / 被否决方案及否决理由 / 重新评估触发条件(须为可观测判据,写不出写「无」)/ 关联代码 / 证据来源
- 证据门(硬约束):优先记有证据的决策——证据限三类:① 设计文档 / ADR 明写 ② commit message / PR 描述明说 ③ 代码注释 / docstring 明写
- 先找再判:三类证据需主动挖掘(查项目设计文档目录含 design-craft 的「关键决策点」表 →
git log -S{关键符号}/ PR 描述 → 关键实现处注释),不被动等待;老模块常三类全无,此时按下方[推测]分级处理,不要直接放弃整条决策 [推测]标注(对齐debug既有约定):无直接证据但代码结构强烈暗示的(如"明显是轮询实现且全模块无 webhook 代码")→ 可记录,决策字段前置[推测],证据来源写「无直接证据,基于{具体结构}推断」;纯猜测无任何结构支撑的禁止记录- 红线:字段空缺写「无」,不因字段空缺而编造备选方案与否决理由(标注"这是推测"允许,编造"曾考虑某方案但因 X 否决"禁止)
- 被否决方案:事后场景常拿不到备选,允许写「无」
- 无任何线索(既无证据也无结构暗示)→ 不产出 C5,在 C0 标注「未发现可追溯的关键决策」
- 证据已失效(设计文档已删、commit 被 squash)但决策可确认的 → 仍记录,证据来源注明失效情况
- 模块无公开类/方法(纯配置型/纯数据型)时: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 完成,不在此重复。
- 审查范围:专家根目录下所有文件,包括:
agent.md(专家名片)C0-使用总览.md、C1-能力契约.md、C2-使用流程.md、C3-代码示例-*.md、C4-数据流向与消费.md(契约层)implementation/下所有实现层文档
- 子专家:每个子专家各自独立审查
- 修复闭环:auto-review 发现的问题必须修复后才能进入 Step 7
- 复杂场景:若 auto-review 判断属于复杂场景并调用了 challenger skill,必须等 challenger 的质疑结果出来后一并处理
- 达上限兜底:若 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 是使用者视角独立验收,不可互相替代
- 分批创建时,每批次完成后对该批次产出验收一次,全部完成后不重复全量验收
验证(测试方式)
- 契约自足性(核心):仅凭
C0-使用总览.md+C1-能力契约.md能否脱离代码使用模块的核心能力 - 代码示例真实性:C1/C2/C3 中的代码示例是否为真实可运行代码(API 签名真实,环境可占位)
- 抽查:
implementation/01-架构.md能否脱离代码独立读懂该业务模块的实现 - 实现层各切面是否遵循 code-to-wiki 格式(R1-R7)
- 契约层各文档是否遵循契约格式(CR1-CR9),无实现细节侵入
- 无内容的切面是否标注「该模块无此项」而非编造
- 核心切面(
C0+C1+implementation/01-架构.md+implementation/02-实现.md+implementation/06-测试.md)是否必出且非空 - 子专家(如有)是否各有完整结构,且无二级嵌套
- 专题(如有)是否含
topic.md+T0-专题总览.md,且不含implementation/ - 专题下是否直接挂专家(不跳级),专家下可挂子专家(仅一级)
- 分批创建时,INDEX.md 是否标注进度,全部完成后是否更新为正常格式
11.5. 模块有测试时,
06-测试.md是否必出且含测试可执行性(运行命令/环境依赖/已知失败);test/known-failures.md是否产出且切面级标注、每条含执行方式(运行命令);PROJECT.md 标注「❌ 无法运行 / 无测试」的服务跳过测试产出,不强制必出 - C1 参数行为语义:枚举/开关/边界敏感参数是否逐值说明可观察行为差异,纯透传参数是否保持简洁不膨胀
- C4(如有数据落地)是否产出,消费方是否模块级概括、是否只写用途不写处理逻辑
- 格式自检 R1–R7 + CR1–CR9 是否全部通过
- 项目全局资产(如已创建 PROJECT.md):是否包含项目信息/技术栈/架构形态/核心功能/核心服务清单(含代码位置/测试可执行性)/配套服务关系/架构图/数据流向图/运行环境
- 创建前资格判断:目标模块是否领域专属且复杂度/规模达标;公共/横切知识是否被正确引导转存项目记忆而非建专家
- 专题记忆(Step 8):专家/专题落盘后是否必须写入一条 ki 专题记忆;是否 8 字段齐全、极简(≤200 字)、只存路标不复制专家本体
- 模块间强关联(Step 8.5):是否调用 strong-relation 识别并记录该模块与外部模块的强关联;写入 ki-search 时是否按功能模块分组(统一父分组「关联关系」+ 动态子分组)、
relation名称是否用-连接不含特殊字符、tags 是否统一为relation - 接口信息(Step 8.3):后端/后台核心模块是否识别暴露接口并调 ki-memory-write 接口信息策略写入;是否按子功能聚合(group=
接口信息/{功能模块名}、relation=子功能名)、tags 是否统一为api;纯内部模块是否跳过并在 C0 标注 - 数据流(Step 8.4):有数据落地的模块是否识别数据实体并调 ki-memory-write 数据流策略写入;是否实体粒度(group=
数据流/{功能模块名}、relation=数据实体名)、tags 是否统一为data;纯计算型模块是否跳过并在 C0 标注 - 资产基线(Step 7):INDEX.md 与 agent.md/topic.md 是否记录 git commit 基线;合并补全/重建后是否刷新为最新 commit(语义 = 资产覆盖的代码基线;expert-lookup 增量更新不刷新)
- 关键决策(Step 8.6 + C5):有证据支撑的决策是否产出
C5-关键决策.md并调 ki-memory-write 决策记忆策略写入(group=决策记录/{功能模块名}、tags=decision);每条决策是否含证据来源、纯猜测内容是否已排除、低置信度的是否已前置[推测]、触发条件是否为可观测判据;是否主动挖掘过三类证据(设计文档 / git log / 注释)而非被动放弃;纯 CRUD / 无线索模块是否跳过并在 C0 标注 - 代码索引回写(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-wikiskill 的规范(该 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")