project-analyze

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Analysis Skill

项目分析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        → 最终报告                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  上下文优化架构                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  阶段1：需求分析      → analysis-config.json              │
│           ↓                                                      │
│  阶段2：初步探索       → 初步探索，确定范围                  │
│           ↓                                                      │
│  阶段3：并行Agent   → sections/section-*.md (直接输出MD)   │
│               ↓ 返回简要JSON                                     │
│  阶段3.5：内容整合   → consolidation-summary.md          │
│           Agent                 ↓ 返回质量评分+问题列表          │
│           ↓                                                      │
│  阶段4：报告组装          → 合并MD + 质量附录                  │
│           ↓                                                      │
│  阶段5：迭代优化        → 最终报告                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Design Principles

核心设计原则

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

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

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: 发现问题 → 提问 → 修复 → 重新检查                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  阶段1：需求发现                                │
│  → 读取: phases/01-requirements-discovery.md                    │
│  → 收集: 报告类型、深度级别、范围、重点领域        │
│  → 输出: analysis-config.json                                 │
├─────────────────────────────────────────────────────────────────┤
│  阶段2：项目探索                                   │
│  → 读取: phases/02-project-exploration.md                       │
│  → 启动: 并行探索Agent                          │
│  → 输出: 阶段3所需的探索上下文                      │
├─────────────────────────────────────────────────────────────────┤
│  阶段3：深度分析（并行Agent）                       │
│  → 读取: phases/03-deep-analysis.md                             │
│  → 参考: specs/quality-standards.md                        │
│  → 每个Agent: 分析代码 → 直接写入sections/section-*.md          │
│  → 返回: {"status", "output_file", "summary", "cross_notes"}  │
├─────────────────────────────────────────────────────────────────┤
│  阶段3.5：内容整合（新增！）                                │
│  → 读取: phases/03.5-consolidation.md                           │
│  → 输入: Agent返回的简要信息 + cross_module_notes             │
│  → 分析: 一致性/完整性/关联性/质量检查                        │
│  → 输出: consolidation-summary.md                             │
│  → 返回: {"quality_score", "issues", "stats"}                 │
├─────────────────────────────────────────────────────────────────┤
│  阶段4：报告生成                                     │
│  → 读取: phases/04-report-generation.md                         │
│  → 检查: 若存在错误，提示用户处理                              │
│  → 合并: 执行摘要 + sections/*.md + 质量附录          │
│  → 输出: {TYPE}-REPORT.md                                     │
├─────────────────────────────────────────────────────────────────┤
│  阶段5：迭代优化                                  │
│  → 读取: phases/05-iterative-refinement.md                      │
│  → 参考: specs/quality-standards.md                        │
│  → 循环: 发现问题 → 提问 → 修复 → 重新检查                       │
└─────────────────────────────────────────────────────────────────┘

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数量	重点
`architecture`	ARCHITECTURE-REPORT.md	5	系统结构、模块、依赖关系
`design`	DESIGN-REPORT.md	4	设计模式、类、接口
`methods`	METHODS-REPORT.md	4	算法、关键路径、API
`comprehensive`	COMPREHENSIVE-REPORT.md	全部	以上所有内容的整合

Agent Configuration by Report Type

按报告类型划分的Agent配置

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

Agent	输出文件	章节
overview	section-overview.md	系统概览
layers	section-layers.md	层级分析
dependencies	section-dependencies.md	模块依赖
dataflow	section-dataflow.md	数据流
entrypoints	section-entrypoints.md	入口点

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

Agent	输出文件	章节
patterns	section-patterns.md	设计模式
classes	section-classes.md	类关系
interfaces	section-interfaces.md	接口契约
state	section-state.md	状态管理

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

Agent	输出文件	章节
algorithms	section-algorithms.md	核心算法
paths	section-paths.md	关键代码路径
apis	section-apis.md	公共API参考
logic	section-logic.md	复杂逻辑

Directory Setup

目录设置

javascript

// 生成时间戳目录名
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"`);

javascript

// 生成时间戳目录名
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

.workflow/.scratchpad/analyze-{timestamp}/
├── analysis-config.json          # 阶段1输出
├── sections/                     # 阶段3（Agent直接写入）
│   ├── section-overview.md
│   ├── section-layers.md
│   ├── section-dependencies.md
│   └── ...
├── consolidation-summary.md      # 阶段3.5输出
├── {TYPE}-REPORT.md              # 最终输出
└── iterations/                   # 阶段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

文档	用途
phases/01-requirements-discovery.md	用户交互、配置收集
phases/02-project-exploration.md	初步探索
phases/03-deep-analysis.md	并行Agent分析
phases/03.5-consolidation.md	跨章节内容整合
phases/04-report-generation.md	报告组装
phases/05-iterative-refinement.md	质量优化
specs/quality-standards.md	质量门槛、标准
specs/writing-style.md	段落式学术写作规范
../_shared/mermaid-utils.md	共享Mermaid工具类