코드 흐름 시각화 규범
이 Skill은 코드 흐름을 정리하고 시각화 문서를 생성하기 위한 재사용 가능한 템플릿과 방법을 제공합니다.
핵심 원칙: 텍스트와 ASCII 차트를 사용하여 '데이터가 어디서 오고, 어떤 계층을 거치며, 최종적으로 어디로 가는지'를 명확히 설명합니다.
사용 시기
다음 시나리오에서 이 Skill을 사용하세요:
- 사용자가 '특정 기능이 어떻게 작동하는지' 물을 때
- 새 기능에 대한 데이터 흐름을 설계해야 할 때
- 리팩토링 전에 기존 로직을 정리해야 할 때
- 기술 문서나 아키텍처 설명을 작성할 때
- 코드 리뷰 시 호출 체인을 시각화해야 할 때
핵심 템플릿
1. 전체 플로우차트 (다중 시나리오 비교)
적용 대상: 한 기능의 여러 사용 시나리오 정리 (예: 수동 vs 자동, 성공 vs 실패)
┌─────────────────────────────────────────────────────────────────────┐
│ 기능 이름 (예: 한도 관리 전체 수명 주기) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
시나리오 1: 시나리오 이름 (예: 자동 한도 상태 조회)
═══════════════════════════════════════════════════════════════════════
사용자 명령
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI 계층 │ Flow 함수 호출
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow 계층 │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Data 계층 │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ 외부 시스템 / 데이터베이스 │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ 데이터 반환
▼
┌──────────────────────────────────┐
│ 데이터 처리 (파싱/변환) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ 반환 값 데이터 클래스 │ ← 유지/단순화 이유 설명
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI 계층 형식화된 출력 │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ 터미널 출력 예시 ║
║ (테두리 상자로 강조, 최종 사용자에게 보이는 효과) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
시나리오 2: 다른 시나리오
═══════════════════════════════════════════════════════════════════════
(위 구조를 반복하며 차이점을 강조)
2. 데이터베이스 테이블 구조 설명
적용 대상: 특정 기능과 관련된 데이터베이스 테이블 설명
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← 기본 키 역할 설명
field1 TEXT NOT NULL, -- 필드 의미 설명
field2 TEXT, -- NULL의 비즈니스 의미
...
);
-- 인덱스 (이 인덱스가 필요한 이유 설명)
CREATE INDEX idx_xxx ON table_name(field1, field2);
예시 데이터 표:
| id | field1 | field2 | field3 | 설명 |
|---|---|---|---|---|
| 42 | value1 | value2 | value3 | 이 레코드의 비즈니스 의미 설명 |
| 43 | ... | ... | ... | ... |
일반적인 쿼리:
-- 시나리오 설명: 언제 이렇게 조회해야 하는가?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. 계층형 호출 체인도 (간소화 버전)
적용 대상: 함수 호출 관계를 빠르게 설명
CLI 계층 (_do_xxx)
│
└─> Flow 계층 (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> 외부 API (HTTP GET ...)
4. 데이터 클래스 설계 분석표
적용 대상: 중간 데이터 클래스의 필요성 평가
| 클래스 이름 | 필드 수 | 용도 | 판정 | 이유 |
|---|---|---|---|---|
XxxResult | 6 | 다중 필드 집계 + CLI 표시 | ✅ 유지 | '최소 필요 원칙' 충족 |
XxxWrapper | 1 | 단일 필드 래핑 | ❌ 삭제 | 과도한 래핑, 원시 타입 직접 반환 |
XxxItem | 3 | 목록 상세 항목 | ✅ 유지 | 비즈니스 의미 있음 |
비교 예시:
# ❌ 과도한 래핑
@dataclass
class XxxResult:
field: SomeType # 필드가 하나만 있음
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ 간소화
def xxx_flow() -> SomeType: # 직접 반환
return value
5. 비즈니스 키포인트 주석
적용 대상: 비즈니스 규칙 및 설계 결정 사항 강조
┌─────────────────────────────────────────────────────────────┐
│ 비즈니스 키포인트 │
├──────────────────────┬──────────────────────────────────────┤
│ 왜 이렇게 설계했는가? │ 구체적인 결정 │
├──────────────────────┼──────────────────────────────────────┤
│ • 데이터 정밀도 │ 금액은 Decimal 사용, 소수점 2자리 │
│ • 멱등성 │ (fund_code, date) 기준 유일 제약 │
│ • 추적 가능성 │ record_id를 전역 고유 식별자로 사용 │
└──────────────────────┴──────────────────────────────────────┘
사용 방법
Step 1: 분석 목표 설정
다음 질문에 답하세요:
- 사용자가 어떤 기능의 흐름을 알고 싶어하는가?
- 이 기능에는 몇 가지 시나리오가 있는가? (성공/실패, 수동/자동 등)
- 어떤 계층이 관련되어 있는가? (CLI → Flow → Data → DB/API)
- 핵심 데이터 클래스는 무엇이며, 왜 그렇게 설계되었는가?
Step 2: 적절한 템플릿 선택
- 다중 시나리오 비교 → 템플릿 1 (전체 플로우차트)
- 단일 흐름 → 템플릿 3 (계층형 호출 체인)
- 데이터베이스 설계 → 템플릿 2 (테이블 구조 + 예시 데이터)
- 데이터 클래스 평가 → 템플릿 4 (분석표)
Step 3: 내용 채우기
원칙:
- 긴 텍스트 대신 ASCII 차트 사용
- 화살표(
│ ▼ ┐ ┘ └ ├ ─)로 데이터 흐름 연결 - 테두리(
┌ ┐ └ ┘ │ ─)로 계층 구분 - 이중선 테두리(
╔ ╗ ╚ ╝ ║ ═)로 사용자에게 보이는 부분 강조 - 키포인트에 주석 추가 (
← 설명)
기호 사용 규칙:
| 기호 | 용도 | 예시 |
|---|---|---|
│ ▼ | 수직 흐름 | 위에서 아래로 데이터 이동 |
→ ← | 수평 설명 | record_id: int ← 데이터베이스 기본 키 |
┌ ┐ └ ┘ | 단선 테두리 | 코드 블록, 명령어 감싸기 |
╔ ╗ ╚ ╝ | 이중선 테두리 | 터미널 출력, 중요 결과 강조 |
═══ | 구분선 | 다른 시나리오 구분 |
Step 4: 비교 분석 추가
Before vs After (리팩토링 시나리오):
# Before (문제 버전)
...코드...
# 문제:
# - 과도한 래핑
# - 필드 중복
# - 인지 부하 증가
# After (개선 버전)
...코드...
# 개선:
# - 의미 있는 타입 직접 반환
# - 중간 계층 감소
# - 유지 보수 비용 절감
실제 사례
사례 1: 한도 관리 흐름 (전체 버전)
(위 템플릿 1 예시 참조, 4개 시나리오의 전체 흐름 전개)
사례 2: 데이터 클래스 평가 (fund_restriction 모듈)
| 함수 | 이전 반환 | 현재 반환 | 판정 | 이유 |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6필드) | 유지 | ✅ | CLI가 모든 필드를 표시해야 함 |
end_restriction | EndRestrictionResult(4필드) | bool | ❌ | 성공/실패만 필요 |
check_trading_status | CheckStatusResult(2필드) | ParsedRestriction | None | ❌ | 단순 래핑에 불과 |
출력 체크리스트
흐름 시각화 문서를 생성할 때 다음을 포함했는지 확인하세요:
- 최상위 개요 (기능 목표, 관련 모듈)
- 시나리오 열거 (성공/실패, 수동/자동 등)
- 계층형 플로우차트 (CLI → Flow → Data → 외부)
- 데이터베이스 테이블 구조 (관련된 경우)
- 예시 데이터 및 쿼리 (이해를 돕기 위해)
- 핵심 데이터 클래스 설명 (유지/단순화 이유)
- 설계 이유 (왜 이렇게 했는가?)
- 향후 확장 지점 (TODO 또는 예약된 인터페이스)
안티패턴 (이렇게 하지 마세요)
❌ 순수 텍스트로 흐름 설명
먼저 CLI 계층의 _do_xxx 함수를 호출하고, 그 다음 _do_xxx는 Flow 계층의 xxx_flow 함수를 호출하며,
xxx_flow는 다시 Data 계층의 xxx_repo.get 메서드를 호출합니다...
✅ ASCII 차트 사용
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ 테이블에 중요 포인트 없음
| 필드 | 타입 |
|---|---|
| id | int |
| name | str |
✅ 비즈니스 의미 강조
| 필드 | 타입 | 설명 | 비즈니스 제약 |
|---|---|---|---|
| id | int | 기본 키 | 자동 생성, 전역 고유 |
| name | str | 펀드 이름 | 비어 있지 않음, 표시용 |
❌ SQL에 시나리오 설명 없음
SELECT * FROM table WHERE id = ?;
✅ 비즈니스 시나리오 포함
-- 시나리오: 사용자가 특정 제한 레코드 상세 조회
SELECT * FROM fund_restrictions WHERE id = ?;
-- 시나리오: DCA 분석 시 특정 날짜에 한도가 적용되었는지 확인
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
다른 Skill과의 협업
- code-style: 코드 예제를 출력할 때 코딩 규칙을 따릅니다.
- architecture: 플로우차트는 계층형 아키텍처 제약 조건을 준수해야 합니다.
- dev-workflow: 흐름을 정리하기 전에 관련 코드와 문서를 먼저 읽습니다.
요약
이 Skill의 핵심 가치:
- 재사용 가능한 템플릿: 처음부터 시작하는 시간을 줄여줍니다.
- 일관된 시각적 스타일: ASCII 차트 + 표 + 테두리
- 비즈니스 관점: 단순한 코드 흐름을 넘어 '왜'에 집중합니다.
- 비교 분석: 리팩토링 전후, 다중 시나리오 비교
- 체크리스트 검사: 핵심 정보 누락 방지
사용 빈도: '특정 기능이 어떻게 작동하는지' 설명이 필요할 때마다 사용할 수 있습니다.