Codebase Analysis Skill

Overview

This skill provides techniques for extracting business requirements, domain knowledge, and technical specifications from existing codebases.

Analysis Objectives

When analyzing a codebase, seek to understand:

• Domain Model: Core entities and their relationships

• Business Rules: Validation, calculations, workflows

• Integrations: External systems and data flows

• User Capabilities: What users can do in the system

• Technical Constraints: Architecture patterns and limitations

Analysis Process

Phase 1: Structure Discovery

• Map project structure and organization

• Identify main components and layers

• Locate configuration and entry points

• Understand build and deployment setup

Phase 2: Domain Model Extraction

• Find entity/model definitions

• Map relationships between entities

• Identify domain vocabulary (ubiquitous language)

• Document data types and constraints

Phase 3: Business Logic Identification

• Locate service/business logic layers

• Extract validation rules

• Document calculations and formulas

• Map state machines and workflows

Phase 4: Integration Mapping

• Find API endpoints and contracts

• Identify external service calls

• Map data flows in/out of system

• Document authentication patterns

Phase 5: Capability Documentation

• List user-facing features

• Map permissions and access control

• Document user workflows

• Identify edge cases and error handling

Code Pattern Recognition

Entity/Model Identification

Look for these patterns:

// C# Entity public class Order { ... }

// Java Entity @Entity public class Order { ... }

// TypeScript Interface interface Order { ... }

// Database Schema CREATE TABLE orders ( ... )

Business Rule Indicators

Watch for these keywords and patterns:

• Validation: Validate , Check , Ensure , Must , Should

• Calculations: Calculate , Compute , Total , Sum

• Conditions: If , When , Unless , Only

• Constraints: Max , Min , Required , Limit

Service Layer Patterns

Identify business logic in:

// Service classes public class OrderService { ... }

// Use cases / Application services public class CreateOrderUseCase { ... }

// Command/Query handlers public class CreateOrderHandler { ... }

API Endpoint Patterns

Look for:

// REST Controllers [Route("api/orders")] [HttpPost] public async Task<Order> Create(...)

// Express routes app.post('/api/orders', ...)

// GraphQL resolvers Mutation: { createOrder: ... }

Analysis Heuristics

Finding Domain Models

• Search for class , interface , type definitions

• Look in folders named: Models , Entities , Domain

• Check database migrations and schema files

• Review ORM configurations

Finding Business Rules

• Search for validation attributes/decorators

• Look for throw statements (business exceptions)

• Find conditional logic in services

• Check for rule engines or policy patterns

Finding Integrations

• Search for HTTP client usage

• Look for message queue producers/consumers

• Find database connection configurations

• Check for external SDK imports

Finding User Capabilities

• Review API endpoints and their permissions

• Check UI components and forms

• Look at authorization/role definitions

• Review menu structures and navigation

Output Artifacts

Domain Model Documentation

Entity: Order

Attributes

Relationships

• Order has many OrderItems (1:N)
• Order belongs to Customer (N:1)

Business Rules

• Order total must equal sum of item totals
• Status can only transition: Draft -> Submitted -> Approved -> Completed

Business Rule Documentation

Rule: Order Validation

Description

Orders must meet these criteria before submission

Conditions

1. Order must have at least one item
2. All items must have valid product references
3. Customer must have valid payment method
4. Total must be greater than $0

Implementation

• File: src/Services/OrderService.cs
• Method: ValidateForSubmission()
• Line: 145-180

Integration Documentation

Integration: Payment Gateway

Type

REST API (Synchronous)

Endpoint

POST https://api.payments.com/v1/charges

Data Flow

• Input: Order total, Customer payment token
• Output: Transaction ID, Status

Error Handling

• Timeout: Retry 3 times with exponential backoff
• Failure: Mark order as payment pending, notify support

Implementation

• File: src/Integrations/PaymentGateway.cs

Code Search Patterns

Finding Entities (by language)

C# / .NET

grep -r "public class.Entity" --include=".cs" grep -r "[Table(" --include="*.cs"

Java

grep -r "@Entity" --include="*.java"

TypeScript

grep -r "interface.{" --include=".ts"

Finding Validation Rules

C# Attributes

grep -r "[Required]|[Range]|[StringLength]" --include="*.cs"

Java Annotations

grep -r "@NotNull|@Size|@Valid" --include="*.java"

Custom validation

grep -r "Validate|throw.Exception" --include=".cs"

Finding API Endpoints

.NET Controllers

grep -r "[Http.]|[Route(" --include=".cs"

Express.js

grep -r "app.(get|post|put|delete)(" --include="*.js"

Reverse Engineering Tips

Start With Entry Points

• Find main() or startup configuration

• Follow dependency injection setup

• Trace from API controllers to services to data

Follow the Data

• Start with database schema or entities

• Trace how data flows through system

• Map CRUD operations for each entity

Look for Tests

• Unit tests reveal expected behavior

• Integration tests show workflows

• Test data shows valid/invalid scenarios

Check Documentation

• Look for README files

• Check API documentation (Swagger/OpenAPI)

• Review code comments and XML docs

Questions to Answer

After analysis, you should be able to answer:

• What entities exist and how do they relate?

• What can users do in this system?

• What business rules govern behavior?

• What external systems does this integrate with?

• What are the key workflows?

• What constraints exist (technical and business)?

• What data does the system manage?

• Who has access to what?

See patterns.md for common architectural patterns to identify.