代码理解技能

何时使用

• •变更开发（change-project）模式下，在需求分析前执行代码理解
• •需要分析现有代码库的结构、依赖关系、接口定义时
• •需要为已有项目生成或更新架构设计文档时

输出格式

• •逆向架构设计书：按 process_templates/architecture.md 模板格式，mode: reverse
• •逆向接口定义：按 process_templates/interfaces.json 格式
• •代码分析摘要：作为架构设计书的附录章节

输出规范

逆向设计书必须包含以下内容，缺少任何必填项视为不完整：

分析步骤

1. 项目结构扫描

• •生成目录树（排除 node_modules、pycache、bin/obj 等构建产物）
• •识别入口文件（main.py、Program.cs、index.ts、main.go 等）
• •检测项目框架（从配置文件和依赖推断：FastAPI、ASP.NET Core、Express、Spring Boot 等）
• •识别项目类型（Web API / CLI / 库 / 桌面应用）

2. 模块划分识别

• •按目录结构和命名空间识别模块边界
• •为每个模块梳理职责（从文件名、类名、函数名、注释推断）
• •绘制 Mermaid 架构块图展示模块间关系
• •标注模块的代码量（文件数、大致行数）

3. 依赖关系分析

外部依赖：

• •从包管理文件提取（requirements.txt / package.json / .csproj / go.mod / Cargo.toml）
• •列出每个依赖的用途和版本

内部依赖：

• •分析 import/using/require 语句，绘制模块间依赖图
• •检测是否存在循环依赖
• •输出依赖方向图（Mermaid 格式）

graph TD
    A[API层] --> B[服务层]
    B --> C[数据层]
    B --> D[工具层]

4. 接口提取

• •HTTP/RPC 接口：提取路由定义、请求方法、请求/响应格式
• •服务接口：提取公共方法签名、参数类型、返回类型
• •数据模型：提取实体类/结构体定义，包含字段名和类型
• •按 interfaces.json 格式输出

5. 数据流追踪

• •从入口文件出发，追踪关键数据的完整路径
• •标注数据经过的模块和转换操作
• •识别数据的持久化方式（数据库、文件、缓存等）
• •用时序图展示关键数据流的调用链

6. 现有测试评估

• •统计测试文件和测试用例数量
• •识别已覆盖的模块和未覆盖的模块
• •评估测试类型分布（单元 / 集成 / 接口 / 系统）
• •检查测试质量（是否有断言、是否测试了异常路径）
• •输出评估结论：
  • •✅ 测试充分：覆盖率 ≥70%，各层均有测试
  • •⚠️ 测试不足：覆盖率 <70% 或某层缺失
  • •❌ 无测试：没有测试代码

7. 编码风格识别

目的：识别现有代码库遵循的编码风格基线，为后续变更开发提供风格参考。

分析要点：

• •缩进方式（空格 / Tab）和缩进宽度
• •命名风格（camelCase / snake_case / PascalCase）在变量、函数、类、常量中的使用模式
• •括号风格（K&R / Allman / 同行）
• •导入/引用的排列顺序和分组规则
• •注释风格（单行 / 多行 / 文档注释格式）
• •文件组织惯例（类的排列顺序、公共/私有成员顺序）

一致性评估：

• •✅ 风格一致：整个项目遵循统一风格
• •⚠️ 风格混杂：不同模块/文件风格不一致（列出差异点）
• •❌ 无明确风格：代码风格随意，无规律可循

风格参考选择规则：

1. •项目已有 .editorconfig / linter 配置（.eslintrc、pyproject.toml [tool.black]、.clang-format 等）→ 以配置为准
2. •项目无配置但风格一致 → 以现有风格为基线
3. •项目风格混杂或无明确风格 → 推荐采用 Google Style Guide（参考 copilot-instructions.md 中的「Google Style Guide 语言对照表」）

8. 代码静态检查

目的：对现有代码执行静态分析，发现潜在缺陷和违规项，作为逆向设计书的质量附录。

执行步骤：

1. •根据语言选择合适的 Linter 和静态分析工具（参考 copilot-instructions.md 中的「Linter / 静态分析工具对照表」）
2. •以默认规则集执行检查，记录结果
3. •将结果按严重程度分类（Error / Warning / Info）
4. •高严重度问题标注在逆向设计书的"风险点"章节

评估标准：

• •✅ 无高严重度问题
• •⚠️ 存在少量高严重度问题（≤5 个）
• •❌ 存在大量高严重度问题（>5 个），需在风险点中重点标注

分析结果的使用方式

逆向设计书是后续流程的基线文档：

1. •PM 使用：理解现有系统范围，更准确地进行变更需求分析
2. •Architect 使用：在逆向基线上做增量架构设计，避免推翻现有设计
3. •Developer 使用：了解代码结构和编码风格基线，定位变更点，保持风格一致性
4. •Tester 使用：了解已有测试覆盖和静态检查基线，制定增量测试计划

注意事项

• •分析必须基于实际代码，不得凭空推测
• •遇到无法判断的模块职责时，标注为"待确认"
• •大型项目可分模块逐步分析，但最终必须输出完整的逆向设计书
• •发现的技术债务和风险点需在分析摘要中明确标注
• •逆向设计书的架构图必须准确反映当前代码结构，而非理想状态
• •编码风格分析应覆盖至少 3 个不同模块的代码文件，确保样本充分
• •静态检查应使用工具默认规则集，不自定义规则（反映项目真实状态）