Legacy Squad Framework

AI 驱动的遗留系统现代化平台

理解。规划。现代化。

🇧🇷 葡萄牙语 · 🇺🇸 英语

``` npx legacy-squad install ```

🔑 零 API 密钥  ·  ☁️ 零外部服务器  ·  💻 在你自己的 IDE 中运行 (Claude Code, Codex, Cursor)

## 📊 在生产环境中得到验证 真实的移动端生产应用 — **约 18,000 LoC**，**98 个依赖**，真实的金融交易： | | | |---|---| | 🔍 **50 项发现**（7 项确定性 + 43 项来自 AI agent） | 📐 **从代码中提取了 63 条业务规则**（11 条隐式） | | 📄 **4 份官方文档**（PRS · SDD · MMP · Specs） | 🎯 **37 个执行规范**，原子化且可部署 | | 📈 **执行准备度：** 38 → 88 / 100 | 🚀 **可部署性：** 按阶段评分 | 只需一个 `npx legacy-squad install` 命令，然后在 IDE 中执行 9 个 slash 命令。 [**→ 阅读完整案例研究**](docs/CASE_STUDY.md) ## 🚀 快速开始 ### 前置条件 - **Node.js ≥ 18** - **支持 AI 的 IDE：** [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex CLI](https://github.com/openai/codex) 或 [Cursor](https://cursor.sh) ### 1. 安装到你的遗留项目中 ``` cd your-legacy-project npx legacy-squad install ``` 执行后，你会立即在 `.legacy-squad/memory/` 中看到框架生成的产出物： - `repo-index.json` — 完整清单（技术栈、模块、依赖、集成） - `findings.json` — 确定性安全发现（OWASP / CWE） - `context-packs.json` — 每个模块的上下文，已为 AI agent 准备就绪

install 命令内部执行的操作

1. 通过清单检测技术栈（`package.json`、`composer.json`、`.csproj`、`pom.xml`） 2. 扫描代码库并构建清单 3. 运行带有 OWASP / CWE 规则的合规引擎 4. 为每个模块生成上下文包（token 高效） 5. 在你的 IDE 中以 slash 命令形式安装这 9 个 agent 6. 验证安装（8 项健康检查）

### 2. 运行你的第一个 AI agent 在项目中打开你的 IDE 并触发 Security Agent。 **Claude Code** ``` claude /legacy-squad-security ``` **Codex CLI** ``` codex @legacy-squad-security ``` 评估结果将写入： ``` .legacy-squad/outputs/assessments/security.md ``` 证据驱动：每项发现都包含 文件:行号 引用、OWASP / CWE 映射、影响和建议 — 完全由在你 IDE 内部运行的 AI 生成。 ### 3. 运行全面诊断 当你对第一个 agent 感到满意后，运行其余四个 agent 以及四个产出物生成器。

完整工作流 — 5 个 agent + 4 个生成器

**第 1 步 — 分析（按顺序运行）** ``` /legacy-squad-security # Security Agent /legacy-squad-architecture # Architecture Agent /legacy-squad-legacy-code # Legacy Code Agent /legacy-squad-business-rules # Business Rules Agent /legacy-squad-modernization # Modernization Agent ``` **第 2 步 — 汇总产出物（在分析后运行）** ``` /legacy-squad-generate-prs # Product Refactor Specification /legacy-squad-generate-sdd # Software Design Document /legacy-squad-generate-mmp # Modernization Master Plan /legacy-squad-generate-specs # Execution Specs (one YAML per unit of work) ```

### 其他命令 ``` npx legacy-squad scan # Re-scan without reinstalling agents npx legacy-squad doctor # Verify installation health ``` ## 为什么选择 Legacy Squad 大多数现有工具只覆盖遗留系统现代化的一个维度。Legacy Squad 覆盖了完整的生命周期 — 从清单梳理到可执行计划 — 并将 AI agent 视为**受方法论约束的参与者**，而不是自由形式的聊天。 | 能力 | 静态分析器
(SonarQube) | SAST / SCA
(Snyk, Checkmarx) | AI 编程助手
(Copilot, Cursor) | **Legacy Squad** | |---|:---:|:---:|:---:|:---:| | 确定性安全规则 (OWASP / CWE) | ✅ | ✅ | — | ✅ | | CVE / 依赖漏洞 | — | ✅ | — | — | | 代码异味与认知复杂度 | ✅ | 部分 | — | ✅ | | 架构映射 (C4, 耦合) | — | — | — | ✅ | | 从代码中提取业务规则 | — | — | — | ✅ | | 分阶段的现代化计划 (MMP) | — | — | — | ✅ | | 原子化、可部署的执行规范 | — | — | — | ✅ | | 输出受证据约束的 AI agent | — | — | 自由形式 | ✅ | | 在你自己的 IDE 中运行（无服务器、无 API 密钥） | — | — | ✅ | ✅ | | 代码库从不会完整发送给 LLM | 不适用 | 不适用 | — | ✅ | 用一句话概括：Legacy Squad 将**确定性扫描**与**受方法论约束的 AI agent** 相结合，生成**结构化的工程产出物**（PRS、SDD、MMP、执行规范） — 而不是聊天记录。 ### 适用场景 - 你有一个处于生产环境的遗留系统，需要在决定现代化什么之前进行**结构化诊断**。 - 你希望每项发现都带有**证据、框架参考、影响和建议** — 而不是毫无根据的建议。 - 你需要一个**分阶段的现代化计划**，该计划是可逆的、可部署的，并且在执行前可由人类批准。 - 你想要 AI 辅助，但**不想将代码库发送到外部服务器**，也不想为此支付另一个席位费用。 ### 不适用场景 - 对于纯粹的 CVE / 依赖漏洞扫描，请使用 [Snyk](https://snyk.io)、[Dependabot](https://github.com/dependabot) 或类似工具 — 它们专门研究此领域，Legacy Squad 不能替代它们。 - 对于持续 CI/CD 代码质量关卡，请使用 [SonarQube](https://www.sonarsource.com/products/sonarqube/) — Legacy Squad 是一个**诊断和规划**框架，而不是持续的质量监控器。 - 对于编辑器内的自动补全或通用编程聊天，[GitHub Copilot](https://github.com/features/copilot) 和 [Cursor](https://cursor.sh) 已经满足了该需求 — Legacy Squad 是从它们停止的地方开始的。 ## 工作原理 ``` ┌─────────────────────┐ │ npx legacy-squad │ │ install │ └─────────┬───────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌────────────┐ ┌────────────┐ │ Scanner │ │ Compliance │ │ Context │ │ (stack, │ │ Engine │ │ Manager │ │ modules) │ │ (OWASP) │ │ (packs) │ └────┬─────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────┐ │ .legacy-squad/memory/ │ │ repo-index.json | findings.json | │ │ context-packs.json │ └──────────────────┬───────────────────────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ .claude/ │ │ AGENTS.md│ │ .cursor/ │ │ commands/│ │ (Codex) │ │ rules/ │ │ (Claude) │ │ │ │ (Cursor) │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └─────────────┼─────────────┘ │ ┌──────▼──────┐ │ IDE + AI │ │ (Claude Code│ │ Codex, │ │ Cursor) │ └──────┬──────┘ │ ┌──────▼──────┐ │ Assessments │ │ + Final PRS │ └─────────────┘ ``` **该框架准备数据并安装 agent。AI 在开发者的 IDE 中运行。** 无需 API 密钥。零外部服务器调用。一切都在本地运行。 ## 安装后的结构 执行 `npx legacy-squad install` 后： ``` your-project/ ├── .legacy-squad/ │ ├── config/ │ │ └── project.yaml # Detected configuration │ ├── memory/ │ │ ├── repo-index.json # Repository inventory │ │ ├── findings.json # Compliance engine findings │ │ └── context-packs.json # Context per module │ ├── outputs/ │ │ ├── assessments/ # Agent assessments (5 .md files) │ │ ├── reports/ # PRS.md + PRS.json │ │ ├── sdd/ # SDD.md + SDD.json │ │ ├── mmp/ # MMP.md + MMP.json │ │ └── specs/ # SPEC-*.yaml + INDEX.md │ └── logs/ │ └── install.log ├── .claude/ │ └── commands/ │ └── legacy-squad/ │ ├── security.md # /legacy-squad-security │ ├── architecture.md # /legacy-squad-architecture │ ├── legacy-code.md # /legacy-squad-legacy-code │ ├── business-rules.md # /legacy-squad-business-rules │ ├── modernization.md # /legacy-squad-modernization │ ├── generate-prs.md # /legacy-squad-generate-prs │ ├── generate-sdd.md # /legacy-squad-generate-sdd │ ├── generate-mmp.md # /legacy-squad-generate-mmp │ ├── generate-specs.md # /legacy-squad-generate-specs │ └── scan.md # /legacy-squad-scan └── AGENTS.md # Codex compatibility ``` ## Agent ### Security Agent (`/legacy-squad-security`) 分析身份验证、密钥、不安全的存储、PII 暴露以及隐私合规性 (LGPD, GDPR)。 **参考：** OWASP MASVS V2, OWASP ASVS, CWE Top 25, LGPD, GDPR, NIST SSDF ### Architecture Agent (`/legacy-squad-architecture`) 使用 C4 图表映射当前架构，识别耦合、结构性风险，并提出增量目标架构建议。 **参考：** C4 Model, Clean Architecture, arc42, ADR ### Legacy Code Agent (`/legacy-squad-legacy-code`) 识别热点、重复代码、JS→TS 迁移进度、测试覆盖率以及重构优先级。 **参考：** Clean Code, Sonar Rules, Cognitive Complexity ### Business Rules Agent (`/legacy-squad-business-rules`) 提取隐藏在代码中的业务规则 — 验证、权限、流程、魔术数字、catch 块中的隐式规则。 **参考：** DDD, Event Storming ### Modernization Agent (`/legacy-squad-modernization`) 将所有评估综合为一个包含阶段、回滚、可部署性评分 (1-10) 和执行准备度评分 (0-100) 的增量计划。 **参考：** Strangler Fig, Branch by Abstraction, Progressive Delivery ### PRS Generator (`/legacy-squad-generate-prs`) 将所有评估整合到 PRS（产品重构规范）中 — 这是为决策者提供的诊断报告。 ### SDD Generator (`/legacy-squad-generate-sdd`) 生成软件设计文档，包含当前和目标架构（Mermaid C4 图表）、组件清单、集成、横切关注点（安全性、可观测性、错误处理、配置）、约束，以及记录了所考虑替代方案的架构决策记录 (ADR)。 **参考：** C4 Model, arc42, ADR, Clean Architecture ### MMP Generator (`/legacy-squad-generate-mmp`) 生成现代化总体计划，包含阶段路线图（基础 → 核心 → 演进，当存在严重发现时带有可选的紧急阶段）、技术栈升级计划、风险矩阵、每个阶段的回滚策略、按维度论证的执行准备度评分 (0-100)、每个阶段的可部署性评分，以及涵盖安全性、代码质量、测试覆盖率和架构的成功指标。 **参考：** Strangler Fig, Branch by Abstraction, Progressive Delivery ### Execution Specs Generator (`/legacy-squad-generate-specs`) 将 MMP 分解为原子化的执行规范 — 每个工作单元一个 YAML 文件，每个都可独立部署，具有二元验收标准、强制回滚策略、证据可追溯性（合规发现 ID + 评估参考）、规范之间的依赖图，以及用于高风险更改的显式 `human_approval_required` 标志。 **参考：** FRAMEWORK_SPECIFICATION 第 8 节（执行规范 schema） ## 支持的技术栈 ### 清单检测（第 1 层 — 确定性） | 清单 | 技术栈 | |----------|-------| | `package.json` | Node.js, React, React Native, Expo, Next.js | | `composer.json` | PHP, Laravel | | `.csproj` | C#, .NET | | `pom.xml` | Java, Spring Boot | ### 扩展检测（第 2 层 — 启发式） TypeScript, JavaScript, PHP, C#, Java, Python, Dart ## 合规引擎 扫描器会自动运行基于 OWASP 和 CWE 的确定性规则： | 规则 | 检测内容 | 技术栈 | 参考 | |------|---------|--------|-----------| | SEC-CRED-001 | 硬编码的凭据（密码、API 密钥、token） | 全部 | OWASP MASVS, CWE-798 | | SEC-CRED-002 | 提交到代码库的 Keystore/证书 | 移动端, 全部 | OWASP MASVS, CWE-312 | | SEC-SQL-001 | SQL 注入（查询中的字符串拼接） | PHP, .NET, Java, Node | OWASP A03, CWE-89 | | SEC-CRYPTO-001 | 弱密码学（MD5, SHA1） | PHP, .NET, Java, Node | OWASP A02, CWE-327 | | SEC-DESER-001 | 不安全的反序列化（BinaryFormatter, `unserialize`, `readObject`） | .NET, PHP, Java | OWASP A08, CWE-502 | | SEC-CMD-001 | 命令注入（带有用户输入的 `exec`, `Runtime.exec`, `shell_exec`） | PHP, .NET, Java, Node | OWASP A03, CWE-78 | | SEC-PATH-001 | 路径遍历（未经验证的文件路径） | PHP, .NET, Java, Node | OWASP A01, CWE-22 | | SEC-XSS-001 | 通过未转义输出引起的 XSS（`echo $_GET`, `Html.Raw`） | PHP, .NET | OWASP A03, CWE-79 | | SEC-LOG-001 | 生产环境中的活动 `console.log` | JS/TS, 移动端 | CWE-532 | | SEC-LOG-002 | 日志/外部服务中的 PII（CPF, SSN, ID） | 全部 | CWE-532, LGPD/GDPR | | SEC-ERR-001 | 空的 catch 块 | 全部 | CWE-390 | | SEC-STORE-001 | AsyncStorage 中的 Token（不安全的存储） | 移动端 | OWASP MASVS | | CQ-MIX-001 | JS 和 TS 文件混合（未完成的 TS 迁移） | JS/TS | Clean Code | | CQ-DEPRECATED-001 | 已废弃的 API（`mysql_*`, `ereg`, `Vector`） | PHP, Java | CVE 分类 | 每项发现都包含：证据（文件、行号、代码片段）、影响、技术参考和建议。 ## 原则| 原则 | 描述 | |-----------|-------------| | **安装优先** | 一个命令安装一切。无需手动设置。 | | **IDE 原生** | Agent 是 IDE 的 slash 命令。AI 来源于开发者的环境。 | | **证据驱动** | 每项发现都有具体的证据（文件、行号、代码片段）。 | | **上下文优先** | 没有任何 LLM 会接收整个代码库 — 仅接收上下文包。 | | **只读** | 该框架不修改代码。它只读取并生成报告。 | | **生产优先** | 每个建议都假设系统处于生产环境中。 | | **增量式** | 每个现代化步骤都是增量的、可逆的且可部署的。 | ## 在生产环境中得到验证 该框架针对一个**生产环境移动应用**（约 1.8 万行代码、98 个依赖、真实的金融交易）进行了验证： **合规引擎（确定性）：** 通过模式匹配发现 7 项问题 **AI Agent（通过 Claude Code）：** +43 项额外发现，包括： - 源代码中从 Base64 解码出的服务账号凭据 - 能够在生产环境中绕过所有身份验证的远程配置标志 - 以明文形式记录到云数据库中的用户密码 - 在云数据库中用作主键的 PII（可枚举） - 在未经用户同意的情况下捕获敏感数据的会话记录 - 从代码中提取的 63 条业务规则（11 条隐式规则，从未记录在案） - 影响核心业务逻辑的日期计算中的潜在 bug **生成的产出物（V1 的 4 项官方交付物）：** - **PRS** — 整合诊断结果的产品重构规范 - **SDD** — 包含当前/目标架构和 8 个 ADR 的软件设计文档 - **MMP** — 包含 4 阶段路线图（紧急 → 基础 → 核心 → 演进）、执行准备度评分 38→88/100、各阶段可部署性评分以及具体回滚策略的现代化总体计划 - **37 个执行规范** — 具有二元验收标准、强制回滚、证据可追溯性和依赖图的原子化、可独立部署的工作单元 **总计：** 只需一个 `npx legacy-squad install` 随后激活 9 个 slash 命令，即可获得 50 项发现 + 4 份汇总产出物 + 37 个可执行规范。 ## 开源核心 ### 社区版 (V1) — 开源 重点：**理解 + 规划** - 具有多技术栈检测的扫描器（PHP/Laravel/Symfony、.NET/ASP.NET、Java/Spring、Node、React Native/Expo） - 带有 14 项确定性规则的合规引擎（OWASP MASVS, ASVS, CWE Top 25） - 上下文管理器（基础版） - **5 个分析 agent**（作为 slash 命令）：security, architecture, legacy-code, business-rules, modernization - **4 个产出物生成器**（作为 slash 命令）：PRS, SDD, MMP, Execution Specs - 支持 Claude Code, Codex CLI（Cursor / Gemini CLI 在路线图中） ### 企业版 (V2) — 开发中 重点：**现代化** - 执行引擎（AI 辅助重构） - Pull Request 引擎 - QA 关卡 - CI/CD 集成 - 自定义规则包 - 仪表板 + 团队协作 ## 路线图 | 周期 | 阶段 | 状态 | |---|---|---| | **当前** | V1 社区版 — 持续改进 | 🔵 活跃 | | **下一步** | V2 企业版 — 执行、重构、PR | 🟡 设计中 | | **未来** | V3 自主版 — 持续现代化 | ⚪ 愿景 | [**→ 完整路线图**](ROADMAP.md) ## 开发 ``` git clone https://github.com/hrpimenta/legacy-squad.git cd legacy-squad pnpm install pnpm approve-builds esbuild # Tests npx vitest run # Dev 模式 (无 build) npx tsx apps/cli/src/index.ts install -p /path/to/project # Build node build.mjs # 测试 bundled 版本 node dist/cli.mjs install -p /path/to/project ``` ### Monorepo 结构 ``` legacy-squad/ ├── packages/ │ ├── core/ # Domain types, ports (Clean Architecture) │ ├── scanner/ # Stack detection, repo index generation │ ├── context/ # Context packs builder │ ├── rules/ # Compliance engine, rule catalog │ ├── agents/ # Agent definitions, installer, doctor │ └── output/ # PRS generator ├── apps/ │ └── cli/ # CLI entry point (Commander.js) ├── templates/ │ └── claude-commands/ # Slash command templates └── docs/ └── plans/ # Architecture decisions, plans ``` ### 测试 ``` npx vitest run # 93 tests (domain, scanner, compliance, agents, installer) npx vitest --watch # Watch mode ``` ## 贡献 我们欢迎各种贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解： - 如何添加合规引擎规则 - 如何改进 agent 模板 - 如何添加 IDE 支持 - 工程标准（TDD, SOLID, 安全性） - 提交约定和 PR 流程 如有问题和提案，请[发起讨论](https://github.com/hrpimenta/legacy-squad/discussions)。 ## License MIT — 详情请参阅 [LICENSE](LICENSE)。

理解。规划。现代化。
Legacy Squad Framework

标签：AI辅助开发, GNU通用公共许可证, Homebrew安装, MITM代理, Node.js, SOC Prime, 业务逻辑提取, 云安全监控, 代码现代化, 开发工具, 暗色界面, 系统重构, 自动化攻击, 静态分析