---
name: reverse_engineering
description: 当需要从现有代码推导设计意图和架构时使用此规则——包括项目反构（分析整个项目）和代码反向设计（分析单个文件）两种场景。适用于：理解大型项目架构、重构前分析、项目文档化、技术债务评估、代码迁移、跨语言实现参考。
---

# 反向工程规则

从现有代码提取设计信息，生成语言无关的设计方案。

## 两种场景

| 场景             | 适用情况                               |
| ---------------- | -------------------------------------- |
| **项目反构**     | 分析整个项目的架构、模块关系、整体设计 |
| **代码反向设计** | 分析单个文件或代码片段的功能和设计     |

**预期效果**：完整架构设计方案、清晰模块划分、组件依赖图、数据流分析、技术栈总结、语言无关设计。

---

# 核心原则

## 通用原则（两种场景均适用）

| 原则         | 要求                                       |
| ------------ | ------------------------------------------ |
| **完整性**   | 设计方案覆盖所有功能点，提供功能对照表验证 |
| **语言无关** | 不含具体语言语法，使用通用设计概念         |
| **可追溯**   | 记录每个设计决策对应的代码位置             |
| **清晰性**   | 使用准确语言描述，提供具体示例             |

## 项目反构专属原则

| 原则       | 要求                                     |
| ---------- | ---------------------------------------- |
| **系统性** | 从根目录开始，按目录层次组织分析         |
| **层次化** | 任务层次与目录层次一致，从顶到底逐层深入 |
| **模块化** | 明确每个模块的职责边界，分析模块间依赖   |

---

# 场景1：项目反构操作流程

## 操作1：项目结构扫描

1. **扫描根目录** - 识别项目类型（Rust/Python/JS等）、构建系统（Cargo.toml/package.json等）、配置文件
2. **识别目录结构** - 源码目录（src/）、测试目录（tests/）、文档目录（docs/）、配置目录（config/）
3. **分析组织模式** - 判断单体/多模块，识别模块划分方式

**输出**：项目结构概览、主要目录文件清单、技术栈标注

## 操作2：创建模块分析任务树

1. **识别主要模块** - 根据目录结构，每个主要模块对应一个 sub 任务
2. **构建层次结构** - 顶层→主要模块→子模块/组件，任务命名：`分析模块：[模块名称]`
3. **分配任务** - 每个 sub 任务专注于一个模块，任务间保持独立

**任务树示例**：

```text
项目反构任务
├── 分析模块：核心业务逻辑
│   ├── 分析子模块：用户管理
│   └── 分析子模块：订单处理
└── 分析模块：基础设施
    ├── 分析子模块：配置管理
    └── 分析子模块：日志系统
```

## 操作3：模块深度分析

对每个模块执行：

1. **结构分析** - `list_dir` 列出文件，统计代码数量和类型分布
2. **代码阅读** - `read_file` 读取关键文件，识别入口点、核心类/函数
3. **依赖分析** - 识别对内/对外依赖，绘制依赖关系图
4. **模式识别** - 识别设计模式（工厂/策略等）和架构模式（MVC/分层等）

**每个模块输出**：职责描述、结构说明、核心组件、依赖图、设计模式、代码来源

## 操作4：跨模块关系分析

1. **数据流分析** - 追踪数据流转路径、转换节点、存储位置
2. **控制流分析** - 分析请求流转、业务流程、异常传播
3. **接口分析** - 识别接口定义、调用方式（同步/异步）、版本兼容性
4. **依赖图构建** - 构建依赖图、识别循环依赖、核心/边缘模块

## 操作5：文档生成

1. **汇总结果** - 整合分析结果，统一术语风格
2. **构建架构图** - 绘制整体架构图，标注模块关系
3. **创建目录结构** - 在 `{{ git_root_dir }}/.jarvis/rules/project_info/` 下创建文档树
4. **生成模块文档** - 每个子模块生成独立 Markdown 文件
5. **生成项目总览** - 生成 `README.md`，包含项目概述、模块索引、依赖图
6. **验证完整性** - 检查覆盖度、文档对应性、结构一致性

**文档目录结构**：

```text
{{ git_root_dir }}/.jarvis/rules/project_info/
├── README.md                      # 项目总览
├── core_business/                 # 核心业务
│   ├── user_management.md
│   └── order_processing.md
├── data_access/                   # 数据访问
│   └── database_models.md
└── infrastructure/                 # 基础设施
    └── logging.md
```

---

# 场景2：代码反向设计操作流程

## 四阶段流程

| 阶段            | 内容                                               |
| --------------- | -------------------------------------------------- |
| **1. 代码阅读** | `read_file` 分析代码，识别架构、主要模块、核心组件 |
| **2. 功能提取** | 提取核心功能、流程分析、接口分析、配置总结         |
| **3. 设计构建** | 构建语言无关设计、定义模块边界、描述算法流程       |
| **4. 验证确认** | 完整性检查、可实现性确认、建议提供                 |

---

# 输出格式要求

## 文档位置规范

| 类型           | 路径                                                                           |
| -------------- | ------------------------------------------------------------------------------ |
| **文档根目录** | `{{ git_root_dir }}/.jarvis/rules/project_info/`                               |
| **项目总览**   | `{{ git_root_dir }}/.jarvis/rules/project_info/README.md`                      |
| **模块文档**   | `{{ git_root_dir }}/.jarvis/rules/project_info/<module_path>/<module_name>.md` |

**命名规范**：小写字母+下划线，目录/文件与模块名一致

## 模块文档格式

````markdown
# [模块名称] 设计文档

## 模块概述

- **职责**：模块的主要功能范围
- **代码位置**：`{{ git_root_dir }}/<module_path>`
- **代码来源**：
  - 目录：`{{ git_root_dir }}/<source_dir>`
  - 文件：`{{ git_root_dir }}/<source_file>` - 作用说明

## 模块结构

```text
module_name/
├── sub_component_1/  # 子组件1
└── component.rs      # 组件
```
````

## 核心组件

### 组件1：组件名称

- **位置**：`module_name/component.rs`
- **职责**：功能描述
- **接口**：主要接口说明

## 依赖关系

- **依赖**：module_a（原因）
- **被依赖**：module_b（用途）
- **外部依赖**：库名（版本和用途）

## 设计模式

- **模式名称**：应用位置 + 应用场景 + 实现方式

## 接口设计

### 对外接口

- **接口1**：功能说明
  - 输入：参数说明
  - 输出：返回说明
  - 错误处理：错误码说明

## 数据流

```text
输入 ──> 组件1 ──> 组件2 ──> 输出
```

## 相关模块

- [模块A](../module_a.md)

````

## 大型模块拆分策略

**拆分条件**（满足任一）：
- 文档行数 > 500
- 功能点 > 5个
- 文件数 > 20个
- 复杂度高

**拆分方式**：
- 按功能点：`initialization.md`、`message_dispatch.md`
- 按层次：`transport_layer.md`、`application_layer.md`
- 按组件：`render_engine.md`、`event_system.md`

**拆分后必须生成 README.md 总览**，包含：模块概述、功能索引、依赖图、数据流图、导航链接

---

# 项目反构输出格式（精简版）

```markdown
# 项目反构设计方案

## 1. 项目概述

- **项目名称/类型/技术栈**：基本信息
- **代码来源**：
  - 目录：`{{ git_root_dir }}/<dir>`
  - 文件：`{{ git_root_dir }}/<file>` - 说明
- **项目结构**：

```text
项目根目录/
├── src/
│   └── module_a/
└── tests/
````

## 2. 整体架构

- **架构模式**：单体/微服务/分层/事件驱动等
- **系统层次**：

```text
┌──────────────────┐
│  表现层/接口层   │
├──────────────────┤
│  业务逻辑层     │
├──────────────────┤
│  数据访问层     │
├──────────────────┤
│  基础设施层     │
└──────────────────┘
```

## 3. 模块设计

### 模块A：模块名称

- **职责**：功能描述
- **代码来源**：目录/文件
- **结构**：目录树
- **核心组件**：组件及职责
- **依赖关系**：依赖/被依赖/外部依赖
- **设计模式**：使用的模式

### 模块依赖图

```text
module_a ──> module_c
module_b ──> module_d ──> module_e
```

## 4. 数据架构

- **核心实体**：主要数据实体和关系
- **数据流图**：

```text
用户输入 ──> 接口层 ──> 业务层 ──> 数据层 ──> 存储
```

## 5. 技术栈

- **语言/框架**：使用的技术和版本
- **构建/测试工具**：工具链
- **主要依赖**：第三方库

## 6. 设计决策

- **决策标题**：背景 + 方案 + 影响 + 代码位置

## 7. 总结

- **项目特点**：优势、特色
- **潜在问题**：技术债务、改进建议
- **学习要点**：核心概念、关键代码

## 附录

- **代码引用索引**：关键文件列表
- **模块文档索引**：链接到各模块文档

````

---

# 代码反向设计输出格式（精简版）

```markdown
### 代码反构设计方案

## 1. 项目概述

- **代码功能**：核心功能描述
- **代码来源**：
  - 文件：`{{ git_root_dir }}/<file>` - 说明
  - 目录：`{{ git_root_dir }}/<dir>` - 说明

## 2. 架构设计

- **架构模式**：分层/微服务/事件驱动等
- **模块设计**：
  - **模块A**：职责 + 输入输出 + 依赖关系
- **数据架构**：数据模型 + 数据流向 + 存储方案

## 3. 功能设计

- **功能点1**：处理流程 + 业务规则 + 边界条件
- **功能点2**：同上
- **算法设计**：算法原理 + 实现步骤 + 复杂度分析

## 4. 接口设计

- **外部接口**：名称 + 输入 + 输出 + 错误处理
- **配置接口**：环境配置 + 参数配置

## 5. 实现指导

- **技术建议**：语言/框架/依赖
- **开发顺序**：阶段1 → 阶段2 → 阶段3
- **质量保证**：测试策略 + 性能要求 + 安全考虑

## 6. 功能对齐验证

- **功能对照表**：原代码功能 ↔ 新设计方案映射
- **差异说明**：改进和优化点
````

---

# 执行检查清单

## 项目反构检查清单

| 阶段         | 检查项                                  |
| ------------ | --------------------------------------- |
| **结构扫描** | [ ] 已扫描根目录识别项目类型            |
|              | [ ] 已识别主要目录结构                  |
|              | [ ] 已生成项目结构概览                  |
| **任务树**   | [ ] 已识别所有主要模块                  |
|              | [ ] 已为每个模块创建 sub 任务           |
|              | [ ] 任务层次与目录层次一致              |
| **模块分析** | [ ] 已分析每个模块的结构                |
|              | [ ] 已识别每个模块的依赖关系            |
|              | [ ] 已识别设计模式                      |
|              | [ ] 已记录代码来源                      |
| **关系分析** | [ ] 已分析数据流/控制流                 |
|              | [ ] 已构建依赖关系图                    |
| **文档生成** | [ ] 已在 `project_info/` 下创建文档结构 |
|              | [ ] 已为每个模块生成独立文档            |
|              | [ ] 已生成 README.md                    |
|              | [ ] 已验证完整性                        |

## 代码反向设计检查清单

| 阶段         | 检查项                       |
| ------------ | ---------------------------- |
| **代码分析** | [ ] 已完整阅读并理解代码架构 |
|              | [ ] 已提取所有核心功能       |
|              | [ ] 已记录代码来源           |
| **设计方案** | [ ] 已构建语言无关的设计方案 |
|              | [ ] 已定义清晰的模块划分     |
|              | [ ] 已明确数据流和控制流     |
| **验证确认** | [ ] 设计方案完整覆盖所有功能 |
|              | [ ] 提供功能对照表验证完整性 |

---

# 最佳实践

## 项目反构

1. **从宏观到微观** - 先整体架构，再具体模块；先模块职责，再实现细节
2. **模块化分析** - 每模块独立分析，关注边界和职责划分
3. **依赖追踪** - 从入口点追踪调用链，识别核心/边缘模块
4. **代码阅读** - 优先阅读接口定义公共API，关注数据结构和关键算法

## 代码反向设计

1. **功能导向** - 关注功能实现，而非语法细节
2. **抽象层次** - 保持适当抽象，不过于具体也不过于抽象
3. **多角度验证** - 从不同角度验证理解是否正确

## 常见问题

| 问题         | 解决方案                                   |
| ------------ | ------------------------------------------ |
| 项目结构复杂 | 从构建配置文件入手，查看入口文件和主函数   |
| 依赖关系复杂 | 绘制依赖图，识别核心/边缘模块              |
| 代码量大     | 优先分析核心模块，关注接口定义而非实现细节 |
| 功能点遗漏   | 建立功能清单，从用户角度思考               |
| 设计过于具体 | 使用通用术语，关注"做什么"而非"怎么做"     |

---

# 相关资源

- [架构图生成规则](../architecture_design/architecture-diagram-generation.md)
- [整洁架构](../architecture_design/clean_architecture.md)
- [SOLID 设计原则](../architecture_design/solid.md)
