# 反向工程规则

## 规则简介

反向工程规则用于指导 Agent 从现有代码中提取设计信息并生成语言无关的设计方案。该规则涵盖两种主要场景：

1. **项目反构**：对整个项目进行系统性反向工程分析，通过识别项目模块结构、分析代码组织层次，生成完整的项目设计方案文档
2. **代码反向设计**：对单个代码文件或代码片段进行反向设计，提取设计信息并生成语言无关的设计方案

**适用场景：**

**项目反构场景：**

- 理解大型项目的整体架构
- 为新团队成员提供项目概览
- 重构前的架构分析
- 项目文档化
- 技术债务评估

**代码反向设计场景：**

- 理解单个文件或代码片段的功能
- 从现有代码提取设计方案用于新实现
- 代码迁移和重构
- 跨语言实现参考

**预期效果：**

- 生成完整的架构设计方案
- 清晰的模块划分和职责定义
- 组件间依赖关系图
- 数据流和控制流分析
- 技术栈和设计模式总结
- 语言无关的设计方案

## 场景选择

在执行反向工程任务前，**必须**明确选择适用的场景：

- **选择项目反构**：当需要分析整个项目的架构、模块关系、整体设计时
- **选择代码反向设计**：当需要分析单个文件或代码片段的功能和设计时

## 你必须遵守的原则

### 1. 完整性原则

- **必须**：确保设计方案覆盖所有功能点
- **禁止**：遗漏任何功能或业务逻辑
- **必须**：提供功能对照表验证完整性
- **项目反构**：必须覆盖所有重要模块和组件
- **代码反向设计**：必须覆盖代码的所有功能点

### 2. 系统性原则（项目反构）

- **必须**：从项目根目录开始，系统性地分析整个项目结构
- **必须**：按照目录层次结构组织分析任务
- **必须**：确保覆盖所有重要模块和组件
- **禁止**：遗漏关键模块或目录
- **必须**：建立完整的项目模块清单

### 3. 层次化原则（项目反构）

- **必须**：按照树状目录结构组织分析任务
- **必须**：为每个主要模块创建独立的 sub 任务
- **必须**：保持任务层次与目录层次一致
- **必须**：从顶层架构到具体实现逐层深入
- **禁止**：扁平化处理，忽略层次关系

### 4. 模块化原则（项目反构）

- **必须**：根据项目结构识别主要模块
- **必须**：明确每个模块的职责和边界
- **必须**：分析模块间的依赖关系
- **必须**：识别模块的输入输出接口
- **禁止**：将不同职责的代码混在一起分析

### 5. 可实现性原则

- **必须**：设计方案必须具有实际可实施性
- **必须**：提供明确的技术选型建议
- **必须**：包含实现指导和注意事项

### 6. 语言无关性原则

- **必须**：设计方案不包含具体编程语言语法
- **必须**：使用通用的设计概念和术语
- **必须**：避免语言特定的实现细节

### 7. 清晰性原则

- **必须**：使用清晰、准确的语言描述设计要素
- **必须**：提供具体的示例和说明
- **必须**：保持设计原则和风格的一致性

### 8. 可追溯性原则（项目反构）

- **必须**：记录每个设计决策对应的代码位置
- **必须**：提供关键代码片段的引用
- **必须**：建立功能与代码的映射关系
- **必须**：标注不确定或需要进一步分析的部分
- **必须**：记录设计方案来源的目录和文件信息

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

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

**执行步骤：**

1. **扫描项目根目录**
   - 使用 `list_dir` 工具扫描项目根目录 `{{ git_root_dir }}`
   - 识别项目类型（如 Rust、Python、JavaScript 等）
   - 识别构建系统（如 Cargo.toml、package.json、CMakeLists.txt 等）
   - 识别配置文件（如 .gitignore、README.md、配置文件等）

2. **识别主要目录结构**
   - 列出所有一级目录和重要文件
   - 识别源代码目录（如 `src/`、`lib/`、`app/` 等）
   - 识别测试目录（如 `tests/`、`test/`、`__tests__/` 等）
   - 识别文档目录（如 `docs/`、`doc/` 等）
   - 识别配置目录（如 `config/`、`.config/` 等）

3. **分析项目组织模式**
   - 判断项目是单体应用还是多模块项目
   - 识别项目的模块划分方式（按功能、按层次、按领域等）
   - 识别项目的命名规范和目录约定

**输出要求：**

- 生成项目结构概览
- 列出主要目录和文件
- 标注项目类型和技术栈

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

**执行步骤：**

1. **识别主要模块**
   - 根据目录结构识别主要模块
   - 每个主要模块对应一个 sub 任务
   - 模块识别原则：
     - 独立的目录（如 `src/module_a/`）
     - 独立的包/库（如 Rust 的 crate、Python 的 package）
     - 功能边界清晰的组件

2. **构建任务层次结构**
   - 顶层任务：项目整体反构
   - 第二层：主要模块分析（每个模块一个 sub 任务）
   - 第三层：子模块或关键组件分析（如需要）
   - 任务命名规范：`分析模块：[模块名称]`

3. **任务分配原则**
   - 每个 sub 任务专注于一个模块的深入分析
   - 任务之间保持独立性，便于并行或顺序执行
   - 任务粒度适中，既不过大也不过小

**任务树示例结构：**

```text
项目反构任务
├── 分析模块：核心业务逻辑模块
│   ├── 分析子模块：用户管理
│   ├── 分析子模块：订单处理
│   └── 分析子模块：支付处理
├── 分析模块：数据访问层
│   ├── 分析子模块：数据库模型
│   └── 分析子模块：数据访问接口
├── 分析模块：API 接口层
│   ├── 分析子模块：REST API
│   └── 分析子模块：GraphQL API
└── 分析模块：基础设施层
    ├── 分析子模块：配置管理
    ├── 分析子模块：日志系统
    └── 分析子模块：错误处理
```

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

**对每个模块执行以下分析：**

1. **模块结构分析**
   - 使用 `list_dir` 列出模块内的所有文件和子目录
   - 识别模块的主要组件和文件组织方式
   - 统计代码文件数量、类型分布

2. **代码阅读与分析**
   - 使用 `read_file` 读取模块的关键文件
   - 识别模块的入口点和主要接口
   - 分析模块的核心类和函数
   - 理解模块的业务逻辑和数据处理流程

3. **依赖关系分析**
   - 识别模块对其他模块的依赖
   - 识别模块对外部库的依赖
   - 识别模块提供的接口和 API
   - 绘制模块的依赖关系图

4. **设计模式识别**
   - 识别模块使用的设计模式（如工厂模式、策略模式等）
   - 识别模块的架构模式（如 MVC、分层架构等）
   - 分析模块的设计原则和理念

**输出要求（每个模块）：**

- 模块职责描述
- 模块结构说明
- 核心组件列表
- 依赖关系图
- 设计模式总结
- **必须**：记录分析的代码来源（目录和文件列表）
- **必须**：生成独立的模块文档文件（见"操作5：项目设计方案整合与文档生成"）

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

**执行步骤：**

1. **数据流分析**
   - 追踪数据在模块间的流转路径
   - 识别数据转换和处理节点
   - 识别数据存储和持久化位置

2. **控制流分析**
   - 分析请求/调用的流转路径
   - 识别主要的业务流程和控制逻辑
   - 识别异常处理和错误传播路径

3. **接口分析**
   - 识别模块间的接口定义
   - 分析接口的调用方式（同步/异步、RPC/消息队列等）
   - 识别接口的版本和兼容性

4. **依赖图构建**
   - 构建模块依赖关系图
   - 识别循环依赖（如存在）
   - 识别核心模块和边缘模块

### 操作5：项目设计方案整合与文档生成

**执行步骤：**

1. **汇总各模块分析结果**
   - 整合所有模块的分析结果
   - 统一术语和描述风格
   - 消除重复和矛盾

2. **构建整体架构图**
   - 绘制项目的整体架构图
   - 标注模块层次和关系
   - 标注数据流和控制流

3. **创建文档目录结构**
   - **必须**：在 `{{ git_root_dir }}/.jarvis/rules/project_info/` 目录下创建文档目录树
   - **必须**：目录结构应反映项目的模块层次结构
   - **必须**：为每个子模块创建对应的目录和文件
   - **目录命名规范**：使用小写字母和下划线，与模块名称保持一致

4. **生成模块文档**
   - **必须**：为每个子模块生成一个独立的 Markdown 文件
   - **文件命名规范**：使用小写字母和下划线，格式为 `<module_name>.md`
   - **文件位置**：放置在对应的模块目录下
   - **文件内容**：包含该模块的完整设计信息（见"模块文档格式要求"）

5. **生成项目总览文档**
   - **必须**：在 `{{ git_root_dir }}/.jarvis/rules/project_info/` 目录下生成项目总览文档 `README.md`
   - **文档内容**：包含项目概述、整体架构设计、模块索引、依赖关系图等
   - **模块索引**：提供所有模块文档的链接和导航

6. **验证完整性**
   - 检查是否覆盖所有主要模块
   - 验证每个模块都有对应的文档文件
   - 验证文档目录结构与项目结构一致
   - 验证设计方案的一致性
   - 补充缺失的关键信息

**文档目录结构示例：**

```text
{{ git_root_dir }}/.jarvis/rules/project_info/
├── README.md                    # 项目总览文档
├── core_business/               # 核心业务逻辑模块目录
│   ├── user_management.md      # 用户管理子模块文档
│   ├── order_processing.md     # 订单处理子模块文档
│   └── payment.md              # 支付处理子模块文档
├── data_access/                # 数据访问层目录
│   ├── database_models.md      # 数据库模型子模块文档
│   └── data_access_interface.md # 数据访问接口子模块文档
├── api_layer/                   # API 接口层目录
│   ├── rest_api.md             # REST API 子模块文档
│   └── graphql_api.md          # GraphQL API 子模块文档
└── infrastructure/              # 基础设施层目录
    ├── config_management.md     # 配置管理子模块文档
    ├── logging.md              # 日志系统子模块文档
    └── error_handling.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`
- **目录结构**：必须反映项目的模块层次结构

**目录命名规范：**

- 使用小写字母和下划线
- 与项目中的模块名称保持一致
- 避免使用特殊字符和空格

**文件命名规范：**

- 使用小写字母和下划线
- 格式：`<module_name>.md`
- 与模块名称保持一致

### 模块文档格式要求

**必须**：每个子模块都要有一个独立的 Markdown 文件，文件格式如下：

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

## 模块概述

### 模块职责
- 模块的主要职责和功能范围

### 模块位置
- 代码位置：`{{ git_root_dir }}/<module_path>`
- 文档位置：`{{ git_root_dir }}/.jarvis/rules/project_info/<module_path>/<module_name>.md`

### 代码来源
- **分析来源目录**：列出用于生成此设计文档的源代码目录路径
  - `{{ git_root_dir }}/<source_directory_1>`
  - `{{ git_root_dir }}/<source_directory_2>`
- **分析来源文件**：列出用于生成此设计文档的关键源代码文件
  - `{{ git_root_dir }}/<source_file_1>` - 文件作用说明
  - `{{ git_root_dir }}/<source_file_2>` - 文件作用说明
- **文件统计**：分析的代码文件总数和类型分布

## 模块结构

\`\`\`text
module_name/
├── sub_component_1/      # 子组件1
├── sub_component_2/      # 子组件2
├── interface.rs          # 接口定义
└── ...
\`\`\`

## 核心组件

### 组件1：组件名称
- **位置**：`module_name/component1.rs`
- **职责**：组件功能描述
- **接口**：主要接口说明
- **依赖**：依赖的其他组件或模块

### 组件2：组件名称
（同上格式）

## 依赖关系

### 依赖的模块
- **模块A**：依赖原因和用途
- **模块B**：依赖原因和用途

### 被依赖的模块
- **模块C**：被依赖的用途

### 外部依赖
- **库1**：版本和用途
- **库2**：版本和用途

## 设计模式

- **模式1**：设计模式名称
  - **应用位置**：在哪些组件中使用
  - **应用场景**：为什么使用该模式
  - **实现方式**：简要说明实现方式

## 关键代码位置

- **核心逻辑**：`module_name/core.rs:50-100`
- **接口定义**：`module_name/interface.rs:10-50`
- **数据处理**：`module_name/data_processor.rs:20-80`

## 接口设计

### 对外接口
- **接口1**：接口名称和功能
  - **输入参数**：参数说明
  - **输出结果**：返回结果说明
  - **错误处理**：错误码和异常处理

### 内部接口
- **接口2**：内部接口说明

## 数据流

\`\`\`text
输入数据 ──> 组件1 ──> 组件2 ──> 输出数据
\`\`\`

## 设计决策

- **决策1**：关键设计决策
  - **背景**：决策的背景和原因
  - **方案**：选择的方案
  - **影响**：对模块的影响

## 相关模块

- [模块A文档](../module_a/module_a.md)
- [模块B文档](../module_b/module_b.md)

## 附录

### 代码引用索引
- **关键文件列表**：重要代码文件及其作用
- **代码片段索引**：关键代码片段的位置
```

### 项目反构输出格式

请严格按照以下格式输出完整的项目设计方案（项目总览文档 `README.md`）：

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

## 1. 项目概述

### 1.1 项目基本信息
- **项目名称**：项目名称
- **项目类型**：项目类型（如 Web 应用、CLI 工具、库等）
- **主要技术栈**：使用的编程语言、框架、工具等
- **构建系统**：使用的构建工具和依赖管理方式
- **项目规模**：代码行数、模块数量、文件数量等统计信息

### 1.2 代码来源
- **分析来源目录**：列出用于生成此设计文档的源代码目录路径
  - `{{ git_root_dir }}/<source_directory_1>` - 目录说明
  - `{{ git_root_dir }}/<source_directory_2>` - 目录说明
- **分析来源文件**：列出用于生成此设计文档的关键源代码文件
  - `{{ git_root_dir }}/<source_file_1>` - 文件作用说明
  - `{{ git_root_dir }}/<source_file_2>` - 文件作用说明
- **分析范围**：说明分析的代码范围和覆盖情况

### 1.3 项目结构概览

\`\`\`text
项目根目录/
├── src/                    # 源代码目录
│   ├── module_a/          # 模块A
│   ├── module_b/          # 模块B
│   └── ...
├── tests/                  # 测试代码
├── docs/                   # 文档
├── config/                 # 配置文件
└── ...
\`\`\`

### 1.4 项目组织模式

- **模块划分方式**：按功能/按层次/按领域等
- **命名规范**：文件命名、目录命名、代码命名规范
- **代码组织原则**：遵循的代码组织原则和约定

## 2. 整体架构设计

### 2.1 架构模式

- **架构类型**：单体架构/微服务架构/分层架构/事件驱动架构等
- **设计理念**：遵循的核心设计理念和原则
- **架构特点**：架构的主要特点和优势

### 2.2 系统层次结构

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

### 2.3 核心组件

- **组件1**：组件名称和职责
- **组件2**：组件名称和职责
- ...

## 3. 模块设计

### 3.1 模块概览

- **模块总数**：项目包含的主要模块数量
- **模块列表**：所有主要模块的名称和简要说明

### 3.2 模块详细设计

#### 模块A：模块名称

**模块职责：**

- 模块的主要职责和功能范围

**代码来源：**

- **分析来源目录**：`{{ git_root_dir }}/<module_a_source_directory>`
- **分析来源文件**：
  - `{{ git_root_dir }}/<module_a_file_1>` - 文件作用说明
  - `{{ git_root_dir }}/<module_a_file_2>` - 文件作用说明

**模块结构：**

\`\`\`text
module_a/
├── sub_module_1/      # 子模块1
├── sub_module_2/      # 子模块2
├── interface.rs       # 接口定义
└── ...
\`\`\`

**核心组件：**

- **组件1**：组件名称和职责
  - 位置：`module_a/component1.rs`
  - 功能：组件功能描述
  - 接口：主要接口说明

**依赖关系：**

- **依赖的模块**：module_b, module_c
- **被依赖的模块**：module_d
- **外部依赖**：第三方库列表

**设计模式：**

- 使用的设计模式：工厂模式、策略模式等

**关键代码位置：**

- 核心逻辑：`module_a/core.rs:50-100`
- 接口定义：`module_a/interface.rs:10-50`

#### 模块B：模块名称

（同上格式）

### 3.3 模块依赖关系图

\`\`\`text
module_a ──┐
           ├──> module_c
module_b ──┘
           │
           └──> module_d ──> module_e
\`\`\`

## 4. 数据架构

### 4.1 数据模型

- **核心实体**：主要的数据实体和关系
- **数据存储**：数据存储方式和位置
- **数据流转**：数据在系统中的流转路径

### 4.2 数据流图

\`\`\`text
用户输入 ──> 接口层 ──> 业务层 ──> 数据层 ──> 存储
                │         │         │
                └─────────┴─────────┘
                    (数据验证和转换)
\`\`\`

## 5. 接口设计

### 5.1 模块间接口

- **接口1**：模块A -> 模块B
  - 接口定义：接口签名和参数说明
  - 调用方式：同步/异步、调用频率等
  - 错误处理：错误码和异常处理机制

### 5.2 外部接口

- **API接口**：对外提供的 API 接口
- **配置文件**：配置接口和参数说明
- **插件接口**：扩展点和插件机制

## 6. 技术栈和工具链

### 6.1 编程语言和框架

- **主要语言**：使用的编程语言及版本
- **核心框架**：使用的主要框架和库
- **版本要求**：语言和框架的版本要求

### 6.2 开发工具

- **构建工具**：构建系统和工具
- **测试框架**：测试框架和工具
- **代码质量工具**：linter、formatter 等

### 6.3 依赖管理

- **依赖列表**：主要第三方依赖
- **依赖版本**：依赖版本管理策略
- **依赖关系**：依赖的层次和关系

## 7. 设计模式和架构模式

### 7.1 使用的设计模式

- **模式1**：设计模式名称
  - 应用位置：在哪些模块中使用
  - 应用场景：为什么使用该模式
  - 实现方式：简要说明实现方式

### 7.2 架构模式

- **分层架构**：各层的职责和边界
- **模块化设计**：模块化的方式和原则
- **依赖注入**：依赖注入的使用方式

## 8. 关键设计决策

### 8.1 架构决策

- **决策1**：关键架构决策
  - **背景**：决策的背景和原因
  - **方案**：选择的方案
  - **影响**：对系统的影响
  - **代码位置**：相关代码位置

### 8.2 技术选型

- **选型1**：技术选型决策
  - **原因**：选择该技术的原因
  - **替代方案**：考虑过的替代方案
  - **权衡**：权衡的考虑因素

## 9. 项目分析总结

### 9.1 项目特点

- **优势**：项目的优势和亮点
- **特色**：项目的独特设计或实现

### 9.2 潜在问题

- **技术债务**：发现的技术债务
- **设计问题**：潜在的设计问题
- **改进建议**：改进建议和方向

### 9.3 学习要点

- **核心概念**：理解项目需要掌握的核心概念
- **关键代码**：需要重点关注的代码位置
- **设计思路**：项目的设计思路和理念

## 10. 附录

### 10.1 代码引用索引

- **关键文件列表**：重要代码文件及其作用
- **代码片段索引**：关键代码片段的位置

### 10.2 参考资料

- **相关文档**：项目相关文档链接
- **设计参考**：设计参考和灵感来源

### 10.3 模块文档索引

- [核心业务逻辑模块](core_business/)
  - [用户管理](core_business/user_management.md)
  - [订单处理](core_business/order_processing.md)
  - [支付处理](core_business/payment.md)
- [数据访问层](data_access/)
  - [数据库模型](data_access/database_models.md)
  - [数据访问接口](data_access/data_access_interface.md)
- [API 接口层](api_layer/)
  - [REST API](api_layer/rest_api.md)
  - [GraphQL API](api_layer/graphql_api.md)
- [基础设施层](infrastructure/)
  - [配置管理](infrastructure/config_management.md)
  - [日志系统](infrastructure/logging.md)
  - [错误处理](infrastructure/error_handling.md)

```

### 代码反向设计输出格式

请严格按照以下格式输出完整的设计方案：

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

**1. 项目概述**

- **代码功能**：简要描述原代码实现的核心功能
- **设计目标**：说明开发需要达到的目标和要求

**1.1 代码来源**

- **分析来源文件**：列出用于生成此设计文档的源代码文件
  - `{{ git_root_dir }}/<source_file_1>` - 文件作用说明
  - `{{ git_root_dir }}/<source_file_2>` - 文件作用说明
- **分析来源目录**：如果涉及多个文件，列出相关目录
  - `{{ git_root_dir }}/<source_directory>` - 目录说明
- **代码范围**：说明分析的代码行数范围和覆盖情况

**2. 架构设计**

**2.1 整体架构**

- **架构模式**：采用的架构模式（如分层架构、微服务架构等）
- **设计原则**：遵循的核心设计原则和理念

**2.2 模块设计**

- **模块A**：模块名称和职责描述
  - **核心职责**：该模块主要负责的功能
  - **输入输出**：接收的输入和产生的输出
  - **依赖关系**：依赖的其他模块或外部服务

- **模块B**：模块名称和职责描述
  - **核心职责**：该模块主要负责的功能
  - **输入输出**：接收的输入和产生的输出
  - **依赖关系**：依赖的其他模块或外部服务

**2.3 数据架构**

- **数据模型**：核心数据结构和实体关系
- **数据流向**：数据在系统中的流转路径
- **存储方案**：数据持久化和缓存策略

**3. 功能设计**

**3.1 核心功能**

- **功能点1**：功能描述和实现要点
  - **处理流程**：详细的处理步骤
  - **业务规则**：相关的业务规则和约束
  - **边界条件**：需要处理的特殊情况

- **功能点2**：功能描述和实现要点
  - **处理流程**：详细的处理步骤
  - **业务规则**：相关的业务规则和约束
  - **边界条件**：需要处理的特殊情况

**3.2 算法设计**

- **算法1**：算法名称和用途
  - **算法原理**：算法的基本原理和思路
  - **实现步骤**：详细的实现步骤
  - **复杂度分析**：时间复杂度和空间复杂度

**4. 接口设计**

**4.1 外部接口**

- **接口A**：接口名称和功能
  - **输入参数**：参数名称、类型和说明
  - **输出结果**：返回结果的结构和说明
  - **错误处理**：错误码和异常处理机制

**4.2 配置接口**

- **环境配置**：运行环境的要求和配置项
- **参数配置**：可配置的参数项和默认值
- **扩展配置**：插件和扩展机制的配置方式

**5. 实现指导**

**5.1 技术建议**

- **开发语言**：推荐的开发语言和版本
- **框架选择**：合适的开发框架和工具
- **依赖管理**：第三方依赖的管理策略

**5.2 开发顺序**

- **第一阶段**：建议优先实现的核心功能
- **第二阶段**：可以后续完善的辅助功能
- **第三阶段**：可选的优化和增强功能

**5.3 质量保证**

- **测试策略**：单元测试、集成测试的重点
- **性能要求**：性能指标和优化建议
- **安全考虑**：安全性要求和防护措施

**6. 与原代码功能对齐验证**

- **功能对照表**：原代码功能与新设计方案的映射关系
- **一致性检查**：确保所有功能都被完整覆盖
- **差异说明**：如有必要，说明设计上的改进和优化

---
```

## 执行检查清单

### 项目反构检查清单

#### 项目结构扫描阶段

- [ ] 已扫描项目根目录并识别项目类型
- [ ] 已识别主要目录结构和组织方式
- [ ] 已分析项目组织模式和命名规范
- [ ] 已生成项目结构概览

#### 任务树创建阶段

- [ ] 已识别所有主要模块
- [ ] 已为每个主要模块创建 sub 任务
- [ ] 任务层次结构与目录层次结构一致
- [ ] 任务粒度适中，便于执行

#### 模块分析阶段

- [ ] 已分析每个模块的结构和组件
- [ ] 已理解每个模块的职责和功能
- [ ] 已识别每个模块的依赖关系
- [ ] 已识别每个模块使用的设计模式
- [ ] 已记录关键代码位置
- [ ] 已记录每个模块的代码来源（目录和文件列表）

#### 关系分析阶段

- [ ] 已分析模块间的数据流
- [ ] 已分析模块间的控制流
- [ ] 已识别模块间的接口定义
- [ ] 已构建模块依赖关系图
- [ ] 已识别循环依赖（如存在）

#### 设计方案整合阶段

- [ ] 已汇总所有模块分析结果
- [ ] 已构建整体架构图
- [ ] 已在 `{{ git_root_dir }}/.jarvis/rules/project_info/` 目录下创建文档目录结构
- [ ] 目录结构反映项目的模块层次结构
- [ ] 已为每个子模块生成独立的 Markdown 文档文件
- [ ] 每个模块文档文件命名规范（小写字母和下划线）
- [ ] 已生成项目总览文档 `README.md`
- [ ] 项目总览文档包含模块索引和导航链接
- [ ] 每个模块文档都包含代码来源信息（目录和文件列表）
- [ ] 项目总览文档包含整体代码来源信息
- [ ] 设计方案格式规范、结构清晰
- [ ] 已验证设计方案完整性
- [ ] 已验证所有模块都有对应的文档文件

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

#### 代码分析阶段

- [ ] 已完整阅读并理解代码的整体架构
- [ ] 已识别主要模块和核心组件
- [ ] 已理解各组件间的调用关系
- [ ] 已提取所有核心业务功能
- [ ] 已分析数据处理流程和算法逻辑
- [ ] 已总结配置参数和环境依赖
- [ ] 已记录分析的代码来源（文件路径和目录信息）

#### 设计方案构建阶段

- [ ] 已构建语言无关的设计方案
- [ ] 已定义清晰的模块划分和职责边界
- [ ] 已描述核心算法和业务规则
- [ ] 已明确数据流和控制流
- [ ] 设计方案具有可实现性

#### 验证确认阶段

- [ ] 设计方案完整覆盖原代码所有功能
- [ ] 提供功能对照表验证完整性
- [ ] 设计方案具有可测试性
- [ ] 提供实现建议和注意事项
- [ ] 使用通用设计术语，避免语言依赖
- [ ] 设计方案中包含完整的代码来源信息

### 输出质量检查（通用）

- [ ] 设计方案结构清晰、层次分明
- [ ] 使用准确、专业的描述语言
- [ ] 提供具体示例说明抽象概念
- [ ] 遵循统一的设计原则和风格
- [ ] 输出格式规范，易于理解和实施
- [ ] 所有文档都包含代码来源信息（目录和文件列表）

## 实践指导

### 项目反构最佳实践

1. **从宏观到微观**

   - 先理解整体架构，再深入具体模块
   - 先理解模块职责，再分析具体实现
   - 保持层次清晰，避免过早陷入细节

2. **模块化分析**
   - 每个模块独立分析，保持关注点分离
   - 先分析模块接口，再分析内部实现
   - 关注模块边界和职责划分

3. **依赖关系追踪**
   - 从入口点开始追踪调用链
   - 识别核心模块和边缘模块
   - 注意循环依赖和紧耦合问题

4. **代码阅读技巧**
   - 优先阅读接口定义和公共 API
   - 关注数据结构和类型定义
   - 理解关键算法和业务逻辑
   - 注意错误处理和边界情况

### 代码反向设计最佳实践

1. **从整体到局部**
   - 先理解整体架构，再深入具体实现
   - 功能导向：关注代码实现的功能，而不是具体的语法细节
   - 文档记录：及时记录分析过程中的关键发现和疑问
   - 多角度验证：从不同角度验证对代码的理解是否正确

2. **设计方案构建技巧**
   - **抽象层次**：保持适当的抽象层次，既不要太具体也不要太抽象
   - **结构化表达**：使用清晰的结构和层次来组织设计内容
   - **示例说明**：通过具体的示例来说明抽象的设计概念
   - **逐步求精**：从高层次设计逐步细化到具体实现细节

### 任务组织技巧（项目反构）

1. **任务粒度控制**
   - 每个 sub 任务专注于一个模块
   - 任务大小适中，便于执行和验证
   - 避免任务过大导致分析不深入

2. **任务依赖管理**
   - 识别任务间的依赖关系
   - 优先执行基础模块的分析任务
   - 可以并行执行独立模块的分析

3. **进度跟踪**
   - 记录每个任务的完成状态
   - 标记需要进一步分析的部分
   - 及时汇总和整合分析结果

### 常见问题和解决方案

#### 问题1：项目结构复杂，难以确定模块边界（项目反构）

**解决方案：**

- 从构建配置文件入手（如 Cargo.toml、package.json）
- 查看项目的入口文件和主函数
- 分析导入/依赖关系确定模块边界
- 参考项目的文档和注释

#### 问题2：模块间依赖关系复杂（项目反构）

**解决方案：**

- 绘制依赖关系图，可视化依赖关系
- 识别核心模块（被多个模块依赖）
- 识别边缘模块（只依赖其他模块，不被依赖）
- 注意循环依赖，可能需要重构

#### 问题3：代码量大，分析耗时

**解决方案：**

- 优先分析核心模块和关键路径
- 使用代码搜索工具快速定位关键代码
- 关注接口定义和公共 API，而非所有实现细节
- 分阶段分析，先完成概览再深入细节

#### 问题4：代码过于复杂难以理解（代码反向设计）

**解决方案：**

- 先绘制代码的模块结构图
- 识别核心流程和辅助流程
- 分阶段进行分析，每次专注于一个模块

#### 问题5：功能点遗漏（代码反向设计）

**解决方案：**

- 建立功能清单，逐项检查
- 从用户角度思考代码的功能
- 通过测试用例来验证功能完整性

#### 问题6：设计过于依赖具体实现（代码反向设计）

**解决方案：**

- 使用通用的设计术语
- 关注"做什么"而不是"怎么做"
- 提供多种实现的可能性

#### 问题7：设计模式识别困难

**解决方案：**

- 关注代码结构和组织方式
- 识别常见的模式特征（如工厂、单例、策略等）
- 参考设计模式相关的代码注释
- 分析代码的抽象层次和封装方式

## 相关资源

- 参考规则：[架构图生成规则]({{ rule_file_dir }}/architecture-diagram-generation.md)
- 参考规则：[整洁架构]({{ rule_file_dir }}/clean_architecture.md)
- 参考规则：[SOLID 设计原则]({{ rule_file_dir }}/solid.md)
任务已完成，是否进行任务分析
