ns-harness-codebase-reverse-spec

代码库逆向系统描述

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

输出语言（硬性规定）

以下两份交付物均仅使用英文：

• {product_root}/docs/context/system-reverse-spec.md（正文，供人阅读）
• {product_root}/docs/context/system-reverse-spec.agent.md（Agent 索引）

不得混用语言。 即使聊天或产品界面使用其他语言，章节标题、标签、业务规则模式（When …, the system …）、术语表、用例和正文也必须全部使用英文。将领域术语翻译成清晰的英文；专有名称和产品名称保持原样。

核心原则

代码是行为的证据。目标是回答系统做什么以及为什么这么做，而不是说明系统如何构建。避免以编程语言、框架、库、数据库、架构模式（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 编写便于人阅读的正文。将标题／重点调整为“对已实现系统的描述”。采用陈述式、现在时，描述观察到的产品行为。正文全部使用英语（模板标签保持英文；所有占位内容均使用英文填写）。

深度（来自阶段 0 / prepare boot）：

模式	人类可读正文（system-reverse-spec.md）	Agent 索引
Executive（默认）	概览简短；实体／用例／规则以紧凑表格或简短要点呈现，不写成长篇内容	始终编写 references/agent_index.template.md 中的 system-reverse-spec.agent.md
Exhaustive	按模板编写完整章节；提供更深入的流程说明	仍需编写 Agent 索引（表格与正文保持一致）

Agent 索引规则：仅使用表格和单行内容；不写段落文本；两份文档同时存在时，Agent 先加载索引。

**仅针对 Agent 索引的保存前处理：**在编写 system-reverse-spec.agent.md 之前，应用 ../ns-harness/references/agent-artifact-compress.md（caveman ultra）。不要用 caveman 风格重写人类可读正文 system-reverse-spec.md。

交付前，执行检查：

1. 逐项检查 references/anti_leakage_checklist.md — 删除或改写任何技术泄漏内容。
2. 可选择运行 scripts/scan_leakage.sh <spec-file> 进行首轮自动扫描（手动检查命中项；脚本只能识别模式，无法判断意图）。
3. 逐项检查 references/coverage_matrix.md — 确认已涵盖每个维度，或明确标记为 N/A 并说明原因。
4. 确认以功能方式描述权限、层级和集成。
5. 属性名称仅在保留业务语义所需时出现，不附带技术细节。
6. 置信度标记应放在附录（“需要与团队确认的内容”）中，不要堆在正文里。
7. 不要将明显的错误伪装成业务规则 — 应将其放入附录，并注明该行为可能并非有意设计。
8. 文档应回答是什么以及为什么（若可推断），绝不描述如何实现。
9. 交付内容全部使用英语 — 不得混用葡萄牙语／英语章节标题、标签或规则句。

阶段 5 — 交付与验证

交付：

1. 最终规格说明 — {product_root}/docs/context/system-reverse-spec.md（Markdown；仅在用户要求时提供 docx）。
2. Agent 索引 — {product_root}/docs/context/system-reverse-spec.agent.md（Executive／prepare 模式下始终提供；Exhaustive 模式下始终建议提供）。
3. 提取日志（可选分享）— 如果用户需要追溯依据，则提供工作日志。
4. “需要与团队确认的内容” — 放在人类可读正文的附录中，并在 Agent 索引中以单行内容对应列出。

询问用户是否希望深入某个模块、切换到 Exhaustive、交付下一个领域切片，或导出为其他格式。

大型代码库策略

当仓库规模超出一次性处理的舒适范围时：

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

应避免的常见错误

• 使用非英语撰写逆向规格说明（或其中部分内容），或将不同语言与英文模板混用。
• 只是为了“提供背景”而罗列技术栈，而不是描述业务行为。
• 混淆文件夹结构（技术产物）与领域结构（业务概念）——务必进行转换。
• 编写规范未来需求的文档，而不是忠实描述当前已实现的系统。
• 未经核实其是否对应真实概念，就将数据库字段名或变量名当作正式业务术语。
• 因担心“耦合”而省略外部集成、访问角色或层级结构——它们都是观察到的领域内容。
• 不做优先级筛选，逐个文件通读整个仓库。
• 将明显损坏或已失效的逻辑描述为“有意设定的业务规则”。
• 在提取内容与最终撰写之间丢失置信度标记——请使用提取日志。

参考文件

文件	阅读时机
references/spec_template.md	阶段 4 — 面向人工阅读的最终文档
references/agent_index.template.md	阶段 4 — 面向 Agent 的精简索引
../ns-harness/references/agent-artifact-compress.md	保存前 — 仅限 Agent 索引
references/extraction_log_template.md	阶段 2 — 提取过程中的工作笔记
references/coverage_matrix.md	阶段 1 和 4 — 完整性检查
references/anti_leakage_checklist.md	阶段 4 — 交付前的合理性检查
scripts/scan_leakage.sh	阶段 4 — 可选的自动初步检查