backend-service-spec-skill

Backend Service Spec Skill

用于把单服务、跨服务、业务域、通信链路、事实需求五类梳理动作统一成一套可复用知识技能。

0. 何时使用

当用户出现以下目标时，使用本技能：

• 想梳理旧系统、微服务、平台型仓库的代码总图
• 想做跨服务调用链、接口链路、消息链路排查
• 想把零散服务文档上卷成“域 -> 服务 -> 规范”三层知识
• 想对单个高价值服务做纵切梳理
• 想在历史 PRD 缺失时，按功能模块从代码事实抽取当前系统事实需求
• 想把代码知识沉淀成团队可复用的中央知识库，而不是停留在一次对话里

如果只是实现功能、修 Bug、写测试，而不是做知识梳理，不优先使用本技能。

1. 核心原则

始终遵守以下约束：

• 严格按代码事实输出，不把猜测写成事实
• 先索引，后正文：先建立地图，再沉淀稳定知识页
• Codemap 是索引层，不是最终知识库正文
• 业务域页的价值是“上卷整理”，不是重复抄写服务页
• 跨服务链路必须区分同步调用、异步消息、定时/补偿、实时通道
• 事实需求抽取必须区分当前代码事实、单边线索、数据线索和待人工确认项
• 无法闭环验证的内容必须显式标注证据等级，不能伪装成已确认
• 如果只看到单边依赖、单边契约、单边 producer/listener，不得直接写成双边已确认闭环
• 在进入正式梳理前，先做 workspace 范围识别

2. 执行前置：workspace 范围识别

在运行核心功能前，先用最小成本判断当前 scope 属于哪一种：

• single-system: 单一系统 / 单一运行时家族
• service-family: 同一家族、多服务协作
• multi-system-workspace: 多套系统共存的工作区

最少要回答三个问题：

1. 当前 scope 是单系统、服务家族，还是多系统并存工作区
2. 本轮目标是全景索引、关键链路、还是稳定知识页
3. 当前产物应该落在 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>服务总图.md
• mydocs/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，再做业务域梳理