repository-analyzer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Repository Analyzer

仓库分析器

Purpose

用途

Quickly understand unfamiliar codebases by automatically scanning structure, detecting technologies, mapping dependencies, and generating comprehensive documentation.

For SDAM users: Creates external documentation of codebase structure you can reference later. For ADHD users: Instant overview without manual exploration - saves hours of context-switching. For all users: Onboard to new projects in minutes instead of days.

通过自动扫描结构、检测技术栈、映射依赖关系、生成综合文档，快速理解不熟悉的代码库。

针对SDAM用户：生成可后续参考的代码库结构外部文档。 针对ADHD用户：无需手动探索即可获得即时概览，节省数小时的上下文切换时间。 针对所有用户：仅需数分钟即可完成新项目上手，而非数天。

Activation Triggers

触发条件

User says: "analyze repository", "understand codebase", "document project"
Requests for: "what's in this repo", "how does this work", "codebase overview"
New project onboarding scenarios
Technical debt assessment requests

用户提及："analyze repository"、"understand codebase"、"document project"
用户请求："这个仓库里有什么"、"这个项目是怎么运行的"、"代码库概览"
新项目上手场景
技术债务评估请求

Core Workflow

核心工作流

1. Scan Repository Structure

1. 扫描仓库结构

Step 1: Get directory structure

bash

undefined

步骤1：获取目录结构

bash

undefined

Use filesystem tools to map structure

tree -L 3 -I 'node_modules|.git|dist|build'


**Step 2: Count files by type**
```bash

tree -L 3 -I 'node_modules|.git|dist|build'


**步骤2：按类型统计文件数量**
```bash

Identify languages used

find . -type f -name ".js" | wc -l find . -type f -name ".py" | wc -l find . -type f -name "*.go" | wc -l

etc...


**Step 3: Measure codebase size**
```bash


**步骤3：统计代码库规模**
```bash

Count lines of code

cloc . --exclude-dir=node_modules,.git,dist,build

undefined

cloc . --exclude-dir=node_modules,.git,dist,build

undefined

2. Detect Technologies

2. 检测技术栈

Languages: JavaScript, TypeScript, Python, Go, Rust, Java, etc.

Frameworks:

Frontend: React, Vue, Angular, Svelte
Backend: Express, FastAPI, Django, Rails
Mobile: React Native, Flutter
Desktop: Electron, Tauri

Detection methods:

javascript

const detectFramework = async () => {
  // Check package.json
  const packageJson = await readFile('package.json');
  const dependencies = packageJson.dependencies || {};

  if ('react' in dependencies) return 'React';
  if ('vue' in dependencies) return 'Vue';
  if ('express' in dependencies) return 'Express';

  // Check requirements.txt
  const requirements = await readFile('requirements.txt');
  if (requirements.includes('fastapi')) return 'FastAPI';
  if (requirements.includes('django')) return 'Django';

  // Check go.mod
  const goMod = await readFile('go.mod');
  if (goMod.includes('gin-gonic')) return 'Gin';

  return 'Unknown';
};

编程语言：JavaScript、TypeScript、Python、Go、Rust、Java等。

框架:

前端：React、Vue、Angular、Svelte
后端：Express、FastAPI、Django、Rails
移动端：React Native、Flutter
桌面端：Electron、Tauri

检测逻辑:

javascript

const detectFramework = async () => {
  // Check package.json
  const packageJson = await readFile('package.json');
  const dependencies = packageJson.dependencies || {};

  if ('react' in dependencies) return 'React';
  if ('vue' in dependencies) return 'Vue';
  if ('express' in dependencies) return 'Express';

  // Check requirements.txt
  const requirements = await readFile('requirements.txt');
  if (requirements.includes('fastapi')) return 'FastAPI';
  if (requirements.includes('django')) return 'Django';

  // Check go.mod
  const goMod = await readFile('go.mod');
  if (goMod.includes('gin-gonic')) return 'Gin';

  return 'Unknown';
};

3. Map Dependencies

3. 映射依赖关系

For Node.js:

bash

undefined

针对Node.js项目:

bash

undefined

Read package.json

cat package.json | jq '.dependencies' cat package.json | jq '.devDependencies'

Check for outdated packages

npm outdated


**For Python**:
```bash

npm outdated


**针对Python项目**:
```bash

Read requirements.txt or pyproject.toml

cat requirements.txt

Check for outdated packages

pip list --outdated


**For Go**:
```bash

pip list --outdated


**针对Go项目**:
```bash

Read go.mod

cat go.mod

Check for outdated modules

go list -u -m all

undefined

go list -u -m all

undefined

4. Identify Architecture Patterns

4. 识别架构模式

Common patterns to detect:

MVC (Model-View-Controller):
```
models/
```
,
```
views/
```
,
```
controllers/
```
Layered:
```
api/
```
,
```
services/
```
,
```
repositories/
```
Feature-based:
```
features/auth/
```
,
```
features/users/
```
Domain-driven:
```
domain/
```
,
```
application/
```
,
```
infrastructure/
```
Microservices: Multiple services in
```
services/
```
directory
Monorepo: Workspaces or packages structure

Detection logic:

javascript

const detectArchitecture = (structure) => {
  if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
    return 'MVC Pattern';
  }
  if (structure.includes('features')) {
    return 'Feature-based Architecture';
  }
  if (structure.includes('domain') && structure.includes('application')) {
    return 'Domain-Driven Design';
  }
  if (structure.includes('services') && structure.includes('api-gateway')) {
    return 'Microservices Architecture';
  }
  return 'Custom Architecture';
};

可检测的常见模式:

MVC (Model-View-Controller): 存在
```
models/
```
、
```
views/
```
、
```
controllers/
```
目录
分层架构: 存在
```
api/
```
、
```
services/
```
、
```
repositories/
```
目录
按feature拆分架构: 存在
```
features/auth/
```
、
```
features/users/
```
等目录
领域驱动设计: 存在
```
domain/
```
、
```
application/
```
、
```
infrastructure/
```
目录
微服务架构:
```
services/
```
目录下存在多个独立服务
Monorepo: 存在workspaces或者packages结构

检测逻辑:

javascript

const detectArchitecture = (structure) => {
  if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
    return 'MVC Pattern';
  }
  if (structure.includes('features')) {
    return 'Feature-based Architecture';
  }
  if (structure.includes('domain') && structure.includes('application')) {
    return 'Domain-Driven Design';
  }
  if (structure.includes('services') && structure.includes('api-gateway')) {
    return 'Microservices Architecture';
  }
  return 'Custom Architecture';
};

5. Extract Technical Debt

5. 提取技术债务

Search for indicators:

bash

undefined

搜索债务标识:

bash

undefined

Find TODOs

grep -r "TODO" --include=".js" --include=".py" --include="*.go"

Find FIXMEs

grep -r "FIXME" --include=".js" --include=".py" --include="*.go"

Find HACKs

grep -r "HACK" --include=".js" --include=".py" --include="*.go"

Find deprecated code

grep -r "@deprecated" --include=".js" --include=".ts"


**Complexity analysis**:
```javascript
// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

grep -r "@deprecated" --include=".js" --include=".ts"


**复杂度分析**:
```javascript
// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

6. Generate Documentation

6. 生成文档

Output format:

markdown

undefined

输出格式:

markdown

undefined

{Project Name} - Repository Analysis

Generated: {timestamp} Analyzed by: Claude Code Repository Analyzer

📊 Overview

Primary Language: {language} Framework: {framework} Architecture: {architecture pattern} Total Files: {count} Lines of Code: {LOC} Last Updated: {git log date}

📁 Directory Structure

project/
├── src/
│   ├── components/
│   ├── services/
│   └── utils/
├── tests/
└── docs/

project/
├── src/
│   ├── components/
│   ├── services/
│   └── utils/
├── tests/
└── docs/

🛠 Technologies

Frontend

React 18.2.0
TypeScript 5.0
Tailwind CSS 3.3

React 18.2.0
TypeScript 5.0
Tailwind CSS 3.3

Backend

Node.js 18
Express 4.18
PostgreSQL 15

Node.js 18
Express 4.18
PostgreSQL 15

DevOps

Docker
GitHub Actions
Jest for testing

Docker
GitHub Actions
Jest for testing

📦 Dependencies

Production (12 packages)

express: 4.18.2
pg: 8.11.0
jsonwebtoken: 9.0.0
...

express: 4.18.2
pg: 8.11.0
jsonwebtoken: 9.0.0
...

Development (8 packages)

typescript: 5.0.4
jest: 29.5.0
eslint: 8.40.0
...

typescript: 5.0.4
jest: 29.5.0
eslint: 8.40.0
...

⚠️ Outdated (3 packages)

express: 4.18.2 → 4.19.0 (minor update available)
jest: 29.5.0 → 29.7.0 (patch updates available)

express: 4.18.2 → 4.19.0 (minor update available)
jest: 29.5.0 → 29.7.0 (patch updates available)

🏗 Architecture

Pattern: Layered Architecture

Layers:

API Layer (
```
src/api/
```
): REST endpoints, request validation
Service Layer (
```
src/services/
```
): Business logic
Repository Layer (
```
src/repositories/
```
): Database access
Models (
```
src/models/
```
): Data structures

Data Flow:

Client → API → Service → Repository → Database

Pattern: Layered Architecture

Layers:

API Layer (
```
src/api/
```
): REST endpoints, request validation
Service Layer (
```
src/services/
```
): Business logic
Repository Layer (
```
src/repositories/
```
): Database access
Models (
```
src/models/
```
): Data structures

Data Flow:

Client → API → Service → Repository → Database

🔍 Code Quality

Metrics:

Average function length: 25 lines
Cyclomatic complexity: 3.2 (low)
Test coverage: 78%
TypeScript strict mode: ✅ Enabled

Strengths:

✅ Well-structured codebase
✅ Good test coverage
✅ Type-safe with TypeScript

Areas for Improvement:

⚠️ 12 TODOs found (see Technical Debt section)
⚠️ 3 outdated dependencies
⚠️ Missing documentation in
```
/utils
```

Metrics:

Average function length: 25 lines
Cyclomatic complexity: 3.2 (low)
Test coverage: 78%
TypeScript strict mode: ✅ Enabled

Strengths:

✅ Well-structured codebase
✅ Good test coverage
✅ Type-safe with TypeScript

Areas for Improvement:

⚠️ 12 TODOs found (see Technical Debt section)
⚠️ 3 outdated dependencies
⚠️ Missing documentation in
```
/utils
```

🐛 Technical Debt

High Priority (3)

FIXME in
```
src/services/auth.js:42
```
: JWT refresh token rotation not implemented
TODO in
```
src/api/users.js:78
```
: Add rate limiting
HACK in
```
src/utils/cache.js:23
```
: Using setTimeout instead of proper cache expiry

FIXME in
```
src/services/auth.js:42
```
: JWT refresh token rotation not implemented
TODO in
```
src/api/users.js:78
```
: Add rate limiting
HACK in
```
src/utils/cache.js:23
```
: Using setTimeout instead of proper cache expiry

Medium Priority (5)

TODO in
```
src/components/Dashboard.jsx:15
```
: Optimize re-renders
TODO in
```
tests/integration/api.test.js:100
```
: Add more edge cases
...

TODO in
```
src/components/Dashboard.jsx:15
```
: Optimize re-renders
TODO in
```
tests/integration/api.test.js:100
```
: Add more edge cases
...

Low Priority (4)

TODO in
```
README.md:50
```
: Update installation instructions
...

TODO in
```
README.md:50
```
: Update installation instructions
...

🚀 Entry Points

Main Application:

```
src/index.js
```
- Server entry point
```
src/client/index.jsx
```
- Client entry point

Development:

```
npm run dev
```
- Start dev server
```
npm test
```
- Run tests
```
npm run build
```
- Production build

Configuration:

```
.env.example
```
- Environment variables
```
tsconfig.json
```
- TypeScript config
```
jest.config.js
```
- Test configuration

Main Application:

```
src/index.js
```
- Server entry point
```
src/client/index.jsx
```
- Client entry point

Development:

```
npm run dev
```
- Start dev server
```
npm test
```
- Run tests
```
npm run build
```
- Production build

Configuration:

```
.env.example
```
- Environment variables
```
tsconfig.json
```
- TypeScript config
```
jest.config.js
```
- Test configuration

📋 Common Tasks

Adding a new feature:

Create component in
```
src/components/
```
Add service logic in
```
src/services/
```
Create API endpoint in
```
src/api/
```
Write tests in
```
tests/
```

Database changes:

Create migration in
```
migrations/
```
Update models in
```
src/models/
```
Run
```
npm run migrate
```

Adding a new feature:

Create component in
```
src/components/
```
Add service logic in
```
src/services/
```
Create API endpoint in
```
src/api/
```
Write tests in
```
tests/
```

Database changes:

Create migration in
```
migrations/
```
Update models in
```
src/models/
```
Run
```
npm run migrate
```

🔗 Integration Points

External Services:

PostgreSQL database (port 5432)
Redis cache (port 6379)
SendGrid API (email)
Stripe API (payments)

API Endpoints:

```
GET /api/users
```
- List users
```
POST /api/auth/login
```
- Authentication
```
GET /api/dashboard
```
- Dashboard data

External Services:

PostgreSQL database (port 5432)
Redis cache (port 6379)
SendGrid API (email)
Stripe API (payments)

API Endpoints:

```
GET /api/users
```
- List users
```
POST /api/auth/login
```
- Authentication
```
GET /api/dashboard
```
- Dashboard data

📚 Additional Resources

Architecture Diagram
API Documentation
Development Guide

Next Steps:

Address high-priority technical debt
Update outdated dependencies
Increase test coverage to 85%+
Document utility functions


See [patterns.md](patterns.md) for architecture pattern library and [examples.md](examples.md) for analysis examples.

Architecture Diagram
API Documentation
Development Guide

Next Steps:

Address high-priority technical debt
Update outdated dependencies
Increase test coverage to 85%+
Document utility functions


查看[patterns.md](patterns.md)获取架构模式库，查看[examples.md](examples.md)获取分析示例。

Advanced Analysis Features

高级分析功能

Git History Analysis

Git历史分析

bash

undefined

bash

undefined

Find most changed files (hotspots)

git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10

Find largest contributors

git shortlog -sn

Recent activity

git log --oneline --since="30 days ago" --no-merges

undefined

git log --oneline --since="30 days ago" --no-merges

undefined

Code Complexity Metrics

代码复杂度指标

bash

undefined

bash

undefined

Using complexity tools

npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'

Or manual analysis

Functions > 50 lines = candidate for refactoring

Files > 500 lines = candidate for splitting

undefined

undefined

Dependency Security

依赖安全检测

bash

undefined

bash

undefined

Check for vulnerabilities

npm audit pip-audit # for Python go mod tidy && go list -m all # for Go

undefined

npm audit pip-audit # for Python go mod tidy && go list -m all # for Go

undefined

Integration with Other Skills

与其他能力的集成

Context Manager

上下文管理器

Save repository overview:

remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
         12 high-priority TODOs, 78% test coverage

保存仓库概览:

remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
         12 high-priority TODOs, 78% test coverage

Error Debugger

错误调试器

If analysis finds common issues:

Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected

如果分析发现常见问题:

Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected

Browser App Creator

浏览器应用生成器

Generate visualization:

Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart

生成可视化内容:

Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart

Quality Checklist

质量检查清单

Before delivering documentation, verify:

✅ Directory structure mapped
✅ Languages and frameworks identified
✅ Dependencies listed
✅ Architecture pattern detected
✅ Technical debt catalogued
✅ Entry points documented
✅ Common tasks explained
✅ Markdown formatted properly

交付文档前，请确认:

✅ 目录结构已完整映射
✅ 编程语言和框架已识别
✅ 依赖已完整列出
✅ 架构模式已检测
✅ 技术债务已分类统计
✅ 入口点已文档化
✅ 常见任务已说明
✅ Markdown格式正确

Output Delivery

输出交付

Format: Markdown file saved to

~/.claude-artifacts/analysis-{project}-{timestamp}.md

(Linux/macOS) or

%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

(Windows)

Notify user:

✅ **{Project Name} Analysis** complete!

**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found

**Documentation saved to:** {filepath}

**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}

**Recommended actions:**
- {action_1}
- {action_2}

格式: Markdown文件保存到

~/.claude-artifacts/analysis-{project}-{timestamp}.md

(Linux/macOS) 或者

%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

(Windows)

用户通知:

✅ **{Project Name} Analysis** complete!

**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found

**Documentation saved to:** {filepath}

**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}

**Recommended actions:**
- {action_1}
- {action_2}

Common Analysis Scenarios

常见分析场景

New Project Onboarding

新项目上手

User joins unfamiliar project → analyzer provides complete overview in minutes

用户加入不熟悉的项目 → 分析器数分钟内提供完整概览

Technical Debt Assessment

技术债务评估

User needs to evaluate legacy code → analyzer identifies all TODOs/FIXMEs/HACKs

用户需要评估遗留代码 → 分析器识别所有TODO/FIXME/HACK

Dependency Audit

依赖审计

User wants to check outdated packages → analyzer lists all outdated dependencies with versions

用户想要检查过时的依赖包 → 分析器列出所有过时依赖及版本

Architecture Documentation

架构文档生成

User needs to document existing project → analyzer generates comprehensive architecture docs

用户需要为现有项目生成文档 → 分析器生成完整的架构文档

Success Criteria

成功标准

✅ Complete codebase structure mapped ✅ All technologies identified correctly ✅ Dependencies catalogued with versions ✅ Architecture pattern detected ✅ Technical debt surfaced ✅ Documentation generated in <2 minutes ✅ Markdown output saved to artifacts ✅ Actionable recommendations provided

✅ 完整映射代码库结构 ✅ 正确识别所有技术栈 ✅ 按版本分类统计依赖 ✅ 检测到对应架构模式 ✅ 披露所有技术债务 ✅ 2分钟内生成文档 ✅ Markdown输出保存到 artifacts 目录 ✅ 提供可执行的改进建议

Additional Resources

额外资源

Pattern Library - Common architecture patterns
Analysis Examples - Real-world repository analyses

模式库 - 常见架构模式
分析示例 - 真实仓库分析案例

Quick Reference

快速参考

Trigger Phrases

触发短语

"analyze repository"
"understand codebase"
"document project"
"what's in this repo"
"codebase overview"
"technical debt report"

"analyze repository"
"understand codebase"
"document project"
"what's in this repo"
"codebase overview"
"technical debt report"

Output Location

输出位置

Linux/macOS:

~/.claude-artifacts/analysis-{project}-{timestamp}.md

Windows:

%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

Linux/macOS:

~/.claude-artifacts/analysis-{project}-{timestamp}.md

Windows:

%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

Analysis Depth Options

分析深度选项

Quick (<1 min): Structure + languages only
Standard (1-2 min): + dependencies + patterns
Deep (3-5 min): + git history + complexity metrics + security audit

快速 (<1分钟): 仅输出结构 + 编程语言
标准 (1-2分钟): 增加依赖分析 + 架构模式检测
深度 (3-5分钟): 增加Git历史分析 + 复杂度指标 + 安全审计