产品经理最怕什么？问开发"这个排序规则到底是怎么定的"，得到一句"我记得是按优先级来的"。业务规则散落在开发的脑子里、零散的注释里、没人维护的老文档里——出了问题，没人能说清楚"当初为什么这么设计"。
xsoway/codebase-graph-prd-rules 给出了一个思路：与其靠人回忆，不如让 AI Agent 直接读代码，把业务规则一条条挖出来，每一条都附上源码位置。v1.0.0 版本包含两个互补的 Skill，一个扫全项目，一个深挖单模块，配套 Python 发布包和可执行的包验证器。
Github: github.com/xsoway/code…
痛点：业务规则为什么总是"失传"？
做过 B 端产品的人都懂这种场景。需求文档写的是"按优先级排序"，但代码里的真实逻辑可能拆成了三层：先过滤不合格的候选，再按某个字段排序，最后还有个终止条件。这三层规则写在不同的文件里，注释可能早就过时了。
更麻烦的是，规则描述模糊。"按优先级排序"这个说法，过滤条件、排序字段、空值处理、并列时怎么办、排完之后还有没有后过滤——每一条都可能藏着坑。QA 拿到这样的描述写测试用例，写出来的用例和真实行为对不上，出了线上问题才发现。
传统做法是找开发口述，或者翻代码注释。但注释会过时，开发会离职，代码会重构。规则没有独立的、可追溯的载体，就注定了"失传"的命运。
核心功能：两个 Skill，两种粒度
这个项目提供两个互补的 AI Agent Skill，共享同一套方法论，覆盖不同的分析粒度：
| 维度 | codebase-graph-business-rules | codebase-graph-module-rules |
|---|---|---|
| 分析范围 | 全项目 | 单个功能/模块 |
| 输入 | 项目根目录 + 源码范围 | 功能描述或模块名 |
| 输出 | 完整集成文档：模块地图、实体状态、数据配置、端到端流程、各模块规则表、测试范围、追溯索引 | 模块专项文档：边界、关系、规则/排序/限制、测试矩阵 |
| 合并规则 | 同一模块的入口/异常/定时器流程合并为一节 | 同一模块的主干/分支链路合并为一节 |
| 适用场景 | "梳理全项目业务规则" | "梳理某个模块的规则" |
选择规则很清晰：模块边界明确时用单模块 Skill，没有单一模块边界时用全项目 Skill。
技术架构：图谱导航，源码确认
方法论核心
这套 Skill 的方法论可以用一句话概括：Graphify 导航，源码确认。先构建代码图谱（Graphify），用图谱定位入口点和候选调用链（触发 → 编排 → 决策 → 存储/日志 → 外部结果），然后每一条规则都必须回到源码、SQL、XML 和配置中去确认。
这个设计背后有一个重要的认知：图谱的边（尤其是推断出来的边）只是线索，不是事实。README 明确写道"an INFERRED graph edge is only a lead, never a fact"——推断出的调用关系必须经过源码验证才能写进文档。这种"图谱导航、源码定案"的两步法，避免了把静态分析的猜测当成业务真相。
三层规则模型
业务规则被严格拆分为三层，绝不混为一谈：资格过滤（候选是否合格）、候选排序（谁先处理——字段、方向、空值规则、并列处理）、运行时控制（限制、去重、并发、发送、失败回滚）。
以排序为例，文档必须写清字段、方向、空值处理、并列行为、后过滤、最终终止条件——而且要对照实际的比较器或 SQL ORDER BY 来写，不能靠假设。这种严格性直接回应了"按优先级排序"这种模糊描述带来的问题。
证据等级体系
文档中的每条信息都标注了证据等级，诚实地区分"我知道什么"和"我不知道什么"：
| 证据等级 | 可以写什么 | 不可以写什么 |
|---|---|---|
| 源码/SQL/配置已审 | 当前条件、顺序、字段、调用、副作用 | 外部系统的最终结果 |
| 图谱 EXTRACTED | 位置和关系线索 | 未读到的业务规则 |
| 图谱 INFERRED | 待源码确认的候选关系 | 已确认的调用或业务契约 |
| 注释/日志/字段名 | 补充意图或待确认项 | 独立事实 |
| 运行时结果 | 该环境/输入下的观察行为 | 覆盖范围之外的普适保证 |
这套体系解决了一个关键问题：AI 生成的文档最怕"看起来很确定但其实是在猜"。通过显式区分证据等级，读者一眼就能知道哪些结论有源码支撑，哪些还需要人工确认。
设计亮点
安全边界：只分析，不执行
两个 Skill 遵守一条铁律：只分析和写文档，绝不执行。它们拒绝未经授权的生产操作——不调用真实下游服务、不发送真实线索、不修改数据。语义提取所需的凭证只存在于进程环境中，绝不写入源码、文档、Skill 文件或输出。未运行的集成行为会被明确报告为"未执行"，不会编造运行时结论。
这种安全设计让 Skill 可以放心地在生产代码库上运行，不用担心 AI"手滑"改了什么东西。
可验证的评估契约
每个 Skill 都携带 3 个评估用例，覆盖成功路径、输入不完整、范围/风险边界三种场景。输入不完整时，Skill 必须报告缺口和"待确认"项，而不是猜测；越界请求（比如发送真实线索）必须被拒绝。
配套的 verify_skill_package.py 验证器检查结构完整性：必需文件存在、SKILL.md 的 front-matter name 与目录匹配、agents/openai.yaml 的 metadata.key 匹配、所有 .md/.yaml 文件中没有凭证类内容。验证器只证明"结构和安全"，不声称"项目已被分析"——这个区分本身就是证据等级理念的体现。
Python 资产包发布
v1.0.0 以 Python sdist + wheel 形式发布，打包了两个 Skill 目录和 verify-skill-package 控制台入口。安装后可以直接运行包验证，也可以通过 make check 执行结构校验和敏感信息红线扫描。发布流程体现了工程规范：Makefile 作为监管入口，scripts/check_secrets.py 负责发布前的红线检查。
适用场景与局限性
这个项目特别适合三类人群：需要梳理全项目业务规则的产品经理和业务分析师——输出的文档用表格和 Mermaid 图讲业务含义，不堆类名；需要明确模块边界和测试矩阵的 QA 工程师——每条关键规则都映射到可执行的 P0/P1 测试断言；需要审计和变更追溯的技术负责人——每条规则都带 src/...:line 来源。
局限性也很明确。项目目前只有 13 个 Star，社区规模很小，Roadmap 中的 CI 工作流、Skill 注册表发布、更多真实项目示例都还未完成。语义图谱提取需要配置 LLM 凭证，没有凭证时会退化为结构图谱加源码审阅，并且会如实报告这一限制。另外，静态包验证不等于真实模型行为——README 反复强调这一点，使用时也需要记住：包验证通过不代表某个项目真的被分析过。
Github: github.com/xsoway/code…
总结
codebase-graph-prd-rules 提出的方案很朴素：业务规则不该只活在开发脑子里，它应该是代码的可追溯投影。通过"图谱导航、源码确认"的两步法、三层规则模型、显式证据等级和"只分析不执行"的安全边界，这套 Skill 试图在 AI 生成内容的可信度上建立一套工程化的约束。
对于正在探索 AI Agent Skill 工程化的团队来说，这个项目展示了几个值得借鉴的做法：评估用例前置（每个 Skill 自带 3 个回归用例）、包结构可验证（验证器检查结构与安全）、证据分级透明（不把猜测包装成事实）。这些做法不止适用于业务规则提取，任何"AI 输出需要人工信任"的场景都可以参考。
关注
如果这篇文章对你有启发，欢迎关注我们，获取更多技术产品的深度分析和开源项目的创意拆解。
