codebase-reverse-spec

代码库逆向系统说明

从现有代码库中重构一份与技术无关的系统说明文档，描述已实现的系统：与产品运行相关的可观察行为、业务规则、权限、层级结构和外部集成。

核心原则

代码是行为的证据。目标是回答系统做什么以及为什么这么做，而非说明系统是如何构建的。避免以编程语言、框架、库、数据库、架构模式（MVC、微服务等）以及类名或函数名作为说明主线。

每句话都遵循黄金法则：“如果我用另一套技术栈从头重写这个系统，这句话仍然成立吗？” 如果不成立，就用业务术语重新表述。

仅在理解当前业务领域不可或缺时，允许例外：

• 外部集成方／提供商名称（ERP、网关、BI、身份认证、分析服务）。
• 访问角色／配置文件和组织层级。
• 为保留业务含义所需的实体属性名称（而非用于说明技术结构）。

适用场景

• 在不丢失业务规则的前提下进行遗留系统现代化改造／迁移
• 为没有文档（或文档已过时）的系统编写说明
• 帮助新团队快速熟悉系统
• 在使用另一套技术栈重写之前审计业务规则
• 编写忠实反映当前系统的功能说明

范围和代码库访问权限

1. 确认代码库路径（如果不明确，则询问）。使用 Read / Glob 高层查看目录结构。
2. 对于单体仓库，确认要分析的产品／模块目录——除非用户明确要求分析整个仓库，否则只分析该子树。
3. 对于外部／遗留代码库，确认是否有读取权限，以及哪些目录不在分析范围内（生成的代码、第三方依赖、仅限基础设施的内容）。

工作流程

按顺序执行各阶段。不要跳过阶段 0——否则最终规范会把猜测和事实混在一起。

阶段 0 — 范围和目标

向用户提问（一次只问一个问题；适合时使用 AskQuestion）：

问题	重要性
整个系统还是特定模块／业务领域？	避免范围蔓延或遗漏
执行摘要还是详尽说明？	确定深度和篇幅
输出语言是什么？	规范语言可能与技能／对话语言不同
是否有需要重点审查的关键／高风险业务领域？	优先审查财务、税务、权限或合规逻辑
分阶段交付（大型代码库）还是一次性交付单份文档？	大型代码库适合按业务领域逐步撰写

如果代码库很大，不要一次性读取所有内容。先进行初步勘察（阶段 1），并按业务影响而非文件大小确定优先级。

阶段 1 — 侦察（绘制地图，而非逐行阅读）

目标：在深入阅读之前，先找到业务逻辑所在的位置。

1. 使用 Glob 或同类工具列出目录树（根目录及约 2 层）。
2. 找出可能属于领域核心的目录和文件，例如名为 services、domain、rules、validators、models、usecases、handlers、controllers 的目录和文件，或语言特定的对应名称。
3. 找出入口点：API 路由、定时任务、消息队列、界面/表单、CLI 命令。这些揭示了系统允许某人（人类或其他系统）执行哪些操作——这是用例的基础。
4. 找出数据源（表、实体、架构）——目的不是记录持久化技术，而是了解业务所跟踪的事物。
5. 如果有，列出现有测试。测试往往比生产代码更能说明业务规则，因为它们通过场景描述预期行为。
6. 明确梳理：
   • 权限与访问模型；
   • 组织/功能层级；
   • 外部集成及各自在业务流程中的作用。
7. 按业务价值（而非技术复杂度）排序，列出优先调查清单。

**检查点（建议）：**在深入提取之前，先向用户展示侦察地图和优先级清单。及早发现范围错误，可以省下数小时的无效阅读。只有在用户要求完全自主运行时才跳过此步骤。

将 references/coverage_matrix.md 用作思维检查清单——标记已发现的内容以及仍需调查的内容。

阶段 2 — 提取规则

针对每个优先调查领域，使用 references/extraction_log_template.md 维护工作日志。暂时不要撰写最终规范——先积累证据并评估置信度。

针对每段逻辑：

1. 阅读相关代码（处理程序、验证、计算、条件判断、状态机）。
2. 思考：
   • 这代表什么业务决策？
   • 哪些输入数据很重要，为什么？
   • 各分支（成功、失败、异常、边界情况）会发生什么？
   • 这条规则是否有合理的业务原因（信用额度、法定期限、财政规则），即使代码没有注释说明？
3. 将每项发现转化为可验证的业务规则陈述：**“当[业务条件]时，系统[预期行为]，除非[例外情况]。”**此类陈述中绝不提及函数/类/变量名称。
4. 标注置信度：
   • 已确认：行为明确，且有测试覆盖或显式验证。
   • 推断：依据代码得出的合理推断，但没有直接确认。
   • 含糊/可疑：代码令人困惑、相互矛盾、已失效或可能存在缺陷。标记为需要人工审查——不要在未警示的情况下将缺陷上升为有意的业务规则。
5. 记录否定规则——系统明确禁止的事项（验证、权限、阻止条件）。限制与能力同样是规范的一部分。
6. 对于外部集成，记录：
   • 业务触发条件；
   • 涉及的业务数据（不记录技术载荷）；
   • 成功/失败时的预期结果；
   • 服务不可用时的运营影响（降级模式、阻断、人工备用方案）。
7. 按语义记录实体属性——只有在不提及属性名称就会产生歧义时，才引用属性名称。
8. 对于状态/状态字段，记录其生命周期：允许的转换、触发者、终止状态，以及转换是受到强制执行还是仅按惯例进行。

阶段 3 — 领域结构化

将提取的材料整理为：

• 业务实体及与业务相关的属性（不是数据库列类型或实现类型）。
• 关系，使用业务语言描述（“订单属于某位客户，并包含一个或多个订单项”）。
• 用例／流程，每项包括：参与者、目标、前置条件、逐步说明的预期行为、结果，以及业务异常／错误。
• 横切策略：适用于多个用例的规则（授权、审计、限制）。
• 访问模型：角色、配置、范围、权限层级。
• 外部集成：第三方系统、业务目的、预期行为。
• 领域术语表：代码中发现的领域专用术语（字段名称、状态、枚举）的清晰定义。
• 状态生命周期（适用时）：实体状态、转换和执行规则。

阶段 4 — 编写最终规范

以 references/spec_template.md 为基础。调整标题／重点，改为“对已实现系统的描述”。不要写成未来的 PRD 或技术代码报告。语气应为陈述式、使用现在时，描述观察到的产品行为。

交付前，进行健全性检查：

1. 逐项检查 references/anti_leakage_checklist.md，删除或改写任何技术细节泄漏。
2. 可选：运行 scripts/scan_leakage.sh <spec-file> 进行初步自动扫描（人工复核命中项；该脚本只能识别模式，无法判断意图）。
3. 逐项检查 references/coverage_matrix.md，确认每个维度都已涵盖，或明确标记为不适用并说明原因。
4. 确认权限、层级和集成都以功能方式描述。
5. 属性名称仅在保留业务语义所需时出现，不包含技术细节。
6. 置信度标记放在附录（“需要与团队确认的方面”）中，不要让正文显得杂乱。
7. 不要将明显的缺陷伪装成业务规则——应将其放入附录，并注明该行为可能并非有意为之。
8. 文档应回答是什么以及为什么（在可推断时），绝不回答如何实现。

阶段 5 — 交付与验证

交付：

1. 最终规范——默认使用 Markdown；仅在用户要求 Word 格式时提供 docx。
2. 提取日志（可选）——如果用户需要追溯证据，可提供工作用的 extraction_log。
3. **“需要与团队确认的方面”**附录——简要列出推断得出的／含义不明确的规则及疑似缺陷。保持认知上的诚实：规范不得假装确定无疑。

询问用户是否希望深入了解某个模块、调整细节程度、交付下一个领域切片（大型代码仓库），或导出其他格式。

大型代码库策略

当代码仓库的规模超出一次处理所能轻松涵盖的范围时：

1. 对整个范围完成阶段 0–1；获取对领域图的检查点审批。
2. 一次提取并起草一个领域（每个领域分别完成阶段 2–4），将其作为一个章节或单独文件。
3. 执行综合检查：合并各领域、去重术语表条目、协调横切策略，并针对整个系统检查一次覆盖矩阵。
4. 不要因追求 100% 覆盖而阻碍交付——交付已完成的领域，并明确列出“尚未分析”的内容。

应避免的常见错误

• 只是为了提供「背景」而罗列技术栈，而不是描述业务行为。
• 混淆文件夹结构（技术产物）与领域结构（业务概念）——应始终进行转换。
• 编写规范性的未来需求文档，而不是如实描述当前已实现的系统。
• 未经核实字段名或变量名是否对应真实概念，就将其当作正式业务术语。
• 因担心「耦合」而遗漏外部集成、访问角色或层级关系——它们都是观测到的领域的一部分。
• 不加优先级地逐个读取整个代码库中的所有文件。
• 将明显有问题或已失效的逻辑当作「有意设计的业务规则」。
• 在提取和最终撰写之间丢失置信度标记——请使用提取日志。

参考文件

文件	阅读时机
references/spec_template.md	阶段 4——最终文档的结构
references/extraction_log_template.md	阶段 2——提取过程中的工作笔记
references/coverage_matrix.md	阶段 1 和 4——完整性检查
references/anti_leakage_checklist.md	阶段 4——交付前检查
scripts/scan_leakage.sh	阶段 4——可选的自动化初步检查