diegosouzapw Project Analysis Skill
Purpose
Quickly understand codebases by systematically analyzing structure, dependencies, patterns, and conventions.
Analysis Framework
Phase 1: High-Level Overview (5 minutes)
# 1. Check project type and structure
ls -la
cat README.md
cat package.json | head -50 # or pyproject.toml, Cargo.toml, etc.
# 2. Understand directory structure
tree -L 2 -I 'node_modules|.git|dist|build'
# 3. Check git history for activity
git log --oneline -20
git shortlog -sn --since="6 months ago"
Phase 2: Dependency Analysis (5 minutes)
# Node.js
cat package.json | jq '.dependencies, .devDependencies'
# Python
cat requirements.txt
cat pyproject.toml
# Go
cat go.mod
# Rust
cat Cargo.toml
Key Questions:
- What frameworks are used?
- What database/cache?
- Any outdated/vulnerable deps?
Phase 3: Architecture Mapping (10 minutes)
## Architecture Map
### Entry Points
- `src/index.ts` - Main application entry
- `src/api/` - REST API endpoints
- `src/workers/` - Background job processors
### Core Modules
- `src/services/` - Business logic
- `src/models/` - Data models/entities
- `src/repositories/` - Data access layer
### Infrastructure
- `src/config/` - Configuration management
- `src/middleware/` - Express middleware
- `src/utils/` - Shared utilities
### Data Flow
Client → API Routes → Controllers → Services → Repositories → Database
Phase 4: Pattern Recognition
Common Patterns to Identify
| Pattern | Files to Check | Indicators |
|---|---|---|
| MVC | controllers/, models/, views/ | Separate concerns |
| Clean Architecture | domain/, application/, infrastructure/ | Dependency inversion |
| Repository | repositories/, *Repository.ts | Data access abstraction |
| Factory | factories/, *Factory.ts | Object creation |
| Singleton | getInstance() | Global state |
| Observer | EventEmitter, on(), emit() | Event-driven |
Phase 5: Code Quality Assessment
# Check for linting/formatting
ls .eslintrc* .prettierrc* .editorconfig
# Check for tests
ls -la tests/ __tests__/ *.test.* *.spec.*
npm test -- --coverage 2>/dev/null
# Check for CI/CD
ls .github/workflows/ .gitlab-ci.yml Jenkinsfile
# Check for documentation
ls docs/ *.md CONTRIBUTING* CHANGELOG*
Analysis Output Template
# Project Analysis: [Project Name]
## Summary
- **Type:** [Web API / CLI / Library / Monorepo]
- **Language:** [TypeScript / Python / Go / Rust]
- **Framework:** [Express / FastAPI / Gin / Actix]
- **Database:** [PostgreSQL / MongoDB / Redis]
- **Last Activity:** [Date]
- **Contributors:** [Number]
## Directory Structure
project/ ├── src/ # Source code │ ├── api/ # HTTP endpoints │ ├── services/ # Business logic │ └── models/ # Data models ├── tests/ # Test files ├── docs/ # Documentation └── scripts/ # Build/deploy scripts
## Key Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| express | 4.18.2 | HTTP server |
| prisma | 5.7.0 | ORM |
| zod | 3.22.0 | Validation |
## Architecture Style
[Description of architectural approach]
## Data Flow
[Diagram or description of how data flows through the system]
## Code Quality Indicators
- [ ] Tests: X% coverage
- [ ] Linting: [ESLint configured]
- [ ] Types: [Strict TypeScript]
- [ ] CI/CD: [GitHub Actions]
- [ ] Docs: [README, API docs]
## Notable Patterns
1. [Pattern 1 with location]
2. [Pattern 2 with location]
## Potential Issues
1. [Issue 1]
2. [Issue 2]
## Recommendations
1. [Recommendation 1]
2. [Recommendation 2]
Framework-Specific Analysis
Node.js / TypeScript
# Check TypeScript config
cat tsconfig.json
# Check for monorepo
ls packages/ apps/ pnpm-workspace.yaml lerna.json
# Check build output
cat package.json | jq '.scripts'
Python
# Check Python version
cat .python-version
cat pyproject.toml | grep python
# Check dependency management
ls requirements.txt pyproject.toml poetry.lock Pipfile
# Check for type hints
grep -r "def.*:.*->" src/ | head -5
Go
# Check Go version
cat go.mod | head -3
# Check project layout
ls cmd/ internal/ pkg/ api/
# Check for common patterns
grep -r "interface {" --include="*.go" | head -5
Rust
# Check edition and dependencies
cat Cargo.toml
# Check module structure
ls src/*.rs
# Check for async runtime
grep -E "tokio|async-std" Cargo.toml
Quick Health Check
## Project Health Score
### Documentation (X/5)
- [ ] README with setup instructions
- [ ] API documentation
- [ ] Architecture docs
- [ ] Contributing guide
- [ ] Changelog
### Testing (X/5)
- [ ] Test files exist
- [ ] Coverage > 60%
- [ ] Integration tests
- [ ] CI runs tests
- [ ] Tests are maintained
### Code Quality (X/5)
- [ ] Linter configured
- [ ] Formatter configured
- [ ] Type safety (TypeScript/types)
- [ ] No obvious code smells
- [ ] Dependencies up to date
### DevOps (X/5)
- [ ] CI/CD pipeline
- [ ] Environment configuration
- [ ] Deployment docs
- [ ] Monitoring setup
- [ ] Security scanning
### Overall: X/20
Onboarding Questions
When analyzing a project for onboarding, answer:
How do I run it locally?
- Setup commands
- Environment variables needed
- Database/service dependencies
How is it structured?
- Where does the code live?
- What are the main components?
- How do they interact?
How do I make changes?
- Branch strategy
- PR process
- Testing requirements
How is it deployed?
- CI/CD pipeline
- Environments (dev/staging/prod)
- Release process
Where do I get help?
- Documentation location
- Team contacts
- Common troubleshooting
Red Flags to Watch For
| Red Flag | Impact | Recommendation |
|---|---|---|
| No tests | High risk changes | Add tests before modifying |
| No types | Runtime errors | Enable strict TypeScript |
| Outdated deps | Security risk | Run npm audit |
| No CI/CD | Manual deploys | Set up GitHub Actions |
| No .gitignore | Secrets in repo | Add immediately |
| Giant files | Hard to maintain | Plan refactoring |
| Deep nesting | Complex logic | Simplify, extract |
| Copy-paste code | Maintenance burden | DRY refactoring |