在软件开发和产品协作中，业务规则长期处于一种尴尬状态：需求文档写得很简略，真实逻辑却散落在代码、配置、SQL 和注释里。时间一长，开发可能离职，注释可能失效，文档也没有人继续维护。等到排查线上问题或重新梳理需求时，团队往往只能重新阅读代码，甚至依赖个别开发者的记忆。
开源项目 xsoway/codebase-graph-prd-rules 试图换一种方式解决这个问题。它在 v1.0.0 版本中提供了两个互补的 AI Agent Skill：一个用于扫描整个项目，另一个用于深挖单个模块。其核心思路不是让 AI 直接“总结”代码，而是通过代码图谱定位线索，再回到源码、SQL、XML 和配置中确认，最终输出带有来源位置的业务规则文档。
从“问开发”到“让代码自己说明”
很多 B 端产品都遇到过类似问题：需求文档中只有一句“按优先级排序”，但实际代码可能包含多层逻辑。系统可能先过滤不符合条件的候选对象，再根据某个字段排序，最后还存在终止条件或后过滤规则。这些逻辑分布在不同文件中，注释也可能早已过时。
这类模糊描述会带来连锁反应。产品经理无法准确解释规则，QA 工程师难以写出与真实行为一致的测试用例，线上问题出现后也很难追溯当初的设计原因。传统做法通常是找开发口述，或者翻查代码注释，但注释会过时，人员会流动，代码也会重构。如果业务规则没有独立的、可追溯的载体，很多细节最终会变成“只有当时负责的人知道”。
codebase-graph-prd-rules 的价值正在于此。它把业务规则视为代码的可追溯投影，而不是依赖个人经验或历史文档。项目给出的方法可以概括为“Graphify 导航，源码确认”：先构建代码图谱，利用图谱定位入口点和候选调用链，包括触发、编排、决策、存储或日志、外部结果等环节；随后，每一条规则都必须回到源码中确认。
README 中明确提到，推断出的图谱边只是线索，不是事实。也就是说，静态分析得到的调用关系不能直接写进文档，必须经过源码验证。这种设计避免了 AI 把推测包装成结论，也降低了自动生成文档时常见的“看似确定、实则猜测”的问题。
三层规则模型与证据分级
在具体分析方式上，该项目将业务规则严格拆分为三层，避免不同性质的逻辑混在一起：
- 资格过滤：判断候选对象是否满足进入后续流程的条件。
- 候选排序：明确谁先被处理，包括排序字段、方向、空值规则、并列处理等。
- 运行时控制：覆盖限制、去重、并发、发送、失败回滚等执行层面的规则。
以排序规则为例，文档不能只写“按优先级排序”，而需要说明具体字段、排序方向、空值如何处理、出现并列时怎么办、排序后是否还有过滤逻辑，以及最终终止条件是什么。这些内容需要对照实际的比较器或 SQL ORDER BY 来确认，而不是依赖抽象描述。
项目还引入了证据等级机制。每条信息都会标注其可信来源，明确区分“已知”和“待确认”。这样做的意义在于，读者可以判断哪些结论有源码支撑，哪些仍需要人工核实。对于 AI 生成的文档来说，这种透明度比单纯追求完整输出更重要。
两个 Skill 在使用场景上也有明确分工。当模块边界清晰时，可以使用单模块 Skill 做深入分析；当规则跨多个模块、没有单一边界时，则使用全项目 Skill 进行扫描。两者共享同一套方法论，但覆盖不同粒度。
安全边界：只分析，不执行
对于在生产代码库上运行的 AI 工具，安全性是绕不开的问题。codebase-graph-prd-rules 对此设定了明确边界：两个 Skill 只做分析和文档生成，不执行未经授权的生产操作。它们不会调用真实下游服务，不会发送真实线索，也不会修改数据。
项目还规定，语义提取所需的凭证只存在于进程环境中，不会写入源码、文档、Skill 文件或输出内容。对于未运行的集成行为，系统会明确报告为“未执行”，不会编造运行时结论。
每个 Skill 都附带 3 个评估用例，分别覆盖成功路径、输入不完整、范围和风险边界三类场景。如果输入不完整，Skill 需要报告缺口和待确认项，而不是直接猜测；如果请求越界，例如要求发送真实线索，则必须拒绝。
配套的 verify_skill_package.py 验证器用于检查包结构完整性，包括必需文件是否存在、SKILL.md 的 front-matter name 是否与目录匹配、agents/openai.yaml 的 metadata.key 是否匹配，以及所有 .md 和 .yaml 文件中是否包含凭证类内容。需要注意的是，验证器只证明结构和安全，并不声称项目已经被分析。
v1.0.0 以 Python sdist 和 wheel 形式发布，打包了两个 Skill 目录以及 verify-skill-package 控制台入口。安装后可以直接运行包验证，也可以通过 make check 执行结构校验和敏感信息红线扫描。Makefile 作为监管入口，scripts/check_secrets.py 负责发布前的凭证检查。
对遗留系统和 AI 工程化的意义
从使用对象看，这个项目主要面向三类角色。产品经理和业务分析师可以用它梳理全项目业务规则，输出内容以表格和 Mermaid 图表达业务含义，而不是堆砌类名。QA 工程师可以基于规则来源明确模块边界和测试矩阵，将关键规则映射到 P0、P1 测试断言。技术负责人则可以在审计和变更追溯时，通过每条规则附带的 src/…:line 来源快速定位代码位置。
不过，项目本身的成熟度仍有局限。目前该项目只有 13 个 Star，社区规模较小，Roadmap 中的 CI 工作流、Skill 注册表发布和更多真实项目示例尚未完成。语义图谱提取需要配置 LLM 凭证；如果没有凭证，系统会退化为结构图谱加源码审阅，并如实报告这一限制。静态包验证也不等于真实模型行为，包验证通过并不代表某个项目已经被完整分析。
尽管如此，codebase-graph-prd-rules 提供了一种值得关注的工程路径。它没有把 AI 文档生成当成简单的总结任务，而是通过图谱导航、源码确认、规则分层、证据分级和只读安全边界，建立一套可验证、可追溯的输出机制。对于遗留系统治理、需求文档补全和 AI Agent Skill 工程化来说，这种做法比单纯追求生成速度更有参考价值。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/dai-ma-li-de-ye-wu-gui-ze-ru-he-bian-cheng-ke-zhui-su-wen
