SuperBizAgent-java/.agents/skills/explore/references/analysis-methods.md

Project Analysis Methods

How to read and understand an unfamiliar code project.

1. Identify the Entry Point

Every project has a door. Find it first.

By Language

Language	Look for
JavaScript/TypeScript	package.json → main / bin / scripts.dev
Python	setup.py → entry_points, pyproject.toml → [project.scripts], or top-level app.py / main.py / __main__.py
Go	package main in any file, conventionally main.go or cmd/*/main.go
Rust	src/main.rs or src/bin/*.rs
Java	Class with public static void main(String[] args)
C/C++	main() function, conventionally in src/main.c
Swift	main.swift or file with @main attribute

In Frameworks

Framework	Entry point
Next.js	app/ or pages/ directory, next.config.js
React (Vite)	src/main.tsx or src/main.jsx
Vue (Vite)	src/main.ts or src/main.js
Express	File that calls app.listen()
FastAPI	File that creates FastAPI() instance
Django	manage.py, then project name directory with urls.py / wsgi.py
Flask	app.py or app/__init__.py
Spring Boot	*Application.java with @SpringBootApplication

2. Judge Project Complexity

Don't over-engineer simple projects. Don't under-analyze complex ones.

Simple (<50 files, single language)

• Read every source file.
• No need for flow diagrams beyond a simple sequence.
• A light /explore pass is probably enough.

Standard (50-500 files, 1-2 languages)

• Read entry point + core modules + 1-2 feature files.
• Build 1-2 flow diagrams.
• /explore is the right level.

Complex (>500 files, multi-language, monorepo)

• Read entry point + architecture docs + one representative module.
• Use /essence to find standout designs, or /explore for one package at a time.
• Do NOT try to understand the whole project in one pass.

3. Separate Core Code from Scaffolding

Not all files are worth reading.

Ignore (scaffolding)

• *.config.js, *.config.ts — configuration, not logic
• dist/, build/, out/ — generated output
• node_modules/, vendor/, .venv/ — dependencies
• *.lock, yarn.lock, go.sum — lock files
• LICENSE, CODEOWNERS, .editorconfig — project meta
• test/fixtures/, test/data/ — test data

Read (core)

• Entry point file
• Router/middleware/config handlers
• Model/entity/schema definitions
• Core algorithm or business logic files
• Files referenced most in imports

Hint: Follow imports

entry file → import A → import B → core logic

Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.

4. Read Unfamiliar Framework Code

You don't know every framework. That's fine.

Strategy

1. Find the routing layer first. Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.

2. Follow ONE request end-to-end. Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.

3. Identify the framework's conventions. Most frameworks follow a pattern:

   • MVC: Controller → Model → View
   • Middleware: Request → Middleware chain → Handler → Response
   • Component: Parent renders children, props flow down, events flow up
   • Plugin: Core calls hooks, plugins register handlers

4. Don't fight the framework's abstraction. If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for new() calls. Understand what abstraction layer they chose.

5. Use the framework's own docs. If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.