project-analyze

catlog22's avatarfrom catlog22

Multi-phase iterative project analysis with Mermaid diagrams. Generates architecture reports, design reports, method analysis reports. Use when analyzing codebases, understanding project structure, reviewing architecture, exploring design patterns, or documenting system components. Triggers on "analyze project", "architecture report", "design analysis", "code structure", "system overview".

⭐837stars🔀72forks📁View on GitHub🕐Updated Jan 4, 2026
[Architecture Design]

When & Why to Use This Skill

The Project Analysis skill is a sophisticated automated documentation engine that performs multi-phase iterative evaluations of software codebases. By leveraging parallel agents and Mermaid diagramming, it generates professional-grade architecture, design, and method analysis reports. It is specifically engineered to reduce the cognitive load of understanding complex systems, providing structured insights into module dependencies, design patterns, and critical code paths with a focus on academic-level clarity and technical rigor.

Use Cases

  • 1. Legacy Codebase Onboarding: Rapidly map out the structure and dependencies of unfamiliar projects to accelerate developer ramp-up time.
  • 2. Architectural Auditing: Generate detailed system overviews and data flow diagrams to identify structural bottlenecks or violations of design principles.
  • 3. Automated Technical Documentation: Maintain high-quality, up-to-date documentation including class relationships, interface contracts, and API references without manual drafting.
  • 4. Pre-Refactoring Analysis: Use deep method and logic analysis to identify critical paths and complex dependencies before implementing major code changes.
  • 5. Quality Assurance & Compliance: Utilize the built-in consolidation agent to score documentation quality and ensure consistency across different system modules.
nameproject-analyze
descriptionMulti-phase iterative project analysis with Mermaid diagrams. Generates architecture reports, design reports, method analysis reports. Use when analyzing codebases, understanding project structure, reviewing architecture, exploring design patterns, or documenting system components. Triggers on "analyze project", "architecture report", "design analysis", "code structure", "system overview".
allowed-toolsTask, AskUserQuestion, Read, Bash, Glob, Grep, Write

Project Analysis Skill

Generate comprehensive project analysis reports through multi-phase iterative workflow.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  Context-Optimized Architecture                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: Requirements      → analysis-config.json              │
│           ↓                                                      │
│  Phase 2: Exploration       → 初步探索，确定范围                  │
│           ↓                                                      │
│  Phase 3: Parallel Agents   → sections/section-*.md (直接写MD)   │
│               ↓ 返回简要JSON                                     │
│  Phase 3.5: Consolidation   → consolidation-summary.md          │
│           Agent                 ↓ 返回质量评分+问题列表          │
│           ↓                                                      │
│  Phase 4: Assembly          → 合并MD + 质量附录                  │
│           ↓                                                      │
│  Phase 5: Refinement        → 最终报告                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Design Principles

  1. Agent 直接输出 MD: 避免 JSON → MD 转换的上下文开销
  2. 简要返回: Agent 只返回路径+摘要，不返回完整内容
  3. 汇总 Agent: 独立 Agent 负责跨章节问题检测和质量评分
  4. 引用合并: Phase 4 读取文件合并，不在上下文中传递
  5. 段落式描述: 禁止清单罗列，层层递进，客观学术表达

Execution Flow

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Requirements Discovery                                │
│  → Read: phases/01-requirements-discovery.md                    │
│  → Collect: report type, depth level, scope, focus areas        │
│  → Output: analysis-config.json                                 │
├─────────────────────────────────────────────────────────────────┤
│  Phase 2: Project Exploration                                   │
│  → Read: phases/02-project-exploration.md                       │
│  → Launch: parallel exploration agents                          │
│  → Output: exploration context for Phase 3                      │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3: Deep Analysis (Parallel Agents)                       │
│  → Read: phases/03-deep-analysis.md                             │
│  → Reference: specs/quality-standards.md                        │
│  → Each Agent: 分析代码 → 直接写 sections/section-*.md          │
│  → Return: {"status", "output_file", "summary", "cross_notes"}  │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3.5: Consolidation (New!)                                │
│  → Read: phases/03.5-consolidation.md                           │
│  → Input: Agent 返回的简要信息 + cross_module_notes             │
│  → Analyze: 一致性/完整性/关联性/质量检查                        │
│  → Output: consolidation-summary.md                             │
│  → Return: {"quality_score", "issues", "stats"}                 │
├─────────────────────────────────────────────────────────────────┤
│  Phase 4: Report Generation                                     │
│  → Read: phases/04-report-generation.md                         │
│  → Check: 如有 errors，提示用户处理                              │
│  → Merge: Executive Summary + sections/*.md + 质量附录          │
│  → Output: {TYPE}-REPORT.md                                     │
├─────────────────────────────────────────────────────────────────┤
│  Phase 5: Iterative Refinement                                  │
│  → Read: phases/05-iterative-refinement.md                      │
│  → Reference: specs/quality-standards.md                        │
│  → Loop: 发现问题 → 提问 → 修复 → 重新检查                       │
└─────────────────────────────────────────────────────────────────┘

Report Types

Type Output Agents Focus
architecture ARCHITECTURE-REPORT.md 5 System structure, modules, dependencies
design DESIGN-REPORT.md 4 Patterns, classes, interfaces
methods METHODS-REPORT.md 4 Algorithms, critical paths, APIs
comprehensive COMPREHENSIVE-REPORT.md All All above combined

Agent Configuration by Report Type

Architecture Report

Agent Output File Section
overview section-overview.md System Overview
layers section-layers.md Layer Analysis
dependencies section-dependencies.md Module Dependencies
dataflow section-dataflow.md Data Flow
entrypoints section-entrypoints.md Entry Points

Design Report

Agent Output File Section
patterns section-patterns.md Design Patterns
classes section-classes.md Class Relationships
interfaces section-interfaces.md Interface Contracts
state section-state.md State Management

Methods Report

Agent Output File Section
algorithms section-algorithms.md Core Algorithms
paths section-paths.md Critical Code Paths
apis section-apis.md Public API Reference
logic section-logic.md Complex Logic

Directory Setup

// 生成时间戳目录名
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const dir = `.workflow/.scratchpad/analyze-${timestamp}`;

// Windows (cmd)
Bash(`mkdir "${dir}\\sections"`);
Bash(`mkdir "${dir}\\iterations"`);

// Unix/macOS
// Bash(`mkdir -p "${dir}/sections" "${dir}/iterations"`);

Output Structure

.workflow/.scratchpad/analyze-{timestamp}/
├── analysis-config.json          # Phase 1
├── sections/                     # Phase 3 (Agent 直接写入)
│   ├── section-overview.md
│   ├── section-layers.md
│   ├── section-dependencies.md
│   └── ...
├── consolidation-summary.md      # Phase 3.5
├── {TYPE}-REPORT.md              # Final Output
└── iterations/                   # Phase 5
    ├── v1.md
    └── v2.md

Reference Documents

Document Purpose
phases/01-requirements-discovery.md User interaction, config collection
phases/02-project-exploration.md Initial exploration
phases/03-deep-analysis.md Parallel agent analysis
phases/03.5-consolidation.md Cross-section consolidation
phases/04-report-generation.md Report assembly
phases/05-iterative-refinement.md Quality refinement
specs/quality-standards.md Quality gates, standards
specs/writing-style.md 段落式学术写作规范
../_shared/mermaid-utils.md Shared Mermaid utilities