Communitygithub.com

코드 흐름 시각화 규범

코드 흐름을 정리하고 시각화하여 명확한 ASCII 플로우차트, 데이터 흐름도 및 테이블 분석을 생성합니다. 기존 코드 분석, 새로운 기능 설계 설명, 기술 문서 작성에 적합합니다.

코드 흐름 시각화 규범란 무엇인가요?

이 스킬은 코드 흐름을 구조화하고 시각화하는 템플릿과 방법론을 제공합니다. 개발자는 ASCII 다이어그램과 테이블을 사용하여 '데이터가 어디서 오고, 어떤 계층을 거치며, 최종적으로 어디로 가는지'를 명확하게 설명할 수 있습니다. CLI, Flow, Data, 외부 시스템을 포함한 계층별 호출 체인을 다이어그램으로 표현하고, 데이터베이스 테이블 구조, 데이터 클래스 설계 평가, 그리고 비즈니스 규칙을 강조하여 문서화할 수 있습니다. 주요 사용 사례로는 기존 기능 분석, 새 기능 설계, 리팩토링 전 로직 정리, 기술 문서 작성 등이 있습니다. 스킬은 플랫폼에 독립적이며, ASCII 차트, 표, 그리고 비교 분석을 통해 코드의 이해도를 높이고 유지보수성을 개선하는 데 중점을 둡니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/code-flow-viz-mmorit00-fund-portfolio-bot-2

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

코드 흐름 시각화 규범은(는) 무엇을 하나요?

본 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);

예시 데이터 테이블:

idfield1field2field3설명
42value1value2value3이 레코드의 비즈니스 의미 설명
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. 데이터 클래스 설계 분석 테이블

적용 대상: 중간 데이터 클래스의 필요성 평가할 때

클래스명필드 수용도판정이유
XxxResult6다중 필드 집계 + CLI 표시✅ 유지"최소 필요 원칙" 충족
XxxWrapper1단일 필드 래핑❌ 삭제과도한 래핑, 원시 타입 직접 반환
XxxItem3리스트 세부 항목✅ 유지비즈니스 의미 있음

비교 예시:

# ❌ 과도한 래핑
@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: 분석 목표 결정

다음 질문에 답하세요:

  1. 사용자가 이해하려는 기능은 무엇인가요?
  2. 이 기능에는 몇 가지 시나리오가 있나요? (성공/실패, 수동/자동 등)
  3. 관련된 계층은 무엇인가요? (CLI → Flow → Data → DB/API)
  4. 핵심 데이터 클래스는 무엇이며, 왜 그렇게 설계되었나요?

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_restrictionAddRestrictionResult(6필드)유지✅CLI에서 모든 필드 표시 필요
end_restrictionEndRestrictionResult(4필드)bool❌성공/실패만 필요
check_trading_statusCheckStatusResult(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

❌ 핵심 없는 테이블

필드타입
idint
namestr

✅ 비즈니스 의미 강조

필드타입설명비즈니스 제약
idint기본 키자동 생성, 전역 고유
namestr펀드 이름비어 있지 않음, 표시용

❌ 시나리오 설명 없는 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의 핵심 가치:

  1. 재사용 가능한 템플릿: 매번 처음부터 시작하는 시간 절약
  2. 통일된 시각적 스타일: ASCII 다이어그램 + 테이블 + 테두리
  3. 비즈니스 관점: 단순한 코드 흐름이 아닌 "왜"에 초점
  4. 비교 분석: 리팩토링 전후, 다중 시나리오 비교
  5. 체크리스트 검사: 핵심 정보 누락 방지

사용 빈도: "특정 기능이 어떻게 작동하는지" 설명이 필요할 때마다 사용할 수 있습니다.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

관련 스킬