코드 흐름 시각화 규범은(는) 무엇을 하나요?
본 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 다이어그램 + 테이블 + 테두리
- 비즈니스 관점: 단순한 코드 흐름이 아닌 "왜"에 초점
- 비교 분석: 리팩토링 전후, 다중 시나리오 비교
- 체크리스트 검사: 핵심 정보 누락 방지
사용 빈도: "특정 기능이 어떻게 작동하는지" 설명이 필요할 때마다 사용할 수 있습니다.