name: codebase-analysis description: 系统分析代码库结构、复杂性、依赖关系和架构模式，以理解项目组织 version: 1.0.0 author: AI-Vibe-Prompts tags: [分析, 代码质量, 架构, 依赖关系] auto_invoke: true

代码库分析技能

目标

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

项目结构和组织
技术栈和依赖关系 n- 架构模式和约定
代码复杂性和质量指标
关键组件及其关系

何时使用此技能

自动触发时机：

开始新项目时
用户要求“分析”、“审查”、“审计”或“理解”代码库时
做出架构决策之前
计划重构或重大变更时
新开发人员入职时

分析方法论

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

目标：映射高层次的项目组织

工具：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/

阶段2：技术栈分析

目标：识别框架、库和版本

工具：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 模块
- 测试：Vitest、Jest、Playwright、Cypress
- 构建工具：Vite、Webpack、esbuild、Turbopack

阶段3：架构模式分析

目标：理解代码组织和模式

工具：Grep、Glob、Read

流程：

组件模式（针对 React/Vue/Svelte）：

使用 Glob 查找：**/*.{jsx,tsx,vue,svelte}
分析：
- 组件命名约定
- 文件结构（共置样式、测试）
- 组件大小（代码行数）

API/后端模式：

使用 Grep 搜索：
- API 路由："export.*GET|POST|PUT|DELETE"
- 数据库查询："prisma\.|mongoose\.|sql"
- 身份验证："auth|jwt|session"

状态管理模式：

使用 Grep 查找：
- Context API："createContext|useContext"
- Redux："createSlice|useSelector"
- Zustand："create.*useStore"

文件组织模式：
- 单体仓库：检查 packages/、apps/、turbo.json、nx.json
- 基于功能：检查 features/、modules/ 等目录
- 基于分层：检查 components/、services/、utils/、hooks/

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

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

工具：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）

代码复杂性指标：

使用 Grep 标记潜在问题：
- 大文件：查找 > 500 行的文件
- 深度嵌套：搜索过度缩进
- TODO/FIXME 注释：Grep 查找 "TODO|FIXME|HACK"
- 控制台日志：Grep 查找 "console\.(log|debug|warn)"

阶段5：依赖与安全分析

目标：识别过时或易受攻击的依赖项

工具：Bash、Read

流程：

检查锁定文件：
- 是否存在 package-lock.json、yarn.lock、pnpm-lock.yaml
运行安全审计（如果 npm/pnpm 可用）：
```
npm audit --json
# 或
pnpm audit --json
```
检查过时依赖项：
```
npm outdated
```

输出格式

提供结构化分析报告：

# 代码库分析报告

## 项目概览
- **名称**：[来自 package.json 的项目名称]
- **类型**：[框架/库]
- **版本**：[版本]
- **Node.js**：[所需版本]

## 技术栈
### 核心框架
- [框架名称和版本]

### 关键依赖项
- UI：[库]
- 状态：[库]
- 路由：[库]
- 样式：[库]
- 测试：[库]

### 构建工具
- [Vite/Webpack/等]

## 架构

### 目录结构

[关键目录的树状表示]


### 识别出的模式
- [组件模式]
- [状态管理方法]
- [API 结构]
- [文件组织]

## 代码质量指标
- **TypeScript**：[严格/宽松/无]
- **代码检查**：[ESLint/Biome/无]
- **测试**：[找到 X 个测试文件，覆盖率：Y%]
- **代码问题**：[TODOs：X，控制台日志：Y]

## 建议
1. [优先建议]
2. [次优先建议]
3. ...

## 风险领域
- [潜在问题或技术债务]

## 后续步骤
- [基于分析的推荐行动]

最佳实践

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

与其他技能的集成

此技能与以下技能配合良好：

quality-gates - 使用分析结果运行适当的质量检查
project-initialization - 与模板比较以识别缺失的设置
refactoring-safe - 识别重构机会
框架特定技能（nextjs-optimization、react-patterns） - 基于检测到的框架自动触发

错误处理

如果分析无法完成：

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

版本历史

1.0.0（2025-01-03）：初始技能创建，支持渐进式披露