codebase-mapper

description	Use when analyzing an existing codebase to generate ARCHITECTURE.md and STACK.md, or when mapping project structure, dependencies, patterns, integrations, and technical debt before planning.
name	codebase-mapper
trigger	코드베이스 분석, 프로젝트 구조 파악, 아키텍처 문서화, 기술 부채 조사, analyze codebase, map structure, onboarding, 의존성 분석, 패턴 식별, 통합 매핑, 기술 스택 파악, 코드 구조 스캔, 레거시 이해, 리팩토링 준비, 아키텍처 도출, 기술 부채 감사, dependency map, tech stack analysis, code structure scan, legacy code review, refactoring prep, architecture mapping, tech debt audit, generate architecture doc, generate stack doc

Quick Reference

• 프로젝트 타입 식별: package.json, pyproject.toml 등 마커 파일로 생태계 먼저 확인
• 5 핵심 분석: Structure, Dependency, Pattern, Integration, Technical Debt 필수 수행
• 의사결정 기준: Entry point, Key Patterns, Integrations, Debt 항목 반드시 식별
• 필수 출력물: .hxsk/ARCHITECTURE.md 및 .hxsk/STACK.md 생성 완료 여부 확인
• 체크리스트: 9 단계 분석 항목 (타입~출력) 모두 완료되었는지 최종 점검

Analysis Domains

1. Structure Analysis

Understand how the project is organized:

• Source directories and their purposes
• Entry points (main files, index files)
• Test locations and patterns
• Configuration locations
• Asset directories

2. Dependency Analysis

Map what the project depends on:

• Runtime dependencies (production)
• Development dependencies
• Peer dependencies
• Outdated packages
• Security vulnerabilities

3. Pattern Analysis

Identify how code is written:

• Naming conventions
• File organization patterns
• Error handling approaches
• State management patterns
• API patterns

4. Integration Analysis

Map external connections:

• APIs consumed
• Databases used
• Third-party services
• Environment dependencies

5. Technical Debt Analysis

Surface issues to address:

• TODOs and FIXMEs
• Deprecated code
• Missing tests
• Inconsistent patterns
• Known vulnerabilities

---

Scanning Process

Phase 1: Project Type Detection

Identify project type from markers:

# Node.js/JavaScript
test -f "package.json"

# Python
test -f "requirements.txt" || test -f "pyproject.toml"

# Rust
test -f "Cargo.toml"

# Go
test -f "go.mod"

# .NET
ls *.csproj 2>/dev/null

Phase 2: Structure Scan

# Get directory structure (excluding common non-source dirs)
find . -type d \
    -not -path "*/node_modules/*" \
    -not -path "*/.git/*" \
    -not -path "*/__pycache__/*" \
    -not -path "*/dist/*" \
    -not -path "*/build/*" \
    -not -path "*/.next/*"

Phase 3: Dependency Extraction

For each ecosystem:

Node.js:

cat package.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('dependencies',{})); print(d.get('devDependencies',{}))"

Python:

# pyproject.toml (uv/poetry)
cat pyproject.toml
# requirements.txt (pip)
cat requirements.txt

Phase 4: Pattern Discovery

Search for common patterns:

# Components
find . -type f \( -name "*.tsx" -o -name "*.jsx" \) -not -path "*/node_modules/*"

# API routes
find . -path "*/api/*" -type f \( -name "*.ts" -o -name "*.js" \)

# Models/schemas
grep -rn "interface\|type\|schema" --include="*.ts"

Phase 5: Debt Discovery

# TODOs
grep -rn "TODO\|FIXME\|HACK\|XXX" src/

# Deprecated
grep -rn "@deprecated\|DEPRECATED" .

# Console statements (often debug leftovers)
grep -rn "console\.\(log\|debug\|warn\)" src/

---

Output Format

ARCHITECTURE.md

# Architecture

> Generated by /map on {date}

## Overview
{High-level system description}

## System Diagram

{ASCII or description of component relationships}

## Components

### {Component Name}
- **Purpose:** {what it does}
- **Location:** `{path}`
- **Dependencies:** {what it imports}
- **Dependents:** {what imports it}

## Data Flow
{How data moves through the system}

## Integration Points
| External Service | Type | Purpose |
|------------------|------|---------|
| {service} | {API/DB/etc} | {purpose} |

## Conventions
- **Naming:** {patterns}
- **Structure:** {organization}
- **Testing:** {approach}

## Technical Debt
- [ ] {Debt item with location}

STACK.md

# Technology Stack

> Generated by /map on {date}

## Runtime
| Technology | Version | Purpose |
|------------|---------|---------|
| {tech} | {version} | {purpose} |

## Production Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {pkg} | {version} | {purpose} |

## Development Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {pkg} | {version} | {purpose} |

## Infrastructure
| Service | Provider | Purpose |
|---------|----------|---------|
| {svc} | {provider} | {purpose} |

## Configuration
| Variable | Purpose | Required |
|----------|---------|----------|
| {var} | {purpose} | {yes/no} |

---

Checklist

Before Completing Map:

• Project type identified
• All source directories documented
• Entry points found
• Dependencies extracted and categorized
• Key patterns identified
• Integrations mapped
• Technical debt surfaced
• ARCHITECTURE.md created
• STACK.md created

네이티브 도구 활용

코드베이스 분석은 네이티브 도구로 수행:

# 디렉토리 구조 탐색
Glob(pattern: "src/**/*.{ts,js,py,go}")

# Import 의존성 분석
Grep(pattern: "^import|^from.*import|require\\(", path: "src/", output_mode: "content")

# 엔트리 포인트 탐색
Glob(pattern: "**/main.{ts,js,py,go}")
Glob(pattern: "**/index.{ts,js}")

# 설정 파일 확인
Glob(pattern: "*.{json,yaml,toml}")

# 구조 스캔 (bash 스크립트 사용 가능)
bash .hxsk/skills/codebase-mapper/scripts/scan_structure.sh

Iron Laws

NO STRUCTURE SCAN WITHOUT PROJECT TYPE DETECTION FIRST NO DEPENDENCY EXTRACTION WITHOUT STRUCTURE ANALYSIS FIRST NO PATTERN DISCOVERY WITHOUT DEPENDENCY MAPPING FIRST NO DEBT SURFACING WITHOUT PATTERN IDENTIFICATION FIRST NO SCANNING WITHOUT EXCLUSION FILTERS (node_modules, .git, etc.) FIRST NO DOCUMENT GENERATION (ARCHITECTURE.md, STACK.md) WITHOUT CHECKLIST COMPLETION FIRST NO DEBT ANALYSIS WITHOUT DEFINED GREP PATTERNS FIRST NO IMPORT ANALYSIS WITHOUT NATIVE TOOL USAGE (Glob/Grep) FIRST