change-overview

Change Overview

현재 브랜치의 변경사항을 분석하여 클래스 관계도, Before/After 비교, 시그널/이벤트 플로우, 핵심 API 변경을 터미널에 시각적으로 출력한다.

이 스킬은 READ-ONLY이며 파일을 수정하지 않는다.

출력 언어

프로젝트의 주요 언어(커밋 메시지, 주석, README 등)를 감지하여 출력 언어를 결정한다. 코드 식별자(클래스명, 메서드명)는 항상 원문 그대로 사용한다.

실행 단계

Step 1: Diff 범위 결정

CURRENT=$(git branch --show-current)

# detached HEAD 처리
if [ -z "$CURRENT" ]; then
  echo "Detached HEAD — comparing against HEAD~10 (최근 10커밋)"
  BASE=$(git rev-parse HEAD~10 2>/dev/null || git rev-list --max-parents=0 HEAD)
else
  # 가장 가까운 remote 브랜치 찾기 (최대 50개만 비교하여 성능 확보)
  BEST_REF=""
  BEST_COUNT=999999
  while read ref; do
    [[ "$ref" == "origin/HEAD" ]] && continue
    [[ "$ref" == "origin/$CURRENT" ]] && continue
    COUNT=$(git rev-list --count "$ref..HEAD" 2>/dev/null) || continue
    if (( COUNT < BEST_COUNT )); then
      BEST_COUNT=$COUNT
      BEST_REF=$ref
    fi
  done < <(git for-each-ref --sort=-committerdate --count=50 --format='%(refname:short)' refs/remotes/origin/)

  if [ -z "$BEST_REF" ]; then
    BEST_REF="origin/main"
  fi

  BASE=$(git merge-base HEAD "$BEST_REF")
  echo "Branch: $CURRENT vs $BEST_REF (base: ${BASE:0:8})"
fi

Step 2: 변경 파일 수집

git diff $BASE...HEAD --stat
git diff $BASE...HEAD --shortstat
git diff $BASE...HEAD --diff-filter=A --name-only  # 신규
git diff $BASE...HEAD --diff-filter=D --name-only  # 삭제
git diff $BASE...HEAD --diff-filter=M --name-only  # 수정

Step 3: 클래스 구조 분석

**Agent(subagent_type="Explore")**를 사용하여 변경된 헤더 파일(.h, .hpp, .ts, .py 등)을 분석한다.

각 헤더/인터페이스 파일에서 추출:

• 클래스명, 베이스 클래스 (상속 관계)
• 인터페이스 구현 관계 (C++: virtual/override, Java/TS: implements, Python: ABC)
• 의존성 주입 (생성자 주입, 데코레이터 패턴, @Inject/@Autowired 등)
• 핵심 public 메서드 시그니처
• 멤버 변수 중 다른 프로젝트 클래스 타입 (조합/소유 관계)
• import/include 중 프로젝트 내부 모듈 (의존 관계)

소스 파일에서 추출:

• 변경된 메서드 시그니처
• signal/slot, event emitter, 옵저버 연결
• DI resolve 패턴

Step 4: 관계도 출력

Unicode box-drawing 문자로 터미널에 클래스 관계도를 그린다.

박스 스타일:

• [NEW]: 신규 클래스
• [MOD]: 수정된 클래스
• [DEL]: 삭제된 클래스
• 태그 없음: 변경되지 않았으나 관계가 있는 클래스

화살표 스타일:

• ──▷ 상속 (inheritance)
• ──● 조합/소유 (composition/owns)
• ──▶ 의존 (dependency/uses)
• ──→ 시그널/이벤트 (signal/event flow)

출력 예시:

┌────────────────────────────────────────────────────┐
│  UserService [NEW]                                 │
│  : IUserService                                    │
├────────────────────────────────────────────────────┤
│  + CreateUser(CreateUserDto)                       │
│  + FindById(string) : User                         │
│  + UpdateProfile(string, UpdateDto)                │
└────────────────────────────┬───────────────────────┘
                             │ ──▶ uses
                             ▼
┌────────────────────────────────────────────────────┐
│  UserRepository [NEW]                              │
│  : IUserRepository                                 │
├────────────────────────────────────────────────────┤
│  + Save(User) : User                               │
│  + FindById(string) : User?                        │
│  + Delete(string) : bool                           │
└────────────────────────────────────────────────────┘

관계도 가독성 규칙:

• 박스 너비는 최소 50자 (내부 텍스트에 맞게 확장). 작은 박스는 읽기 어려움.
• 메서드 시그니처에 파라미터 타입을 포함 (변수명은 생략 가능하나 타입은 표시).
• 화살표와 관계 설명은 박스 사이에 충분한 여백을 두어 시각적 구분.
• 클래스가 3개 이상이면 수직 나열을 기본으로 하고, 독립적인 클래스는 수평 배치.

20개 이상 파일 변경 시: 모듈(디렉토리) 단위로 먼저 요약하고, 핵심 모듈만 클래스 단위로 상세 표시.

클래스가 없는 변경 (config, script, YAML 등): 박스 대신 파일 단위 요약 리스트로 표시:

설정/스크립트 변경
───────────────────────────────────────────
  webpack.config.js [MOD] — output path를 dist/에서 build/로 변경
  .github/workflows/ci.yml [NEW] — GitHub Actions CI 파이프라인 추가
  package.json [MOD] — eslint 9.x 업그레이드

Step 5: Before/After 비교

아키텍처가 크게 변경된 경우 테이블 형태로 비교:

Before/After 비교
═══════════════════════════════════════════════════════════════

  BEFORE: MonolithService (1461줄)
  ├── 데이터 처리
  ├── 비즈니스 로직
  └── UI 렌더링

  AFTER:
  ├── DataProcessor (550줄) [NEW] ← 데이터 처리만 추출
  └── BusinessLogic (987줄) [NEW] ← 비즈니스 로직 분리

  변경 이유: SRP — 데이터 처리와 비즈니스 로직 분리
═══════════════════════════════════════════════════════════════

또는 여러 클래스가 변경된 경우 요약 테이블 사용:

| 클래스                  | 변경   | 줄 수 | 요약                          |
|------------------------|--------|-------|-------------------------------|
| MonolithService        | DEL    | -1461 | DataProcessor + BusinessLogic로 분리 |
| DataProcessor          | NEW    | +550  | 순수 데이터 처리 로직           |
| BusinessLogic          | NEW    | +987  | 비즈니스 로직 + 이벤트 연동     |
| MainScreen             | MOD    | +12   | 새 서비스 통합                  |

Before/After 판단 기준:

• 클래스가 분리(split)되었거나 합쳐(merge)졌을 때
• 상속 구조가 변경되었을 때
• 모듈간 의존성 방향이 바뀌었을 때

변경이 minor한 경우(버그 수정, 리팩토링 수준)에는 이 섹션을 생략한다.

Step 6: 시그널/이벤트 플로우

변경된 클래스가 signal, event emitter, 콜백, 옵저버를 사용하는 경우:

Signal Flow:
  DataProcessor::dataReady
    ──→ EventBus::OnDataProcessed
      ──→ BusinessLogic::HandleData (결과 처리)
      ──→ MainScreen::RefreshView (UI 갱신)

signal/event가 없으면 이 섹션을 생략한다.

Step 7: 구현 상세 설명

각 신규/수정 클래스에 대해 무엇을, 왜, 어떻게 구현했는지 2~4문장으로 설명한다.

리스트 형식으로 작성 (카드/박스 형태 사용 금지):

구현 상세
───────────────────────────────────────────────────────

DataProcessor [NEW] (550줄)
  MonolithService에서 데이터 처리 로직을 추출한 순수 프로세서.
  도메인 타입에 의존하지 않아 향후 다른 모듈에서도 재사용 가능.
  Process(input)로 데이터를 받고, 14개 설정 옵션을 setter로 제어.

BusinessLogic [NEW] (987줄)
  DataProcessor 위에 도메인 로직을 관리하는 서비스.
  HandleData에서 검증/변환 후 eventBus를 통해 결과 전파.

가독성 규칙:

• 장식용 박스 프레임(┌─ ... ─┐ └─ ... ─┘) 사용 금지. 단순 구분선(───) + 들여쓰기만 사용.
• 클래스명은 굵게(bold 불가 시 대문자/브래킷으로 강조), 설명은 2칸 들여쓰기.
• 클래스 간 빈 줄 1개로 구분.

작성 기준:

• 신규 클래스: 존재 이유(왜 분리/생성), 핵심 동작 방식, 주요 API 흐름
• 수정 클래스: 변경 전 역할, 변경 내용, 변경 이유
• 삭제 클래스: 대체된 클래스와 삭제 이유

코드 스니펫이 필요하면 핵심 시그니처 1~3줄만 인라인으로 포함. 전체 코드 붙여넣기 금지.

Step 8: 통계 및 요약

═══════════════════════════════════════
 변경 통계: N파일 (+X -Y줄), 커밋 M개
 신규 모듈: ModuleA, ModuleB
 수정 모듈: ModuleC, ModuleD
 삭제 모듈: (없음)
═══════════════════════════════════════
 핵심 결정:
 • 결정 1에 대한 설명
 • 결정 2에 대한 설명
═══════════════════════════════════════

핵심 결정: git 커밋 메시지와 코드 변경 패턴에서 추론한 주요 설계 결정을 3~5개 bullet으로 정리.

엣지 케이스 처리

상황	동작
변경 파일 0개	"변경사항이 없습니다." 메시지만 출력하고 종료
클래스 없는 변경만 (config, script, docs)	Step 4 관계도를 생략하고, 파일 단위 요약 리스트 + Step 8 통계만 출력
Detached HEAD	최근 10커밋을 범위로 사용, 사용자에게 범위를 안내
remote 브랜치 없음	origin/main 또는 origin/master로 fallback, 없으면 root commit 대비
바이너리 파일 변경	diff 불가 표시 후 파일명과 크기 변화만 기록

출력 모드

기본 모드 (터미널)

/change-overview — 인자 없이 실행하면 터미널 텍스트로 출력.

• 프로젝트 언어에 맞춰 설명, 코드 식별자는 원문 그대로.
• 관계도는 Unicode box-drawing (┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼) 사용.
• 메서드 시그니처는 파라미터 타입만 간략히 (변수명 생략 가능).
• 클래스별 메서드는 핵심 3~5개만 선별 (전체 나열 금지).
• 전체 출력이 터미널 한 화면에 들어올 수 있도록 간결하게 유지.

HTML 모드 (브라우저)

/change-overview --html — HTML 파일을 생성하고 브라우저로 연다.

Step 13 (데이터 수집/분석)은 동일하게 수행한 뒤, Step 48의 결과를 HTML로 렌더링한다.

HTML 생성 절차:

1. OS 임시 디렉토리에 단일 HTML 파일을 Write 도구로 생성한다:
   • Windows: $TEMP/change-overview-<branch>.html (또는 %TEMP%)
   • macOS: $TMPDIR/change-overview-<branch>.html
   • Linux: /tmp/change-overview-<branch>.html
2. 브라우저에서 열기:
   • Windows: start <path>
   • macOS: open <path>
   • Linux: xdg-open <path>

HTML 구조 — 단일 페이지 스크롤 (탭 사용 금지):

모든 섹션을 하나의 페이지에 순서대로 배치한다. 탭으로 분리하면 전환하며 봐야 하는 불편함이 있으므로 스크롤로 전체를 한 번에 파악할 수 있어야 한다.

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <title>Change Overview: [branch]</title>
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <style>/* 다크 테마, 단일 페이지 레이아웃 */</style>
</head>
<body>
  <!-- 상단 배너: 브랜치, 날짜, 파일/줄 통계 -->
  <!-- 섹션 1: 통계 + 핵심 결정 (요약 먼저) -->
  <!-- 섹션 2: 클래스 관계도 (Mermaid classDiagram) -->
  <!-- 섹션 3: Before/After 비교 (있는 경우만) -->
  <!-- 섹션 4: 이벤트 플로우 (있는 경우만) -->
  <!-- 섹션 5: 구현 상세 -->
</body>
</html>

각 섹션 렌더링 방식:

섹션	렌더링
통계 + 핵심 결정	요약 배너 아래에 바로 표시. 파일/줄 수, 핵심 결정 bullet list
관계도	Mermaid.js classDiagram — 클래스 박스, 상속/조합/의존 화살표, [NEW]/[MOD] 스타일
Before/After	Before/After 트리 나란히 배치, 아래에 요약 테이블
이벤트 플로우	Mermaid.js sequenceDiagram — 시그널 발신→수신 순서
구현 상세	클래스별 들여쓰기 리스트, 코드 스니펫은 <pre><code>

Mermaid classDiagram 예시:

classDiagram
    class UserService {
        <<NEW>>
        +CreateUser(CreateUserDto)
        +FindById(string) User
    }
    class UserRepository {
        <<NEW>>
        +Save(User) User
        +FindById(string) User
    }
    UserService --> UserRepository : uses
    UserService ..|> IUserService : implements

스타일 가이드:

• 다크 배경 (#1e1e2e), 밝은 텍스트 (#cdd6f4)
• [NEW] 클래스: 초록 테두리 (#a6e3a1), [MOD] 클래스: 노랑 테두리 (#f9e2af), [DEL]: 빨강 취소선
• 반응형: 좁은 화면에서는 Before/After를 상하로 전환
• 페이지 상단에 브랜치명, 날짜, 파일/줄 수 요약 배너

중요: HTML은 외부 CDN(Mermaid.js)만 사용하는 단일 파일이어야 한다. 별도 CSS/JS 파일을 생성하지 않는다.

언어 지원

이 스킬은 언어에 구애받지 않는다. 클래스 구조 분석 시 프로젝트의 주요 언어를 자동 감지하여 적절한 패턴을 사용한다:

언어	클래스/타입 감지	의존성 감지	이벤트 감지
C++	class, 상속 :, virtual/override	#include, 생성자 주입	connect(), std::function, 콜백, 옵저버
TypeScript/JavaScript	class, interface, implements	import, constructor injection	EventEmitter, on(), addEventListener()
Python	class, 상속 (Base), @dataclass	import, __init__ 파라미터	signal, emit(), 콜백 패턴
Java/Kotlin	class, interface, implements, extends	import, @Inject, @Autowired	@EventListener, Observer
Go	type struct, interface embedding	import, 생성자 패턴	channel, callback
Rust	struct, impl, trait	use, 생성자 패턴	channel, callback