接盘不熟的业务线，我从生产代码反查业务规则

业绩不好看的时候，团队最先动的就是人。产品、研发、测试一批批走，剩下的人每人手里都压着几条没完全摸透的业务线。文档本来就不全，交接再一断，你对着一个系统，既不知道它为什么这么设计，也不知道现在到底发生了什么。

一开始我也按老办法来：翻需求文档、看接口、追着老同事问。但老同事也未必全知道——尤其是那些改了很多轮的规则，早就不在文档里了，也没人能讲清楚。

后来我发现，真正靠得住的来源只有一个：生产环境的项目代码。规则再怎么漂移，最后都会落进代码、SQL、配置和定时任务里。

问题变成：怎么把这一堆代码，变成产品、测试能读、能追、能复现的业务规则。

这是什么

codebase-graph-prd-rules 是一组互补的 AI 代理 Skill，把项目源码整理成供非开发者（产品、运营、QA）阅读的、可追溯的详细业务规则文档。

两个 Skill 共享同一方法论与证据边界——先建 Graphify 代码图谱，用图谱定位入口与调用链路，再逐条用真实源码、SQL/XML 与配置确认规则。图谱负责导航，源码负责确认。两者都不改动业务系统——只分析和写文档。

两个 Skill 覆盖不同粒度：

** codebase-graph-business-rules ** —— _全项目_业务规则。扫描整个项目、建图，产出一份集成文档：模块地图、入口、实体/状态、数据与配置、端到端链路、逐模块规则表、测试范围与追溯索引。
** codebase-graph-module-rules ** —— _单模块_深挖。给定功能描述或模块名，追溯一个模块的规则、排序/限额/状态/流程，产出测试导向的专项文档。

为什么需要

常规做法（反例）	本项目
规则只存在开发者脑中或零散注释里	成文、可源码验证的规则文档
排序被含糊地叫成“优先级”	拆分资格过滤 vs 排序键 vs 后置过滤/终止
无证据，无法核查	每条规则带 `src/...:line` 来源
图谱推断边被当成事实	图谱只作导航；源码确认事实
静态检查通过被说成已验证	静态与运行行为分开、如实报告
模块多条链路在末尾重复追加	同一模块的分支合并到同一节

它解决 5 个工程痛点：

可追溯 — 每条规则记录来源文件+行号，便于审计与变更。
非开发者可读 — 表格与 Mermaid 图解释业务含义，而不是堆类名。
证据诚实分层 — EXTRACTED / INFERRED / 源码确认分开报告。
测试就绪 — 每条关键规则映射到可执行的 P 0/P 1 测试断言矩阵。
安全 — 拒绝未授权的生产动作、绝不输出凭据。

核心概念

1. 图谱导航，源码确认

图谱负责定位入口与候选链路（触发 → 编排 → 决策 → 存储/日志 → 外部结果）。每条规则再用源码、SQL/XML、配置确认——INFERRED 图谱边只是线索，不是事实。

2. 三层规则

业务规则分为三层，绝不混为一谈：

资格过滤 —— 候选是否具备进入资格？
候选排序 —— 谁先处理（字段、方向、null 规则、并列行为）？
运行时控制 —— 限额、去重、并发、发送、失败回滚。

排序必须写明字段、方向、null/空值规则、并列行为、后置过滤与最终终止条件——以实际比较器或 SQL ORDER BY 为准，而非假设。

3. 证据等级

等级	可写结论	不可写结论
源码/SQL/配置已复核	当前实现的条件、顺序、字段、调用与副作用	外部系统最终结果
图谱 EXTRACTED	可作为定位和关系线索	未读实现的业务规则
图谱 INFERRED	标为待源码确认的候选关系	已确认调用或业务合同
注释/日志/字段名	补充意图或待确认项	独立事实
运行结果	该环境和输入下的观测	未覆盖场景的普遍保证

4. 只分析，不执行

两个 Skill 只分析和写文档。未经显式授权，拒绝调用真实下游服务、发送真实线索、改动数据或运行生产行为——并如实报告哪些_未执行_。

仓库结构

codebase-graph-prd-rules/
├── README.md                        # 本说明（英文）
├── README.zh-CN.md                  # 本说明（中文）
├── LICENSE                          # MIT
├── .gitignore                       # 排除 macOS/Python/IDE 产物
├── .gitattributes                   # * text=auto eol=lf
├── codebase-graph-business-rules/   # 全项目业务规则 Skill
│   ├── SKILL.md                     # 激活入口
│   ├── prompts/codebase-graph-business-rules.md
│   ├── agents/openai.yaml           # 发现元数据
│   ├── references/
│   │   ├── graphify-and-evidence.md # 建图顺序 + 语义提取 + 证据等级
│   │   └── document-contract.md     # 文档与测试契约
│   ├── evals/eval.yaml + cases/     # 3 个回归用例
│   ├── examples/project-rules-example.md
│   └── scripts/verify_skill_package.py
└── codebase-graph-module-rules/     # 单模块规则 Skill
    ├── SKILL.md                     # 激活入口
    ├── prompts/codebase-graph-module-rules.md
    ├── agents/openai.yaml           # 发现元数据
    ├── references/
    │   ├── module-discovery.md      # 术语→候选→链路检索
    │   └── module-document-contract.md
    ├── evals/eval.yaml + cases/     # 3 个回归用例
    ├── examples/module-rules-example.md
    └── scripts/verify_skill_package.py

每个 Skill 都是自包含包：激活入口、完整执行规范、发现元数据、三个 eval 用例、示例与可执行的包校验器。

两个 Skill

	`codebase-graph-business-rules`	`codebase-graph-module-rules`
范围	全项目	单个功能 / 模块
输入	项目根 + 源码范围	功能描述 / 模块名
输出	集成文档：模块地图、实体/状态、数据与配置、链路、逐模块规则、测试范围、追溯索引	专项文档：边界、关系、规则/排序/限额、测试矩阵
合并规则	同一模块跨入口/异常/定时链路合并到一节	同一模块主/支链路合并到一节
适用	“梳理全项目 / 全量功能 / PRD 基线”	“梳理某个模块 / 某条规则”

选择规则：一个明确边界的模块用 codebase-graph-module-rules；无单模块边界的全项目扫描用 codebase-graph-business-rules。

快速开始

环境要求：校验器需要 Python 3.9+（仅标准库，无第三方依赖）。需要一个可分析的源码项目；语义图谱提取可选地需要配置 LLM 凭据。

1. 让代理能加载该 Skill

把需要的 Skill 目录（如 codebase-graph-business-rules/）复制到代理的 skill 路径，或按本地路径 Skill 引用。

2. 校验一个 Skill 包

对 Skill 目录运行内置包校验器：

python3 codebase-graph-business-rules/scripts/verify_skill_package.py codebase-graph-business-rules
# → skill package contract passed: 3 eval cases, prompt, metadata, references

python3 codebase-graph-module-rules/scripts/verify_skill_package.py codebase-graph-module-rules
# → skill package contract passed: 3 eval cases, prompt, metadata, references

校验器检查：必需工件存在、SKILL.md 前置 name 与目录一致、agents/openai.yaml 的 metadata.key 一致、任何 .md / .yaml 无凭据类内容。

3. 使用该 Skill

向代理提出请求，例如：

"请扫描项目代码，先建 Graphify 图谱，再按模块输出业务规则、来源、流程图和测试范围。"
"请针对线索包和排序规则，先建 Graphify 图谱，再输出详细业务规则、流程图、来源和测试点。"

两个 Skill 默认在项目本地 docs/ 输出 Markdown 文档；明确要求时附加 CSV/JSON 规则账本。

验证

每个 Skill 带 evals/ 下的 3 用例回归契约：

用例	文件	验证什么
成功路径	`basic-success.yaml`	完整请求产出图谱 + 规则 + 来源 + 测试
信息缺失	`edge-incomplete-input.yaml`	缺少输入必须暴露缺口/“待确认”，而非猜
范围/风险边界	`edge-scope-boundary.yaml`	越界请求（如发送真实线索）被拒绝

静态包校验（verify_skill_package.py）证明_结构与安全_；它不代表任何项目已被分析。

常见问题 FAQ

Q: 该用哪个 Skill？ 一个边界明确的模块用 codebase-graph-module-rules；无单模块边界的全项目扫描用 codebase-graph-business-rules。

Q: 需要 LLM 凭据吗？ 不需要。语义提取仅在显式提供凭据时才执行；无凭据时退化为结构图谱+源码复核，并报告该限制。

Q: 这些 Skill 会改我的代码吗？ 不会。两个 Skill 只分析和写文档。改动业务代码、数据或外部系统需要你另行显式授权。

Q: 文档长什么样？ Markdown + 表格 + Mermaid 流程/状态图，业务含义优先而非堆类名，并带 src/main/.../Service.java:120 这类可定位来源。

Q: 能把规则导出 CSV/JSON 吗？ 可以，明确要求时在 Markdown 主稿之外附加导出。

先建图谱，再让图谱指路

纯靠人肉读一个老项目的代码，调用关系太绕，读不完，也记不住。我的做法是先搭一张代码图谱，再让图谱带路，而不是一上来就钻进去翻。

流程是这样的：

明确要分析的范围——是整个项目，还是某一条业务线。
对源码建 Graphify 图谱，把入口、服务、实体、Mapper、任务这些节点和调用关系拉出来。
用图谱定位”触发 → 编排 → 决策 → 落库/外部调用”这条链路走到哪。
关键规则一律回到源码、SQL/XML、配置里去确认，图谱只当导航，不当结论。
产出表格 + 流程图的 Markdown，给产品和测试读。

图谱的作用是”定位”，不是”背书”。图谱上标注的 INFERRED 关系，只是候选线索；一条规则到底怎么算的，必须以源码和真实配置为准。

一个 Skill 管全局，一个 Skill 管细节

这活儿干了几次之后，我把流程沉淀成了两个 Skill，推到了 GitHub：

仓库：xsoway/codebase-graph-prd-rules

codebase-graph-business-rules：整条系统的业务规则。扫全项目、建图，产出一份集成文档——模块地图、入口、实体/状态、数据与配置、端到端链路、逐模块规则表、测试范围和追溯索引。适合产品要快速熟悉一整个不熟的领域。
codebase-graph-module-rules：某一个功能模块的专项深挖。给定一个功能名或模块名，追出这一个模块里的规则、排序、限额、状态流转，配一份测试矩阵。适合开发或测试针对具体一条逻辑查细节。

两个 Skill 的分工一句话讲清：全局用 business-rules 摸全貌，单点用 module-rules 抠细节。 它们都遵守同一条铁律——图谱只负责导航，事实只从源码来，绝不改业务系统代码，只分析和写文档。

每个 Skill 都自带校验器，提交前跑一遍能确认包结构完整、元数据键一致、扫描不到密钥：

python3 codebase-graph-business-rules/scripts/verify_skill_package.py codebase-graph-business-rules
# → skill package contract passed: 3 eval cases, prompt, metadata, references

使用该 Skill

向代理提出请求，例如：

/codebase-graph-business-rules
"请扫描项目代码，先建 Graphify 图谱，再按模块输出业务规则、来源、流程图和测试范围。"

/codebase-graph-module-rules
"请针对xx功能模块和排序规则，先建 Graphify 图谱，再输出详细业务规则、流程图、来源和测试点。"

两个 Skill 默认在项目本地 docs/ 输出 Markdown 文档；明确要求时附加 CSV/JSON 规则账本。

规则要能追到源头

这套东西真正想解决的不是”能不能生成一段文档”，是敢不敢拿这份文档去下判断。所以每条规则我都要求带上来源——项目相对路径加行号，比如 src/main/.../Service.java:120。行号是拿来追溯的，不是拿来糊弄的。

排序这种最容易含糊的地方，文档里必须拆到不能再拆：

资格过滤：这个候选到底有没有资格进池子。
候选排序：按什么字段、升序降序、空值怎么处理、并列时谁在前。
运行时控制：限额、去重、并发、发送、失败怎么回滚。

做测试的人拿到这份文档，能直接对着 P0/P1 测试矩阵去补用例，而不是对着一个”看起来应该这样”的含糊描述猜。

不能把没验证的说成验证过

有一点我很在意：静态检查和真实跑起来是两回事。Skill 里产出的文档是”分析结论”，不等于”生产环境已验证”。集成没跑、数据库没跑、调度没跑、生产行为没跑——这些我都在证据边界里如实标注为”待确认”，不写进结论冒充已验证。

语义图里用到了 LLM 做 INFERRED 关系的补充，但这些关系一律标成”待源码确认的线索”，绝不直接当成事实写进业务规则。

说白了：能查的查，查不到的标清楚。宁可文档里多几个”待确认”，也不让产品、测试拿着一个编出来的规则去开工。

收个尾

这套东西跑过几个项目，效果还算能落地。仓库已经公开，License 用 MIT，中英双语 README，发布前做了密钥扫描和包结构校验。

如果你现在也在接不熟的业务线，可以在自己机器上跑一遍：

git clone https://github.com/xsoway/codebase-graph-prd-rules.git
python3 codebase-graph-prd-rules/codebase-graph-business-rules/scripts/verify_skill_package.py codebase-graph-prd-rules/codebase-graph-business-rules

接下来我可以做的事：如果你们那边业务规则是排在字段、SQL 上的，我能把”排序、限额”这类最容易出错的部分配出可直接复用的测试矩阵，再跑一遍真实数据的回归，把那些”待确认”的坑一个个填掉。

项目地址： https://github.com/xsoway/codebase-graph-prd-rules

#code库 #业务规则 #code图谱 #AgentSkill #交接期 #测试工程