lucasacoutinho/dds

# 开发驱动规范 (DDS)：将遗留代码库逆向工程为 Arc42 规范 DDS 是 SDD 的逆过程。SDD 将规范转化为代码；DDS 将代码转化为规范。将其用于遗留代码库——老旧的 PHP、.NET Framework、Delphi、经典的 Java EE、不可触碰的 Rails 单体应用——以生成足够详细的基于 Arc42 的规范，从而足以在现代技术栈中**重建系统**。 ## 为什么会有这个项目 遗留代码库在数十年间积累了大量未记录的业务知识。数据校验隐藏在控制器中。业务计算隐藏在存储过程中。工作流隐藏自 2012 年以来就无人问津的 `IF` 语句里。系统现代化往往陷入停滞，因为没人能回答“这个系统到底在做什么？” DDS 回答了这个问题。它会生成一份基于引用的规范，其中每一个关于行为的陈述都可以追溯到遗留源代码中的 `file:line`（文件:行号）。然后，fidelity-judge（保真度评估）Agent 会对这些引用进行随机抽样，并与实际代码进行比对验证，在编造的规则混入规范之前将其剔除。 ## 主要特性 - **引用优先** — 每一个关于行为的陈述都附带一个 `[file:line]`（文件:行号）引用。未注明引用的陈述将无法通过 fidelity-judge 的验证。 - **自下而上的挖掘** — 从具体组件（SQL、处理器、模块）开始，向上综合提炼出整体架构。这是对 SDD 自上而下流程的逆向操作。 - **LLM-as-Judge（大模型作为评判者）保真度验证** — 对声称的规则进行随机抽样，并在源代码中逐行验证。有效捕获逆向工程中的头号风险：大模型幻觉（hallucination）产生的虚假业务规则。 - **多 Agent 上下文隔离** — 包含 8 个专用 Agent，每个都有明确的职责（surveyor、module-excavator、data-archaeologist、business-rule-extractor、integration-mapper、dead-code-detector、spec-assembler、fidelity-judge）。没有任何一个 Agent 会将整个代码库全部装入其上下文中。 - **按模块分解 + 全局注册表** — 每个模块对应一个 `spec/modules/.md` 文件，外加全局的 `spec/business-rules.md`、`spec/sql-inventory.md`、`spec/data-dictionary.md`、`spec/integrations.md`、`spec/dead-code.md` 文件。 - **基于 Arc42 的输出** — 统一的规范遵循 arc42 的 12 节模板（引言、约束、上下文、解决方案策略、构建块、运行时、部署、概念、决策、质量、风险、术语表），这些内容均从观察到的代码模式中重构而来。 ## 快速开始 本仓库是一个单插件的 Claude Code 市场。将其添加为市场源，然后安装该插件： ``` /plugin marketplace add lucasacoutinho/dds /plugin install dds@lucasacoutinho/dds ``` 启用后，请按顺序运行： ``` # 阶段 1：快速 reconnaissance — 检测 stack、modules、entry points /dds:survey # 阶段 2：逐 module 深度 excavation（繁重；选择一个开始） /dds:excavate # 或者一次性处理所有 modules： /dds:excavate --all # 阶段 4：组装统一的 Arc42 spec /dds:assemble ``` 输出结果将保存到 `spec/` 目录（可见，会被提交到 Git）以及 `.specs/scratchpad/` 目录（被 Git 忽略的子 Agent 工作区）中。 ## 整体流程 ``` Phase 1: Reconnaissance (top-down, fast) └─ /dds:survey surveyor agent → spec/00-survey.md Phase 2: Excavation (bottom-up, heavy) └─ /dds:excavate ├─ module-excavator → spec/modules/.md (line-by-line) ├─ data-archaeologist → spec/sql-inventory.md + spec/data-dictionary.md ├─ integration-mapper → spec/integrations.md ├─ business-rule-extractor → spec/business-rules.md ├─ dead-code-detector → spec/dead-code.md └─ fidelity-judge → verifies sampled citations against source Phase 4: Arc42 Assembly └─ /dds:assemble spec-assembler → spec/01-introduction-goals.md ... spec/12-glossary.md ``` ## 命令 | 命令 | 用途 | 开销 | |---|---|---| | [`/dds:survey`](skills/survey/SKILL.md) | 阶段 1 — 检测技术栈、模块、入口点、部署拓扑结构及挖掘成本 | 快速（约 30 分钟） | | [`/dds:excavate`](skills/excavate/SKILL.md) | 阶段 2 — 针对每个模块进行深入挖掘，采用引用优先的陈述并进行保真度验证 | 高（数小时/数天） | | [`/dds:assemble`](skills/assemble/SKILL.md) | 阶段 4 — 将各模块的规范综合提炼为 Arc42 12 节规范 | 中等 | ## Agents 以下的 Agents 均与具体模型无关 —— Agent 的元数据中并没有绑定特定模型。每个 SKILL.md 在调度子 Agent 时都会推荐一个合适的能力级别，但最终的选择取决于宿主平台和用户。 | Agent | 建议能力 | 何时使用 | |---|---|---| | [`dds:surveyor`](agents/surveyor.md) | 快速，广度优先 | 阶段 1 侦察 — 技术栈、模块映射图、入口点 | | [`dds:module-excavator`](agents/module-excavator.md) | 强阅读，结构化输出 | 每个模块对应一个 — 逐行阅读，生成模块规范 | | [`dds:data-archaeologist`](agents/data-archaeologist.md) | 强 SQL/数据库推理 | 提取数据库 schemas、SQL 查询、存储过程、ORM 映射 | | [`dds:business-rule-extractor`](agents/business-rule-extractor.md) | 强推理能力 | 寻找校验、计算、工作流、authz（授权）规则；标注所有来源 | | [`dds:integration-mapper`](agents/integration-mapper.md) | 快速模式识别 | 外部边界 — HTTP、队列、文件 I/O、定时任务、FFI | | [`dds:dead-code-detector`](agents/dead-code-detector.md) | 轻量级 | 查找带有置信度评级的疑似无用代码 | | [`dds:spec-assembler`](agents/spec-assembler.md) | 强综合能力 | 将各模块规范综合提炼为 Arc42 各节内容 | | [`dds:fidelity-judge`](agents/fidelity-judge.md) | 强精准推理 | 随机抽样引用并与源代码进行比对验证 | ## 输出结构 ``` spec/ # DDS primary output — visible, committed ├── 00-survey.md # Phase 1: stack, module map, entry points ├── 01-introduction-goals.md # Arc42 §1 ├── 02-constraints.md # Arc42 §2 ├── 03-context-scope.md # Arc42 §3 ├── 04-solution-strategy.md # Arc42 §4 ├── 05-building-blocks.md # Arc42 §5 ├── 06-runtime.md # Arc42 §6 ├── 07-deployment.md # Arc42 §7 ├── 08-concepts.md # Arc42 §8 ├── 09-decisions.md # Arc42 §9 — reconstructed ADRs ├── 10-quality.md # Arc42 §10 ├── 11-risks-debt.md # Arc42 §11 ├── 12-glossary.md # Arc42 §12 ├── modules/.md # Per-module deep dive ├── data-dictionary.md # Tables, columns, types, constraints ├── sql-inventory.md # Every query + stored proc with purpose ├── business-rules.md # Validations, calculations, workflows, authz ├── integrations.md # External system boundaries ├── dead-code.md # Orphaned code with verification flags └── .dds-state.json # Per-module excavation state ``` ## 模式 本插件实现了以下关键模式： - **引用优先的陈述** — 每一个关于行为的陈述都标注了 `[file:line]`。未标注的陈述将在 fidelity-judge 检查时自动失败。有效降低大模型幻觉引发的虚假业务规则风险。 - **随机抽样的保真度验证** — LLM-as-Judge 抽取 10% 的引用（可配置），阅读被引用的代码行并进行保真度评分。能在错误规则进入规范之前，提前捕获 WRONG_LINES、WRONG_FILE 和 HALLUCINATION（幻觉）等判定结果。 - **强制逐行阅读** — Module-excavator 的提示词要求必须对每一个非平凡文件执行 Read 操作（禁止仅从文件名或注释中进行粗略推断）。 - **多 Agent 上下文隔离** — 每个模块对应一个 Agent + 每个关注点（数据、集成、规则、死代码）对应一个 Agent。没有任何一个 Agent 会将整个代码库全盘放入上下文中。 - **基于暂存区的综合** — 每个 Agent 先将原始发现转储到 `.specs/scratchpad/.md`，然后再将经过验证的陈述综合提炼到规范中。 - **基于磁盘的状态机** — `spec/.dds-state.json` 记录每个模块的状态：`unexplored → surveyed → excavated → excavated_with_warnings`。 ## 与 SDD 的关系 DDS 和 SDD 在概念上是互补的，但在操作上是解耦的。DDS 负责生成规范；如果你想驱动代码重写，可以手动调用 SDD 的 `/plan-task` 和 `/implement-task`，并指向对应的 `spec/modules/.md` 文件。在 v1 版本中没有自动化的衔接桥梁。 | 维度 | SDD (正向) | DDS (逆向) | |---|---|---| | 方向 | 规范 → 代码 | 代码 → 规范 | | 流程 | 自上而下的设计 | 自下而上的挖掘 | | 业务分析师 | 发明验收标准 | 从代码中提取规则 | | 架构阶段 | 综合设计 | 重构设计 | | 评判者 (Judges) | 评估计划质量 | 评估规范保真度 | ## 感性逆向工程 vs 忠实逆向工程 fidelity-judge 是 DDS 区别于“让我读读代码然后写个 Markdown 总结”方法的关键所在。如果没有它，LLM 会自信地凭空捏造听起来合理但实际上根本不存在的业务规则。有了它，每一个陈述都有据可查。 为了提升速度，你可以带上 `--skip-judges` 运行，但这样得出的规范其可信度并不比单次 LLM 总结生成的结果高。 为了进一步提高保真度，你可以提高抽样率（`--sample-rate 0.25`）或阈值（`--target-fidelity 4.5`），但这会增加 Token 的开销。 ## 理论基础 - **Arc42** ([arc42.org](https://arc42.org)) — 规范树所遵循的架构文档标准 - **Chain-of-Verification** ([arXiv:2309.11495](https://arxiv.org/abs/2309.11495)) — 启发了“先引用、后验证”的模式 - **LLM-as-a-Judge** ([arXiv:2306.05685](https://arxiv.org/abs/2306.05685)) — 用于保真度验证环节 - **软件检查抽样** — 随机抽样声明验证，经典的软件工程 (SE) 质量保证 (QA) 技术 - 遗留系统现代化文献中的通用逆向工程实践 ## 设计 有关完整的架构设计原理，请参阅 [docs/design.md](docs/design.md) —— 涵盖了流水线阶段、引用优先的约束机制、fidelity-judge 方法论以及设计过程中探讨的各种权衡。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI4Code, AI编程, Arc42, C2, Delphi, DevOps工具链, DLL 劫持, JavaEE, LLM作为裁判, OpenVAS, PHP, PyRIT, RubyonRails, 业务规则提取, 云安全监控, 云资产清单, 代码分析, 代码文档化, 代码理解, 凭证管理, 单体架构重构, 多智能体系统, 大语言模型, 技术债务治理, 文档自动生成, 系统架构文档, 软件架构, 软件现代化, 逆向工程, 遗留代码重构, 遗留系统现代化, 防御加固, 静态分析