codebase-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Analysis Skill

代码库分析Skill

Objective

目标

Perform comprehensive, systematic analysis of project codebases to understand:

Project structure and organization
Technology stack and dependencies
Architectural patterns and conventions
Code complexity and quality metrics
Key components and their relationships

对项目代码库进行全面、系统性的分析，以了解：

项目结构与组织方式
技术栈与依赖关系
架构模式与约定
代码复杂度与质量指标
核心组件及其相互关系

When to Use This Skill

使用场景

Auto-invoke when:

Starting work on a new project
User asks to "analyze", "review", "audit", or "understand" the codebase
Before making architectural decisions
Planning refactoring or major changes
Onboarding new developers

在以下场景自动调用：

开始参与新项目工作时
用户要求“分析”“评审”“审计”或“理解”代码库时
制定架构决策前
规划重构或重大变更时
新开发人员入职培训时

Analysis Methodology

分析方法

Phase 1: Discovery (Project Structure)

阶段1：发现（项目结构）

Goal: Map the high-level project organization

Tools: Glob, LS, Read

Process:

Identify project type by reading
```
package.json
```
,
```
tsconfig.json
```
, or framework-specific configs

Map directory structure using LS at root level:

Key directories to identify:
- Source code: src/, app/, pages/, components/
- Tests: __tests__/, tests/, *.test.*, *.spec.*
- Config: config/, .config/
- Documentation: docs/, README.md
- Build output: dist/, build/, .next/

Scan for important files:

Build configs:

vite.config.*, webpack.config.*, next.config.*

TypeScript:
```
tsconfig.json
```
,
```
tsconfig.*.json
```

Package management:

package.json

package-lock.json

yarn.lock

pnpm-lock.yaml

Environment:
```
.env*
```
,
```
.env.example
```
Git:
```
.gitignore
```
,
```
.git/
```

目标：梳理项目的高层级组织架构

工具：Glob、LS、Read

流程：

识别项目类型：读取
```
package.json
```
、
```
tsconfig.json
```
或框架特定配置文件

映射目录结构：在根目录使用LS命令：

需要识别的关键目录：
- 源代码：src/, app/, pages/, components/
- 测试：__tests__/, tests/, *.test.*, *.spec.*
- 配置：config/, .config/
- 文档：docs/, README.md
- 构建输出：dist/, build/, .next/

扫描重要文件：

构建配置：

vite.config.*, webpack.config.*, next.config.*

TypeScript配置：
```
tsconfig.json
```
,
```
tsconfig.*.json
```

包管理：

package.json

package-lock.json

yarn.lock

pnpm-lock.yaml

环境配置：
```
.env*
```
,
```
.env.example
```
Git相关：
```
.gitignore
```
,
```
.git/
```

Phase 2: Technology Stack Analysis

阶段2：技术栈分析

Goal: Identify frameworks, libraries, and versions

Tools: Read, Grep

Process:

Read package.json:
- Extract
```
dependencies
```
  (runtime libraries)
- Extract
```
devDependencies
```
  (development tools)
- Note
```
scripts
```
  (available commands)
- Check
```
engines
```
  (Node.js version requirements)
Identify framework:
- Next.js: Check for
```
next
```
  in dependencies,
```
next.config.*
```
  ,
```
app/
```
  or
```
pages/
```
  directory
- React: Check for
```
react
```
  and
```
react-dom
```
- Vue: Check for
```
vue
```
  ,
```
*.vue
```
  files
- Svelte: Check for
```
svelte
```
  ,
```
*.svelte
```
  files
- Angular: Check for
```
@angular/core
```
  ,
```
angular.json
```
Identify key libraries:
- State management: Redux, Zustand, MobX, Pinia
- Routing: react-router, vue-router, next/navigation
- UI libraries: MUI, Ant Design, shadcn/ui, Chakra UI
- Styling: Tailwind CSS, styled-components, emotion, CSS modules
- Testing: Vitest, Jest, Playwright, Cypress
- Build tools: Vite, Webpack, esbuild, Turbopack

目标：识别框架、库及其版本

工具：Read、Grep

流程：

读取package.json：
- 提取
```
dependencies
```
  （运行时库）
- 提取
```
devDependencies
```
  （开发工具）
- 记录
```
scripts
```
  （可用命令）
- 查看
```
engines
```
  （Node.js版本要求）
识别框架：
- Next.js：检查依赖中是否有
```
next
```
  、是否存在
```
next.config.*
```
  、
```
app/
```
  或
```
pages/
```
  目录
- React：检查是否有
```
react
```
  和
```
react-dom
```
  依赖
- Vue：检查是否有
```
vue
```
  依赖、
```
*.vue
```
  文件
- Svelte：检查是否有
```
svelte
```
  依赖、
```
*.svelte
```
  文件
- Angular：检查是否有
```
@angular/core
```
  依赖、
```
angular.json
```
  文件
识别核心库：
- 状态管理：Redux、Zustand、MobX、Pinia
- 路由：react-router、vue-router、next/navigation
- UI库：MUI、Ant Design、shadcn/ui、Chakra UI
- 样式方案：Tailwind CSS、styled-components、emotion、CSS modules
- 测试工具：Vitest、Jest、Playwright、Cypress
- 构建工具：Vite、Webpack、esbuild、Turbopack

Phase 3: Architecture Pattern Analysis

阶段3：架构模式分析

Goal: Understand code organization and patterns

Tools: Grep, Glob, Read

Process:

Component patterns (for React/Vue/Svelte):

Use Glob to find: **/*.{jsx,tsx,vue,svelte}
Analyze:
- Component naming conventions
- File structure (co-located styles, tests)
- Component size (lines of code)

API/Backend patterns:

Use Grep to search for:
- API routes: "export.*GET|POST|PUT|DELETE"
- Database queries: "prisma\.|mongoose\.|sql"
- Authentication: "auth|jwt|session"

State management patterns:

Use Grep to find:
- Context API: "createContext|useContext"
- Redux: "createSlice|useSelector"
- Zustand: "create.*useStore"

File organization patterns:
- Monorepo: Check for
```
packages/
```
  ,
```
apps/
```
  ,
```
turbo.json
```
  ,
```
nx.json
```
- Feature-based: Check for directories like
```
features/
```
  ,
```
modules/
```
- Layer-based: Check for
```
components/
```
  ,
```
services/
```
  ,
```
utils/
```
  ,
```
hooks/
```

目标：理解代码组织方式与模式

工具：Grep、Glob、Read

流程：

组件模式（适用于React/Vue/Svelte）：

Use Glob to find: **/*.{jsx,tsx,vue,svelte}
Analyze:
- Component naming conventions
- File structure (co-located styles, tests)
- Component size (lines of code)

API/后端模式：

Use Grep to search for:
- API routes: "export.*GET|POST|PUT|DELETE"
- Database queries: "prisma\.|mongoose\.|sql"
- Authentication: "auth|jwt|session"

状态管理模式：

Use Grep to find:
- Context API: "createContext|useContext"
- Redux: "createSlice|useSelector"
- Zustand: "create.*useStore"

文件组织模式：
- 单仓多包（Monorepo）：检查是否存在
```
packages/
```
  ,
```
apps/
```
  ,
```
turbo.json
```
  ,
```
nx.json
```
- 基于功能：检查是否有
```
features/
```
  ,
```
modules/
```
  等目录
- 基于分层：检查是否有
```
components/
```
  ,
```
services/
```
  ,
```
utils/
```
  ,
```
hooks/
```
  等目录

Phase 4: Code Quality & Complexity Assessment

阶段4：代码质量与复杂度评估

Goal: Identify potential issues and technical debt

Tools: Grep, Bash, Read

Process:

Linting & Formatting:
- Check for:
```
.eslintrc*
```
  ,
```
.prettierrc*
```
  ,
```
biome.json
```
- Run linter if available:
```
npm run lint
```
  (via Bash)
Testing coverage:
- Find test files: Use Glob for
```
**/*.{test,spec}.{js,ts,jsx,tsx}
```
- Calculate coverage: Run
```
npm run test:coverage
```
  if available
TypeScript strictness:
- Read
```
tsconfig.json
```
- Check
```
strict: true
```
  ,
```
strictNullChecks
```
  , etc.
- Look for
```
@ts-ignore
```
  or
```
any
```
  usage (Grep)

Code complexity indicators:

Use Grep to flag potential issues:
- Large files: Find files > 500 lines
- Deep nesting: Search for excessive indentation
- TODO/FIXME comments: Grep for "TODO|FIXME|HACK"
- Console logs: Grep for "console\.(log|debug|warn)"

目标：识别潜在问题与技术债务

工具：Grep、Bash、Read

流程：

代码检查与格式化：
- 检查是否存在：
```
.eslintrc*
```
  ,
```
.prettierrc*
```
  ,
```
biome.json
```
- 若可用则运行检查工具：
```
npm run lint
```
  （通过Bash执行）
测试覆盖率：
- 查找测试文件：使用Glob匹配
```
**/*.{test,spec}.{js,ts,jsx,tsx}
```
- 计算覆盖率：若可用则运行
```
npm run test:coverage
```
TypeScript严格性：
- 读取
```
tsconfig.json
```
- 检查
```
strict: true
```
  ,
```
strictNullChecks
```
  等配置项
- 查找
```
@ts-ignore
```
  或
```
any
```
  的使用情况（通过Grep）

代码复杂度指标：

Use Grep to flag potential issues:
- Large files: Find files > 500 lines
- Deep nesting: Search for excessive indentation
- TODO/FIXME comments: Grep for "TODO|FIXME|HACK"
- Console logs: Grep for "console\.(log|debug|warn)"

Phase 5: Dependency & Security Analysis

阶段5：依赖与安全分析

Goal: Identify outdated or vulnerable dependencies

Tools: Bash, Read

Process:

Check for lock files:

Presence of

package-lock.json

yarn.lock

pnpm-lock.yaml

Run security audit (if npm/pnpm available):
bash
```
npm audit --json
# or
pnpm audit --json
```
Check for outdated dependencies:
bash
```
npm outdated
```

目标：识别过时或存在安全漏洞的依赖

工具：Bash、Read

流程：

检查锁文件：

是否存在

package-lock.json

yarn.lock

pnpm-lock.yaml

运行安全审计（若npm/pnpm可用）：
bash
```
npm audit --json
# or
pnpm audit --json
```
检查过时依赖：
bash
```
npm outdated
```

Output Format

输出格式

Provide a structured analysis report:

markdown

undefined

提供结构化的分析报告：

markdown

undefined

Codebase Analysis Report

Project Overview

Name: [project name from package.json]
Type: [framework/library]
Version: [version]
Node.js: [required version]

Name: [project name from package.json]
Type: [framework/library]
Version: [version]
Node.js: [required version]

Technology Stack

Core Framework

[Framework name & version]

[Framework name & version]

Key Dependencies

UI: [library]
State: [library]
Routing: [library]
Styling: [library]
Testing: [library]

UI: [library]
State: [library]
Routing: [library]
Styling: [library]
Testing: [library]

Build Tools

[Vite/Webpack/etc]

[Vite/Webpack/etc]

Architecture

Directory Structure

[tree-like representation of key directories]

[tree-like representation of key directories]

Patterns Identified

[Component patterns]
[State management approach]
[API structure]
[File organization]

[Component patterns]
[State management approach]
[API structure]
[File organization]

Code Quality Metrics

TypeScript: [strict/loose/none]
Linting: [ESLint/Biome/none]
Testing: [X test files found, coverage: Y%]
Code Issues: [TODOs: X, Console logs: Y]

TypeScript: [strict/loose/none]
Linting: [ESLint/Biome/none]
Testing: [X test files found, coverage: Y%]
Code Issues: [TODOs: X, Console logs: Y]

Recommendations

[Priority recommendation]
[Next priority]
...

[Priority recommendation]
[Next priority]
...

Risk Areas

[Potential issues or technical debt]

[Potential issues or technical debt]

Next Steps

[Suggested actions based on analysis]

undefined

[Suggested actions based on analysis]

undefined

Best Practices

最佳实践

Progressive Detail: Start with high-level overview, dive deeper only when needed
Context Window Management: For large codebases, analyze in chunks (by directory/feature)
Tool Selection:
- Use Glob for file discovery (faster than find)
- Use Grep for pattern search (faster than reading all files)
- Use Read only for critical files (package.json, configs)
Time Efficiency: Complete analysis in < 60 seconds for typical projects
Actionable Insights: Always provide specific, actionable recommendations

渐进式细节分析：从高层级概述开始，仅在需要时深入细节
上下文窗口管理：对于大型代码库，按目录/功能分块分析
工具选择：
- 使用Glob进行文件发现（比find更快）
- 使用Grep进行模式搜索（比读取所有文件更快）
- 仅对关键文件使用Read（如package.json、配置文件）
时间效率：典型项目的分析需在< 60秒内完成
可落地的洞察：始终提供具体、可执行的建议

Integration with Other Skills

与其他Skill的集成

This skill works well with:

```
quality-gates
```
- Use analysis results to run appropriate quality checks
```
project-initialization
```
- Compare against templates to identify missing setup
```
refactoring-safe
```
- Identify refactoring opportunities
Framework-specific skills (
```
nextjs-optimization
```
,
```
react-patterns
```
) - Auto-invoke based on detected framework

本Skill可与以下Skill协同使用：

```
quality-gates
```
- 利用分析结果运行相应的质量检查
```
project-initialization
```
- 与模板对比，识别缺失的配置项
```
refactoring-safe
```
- 识别重构机会
框架特定Skill（
```
nextjs-optimization
```
,
```
react-patterns
```
）- 根据检测到的框架自动调用

Error Handling

错误处理

If analysis cannot complete:

Missing dependencies: Suggest running
```
npm install
```
Corrupted files: Report specific files and continue with partial analysis
Large codebase: Switch to targeted analysis mode (specific directories only)
Permission issues: Request necessary file access permissions

若分析无法完成：

依赖缺失：建议运行
```
npm install
```
文件损坏：报告具体损坏的文件，继续完成部分分析
大型代码库：切换到针对性分析模式（仅分析特定目录）
权限问题：请求必要的文件访问权限

Version History

版本历史

1.0.0 (2025-01-03): Initial skill creation with progressive disclosure support

1.0.0 (2025-01-03): Initial skill creation with progressive disclosure support