Reversa — 詳細教學與資安審查

Reversa 是把「legacy system (傳統系統)」變成「executable specifications (可執行規格)」的逆向工程框架。本教學帶你從零理解、安裝、實際跑一輪、評估資安、整合進現有工作流。

1. 專案定位

1.1 它解決什麼問題

單行版本：你接手一個沒有文件、原作者已離職、不敢動的 legacy codebase，但需要讓 AI agent 幫你維護或重寫——Reversa 就是「先讓 agent 看懂這個系統」的那一層。

長版本：

• 現代 coding agent (Claude Code / Codex / Cursor) 在 greenfield (綠地新專案) 表現極好，因為你可以給它清晰的 spec。
• 在 brownfield (棕地舊專案) 表現崩潰，因為「implicit knowledge (隱性知識)」散落在 code、commit history、SQL、validation、註解、員工腦袋裡。
• Reversa 的核心命題：在 agent 動手前，先把隱性知識抽出來變成可審計的 spec。
• 三層信心標記（🟢 CONFIRMED / 🟡 INFERRED / 🔴 GAP）讓你知道「哪些可以信、哪些是猜的、哪些必須問人」。

1.2 它不是什麼

• ❌ 不是 AI 程式碼產生器（不寫一行新功能）
• ❌ 不是 純文件產生器（產出是「operational contract (可執行契約)」，不是給人讀的 README）
• ❌ 不是 LLM API 包裝器（不要 API key，完全委派給你本地的 coding agent）
• ❌ 不是 linting / SAST 工具

1.3 適用場景

2. 安裝指南

2.1 系統需求

• Node.js ≥ 18.20.2（純 ES Module，無 transpile）
• 任一支援的 coding agent：Claude Code / Codex / Cursor / Gemini CLI / Windsurf / Cline / Roo Code / GitHub Copilot / Aider / Amazon Q Developer（共 13 種）
• 磁碟：< 5 MB（npm 套件 + agent skill 檔案）

2.2 安裝步驟

1# 1. 進到 legacy 專案根目錄
2cd /path/to/your-legacy-project
3
4# 2. （強烈建議）先 git commit + push 一份備份
5git add -A && git commit -m "backup before reversa"
6git push  # 或 cp -r . ../backup
7
8# 3. 安裝 Reversa（會跑互動式 installer）
9npx reversa install

Installer 會做什麼：

1. 偵測目錄裡已有的 AI engine（看有沒有 CLAUDE.md / .cursorrules / .windsurfrules …）
2. 詢問你要裝哪些 agent team（6 個 team，預設全勾）
3. 蒐集專案名、主要語言、偏好設定
4. 複製 agent 到 .agents/skills/（共用）+ .claude/skills/（Claude Code 專用）
5. 在每個引擎的標準位置建立 entry file（CLAUDE.md / AGENTS.md / .cursorrules …）
6. 建立 .reversa/ 目錄結構：state.json / config.toml / plan.md / version
7. 計算所有檔案的 SHA-256 manifest，存到 .reversa/_config/files-manifest.json

2.3 安裝流程圖

flowchart TD
  A["你: cd legacy-project"] --> B["你: npx reversa install"]
  B --> C{"偵測現有引擎"}
  C -->|有 CLAUDE.md| D["✅ Claude Code"]
  C -->|有 AGENTS.md| E["✅ Codex / Opencode / Antigravity"]
  C -->|有 .cursorrules| F["✅ Cursor"]
  C -->|都沒有| G["互動選擇引擎"]
  D & E & F & G --> H["詢問要裝哪些 Team
(預設全勾)"]
  H --> I["複製 agents/ → .agents/skills/
+ .claude/skills/ 等"]
  I --> J["建立 .reversa/ 結構
state.json / config.toml / plan.md"]
  J --> K["生成 SHA-256 manifest"]
  K --> L["✅ 安裝完成"]

2.4 不可變保證（安裝前必讀）

🔒 Reversa 從不修改或刪除你的既有檔案。

Installer 只新增檔案（CLAUDE.md / AGENTS.md / .agents/skills/ …）。Agent 在分析過程中受到嚴格限制：所有寫入只能進 .reversa/ 與 _reversa_sdd/ 兩個目錄。

但 LLM 仍可能犯錯，強烈建議安裝前：

1. 把專案 git commit 並 push 到遠端
2. cp -r project project-backup 做本機備份

2.5 卸載

1npx reversa uninstall

只移除 Reversa 自己建立的檔案（會檢查 manifest），legacy project 任何檔案都不會動到。

3. 核心架構解析

3.1 五階段 Discovery Pipeline

/reversa 是整個框架的入口，由 Reversa 主 orchestrator 協調 5 個 phase：

flowchart LR
  S["1. Scout
偵察"] --> A["2. Archaeologist
挖掘"]
  A --> D["3. Detective
解讀"]
  D --> AR["4. Architect
合成"]
  D --> W["4. Writer
規格"]
  AR --> R["5. Reviewer
審查"]
  W --> R
  R --> OUT["📦 _reversa_sdd/
operational specs"]

每完成一個 agent，會把 checkpoint 寫到 .reversa/state.json，所以中途斷線、明天重來只要再打 /reversa 就會接續。

3.2 延伸 Pipeline（裝完 Discovery 之後可選擇）

flowchart TD
  D["Discovery (/reversa)
產出 _reversa_sdd/"]
  D --> F["/reversa-forward
spec → 可執行 code
(7-agent pipeline)"]
  D --> M["/reversa-migrate
spec → 新 stack rebuild
(6-agent pipeline)"]
  D --> DOC["/reversa-docs
spec → HTML mini-site
(4-agent pipeline)"]
  D --> P["/reversa-pricing-*
spec → 預算估算"]

  NEW["/reversa-new
greenfield 起手
(4-agent pipeline)"] --> F

3.3 六大 Team / ~50 個 agent 全表

Discovery Team（必裝，13 agents）

Code Forward Agents（feature evolution，~10 agents）

requirements → clarify → quality → plan → to-do → audit → coding，每階段一個 agent，全部 stage gate（必須輸入 CONTINUAR 才會推進）。

Migration Agents（legacy rebuild，6 agents）

Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector，產出 Strangler Fig / Big Bang / Parallel Run / Branch by Abstraction 等遷移策略 + Gherkin parity spec。

Documentation Team（HTML mini-site，4 agents + 5 shared skills）

Mapper → Analyst → Storyteller → Publisher，產出含 Three.js 3D Code City、D3 force-directed module graph、Highcharts treemap、client-side glossary search 的離線 HTML。

其他

• Code New Project Agents（4 agents）：greenfield 起手 (Ideator → Researcher → Drafter → Spec SDD)
• Pricing Team（3 agents）：pricing-profile / pricing-size / pricing-estimate
• Translators（1 agent）：N8N Translator 把 n8n workflow JSON 變成 SDD spec

3.4 輸出產物完整清單

 1_reversa_sdd/
 2├── inventory.md              # 專案清單
 3├── dependencies.md           # 依賴 + 版本
 4├── code-analysis.md          # 模組技術分析
 5├── data-dictionary.md        # 資料字典
 6├── domain.md                 # glossary + business rule
 7├── state-machines.md         # state machine (Mermaid)
 8├── permissions.md            # 權限矩陣
 9├── architecture.md           # 架構總覽
10├── c4-context.md             # C4: Context
11├── c4-containers.md          # C4: Container
12├── c4-components.md          # C4: Component
13├── erd-complete.md           # 完整 ERD (Mermaid)
14├── confidence-report.md      # 信心報告 🟢🟡🔴
15├── gaps.md                   # 識別出的 gap
16├── questions.md              # 待人工驗證的問題
17├── sdd/[component].md        # 每個 component 一份 spec
18├── openapi/                  # API spec (若有)
19├── user-stories/             # User story (若有)
20├── adrs/                     # 回溯式架構決策
21├── flowcharts/               # flowchart (Mermaid)
22├── sequences/                # sequence diagram
23├── ui/                       # UI spec (Visor 產)
24├── database/                 # DB spec (Data Master 產)
25├── design-system/            # design token
26└── traceability/
27    ├── spec-impact-matrix.md   # spec → spec 影響圖
28    └── code-spec-matrix.md     # code 檔案 → 對應 spec

/reversa-forward 每個 feature 額外產生：

1_reversa_forward/<NNN>-<short-name>/
2├── requirements.md / roadmap.md / investigation.md
3├── data-delta.md / onboarding.md / interfaces/
4├── actions.md / progress.jsonl
5├── legacy-impact.md / regression-watch.md
6└── audit/{requirements-audit.md, cross-check.md}

4. Helper Scripts 詳細用法

4.1 CLI 指令清單

1npx reversa install         # 互動式安裝
2npx reversa status          # 顯示當前分析狀態
3npx reversa update          # 升級 agent 到最新版（用 SHA-256 比對，不蓋你改過的檔）
4npx reversa add-agent       # 補裝某個 agent
5npx reversa add-engine      # 補裝某個引擎
6npx reversa uninstall       # 安全卸載
7npx reversa export-diagrams # 把所有 Mermaid block 匯出成 SVG/PNG
8                            # 選項: --format=svg|png --output=<folder>
9                            # 需先: npm install -g @mermaid-js/mermaid-cli

4.2 內部結構（安裝後）

 1.reversa/
 2├── state.json              # 跨 session 的分析狀態（checkpoint 機制）
 3├── config.toml             # 專案設定
 4├── config.user.toml        # 個人偏好（不要 commit）
 5├── plan.md                 # 探索計畫（使用者可手動編輯）
 6├── version                 # 安裝版本
 7├── context/
 8│   ├── surface.json        # Scout 產出
 9│   └── modules.json        # Archaeologist 產出
10└── _config/
11    ├── manifest.yaml       # 安裝 metadata
12    └── files-manifest.json # SHA-256 hash 表（給 update 用）
13
14.agents/skills/             # 共用 skill 目錄（所有引擎共用）
15.claude/skills/             # Claude Code 專用 mirror

4.3 lib/ 內部模組（1,912 行 JS，15 個檔案）

5. 應用場景

5.1 場景 A：接手 COBOL ATM 系統要評估改造（paper 的 case study）

1cd /atm-cobol-legacy
2npx reversa install                # 裝完
3# 在 Claude Code 裡輸入
4/reversa                            # 跑完 Discovery
5# → 產出 _reversa_sdd/（517 個 claim、10 個 gap、53 個 Gherkin scenario）
6
7/reversa-migrate                    # 接著問遷移策略
8# → 建議 Strangler Fig，產出 Go target architecture + parity spec

5.2 場景 B：想在現有系統加新 feature

1cd /existing-project
2npx reversa install
3/reversa                            # 先建立 spec baseline
4/reversa-forward                    # 啟動 feature 開發
5# Reversa 會自動偵測現在在哪個階段（requirements / clarify / quality / plan / to-do / audit / coding）
6# 一階段一階段推，每階段都要你 CONTINUAR 才會跑下一步

5.3 場景 C：把系統的內部運作做成可分享的 HTML

1cd /already-installed-project
2/reversa-docs                       # 啟動 Documentation Team
3# → .reversa/documentation/index.html（含 3D Code City + D3 module graph + 互動 deck）
4# → 完全 offline，file:// 雙擊就能開

5.4 場景 D：Greenfield，從一句話 idea 開始

1mkdir my-new-project && cd my-new-project
2npx reversa install
3/reversa-new                        # Ideator → Researcher → Drafter → Spec SDD
4# → 4 個檔案：ideation.md / personas.md / prd.md / sdd/*.md
5/reversa-forward                    # 接著寫 code

5.5 場景 E：在 sandbox 評估第三方 legacy（搭配本知識庫的 meeting-intel）

1# 對方廠商提供 source code 想評估技術風險
2git clone <vendor-repo> /tmp/vendor-sandbox
3cd /tmp/vendor-sandbox
4npx reversa install
5/reversa                            # 跑 Discovery
6# → 用 confidence-report.md + gaps.md 寫成戰術 brief 給 meeting

6. 資安掃描報告

掃描範圍：v1.2.47 (5aee5f4) — lib/、bin/、agents/reversa/SKILL.md、README、package.json 掃描方式：grep -rn -E "eval\(|exec\(|child_process|spawn|shell.*=.*true|fs\.write|fetch\(|process\.env|password|api_key|secret|token"

6.1 紅綠燈總覽

6.2 細項

6.3 進階建議

• ✅ 安裝前 git commit + push 一份完整備份（即使 Reversa 不改你的檔，agent 仍可能誤動）
• ✅ 在隔離環境（Docker / sandbox）先試一次再放進生產 repo
• ⚠️ 注意：跑 Reversa 時你本地的 coding agent（Claude Code / Cursor）會讀整個 codebase 並送到該服務的 LLM —— 這是 agent 本身的資料外送，不是 Reversa 造成。有合規限制的程式碼不要跑
• ⚠️ 13 種引擎的 entry file（CLAUDE.md / AGENTS.md …）會被新增到 repo 根目錄，要記得 .gitignore 或選擇性 commit

7. FAQ

Q1: Reversa 自己會呼叫 LLM 嗎？要不要 API key？

不會、不要。Reversa 只是把 agent skill 寫到你的專案，真正執行 LLM 的是你本地的 coding agent（Claude Code / Codex / Cursor 之類）。Reversa 自己只是 Node.js CLI，沒有任何 LLM 依賴。

Q2: 13 種引擎都要裝？

不用。installer 會偵測你已有的引擎，只在偵測到的引擎建立 entry file。/reversa add-engine 可以事後補。

Q3: 跟 Continue / Cline / Aider 這種「自己會跑 LLM」的工具有衝突嗎？

無衝突。Reversa 對所有引擎一視同仁——你愛用哪個 agent 就在哪個 agent 裡呼叫 /reversa。

Q4: 我的專案不是 legacy 也想用怎麼辦？

• 新專案 → /reversa-new（greenfield pipeline）
• 既有專案要演進新 feature → /reversa-forward
• 想做文件 mini-site → /reversa-docs（issue #11 證實這個用法）

Q5: COBOL / Delphi / VB6 / Clipper 這種冷門語言支援嗎？

支援。Reversa 的 agent 用 LLM 做語意分析，不靠 AST parser。paper 的 case study 就是 ATM COBOL → Go。

Q6: 升級會不會蓋掉我手動改過的 agent 設定？

不會。npx reversa update 用 SHA-256 manifest 偵測你改過的檔，會跳過。

Q7: 跑完後輸出在哪？

預設 _reversa_sdd/，可在 .reversa/config.toml 改 output_folder。

Q8: 中途斷線怎麼辦？

重新打 /reversa，Reversa 會讀 .reversa/state.json 從上次 checkpoint 接續。

Q9: 跟「model-driven reverse engineering」/ XIS-Reverse / ProMeTA 有什麼不同？

那些是學術派傳統做法（用 metamodel + AST），Reversa 是 LLM-native：靠多 agent 分工 + 信心標記 + 缺口可視化。詳見 arXiv paper §2.5「Positioning synthesis」。

Q10: 為什麼產出物叫「operational contract」而不是「documentation」？

因為目標讀者是 coding agent 不是人。Spec 需要：可機器讀、有 traceability（連回 code 檔案 + 行號）、有信心標記、有 gap 明示——這些屬性比可讀性重要。

8. 進階技巧

8.1 用 stage gate 控制進度

每個 orchestrator 都會在 agent 之間停下來等使用者輸入 CONTINUAR。如果你想自動跑完，可以在 prompt 加「請自動繼續所有階段直到完成」。但對 legacy 系統強烈不建議——你會錯過 review 機會。

8.2 客製 agent

修改 .agents/skills/reversa-<agent>/SKILL.md，下次 update 會用 SHA-256 偵測「使用者已改」自動跳過。

8.3 匯出 Mermaid 為 SVG

1npm install -g @mermaid-js/mermaid-cli
2npx reversa export-diagrams --format=svg --output=./diagrams

把 _reversa_sdd/ 裡所有 mermaid block 抽出來變成可分享的 SVG。

8.4 多語言 mkdocs 站台

sandeco.github.io/reversa 提供英 / 葡 / 西三語文檔，可離線下載 mkdocs build 自架。

8.5 在 monorepo / 多服務專案怎麼跑

Reversa 偏好「一個 package 一個 install」。若 monorepo 有多服務（如 services/api / services/web），分別 cd 進去各裝一份。各自的 .reversa/ 互不干擾。

9. 整合進其他工作流

9.1 與 graphify（本知識庫 Layer 4）

Reversa 產出 _reversa_sdd/c4-*.md + erd-complete.md，可直接餵給 graphify：

1cp -r /your-project/_reversa_sdd projects/your-project-reversa
2cd projects/your-project-reversa
3graphify init .                     # 建 knowledge graph

9.2 與 gitnexus（Layer 6）

code-spec-matrix.md 是 code → spec 的對應，gitnexus 是 code → symbol。兩個併起來查 impact：

1gitnexus impact: <symbol>           # 哪些檔案會被影響
2# 再去 code-spec-matrix.md 查那些檔案對應到哪些 spec

9.3 與 paper-tutorial（Layer 15）

Paper 本人就是 arXiv 2605.18684。本工作流就是這層的實例化：

• ai-save 已存 paper md → inbox/2026-05-25-article-arxiv-org-html-2605-18684v1.md
• 本檔 + gh-save md 是 paper 的「reference implementation tutorial」

9.4 與 meeting-intel（Layer 14）

評估第三方 vendor 的 legacy 系統時：

1廠商寄 source code → 隔離 sandbox → npx reversa install → /reversa
2→ confidence-report.md + gaps.md 萃取要點
3→ 寫戰術 brief 到 docs/superpowers/specs/YYYY-MM-DD-meeting-intel-<vendor>.md

10. 重點摘要 Checklist

• Reversa 不是 LLM 包裝器，不要 API key，委派給本地 coding agent
• 安裝只新增檔案，從不修改 / 刪除 legacy 既有檔案
• 寫入受限於 .reversa/ + _reversa_sdd/ 兩個目錄
• 13 種 coding agent 引擎都支援
• ~50 個 agent 分 6 個 team，預設全裝
• 5-phase Discovery pipeline：Scout → Archaeologist → Detective → (Architect + Writer) → Reviewer
• 三層信心標記 🟢 CONFIRMED / 🟡 INFERRED / 🔴 GAP
• 中央 checkpoint：.reversa/state.json 允許跨 session 接續
• 安全：execFileSync + existsSync 守門，歷史 CVE #7 已修
• 升級用 SHA-256 manifest，不蓋你改過的檔
• 對應 paper：arXiv:2605.18684（Macedo & da Costa, 2026）

11. 進一步閱讀

• 倉庫：https://github.com/sandeco/reversa
• 三語 mkdocs 站台：https://sandeco.github.io/reversa/
• arXiv paper：https://arxiv.org/abs/2605.18684
• 本工作流產出的 gh-save md：inbox/2026-05-25-github-sandeco-reversa.md
• 本工作流存的 paper md：inbox/2026-05-25-article-arxiv-org-html-2605-18684v1.md
• 作者頻道（巴西葡語 AI 影片）：YouTube @sandecofilho
• 相關 issue：
  • #11 不做 migration，純文件用法（已加 /reversa-docs）
  • #13 建議擴充 Pentester / QA agent

本教學由 gh-tutorial-qd 工作流自動生成於 2026-05-25。對應的 quarkdown HTML 版本（paged / plain）已於 Discord 上傳。