project-analyzer

SKILL.md

---
name: project-analyzer
description: Comprehensive code project analysis and architecture review tool. Automatically generates structured reports with tree structures, ASCII architecture diagrams, code highlight analysis, and prioritized defect identification (P0/P1/P2). TRIGGER for explicit project analysis requests with a clear target path or URL. NOT for: code questions ("这个函数是做什么的"), vague requests without a target, or single-file tasks. Works with local paths OR GitHub URLs.
---

# Code Project Analyzer

Analyze code projects and generate comprehensive structured reports.

## Overview

This skill analyzes code projects to understand their architecture, identify highlights and defects, and produce a structured markdown report following a specific template.

**Input**: Project path (local filesystem) or GitHub repository URL
**Output**: `analysis_YYYYMMDD.md` file with structured analysis

## Workflow

### 1. Input Validation and Setup

#### Step 1a: Input Clarity Check (Critical)

Before proceeding, verify the user has provided sufficient information:

**Required**: A specific project path OR GitHub repository URL

**If input is ambiguous** (e.g., "帮我看看这个项目的架构" without specifying which project):
- Ask the user to clarify: "请提供要分析的项目路径（例如 /path/to/project）或 GitHub 仓库 URL"
- Do NOT assume the current working directory or guess the user's intent
- Only proceed once a clear target is provided

**If input is a code question** (e.g., "这个函数是做什么的？"):
- This is NOT a project analysis task. Answer the question directly without invoking the full analysis workflow.

#### Step 1b: Path Validation

**For local paths**:
- Verify the path exists
- Identify the project root (look for common markers: `.git`, `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, etc.)

**For GitHub URLs**:
- Clone the repository to a temporary location
- Use the cloned path for analysis
- Clean up after report generation

**Validation**:
- Ensure the project contains source code files
- Reject if it's only documentation or configuration

### 2. Ignore Non-Essential Files

Exclude these from analysis:
- **Tests**: `test/`, `tests/`, `spec/`, `__tests__/`, `*.test.*`, `*.spec.*`
- **Documentation**: `docs/`, `*.md`, `README*`, `CHANGELOG*`, `LICENSE*`
- **Configuration**: `.github/`, `.gitlab-ci.yml`, `*.config.js`, `*.config.ts`, `.env*`, `docker-compose.yml`, `Dockerfile`
- **CI/CD**: `.travis.yml`, `Jenkinsfile`, `.circleci/`, `azure-pipelines.yml`
- **Build artifacts**: `dist/`, `build/`, `target/`, `node_modules/`, `__pycache__/`, `.venv/`
- **IDE configs**: `.vscode/`, `.idea/`, `*.swp`, `*.swo`

**Use Glob tool to find files**:
```bash
# Example: Find Python source files
**/*.py but exclude test/**, **/__pycache__/**

# Example: Find JavaScript/TypeScript source files
**/*.{js,jsx,ts,tsx} but exclude node_modules/**, **/*.test.*
```

### 3. Depth Control for Large Projects

For projects with many files, limit analysis to core code:

**Detection**: If the project has >100 source files or >10,000 lines of code

**Strategy**:
1. Identify entry points: `main.*`, `index.*`, `app.*`, `src/main.*`
2. Map module dependencies starting from entry points
3. Analyze up to **3 levels deep** from entry points
4. Skip deeply nested utility modules unless they're critical

**Priority order**:
1. Core business logic (domain models, services, controllers)
2. API endpoints and routing
3. Data models and schemas
4. Key abstractions and interfaces
5. Utility functions (only if time permits)

### 4. Analyze Project Structure

**Step 1: Map the directory tree**
- Use Glob to list directories
- Create a tree structure (max 3 levels shown)
- Identify module purposes from names

**Step 2: Read key files**
- Package manifests: `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`
- Main entry points
- Core module files
- Configuration files (for understanding tech stack only)

**Step 3: Understand relationships**
- Import/dependency analysis
- API contracts
- Data flow patterns

### 5. Generate Analysis Report

Follow this exact template structure:

```markdown
# [Project Name] 代码分析

# 项目概要

[Concise summary of what the project does, based on code analysis, not README]

# 项目架构

## 代码结构

[Tree structure with module descriptions, max 3 levels]

## 模块架构

[Architecture design philosophy, component relationships]

[ASCII architecture diagram]

## 亮点分析

[3-5 project highlights with code examples]

## 缺陷分析

[Defects organized by priority P0/P1/P2 with improvement plans]
```

## Output Sections Detail

### 项目概要 (Project Overview)

- Extract purpose from code, not documentation
- Focus on core functionality and value proposition
- 2-3 sentences maximum
- Example: "A real-time collaborative document editing service built with WebSocket and CRDT conflict resolution. Enables multiple users to edit simultaneously with automatic sync."

### 代码结构 (Code Structure)

Present as a tree with descriptions:

```
project-root/
├── src/              # Source code root
│   ├── api/          # REST API endpoints
│   ├── services/     # Business logic layer
│   └── models/       # Data models
├── config/           # Configuration files
└── scripts/          # Build and deployment scripts
```

**Guidelines**:
- Show max 3 levels
- Add brief description for each major directory
- Hide non-essential directories

### 模块架构 (Module Architecture)

**Architecture description**:
- Design pattern(s) used (MVC, microservices, layered, etc.)
- Component relationships
- Data flow direction
- Key abstractions

**ASCII Architecture Diagram**:
```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTP/WS
       ▼
┌─────────────┐     ┌──────────────┐
│  API Layer  │────▶│  Services    │
└─────────────┘     └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   Database   │
                    └──────────────┘
```

**Diagram guidelines**:
- Use ASCII box-drawing characters
- Show data flow with arrows (▶, ▼)
- Keep it simple and readable
- Max width: 60 characters

### 亮点分析 (Highlights)

Identify 3-5 highlights:

**Good highlight criteria**:
- Innovative architecture or design pattern
- Performance optimization
- Robust error handling
- Clean code organization
- Useful abstractions
- Security best practices

**Format**:
```markdown
## 亮点分析

### 1. [Highlight Title]

[Brief explanation of why this is a highlight]

**代码示例**:
`​``python
# path/to/file.py:45
def innovative_function():
    # Code that demonstrates the highlight
    pass
`​``

[Optional: Impact or benefit]
```

**Must include**:
- File path and line number reference
- Code snippet (max 10 lines)
- Explanation of why it's valuable

### 缺陷分析 (Defects)

Organize by priority:

**Priority levels**:
- **P0**: Critical issues (security vulnerabilities, data loss risk, crashes)
- **P1**: Important issues (performance bottlenecks, maintainability problems)
- **P2**: Minor issues (code style, documentation gaps, optimization opportunities)

**Table format**:
```markdown
## 缺陷分析

| 优先级 | 问题 | 优化方案 |
|--------|------|----------|
| P0 | SQL injection in user input | Use parameterized queries in api/handlers.py |
| P1 | N+1 query in order list | Add eager loading in services/orders.py |
| P2 | Missing type hints | Add Python type annotations incrementally |
```

**Guidelines**:
- Be specific: include file paths and line numbers
- Propose actionable solutions
- Limit to top 10 issues (focus on most impactful)
- Balance P0/P1/P2 based on actual findings

## Processing Strategy

### For Small Projects (<50 files)

1. Read all source files
2. Build complete dependency graph
3. Analyze all modules thoroughly
4. Generate comprehensive report

### For Medium Projects (50-200 files)

1. Identify entry points and core modules
2. Read top-level architecture files
3. Sample representative files from each module
4. Build partial dependency graph
5. Focus analysis on critical paths

### For Large Projects (>200 files)

1. **Stop and ask user**: "This is a large project (>200 files). I'll analyze the core architecture at 3 levels depth. This will take ~5 minutes. Proceed?"
2. Map directory structure first (don't read files yet)
3. Identify entry points: `main.*`, `index.*`, `app.*`
4. Read only:
   - Entry points
   - First-level dependencies
   - Second-level dependencies
   - Key configuration files
5. Build shallow dependency graph (3 levels)
6. Generate focused report on architecture patterns

### Language-Specific Patterns

**Python**:
- Look for: `setup.py`, `requirements.txt`, `pyproject.toml`
- Entry points: `__main__.py`, `main.py`, `app.py`, `wsgi.py`
- Key dirs: `src/`, `app/`, `core/`

**JavaScript/TypeScript**:
- Look for: `package.json`, `tsconfig.json`
- Entry points: `index.js`, `index.ts`, `app.js`, `server.js`
- Key dirs: `src/`, `lib/`, `dist/` (for build output only)

**Go**:
- Look for: `go.mod`, `go.sum`
- Entry points: `main.go`, `cmd/` directory
- Key dirs: `pkg/`, `internal/`, `cmd/`

**Rust**:
- Look for: `Cargo.toml`, `Cargo.lock`
- Entry points: `src/main.rs`, `src/lib.rs`
- Key dirs: `src/`

**Java/Kotlin**:
- Look for: `pom.xml`, `build.gradle`
- Entry points: `src/main/java/**/Main.java`, `src/main/kotlin/**/Main.kt`
- Key dirs: `src/main/`, `src/test/`

## Report File Generation

**Filename format**: `analysis-<project_name>-YYYYMMDD.md`

**Example**: `analysis-my_repo-20260305.md` for March 5, 2026

**Location**: Save in the project root or current working directory

**Date**: Use current date from system context

## Examples

### Input Example 1: Local Path
```
分析 /Users/username/projects/myapp
```

### Input Example 2: GitHub URL
```
分析 https://github.com/username/repo-name
```

### Output Example
```
已生成分析报告：analysis-repo_name-20260305.md
```

## Error Handling

**Invalid path**: "错误：路径不存在或无法访问。请检查路径是否正确。"

**Empty project**: "错误：该项目不包含源代码文件。"

**GitHub clone failure**: "错误：无法克隆仓库。请检查URL是否正确，或网络连接。"

**Permission denied**: "错误：没有权限访问该项目。"

## Summary

1. Accept local path or GitHub URL
2. Ignore tests, docs, configs, CI/CD files
3. For large projects, analyze only 3 levels deep from entry points
4. Generate structured report following the template
5. Use ASCII diagrams for architecture visualization
6. Include code examples with file paths and line numbers
7. Organize defects by P0/P1/P2 priority
8. Save as `analysis-<project_name>-YYYYMMDD.md`