AgentSkillsCN

analyzing-projects

掌握项目结构、架构与代码库的理解之道。

SKILL.md
--- frontmatter
name: analyzing-projects
description: Knowledge and patterns for understanding project structures, architectures, and codebases.

Analyzing Projects Skill

This skill provides patterns and techniques for understanding unfamiliar codebases and project structures.

Quick Reconnaissance

1. Project Type Detection

Check for key files to identify the project type:

FileIndicates
package.jsonNode.js project
pyproject.tomlModern Python project
requirements.txtPython project
go.modGo project
Cargo.tomlRust project
pom.xmlJava Maven project
build.gradleJava Gradle project
GemfileRuby project

2. Framework Detection

File/PatternFramework
next.config.jsNext.js
vite.config.tsVite
angular.jsonAngular
src/App.vueVue.js
manage.pyDjango
app.py / Flask importsFlask
main.goGo
src/main.rsRust

3. Architecture Patterns

Look for these directory structures:

code
# Monolith
src/
  models/
  views/
  controllers/

# Microservices
services/
  user-service/
  order-service/
  payment-service/

# Domain-Driven Design
src/
  domain/
  application/
  infrastructure/

# Feature-based
src/
  features/
    auth/
    dashboard/
    settings/

Key Files to Read First

  1. •/strategy/VISION.md - Strategic context (if exists)
  2. •/strategy/OKRs.md - Current priorities (if exists)
  3. •/strategy/adrs/ - Architecture decisions (if exists)
  4. •README.md - Project overview and setup
  5. •package.json / pyproject.toml - Dependencies and scripts
  6. •docker-compose.yml - Services and infrastructure
  7. •.env.example - Required configuration
  8. •Makefile / justfile - Available commands

Strategy Folder (if present)

If a /strategy/ folder exists, prioritize reading:

FilePurpose
VISION.mdNorth star, strategic bets, non-goals
OKRs.mdCurrent quarter objectives
epics/*.mdActive feature initiatives
tasks/*.mdSpecific work items
adrs/*.mdSettled architectural decisions

Mapping Dependencies

External Dependencies

bash
# Python
cat pyproject.toml | grep -A 100 "\[dependencies\]"

# Node
cat package.json | jq '.dependencies, .devDependencies'

Internal Dependencies

bash
# Find imports
grep -rh "^import\|^from" src/ | sort | uniq -c | sort -rn

# Find module usage
grep -rn "from src\." . --include="*.py"

Understanding Data Flow

  1. •Entry points - Where requests come in
  2. •Routes/Controllers - Request handling
  3. •Services - Business logic
  4. •Models - Data structures
  5. •Repositories - Data access
  6. •External APIs - Outbound calls

Common Patterns to Identify

Authentication

  • •JWT tokens
  • •Session-based
  • •OAuth providers

Database

  • •ORM (SQLAlchemy, Prisma, TypeORM)
  • •Raw SQL
  • •NoSQL (MongoDB, Redis)

API Style

  • •REST
  • •GraphQL
  • •gRPC
  • •WebSocket

Testing Strategy

  • •Unit tests
  • •Integration tests
  • •E2E tests

Analysis Checklist

  • • Does a /strategy/ folder exist? If so, read VISION.md and OKRs.md first.
  • • Are there ADRs in /strategy/adrs/? These contain settled decisions.
  • • What type of project is this?
  • • What framework(s) are used?
  • • What is the directory structure pattern?
  • • What are the main entry points?
  • • What are the key dependencies?
  • • How is configuration managed?
  • • What testing approach is used?
  • • How is the project built and deployed?