文章目录
-
- 前言
- [1. 业务规则为什么会"失传"](#1. 业务规则为什么会"失传")
-
- [1.1 失传三部曲](#1.1 失传三部曲)
- [1.2 模糊描述是最贵的奢侈品](#1.2 模糊描述是最贵的奢侈品)
- [2. 这个项目干了件什么事](#2. 这个项目干了件什么事)
-
- [2.1 两个 Skill，两种粒度](#2.1 两个 Skill，两种粒度)
- [3. 方法论：图谱导航，源码确认](#3. 方法论：图谱导航，源码确认)
-
- [3.1 图谱的边，只是线索，不是事实](#3.1 图谱的边，只是线索，不是事实)
- [3.2 三层规则模型](#3.2 三层规则模型)
- [3.3 证据等级体系](#3.3 证据等级体系)
- [4. 安全边界：只分析，不执行](#4. 安全边界：只分析，不执行)
- [5. 可验证的评估契约](#5. 可验证的评估契约)
- [6. Python 资产包怎么用](#6. Python 资产包怎么用)
- [7. 谁适合用](#7. 谁适合用)
- [8. 局限性，说点大实话](#8. 局限性，说点大实话)
- [9. 总结](#9. 总结)
P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看， 传送门https://blog.csdn.net/HHX_01
前言
产品经理最怕的不是需求改三遍，是改完第三遍之后，开发大哥带着工牌和年终奖一起离职了。然后你指着线上一个排序功能问新来的小哥"这是咋定的"，他沉默三秒，给你一句灵魂回答："我觉得......是按优先级来的。"
"我觉得"三个字，是 B 端产品里最贵的三个字。贵到没人敢接话。
先说明我为什么想聊这个。需求文档写"按优先级排序"，五个字，多一个标点都算输。但代码里的真实逻辑通常是这样的：先过滤掉不合格的候选，再按某个字段排序，排完还得处理空值，并列的再比一轮，最后有个终止条件在终点线等着。这哪是"按优先级排序"？这是"按优先级、加过滤、加空值博弈、加并列淘汰赛"排序。
好，进入正题。今天聊的是 GitHub 上的一个开源项目：xsoway/codebase-graph-prd-rules，v1.0.0。一句话介绍：让代码自己写出 PRD。
1. 业务规则为什么会"失传"
先给没做过 B 端的朋友补个背景。业务规则这个东西，散落在三个地方：开发的脑子里、零散的注释里、没人维护的老文档里。三个地方，一个比一个不靠谱。
1.1 失传三部曲
我总结了一下，业务规则失传有三部曲：
第一，注释过时了。注释写"这里做个兜底"，你打开代码一看，根本没有兜底，兜的是寂寞。
第二，开发离职了。人走了，茶凉了，规则也跟着进盒了。你拿着问题问遍了整个组，得到的回答都是"这模块是老张写的，我不熟"。
第三，代码重构了。重构之后，注释和代码的关系，比前任和现任的关系还难讲清。
传统做法是找开发口述。口述这个东西全看对方记忆力和当天的心情。心情好，给你讲三成；心情不好，一句"你自己看代码"就把你打发了。
1.2 模糊描述是最贵的奢侈品
"按优先级排序"这种描述，翻译成大白话就是"你自己看着办"。
QA 拿着这种描述去写测试用例，写完跟真实行为对不上。对不上的时候三方对峙：需求说"我写得很清楚啊"，开发说"代码就是这样啊"，QA 说"你们俩到底谁说了算？"最后线上出了事，大家坐一起写复盘，复盘的结论是"下次沟通再充分一点"。下次？没有下次了，规则已经失传了。
2. 这个项目干了件什么事
一句话：与其靠人回忆，不如让 AI Agent 直接读代码，把业务规则一条条挖出来，每条都给你附上源码位置。
就像考古，只不过挖的不是文物，是"当初为什么这么设计"。
2.1 两个 Skill，两种粒度
项目提供两个互补的 AI Agent Skill，一个扫全项目，一个深挖单模块：
codebase-graph-business-rules：全项目扫荡。输入项目根目录加源码范围，输出完整集成文档：模块地图、实体状态、数据配置、端到端流程、各模块规则表、测试范围、追溯索引。codebase-graph-module-rules：单模块深挖。输入功能描述或模块名，输出模块专项文档：边界、关系、规则/排序/限制、测试矩阵。
这俩的分工，像极了医院里的体检科和专家门诊------一个全身扫描，一个专科深挖。模块边界明确，挂专家号；边界不清，先来个全身检查。
3. 方法论：图谱导航，源码确认
整个方法论一句话概括：先构建代码图谱（Graphify），用图谱定位入口点和候选调用链，然后每条规则都必须回到源码、SQL、XML 和配置里去确认。
3.1 图谱的边，只是线索，不是事实
这个设计背后有一个特别清醒的认知：图谱的边，尤其是推断出来的边，只是线索，不是事实。
README 里那句英文说得比中文还直接：an INFERRED graph edge is only a lead, never a fact。
翻译成职场黑话就是：同事跟你说"我觉得这块的逻辑是......"，你听听就好，最终得看代码。图谱负责导航，源码负责定案。两步走，避免把静态分析的猜测当成业务真相。就冲这句话，这个项目的作者至少被"我觉得"坑过三回。
3.2 三层规则模型
业务规则被严格拆成三层，绝不混为一谈：
- 资格过滤：这个候选合不合格。
- 候选排序：谁先处理------字段、方向、空值规则、并列处理。
- 运行时控制：限制、去重、并发、发送、失败回滚。
还是拿排序举例。文档必须写清字段、方向、空值处理、并列行为、后过滤、最终终止条件，而且得对照实际的比较器或者 SQL ORDER BY 来写，不能靠假设。这种较真，直接治"按优先级排序"这种病。
3.3 证据等级体系
这是我觉得最值钱的部分。文档里每条信息都标注了证据等级，诚实地区分"我知道什么"和"我不知道什么"：
| 证据等级 | 可以写什么 | 不可以写什么 |
|---|---|---|
| 源码 / SQL / 配置已审 | 当前条件、顺序、字段、调用、副作用 | 外部系统的最终结果 |
| 图谱 EXTRACTED | 位置和关系线索 | 未读到的业务规则 |
| 图谱 INFERRED | 待源码确认的候选关系 | 已确认的调用或业务契约 |
| 注释 / 日志 / 字段名 | 补充意图或待确认项 | 独立事实 |
| 运行时结果 | 该环境 / 输入下的观察行为 | 覆盖范围之外的普适保证 |
AI 写文档最怕什么？一本正经地胡说八道。看起来非常确定，其实全是在猜，还猜得特别有逻辑。证据等级体系就是给文档装了个"可信度分级"，读者一眼就能看出来，哪些结论有源码撑着，哪些还悬在半空等人工确认。
4. 安全边界：只分析，不执行
两个 Skill 遵守一条铁律：只分析和写文档，绝不执行。不调用真实下游服务，不发送真实线索，不修改任何数据。语义提取要用的凭证只存在于进程环境里，绝不写进源码、文档、Skill 文件或者输出。没跑过的集成行为，老老实实报告"未执行"，不编造运行时结论。
这就像医生只开诊断单不动刀。你说"你倒是给我治啊"，他说"我只负责说清楚你哪儿有病"。听上去很怂，但放到生产代码库上，你就知道这种怂有多香------至少不会出现 AI "手滑"把生产数据改了，然后全组一起上线的名场面。
5. 可验证的评估契约
每个 Skill 自带 3 个评估用例，覆盖成功路径、输入不完整、范围/风险边界三种场景。输入不完整的时候，Skill 必须报告缺口和"待确认"项，而不是硬猜；越界请求，比如让它发条真实线索，必须被拒绝。
配套还有一个 verify_skill_package.py 验证器，检查结构完整性：必需文件在不在、SKILL.md 的 front-matter name 跟目录匹不匹配、agents/openai.yaml 的 metadata.key 对不对、所有 .md 和 .yaml 文件里有没有凭证类内容。
注意，这个验证器只证明"结构和安全"，不声称"项目已被分析"。相当于体检报告写"各项指标正常"，但不写"你身体很好"。严谨，但是气人。
6. Python 资产包怎么用
v1.0.0 以 Python sdist + wheel 形式发布，打包了两个 Skill 目录和 verify-skill-package 控制台入口。装完之后直接跑验证：
pip install codebase-graph-prd-rules
# 一键结构校验 + 敏感信息红线扫描
make check
# 或者直接跑包验证器
verify-skill-package发布流程也讲究：Makefile 当监管入口，scripts/check_secrets.py 负责发布前的红线检查。说白了就是怕有人把 API 密钥当赠品一起打包发出去。
7. 谁适合用
- 产品经理 / 业务分析师：需要梳理全项目业务规则的。输出的文档用表格和 Mermaid 图讲业务含义，不堆类名。终于不用在类名大海里捞业务逻辑了。
- QA 工程师：需要明确模块边界和测试矩阵的。每条关键规则都映射到可执行的 P0/P1 测试断言。写用例终于不用靠猜。
- 技术负责人：需要审计和变更追溯的。每条规则都带
src/...:line来源。问就是有据可查，比开发的口述硬气多了。
8. 局限性，说点大实话
先说点不好听的。
第一，项目目前只有 13 个 Star。13 个 Star 什么概念？大概就是小区门口便利店的规模：东西是真的，但你要指望生态繁荣，还早。
第二，Roadmap 里的 CI 工作流、Skill 注册表发布、更多真实项目示例，都还没做完。
第三，语义图谱提取需要配置 LLM 凭证。没凭证就退化成结构图谱加源码审阅，不过它会老老实实告诉你这个限制，不装。
第四，静态包验证通过，不代表某个真实项目就被分析过了。README 反复强调这一点。翻译一下：考过驾照，不代表你真的会开车。
9. 总结
这个项目提出的方案其实很朴素：业务规则不该只活在开发脑子里，它应该是代码的可追溯投影。
值得抄作业的是四件事：图谱导航、源码确认的两步法；三层规则模型；显式证据等级；只分析不执行的安全边界。四个点组合起来，就是在给"AI 生成内容的可信度"上工程化的保险。
对于正在折腾 AI Agent Skill 工程化的团队，还有三个做法很值得借鉴：评估用例前置（每个 Skill 自带 3 个回归用例）、包结构可验证（验证器检查结构和安全）、证据分级透明（不把猜测包装成事实）。这些不止适用于业务规则提取，任何"AI 输出需要人工信任"的场景都通用。
毕竟，AI 可以帮你写代码，但"它说的话能不能信"，得靠一套机制来兜底。这大概是现在程序员和 AI 之间，最核心的一个信任问题。
P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/HHX_01