Back to Details

codebase-architecture-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Architecture Analysis

代码库架构分析

When to use this skill

何时使用该技能

Use this skill when you need to understand the high-level architecture and structure of a codebase. Specifically, use it when you need to:
  • Create architecture diagrams for documentation
  • Understand component relationships and dependencies
  • Assess hosting infrastructure and deployment architecture
  • Generate comprehensive architectural overviews
  • Document data flow between system components
  • Create visual representations of code organization
当你需要理解代码库的高层架构和结构时，使用本技能。具体来说，在以下场景使用：
  • 为文档创建架构示意图
  • 理解组件关系与依赖
  • 评估托管基础设施与部署架构
  • 生成全面的架构概述
  • 记录系统组件间的数据流
  • 创建代码组织的可视化表示

Overview

概述

This skill guides a specialized agent through a comprehensive analysis of a GitHub repository to produce detailed architecture documentation. The analysis includes ASCII diagrams, component maps, infrastructure details, and file-level assessments.
本技能会引导一个专用Agent对GitHub仓库进行全面分析，以生成详细的架构文档。分析内容包括ASCII示意图、组件映射、基础设施细节以及文件级评估。

Workflow

工作流程

Step 1: Repository Setup

步骤1：仓库设置

Input required:
  • GitHub repository URL or 
    owner/repo
    format
  • Optional: Specific branch or commit to analyze
Actions:
  1. Clone the repository using the GitHub PAT from environment variables
  2. Verify the repository is cloned successfully
  3. Document the repository metadata (language, size, structure)
YOU MUST CLONE THE REPOSITORY AND INSPECT THE FILES USING BASH TOOLS AND GIT CLI RATHER THAN MCP.
所需输入：
  • GitHub仓库URL或
    owner/repo
    格式
  • 可选：要分析的特定分支或提交
操作：
  1. 使用环境变量中的GitHub PAT克隆仓库
  2. 验证仓库克隆成功
  3. 记录仓库元数据（语言、大小、结构）
必须使用Bash工具和Git CLI而非MCP来克隆仓库并检查文件。

Step 2: Codebase Discovery and Assessment

步骤2：代码库发现与评估

Analyze the directory structure:
  1. Map the complete directory tree
  2. Identify major components/modules/packages
  3. Classify directories by purpose (src, config, tests, build, etc.)
  4. Count files by type (TypeScript, Python, JSON, etc.)
  5. Identify entry points and main application files
For each file, assess:
  • File type and purpose
  • Size and complexity
  • Key imports and dependencies
  • What module/component it belongs to
  • Role in the overall system
分析目录结构：
  1. 绘制完整的目录树
  2. 识别主要组件/模块/包
  3. 按用途对目录分类（src、config、tests、build等）
  4. 按文件类型统计数量（TypeScript、Python、JSON等）
  5. 识别入口点和主应用文件
对每个文件进行评估：
  • 文件类型与用途
  • 大小与复杂度
  • 关键导入与依赖
  • 所属的模块/组件
  • 在整体系统中的角色

Step 3: Create Architecture Diagrams

步骤3：创建架构示意图

Create multiple ASCII diagrams:
  1. System Architecture Diagram
    • High-level components and their relationships
    • External systems and services
    • Data flow between components
  2. Deployment Architecture
    • Hosting infrastructure (cloud platform, containers, etc.)
    • Service relationships
    • Network and database layers
  3. File Structure Diagram
    • Directory hierarchy showing major components
    • Key files and their purposes
    • Organization by feature or layer
  4. Data Flow Diagram
    • How data moves through the system
    • API endpoints and their interactions
    • Database access patterns
Example ASCII diagram structure:
┌─────────────────────────────────────────────────┐
│                  Client (React)                  │
├─────────────────────────────────────────────────┤
│  - Components                                    │
│  - Pages                                         │
│  - State Management                              │
└────────────────┬────────────────────────────────┘
                 │ HTTP/WebSocket
┌────────────────▼────────────────────────────────┐
│            Backend Server (Node.js)              │
├─────────────────────────────────────────────────┤
│  - API Routes                                    │
│  - Authentication                                │
│  - Business Logic                                │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│            Database & External APIs              │
├─────────────────────────────────────────────────┤
│  - PostgreSQL / MongoDB                          │
│  - Third-party Services                          │
└─────────────────────────────────────────────────┘
创建多幅ASCII示意图：
  1. 系统架构示意图
    • 高层组件及其关系
    • 外部系统与服务
    • 组件间的数据流
  2. 部署架构
    • 托管基础设施（云平台、容器等）
    • 服务关系
    • 网络与数据库层
  3. 文件结构示意图
    • 显示主要组件的目录层级
    • 关键文件及其用途
    • 按功能或分层的组织方式
  4. 数据流示意图
    • 数据在系统中的流转方式
    • API端点及其交互
    • 数据库访问模式
示例ASCII示意图结构：
┌─────────────────────────────────────────────────┐
│                  Client (React)                  │
├─────────────────────────────────────────────────┤
│  - Components                                    │
│  - Pages                                         │
│  - State Management                              │
└────────────────┬────────────────────────────────┘
                 │ HTTP/WebSocket
┌────────────────▼────────────────────────────────┐
│            Backend Server (Node.js)              │
├─────────────────────────────────────────────────┤
│  - API Routes                                    │
│  - Authentication                                │
│  - Business Logic                                │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│            Database & External APIs              │
├─────────────────────────────────────────────────┤
│  - PostgreSQL / MongoDB                          │
│  - Third-party Services                          │
└─────────────────────────────────────────────────┘

Step 4: Component Analysis

步骤4：组件分析

For each major component, document:
  • Purpose and responsibilities
  • Key files and entry points
  • External dependencies
  • Interactions with other components
  • API surface (if applicable)
Document component categories:
  • Frontend Components: UI components, pages, layouts
  • Backend Services: API endpoints, middleware, handlers
  • Business Logic: Core algorithms, processing
  • Infrastructure: Configuration, build, deployment
  • Testing: Test utilities, test files
  • Documentation: READMEs, specs, guides
对每个主要组件进行记录：
  • 用途与职责
  • 关键文件与入口点
  • 外部依赖
  • 与其他组件的交互
  • API接口（如适用）
记录组件类别：
  • 前端组件：UI组件、页面、布局
  • 后端服务：API端点、中间件、处理器
  • 业务逻辑：核心算法、处理流程
  • 基础设施：配置、构建、部署
  • 测试：测试工具、测试文件
  • 文档：README、规格说明、指南

Step 5: Technology Stack Assessment

步骤5：技术栈评估

Identify and document:
  • Programming languages used
  • Key frameworks and libraries
  • Database systems
  • External services and APIs
  • Development tools and build systems
  • Container/deployment technologies
  • Version numbers where significant
识别并记录：
  • 使用的编程语言
  • 关键框架与库
  • 数据库系统
  • 外部服务与API
  • 开发工具与构建系统
  • 容器/部署技术
  • 重要的版本号

Step 6: Hosting and Infrastructure Analysis

步骤6：托管与基础设施分析

Assess the deployment architecture:
  1. Identify hosting platform (AWS, GCP, Vercel, Cloudflare, etc.)
  2. Document service configuration
    • Environment variables
    • Build processes
    • Deployment scripts
  3. Identify infrastructure-as-code files (Terraform, Docker, etc.)
  4. Document scaling considerations
  5. Identify external service dependencies
评估部署架构：
  1. 识别托管平台（AWS、GCP、Vercel、Cloudflare等）
  2. 记录服务配置
    • 环境变量
    • 构建流程
    • 部署脚本
  3. 识别基础设施即代码文件（Terraform、Docker等）
  4. 记录扩容考量
  5. 识别外部服务依赖

Step 7: Generate Final Documentation

步骤7：生成最终文档

Create a comprehensive architecture document including:
  1. Executive Summary
    • Project purpose
    • High-level architecture overview
    • Technology stack
    • Hosting platform and deployment
  2. Architecture Diagrams (multiple views as described in Step 3)
  3. Component Catalog
    • List of major components
    • Purpose of each
    • Key files
    • Dependencies
  4. File Structure Overview
    • Directory layout with purposes
    • Important files highlighted
  5. Data Flow Explanation
    • How requests are processed
    • Database interactions
    • External API calls
  6. Technology Details
    • Language versions
    • Framework versions
    • Key library versions
    • Database schema summary (if visible in code)
  7. Deployment and Hosting
    • Hosting platform details
    • Build and deployment process
    • Environment configuration
    • Scaling considerations
  8. Dependencies and Integrations
    • List of external services
    • API integrations
    • Authentication/authorization approach
创建包含以下内容的全面架构文档：
  1. 执行摘要
    • 项目用途
    • 高层架构概述
    • 技术栈
    • 托管平台与部署方式
  2. 架构示意图（如步骤3所述的多视角视图）
  3. 组件目录
    • 主要组件列表
    • 每个组件的用途
    • 关键文件
    • 依赖项
  4. 文件结构概述
    • 带用途说明的目录布局
    • 重点标记的重要文件
  5. 数据流说明
    • 请求处理流程
    • 数据库交互
    • 外部API调用
  6. 技术细节
    • 语言版本
    • 框架版本
    • 关键库版本
    • 数据库架构摘要（如代码中可见）
  7. 部署与托管
    • 托管平台详情
    • 构建与部署流程
    • 环境配置
    • 扩容考量
  8. 依赖与集成
    • 外部服务列表
    • API集成
    • 认证/授权方案

Common Patterns

常见模式

For Monolithic Applications

单体应用

  • Single codebase containing frontend, backend, and shared logic
  • Clear separation between presentation, business logic, and data layers
  • Review package.json/requirements.txt for all dependencies
  • 包含前端、后端与共享逻辑的单一代码库
  • 表示层、业务逻辑层与数据层之间界限清晰
  • 查看package.json/requirements.txt获取所有依赖

For Microservices

微服务

  • Multiple services in separate directories or repositories
  • Service communication documented in deployment config
  • API contracts between services
  • Separate databases per service (typically)
  • 多个服务位于不同目录或仓库
  • 服务通信记录在部署配置中
  • 服务间的API契约
  • 通常每个服务有独立数据库

For Full-Stack Web Applications

全栈Web应用

  • Frontend framework (React, Vue, Angular, etc.)
  • Backend framework (Node.js/Express, Python/Django, etc.)
  • Database (SQL or NoSQL)
  • API layer connecting frontend and backend
  • 前端框架（React、Vue、Angular等）
  • 后端框架（Node.js/Express、Python/Django等）
  • 数据库（SQL或NoSQL）
  • 连接前端与后端的API层

Edge Cases

边缘情况

Large Codebases:
  • Focus on major components first
  • Group related files together
  • Create summary before diving into details
Polyglot Repositories:
  • Separate analysis by language when relevant
  • Document language integration points
  • Highlight cross-language dependencies
Complex Infrastructure:
  • Document infrastructure-as-code separately
  • Identify deployment stages (dev, staging, prod)
  • Note auto-scaling or load balancing configurations
大型代码库：
  • 先聚焦主要组件
  • 将相关文件分组
  • 先创建摘要再深入细节
多语言仓库：
  • 相关时按语言分开分析
  • 记录语言集成点
  • 突出跨语言依赖
复杂基础设施：
  • 单独记录基础设施即代码
  • 识别部署阶段（开发、预发布、生产）
  • 记录自动扩容或负载均衡配置

Output Format

输出格式

The final architecture analysis should be delivered as:
  1. A comprehensive Markdown document with embedded ASCII diagrams
  2. Clear section headers and navigation
  3. Links between related sections
  4. Visual hierarchy showing component relationships
  5. Concise but complete descriptions
最终的架构分析应以下列形式交付：
  1. 包含嵌入式ASCII示意图的全面Markdown文档
  2. 清晰的章节标题与导航
  3. 相关章节间的链接
  4. 显示组件关系的可视化层级
  5. 简洁但完整的描述

Tools and Resources

工具与资源

The agent may use:
  • Git commands to explore repository structure
  • File reading tools to examine source code
  • Text parsing to extract key information
  • ASCII art libraries for diagram generation
Agent可使用：
  • Git命令探索仓库结构
  • 文件读取工具检查源代码
  • 文本解析提取关键信息
  • ASCII绘图库生成示意图

Example Use Case

示例用例

User Request: "Analyze the architecture of the user-management microservice in our platform"
Agent Process:
  1. Clones the user-management repository
  2. Maps the directory structure (controllers, models, tests, config)
  3. Creates ASCII diagrams showing:
    • Service components (auth handler, user DB access, role manager)
    • Data flow (API request → controller → service → database)
    • Deployment (Docker container → Kubernetes → PostgreSQL)
  4. Documents all dependencies and integrations
  5. Provides complete architecture documentation
用户请求：“分析我们平台中用户管理微服务的架构”
Agent流程：
  1. 克隆用户管理仓库
  2. 绘制目录结构（控制器、模型、测试、配置）
  3. 创建ASCII示意图，展示：
    • 服务组件（认证处理器、用户数据库访问、角色管理器）
    • 数据流（API请求→控制器→服务→数据库）
    • 部署（Docker容器→Kubernetes→PostgreSQL）
  4. 记录所有依赖与集成
  5. 提供完整的架构文档

Success Criteria

成功标准

The analysis is complete when:
  • ✅ Repository successfully cloned and analyzed
  • ✅ All major components identified
  • ✅ Multiple ASCII diagrams created showing different views
  • ✅ File structure documented and explained
  • ✅ Technology stack clearly identified
  • ✅ Hosting/deployment architecture understood
  • ✅ Data flow between components visible
  • ✅ Comprehensive documentation generated
满足以下条件时分析完成：
  • ✅ 仓库成功克隆并分析
  • ✅ 所有主要组件已识别
  • ✅ 创建多幅展示不同视角的ASCII示意图
  • ✅ 文件结构已记录并说明
  • ✅ 技术栈已清晰识别
  • ✅ 托管/部署架构已理解
  • ✅ 组件间的数据流已可视化
  • ✅ 生成全面的文档