project-analyze

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