| name | backend-service-spec-skill |
| description | 用于旧系统、微服务、平台型仓库的代码知识梳理与中央知识库沉淀。统一支持跨服务 create_codemap、跨服务业务域梳理、crate_router_map、单服务纵切梳理、事实需求抽取。强调严格按代码事实输出，并显式区分 scope、参数清晰度、链路类型、需求证据等级与证据闭环状态。 |
Backend Service Spec Skill
用于把单服务、跨服务、业务域、通信链路、事实需求五类梳理动作统一成一套可复用知识技能。
0. 何时使用
当用户出现以下目标时，使用本技能：
- 想梳理旧系统、微服务、平台型仓库的代码总图
- 想做跨服务调用链、接口链路、消息链路排查
- 想把零散服务文档上卷成“域 -> 服务 -> 规范”三层知识
- 想对单个高价值服务做纵切梳理
- 想在历史 PRD 缺失时，按功能模块从代码事实抽取当前系统事实需求
- 想把代码知识沉淀成团队可复用的中央知识库，而不是停留在一次对话里
如果只是实现功能、修 Bug、写测试，而不是做知识梳理，不优先使用本技能。
1. 核心原则
始终遵守以下约束：
- 严格按代码事实输出，不把猜测写成事实
- 先索引，后正文：先建立地图，再沉淀稳定知识页
- Codemap 是索引层，不是最终知识库正文
- 业务域页的价值是“上卷整理”，不是重复抄写服务页
- 跨服务链路必须区分同步调用、异步消息、定时/补偿、实时通道
- 事实需求抽取必须区分当前代码事实、单边线索、数据线索和待人工确认项
- 无法闭环验证的内容必须显式标注证据等级，不能伪装成已确认
- 如果只看到单边依赖、单边契约、单边 producer/listener，不得直接写成双边已确认闭环
- 在进入正式梳理前，先做 workspace 范围识别
2. 执行前置：workspace 范围识别
在运行核心功能前，先用最小成本判断当前 scope 属于哪一种：
single-system: 单一系统 / 单一运行时家族service-family: 同一家族、多服务协作multi-system-workspace: 多套系统共存的工作区
最少要回答三个问题：
- 当前 scope 是单系统、服务家族，还是多系统并存工作区
- 本轮目标是全景索引、关键链路、还是稳定知识页
- 当前产物应该落在
mydocs/ 的哪一层
如果识别为 multi-system-workspace：
- 第一轮优先
create_codemap: mode=service_landscape
- 先切 family，再做闭环链路
- 不要直接上
build_domain_map
详见：references/workspace-classification.md
3. 核心功能
3.1 跨服务 create_codemap
用途：
- 在多服务、微服务、平台仓库中生成跨服务 CodeMap
- 继承 sdd-riper 的
create_codemap 思想，但升级为“服务间视角”
- 不只看单项目结构，还看服务注册、调用方向、依赖关系、上下游角色、关键链路
适用输入：
create_codemap: mode=service_landscape, scope=<系统名或服务群>, goal=<梳理目标>
也兼容：
create_codemap: mode=project, scope=<项目名>, goal=<输出项目总图与核心流程>
create_codemap: mode=feature, scope=<关键功能或链路>, goal=<梳理核心入口与主链路>
create_codemap: mode=service_chain, scope=<跨服务业务链>, goal=<梳理服务级链路>
输出重点：
- 服务清单
- 服务职责边界
- 服务间调用关系
- 入口与出口
- 同步/异步链路索引
- 外部系统依赖
- 风险热点
- 代码证据来源
- workspace 范围判断
默认产物：
mydocs/codemap/YYYY-MM-DD_hh-mm_<name>服务总图.mdmydocs/codemap/YYYY-MM-DD_hh-mm_<name>链路地图.md
详情模板见 references/codemap-modes.md
3.2 跨服务业务域梳理
用途：
- 把零散服务知识提升为团队可复用的上下文层
- 形成“域 -> 服务 -> 规范”三层知识结构
- 支持中央仓库、Wiki、OpenSpec、旧系统知识库共建
适用输入：
build_domain_map: scope=<系统或服务群>, goal=<按业务域梳理>
输出规则：
- 域层只做上卷整理，不重写服务页全文
- 域层必须区分：强事实承载服务、线索级关联服务、仍待补证关系
- 规范层必须区分：
code-fact-summary 与 team-proposed-standard
- 最好先完成关键服务的
service_deep_dive，再做业务域梳理
详情模板见 references/domain-layering.md
3.3 crate_router_map
用途：
- 梳理请求在跨服务之间的完整通信路径
- 同时覆盖同步与异步通信
- 支持接口级和链路级视角
- 支持跨团队、跨技术栈系统
说明：
- 按用户要求，保留命令名
crate_router_map
- 也兼容别名
create_router_map
适用输入：
crate_router_map: scope=<业务链路或入口>, goal=<梳理跨服务通信链路>
输出必须拆开：
- 同步调用链
- 异步消息链
- 定时/补偿链
- 实时通道链（如存在）
证据等级至少区分：
fact-closedfact-send-sidefact-receive-sidecontract-visibleclue
详情模板见 references/router-map.md
3.4 单服务纵切梳理
用途：
- 对单个高价值服务做系统性纵切
- 形成可长期复用的服务知识页集合
适用输入：
service_deep_dive: scope=<服务名>, goal=<梳理高价值服务>
推荐输出：
overview.mdentrypoints.mddependencies.mdmq.mdsources.md
大服务第二轮按需补：
api.mdcall-chain.mdexternal-dependencies.mdroute-map.mdtopic-detail.mdws.mdruntime-config.mdrisk-and-hotspots.md
其中 api.md 必须显式标注参数清晰度分层：
- 路径级
- 签名级
- DTO 字段级
- payload/schema 级
详情模板见 references/service-deep-dive.md
3.5 requirement_fact_map
用途：
- 在历史 PRD、需求评审记录缺失时，从当前代码事实抽取“系统事实上已经支持了哪些需求”
- 按功能模块沉淀项目需求知识库
- 把接口、页面、任务、消息、配置、数据对象、链路证据上卷为事实需求
- 显式区分已闭环需求、单边事实、数据线索、命名线索和待人工确认项
适用输入：
requirement_fact_map: scope=<系统、服务群、功能模块或关键链路>, goal=<按功能模块抽取当前事实需求>
输出重点：
- 功能模块识别依据
- 模块级事实需求列表
- 需求到代码证据矩阵
- 需求证据等级
- 关联 codemap / service_deep_dive / routermap / domain map
- 未闭环需求与人工确认项
默认产物：
mydocs/requirements/index.mdmydocs/requirements/modules/<module>.mdmydocs/requirements/evidence/requirement-evidence-matrix.mdmydocs/requirements/gaps/requirement-gaps.md
详情模板见 references/requirement-fact-extraction.md
4. 推荐工作流
4.1 多系统工作区首轮
classify_workspace -> create_codemap(service_landscape) -> 按 family 拆 scope -> 选关键服务做 service_deep_dive -> 对关键链路做 crate_router_map -> 最后再评估 build_domain_map
4.2 旧系统中央知识库建设
先做 create_codemap -> 再做关键链路 crate_router_map -> 再做关键服务 service_deep_dive -> 按需做 requirement_fact_map -> 服务事实和事实需求稳定后再做 build_domain_map
4.3 单服务起步
先做 service_deep_dive -> 若发现明显上下游协作，再补 crate_router_map / build_domain_map
5. 事实分层规则
输出任何文档时，优先区分：
- 代码中直接确认
- 由多处代码交叉确认
- 只看到发送侧 / 接收侧 / 契约侧，但未闭环
- 仅为命名、配置、兄弟仓、topic、handler 等线索
- 团队建议或待定规范
禁止：
- 把命名推测写成业务定义
- 把单边 Feign 依赖写成双边已确认闭环
- 把 MQ producer 存在写成 listener 必然存在
- 把 listener 存在写成 producer 已确认
- 把签名级清晰写成字段级已明确
- 把多系统工作区误写成单系统
- 把代码线索补写成历史 PRD 或产品意图
- 把单服务内部能力写成端到端事实需求
- 把
clue、fact-data-only、fact-entry-only 直接写成已确认需求
6. 产物分层
mydocs/
codemap/
services/
domains/
requirements/
routermap/
diagrams/
context/
specs/
validation/
index/
使用建议：
mydocs/codemap/：地图索引层mydocs/services/：单服务纵切知识页mydocs/domains/：业务域上卷页mydocs/requirements/：按功能模块沉淀当前系统事实需求、证据矩阵和需求缺口mydocs/routermap/：跨服务通信链路层mydocs/diagrams/：图产物层，统一放 Markdown 内嵌 Mermaid 的架构图、调用关系图、依赖图、时序图mydocs/context/：上下文资料与补充材料mydocs/specs/：Research / Plan / Review 等过程文档mydocs/validation/：闭环验证、未闭环清单、质量检查页mydocs/index/：总索引、导航页与汇总入口
7. 必看引用
references/workspace-classification.mdreferences/codemap-modes.mdreferences/router-map.mdreferences/domain-layering.mdreferences/service-deep-dive.mdreferences/requirement-fact-extraction.mdreferences/central-repo-conventions.mdreferences/quality-checklist.mdreferences/usage-guide.mdreferences/output-templates.mdreferences/diagram-output-guidelines.mdreferences/mermaid-safety-checklist.zh-CN.md
8. 输出风格
- 先给结论，再给结构
- 以事实为主，不写推测性业务发散
- 文件命名稳定，可长期复用
- 目录适合中央仓库团队协作
- 文档默认面向“团队知识复用”，不是一次性分析笔记
- 图产物默认使用
Markdown + Mermaid，图片只作为派生结果，不替代源文件
- 图产物默认优先内嵌到对应正文；只有在需要跨文档复用、独立高频更新、集中导出管理，或用户明确要求图文分离时，才拆到
mydocs/diagrams/
- 如果图拆到
mydocs/diagrams/，正文里仍需保留简短说明和直接链接，保证上下文可读
- Mermaid 节点标签优先写“角色语义”或“动作语义”，不要默认把
method(arg) 这类方法签名直接塞进节点
- 精确的方法名、DTO 名、枚举名、Redis key、topic 名等细节保留在图下正文说明中，图节点本身优先保证兼容渲染
- 如果节点文本需要换行，优先拆成短语，不要在同一节点里叠加括号参数、引号、复杂 JSON 和多层标点
- 图产物交付前，按
references/mermaid-safety-checklist.zh-CN.md 做最后一轮自检
7.5 新增规则页
为弥补长期中央仓库维护能力，本技能新增三份规则型参考页：
references/knowledge-lifecycle.mdreferences/incremental-update-policy.mdreferences/workflow-state-model.md
使用时建议：
- 先按
workspace-classification.md 判断范围
- 再按
knowledge-lifecycle.md 判断优先读取 current 还是 draft
- 再按
incremental-update-policy.md 决定增量补齐还是重建
- 最后用
workflow-state-model.md 判断当前处于哪种执行状态
