Reversa

作者：sandeco

将遗留系统转化为 AI 编程代理（AI Agents）的可执行规范。

📄 论文： Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents — Macedo & da Costa，2026年5月。

Reversa 是一个规范反向工程框架。将其安装到遗留项目中，它将协调一组专门的 AI 代理来分析现有代码，并生成完整、可追溯的规范，供任何 AI 编程代理使用。

---

---

为什么需要 Reversa

大多数生产系统承载着多年积累的知识：隐含的业务规则、未记录的架构决策，以及埋藏在无人敢触碰的代码中的关键逻辑。这些知识虽然存在，但却被“困”住了。

AI 代理在创建和演进软件方面具有变革性，但它们必须依赖规范才能安全运行。对于新系统，你可以编写规范供代理执行；但对于遗留系统——或那些仅凭“直觉编码”（vibe coding）构建的系统——由于缺乏规范，代理根本无法得知哪些操作可能会破坏系统。

Reversa 是连接遗留系统与 AI 代理的桥梁。

它通过分析现有代码，提取积累的知识（业务规则、流程、模块契约、追溯性的架构决策），并将这一切转化为可执行、可追溯的规范，供任何编程代理使用。

其产出并非供人类阅读的文档，而是操作契约（operational contracts），使代理能够在忠于现有系统逻辑的前提下对其进行演进。

---

安装

在遗留项目的根目录下运行：

npx reversa install

安装程序将执行以下操作：

1. 检测环境中现有的 AI 引擎（如 Claude Code, Codex, Cursor 等）
2. 询问需要安装哪些代理（默认全选）
3. 收集项目名称、语言和偏好设置
4. 将代理复制到 .agents/skills/ 目录（若使用 Claude Code 则同时复制到 .claude/skills/）
5. 创建引擎入口文件（如 CLAUDE.md, AGENTS.md 等）
6. 创建 .reversa/ 结构，包含状态、配置和计划
7. 生成 SHA-256 清单以实现安全更新

Reversa 绝不会删除或修改你项目中的现有文件。 代理仅向 .reversa/ 目录和输出文件夹（默认为 _reversa_sdd/）写入内容。

要求： Node.js 18+

---

[!IMPORTANT]

🔒 保证遗留项目的不变性

安装程序仅会创建新文件（CLAUDE.md, AGENTS.md, .agents/skills/ 等），绝不会修改或删除项目中的任何现有文件。在分析过程中，代理遵循严格且不可违背的指令：所有写入操作均仅限于 .reversa/ 和 _reversa_sdd/ 目录——项目中其他任何文件都不会被触及。

[!CAUTION]

💾 开始前请备份你的项目

尽管 Reversa 不会修改你的文件，但 AI 代理可能会犯错。我们强烈建议：

1. 在 Git 中对项目进行版本控制 —— 确保在开始分析前已提交所有文件
2. 将仓库托管在 GitHub（或 GitLab, Bitbucket）—— 这样你拥有安全的远程副本
3. 创建文件夹的本地副本 —— 执行简单的 cp -r my-project my-project-backup 即可防止任何意外发生

如果分析过程中出现意外，你可以通过 git restore . 或从备份副本中恢复原始状态。

[!WARNING] 🔑 Reversa 不会请求、存储或传输任何 LLM 服务的 API 密钥。 所有智能能力均委托给环境中已有的 AI 代理（Claude Code, Codex, Cursor 等）——不涉及任何外部认证依赖。

---

如何使用

安装完成后，在 AI 代理中打开项目并激活 Reversa：

/reversa

对于不支持斜杠命令的引擎（如 Codex）：

reversa

Reversa 会进行自我介绍，创建个性化的探索计划，并协调整个分析过程。进度会在每个检查点保存到 .reversa/state.json 中——如果会话中断，只需再次输入 reversa 即可从上次停止的地方继续。

对于其他工作流，请使用相应的入口命令：

目标	命令