Analyze Open-Source Project#

Systematically analyze an open-source project's codebase to help the user quickly understand its architecture, core logic, data flows, key APIs, and algorithm implementations.

All analysis output MUST be in Chinese (zh-CN).

Execution Workflow#

Follow these steps strictly in order. Use parallel subagents (Task tool with subagent_type="explore") where noted.

Phase 1: Context Gathering#

Read these files first (use parallel reads):

1. README.md (or README.rst, README.txt) — project purpose, features, quick start
2. Primary config/dependency file — detect tech stack:
   • Node.js: package.json
   • Python: pyproject.toml > setup.py > requirements.txt
   • Go: go.mod
   • Java/Kotlin: pom.xml or build.gradle
   • Rust: Cargo.toml
   • C/C++: CMakeLists.txt or Makefile
   • .NET: *.csproj or *.sln
3. CI/Docker files if present ( Dockerfile, .github/workflows/) — reveals build & deploy info

Summarize: project name, purpose, tech stack, major dependencies, and build/run commands.

Phase 2: Directory Structure Scan#

Run a directory listing (depth 2) to map out the project layout.

Classify each top-level directory into one of:

• core: main business logic
• api: HTTP/gRPC/CLI interface layer
• model/entity: data models or domain objects
• config: configuration and environment
• util/common: shared utilities
• test: test suites
• docs: documentation
• scripts/tools: build or deployment scripts
• other: anything else

Phase 3: Entry Point Identification#

Search for program entry points based on the detected tech stack:

Tech StackTypical Entry PointsNode.jspackage.json "main"/"scripts.start", index.js, src/index.ts, app.jsPython__main__.py, main.py, app.py, manage.py, cli.pyGomain.go, cmd/*/main.goJavaclasses with public static void main, @SpringBootApplicationRustsrc/main.rs, src/lib.rsC/C++main.c, main.cppWeb Frontendsrc/index.tsx, src/main.ts, src/App.vue

Read the entry point file(s) and trace the initialization/bootstrap sequence.

Phase 4: Deep Analysis#

Perform all four dimensions of analysis. Use parallel explore subagents for independent dimensions.

4a. Architecture & Module Dependencies

• Identify the architectural pattern (MVC, Clean Architecture, Hexagonal, Microservices, Monolith, etc.)
• Map module dependencies — which modules import/call which
• Produce a Mermaid graph showing module relationships

4b. Core Business Flow & Data Flow

• Trace the primary user-facing workflow(s) end-to-end
• Identify how data enters, transforms, persists, and exits the system
• Produce a Mermaid flowchart or sequence diagram for the most important flow

4c. Key API Interfaces & Call Chains

• List public API endpoints or exported interfaces
• For the top 3-5 most important APIs, trace the call chain from handler to data layer
• Note middleware, interceptors, or decorators in the chain

4d. Algorithm & Function Implementation

• Identify non-trivial algorithms or complex business logic
• Extract the key code snippets (keep concise, max ~30 lines each)
• Annotate each snippet explaining the logic step by step

Output Format#

Use the template defined in template.md to structure the final report.

Key formatting rules:

• Use Markdown headings ( ##, ###) for clear hierarchy
• Include at least 2 Mermaid diagrams (architecture graph + primary flow)
• Code snippets use CODE REFERENCE format ( startLine:endLine:filepath) when citing existing code
• Keep the entire report readable in under 15 minutes

Guidelines#

• Depth over breadth: It is better to deeply explain 3 critical modules than to shallowly list 20.
• Follow the data: When in doubt about what to analyze next, follow the data flow.
• Cite code: Always reference specific files and line numbers — never make vague claims.
• Be opinionated: State clearly what the architectural strengths and weaknesses are.
• Progressive disclosure: Start with executive summary; put detailed analysis in later sections. The user should get 80% of the value from the first 20% of the report.