LISA

주니어 개발자 (iOS 개발은 처음). 바이브 코딩으로 첫 번째 iOS 앱을 개발하고 출시한 경험을 공유합니다. 앱을 통한 소소한 수익화를 꿈꾸며 좌충우돌하는 개발자의 성장 스토리.

4 minute read

Available in other languages

🇪🇸 Español
🇺🇸 English

안녕하세요, LISA입니다! 🙂

“설계 문서에 다이어그램 넣어야 하는데…”

예전의 저:

  • PowerPoint 켜고
  • 도형 그리고
  • 화살표 배치하고
  • 색깔 고르고
  • 정렬하고
  • 30분 지남… 😅

“이미지나 PDF를 직접 만들어야 한다”는 고정관념이 있었어요.

그런데 첫 번째 글에서 언급했듯이, Mermaid + AI 도구로 만들면 기대 이상의 품질이 나오더라고요!

오늘은 실제로 어떻게 활용해서 팀 커뮤니케이션을 효율화했는지 공유해드릴게요.

Mermaid가 뭔가요?

텍스트로 다이어그램을 그리는 도구예요.

간단한 예시

이렇게 쓰면:

graph LR
    A[시작] --> B[처리]
    B --> C[완료]

이렇게 보여요: 시작 → 처리 → 완료 (화살표로 연결된 박스 형태)

왜 좋을까?

✅ 버전 관리: Git으로 히스토리 추적 ✅ 수정 용이: 텍스트만 고치면 됨 ✅ 일관성: 스타일 자동 적용 ✅ 협업: 코드 리뷰처럼 다이어그램 리뷰 가능 ✅ AI 친화적: Claude Code가 바로 생성 가능

자세한 문법이 궁금하다면?

Mermaid 공식 문서에 가면 모든 다이어그램 타입과 문법이 자세히 나와있어요:

  • 공식 문서: https://mermaid.js.org/
  • 라이브 에디터: https://mermaid.live/

하지만 저는 문법을 외우거나 매뉴얼을 찾아볼 필요가 없었어요. 왜냐하면…

AI 도구와의 조합이 게임 체인저

예전 방식 (문법 공부)

  1. Mermaid 문서 열기
  2. 원하는 다이어그램 타입 찾기
  3. 문법 읽고 이해하기
  4. 직접 코드 작성
  5. 에러 나면 다시 문서 보기
  6. 수정하고 재시도

시간: 20-30분 (문법 익히는 시간 포함)

AI 도구 활용 (지금)

Claude Code에게:

“로그인 프로세스 시퀀스 다이어그램 만들어줘. 사용자 → 웹 → API → DB 순서로”

결과: → 몇 초 안에 Mermaid 코드 생성 → 바로 시각화 → 수정 필요하면 “Redis 캐싱 추가해줘” 한 마디면 됨

시간: 1-2분

문법 몰라도 돼요! AI가 다 해줘요.

실제 업무에서 이렇게 써요

상황 1: 요구사항 분석 회의

예전:

  • 기획자: “유스케이스 다이어그램 있으면 이해하기 쉬울 것 같은데…”
  • 저: “회의 끝나고 그려서 공유할게요” (30분 후…)

지금:

  • 기획자: “유스케이스 다이어그램 있으면…”
  • 저: Claude Code 켜고 1분 “이거 어때요?” (회의 중 바로 공유)

효과:

  • ✅ 회의 중 즉시 시각화
  • ✅ 바로 피드백 받고 수정
  • ✅ 회의 끝나면 문서 완성

상황 2: 설계 리뷰

예전:

  • “이 기능 어떻게 구현할 거예요?”
  • 말로 설명… (서로 이해도 다름)
  • “아, 그거 PowerPoint로 그려서 공유할게요”
  • 다음 날…

지금:

  • “이 기능 어떻게 구현할 거예요?”
  • Claude Code에게 시퀀스 다이어그램 요청 1분
  • “이렇게요” (바로 공유)
  • 그 자리에서 논의 완료

효과:

  • ✅ 즉각적인 피드백
  • ✅ 오해 줄어듦
  • ✅ 의사결정 빨라짐

상황 3: PR 리뷰

예전:

## Changes
- 로그인 프로세스 리팩토링
- 세션 관리 개선

(설명 길게...)

지금:

## Changes
- 로그인 프로세스 리팩토링

## Architecture
[시퀀스 다이어그램 - 기존]
[시퀀스 다이어그램 - 개선]

한 눈에 보이죠?

효과:

  • ✅ 리뷰어가 빠르게 이해
  • ✅ 리뷰 시간 단축
  • ✅ 더 나은 피드백

실전 활용: 다이어그램 타입별

1. 시퀀스 다이어그램 (가장 많이 씀)

언제 써요?

  • API 설계 논의
  • 프로세스 설명
  • 에러 처리 흐름
  • 성능 최적화 논의

Claude Code에게:

“주문 프로세스 시퀀스 다이어그램 만들어줘. 재고 확인, 결제, 배송 단계 포함해줘”

→ 1분 후 완성 → 회의 중 바로 사용

실제 효과:

  • 기획자: “아, 결제 실패하면 어떻게 되나요?”
  • 저: “다이어그램에 에러 처리 추가해줘” (10초 후 업데이트)
  • 모두: “아! 이해했어요!”

2. 상태 다이어그램

언제 써요?

  • 복잡한 상태 관리 설명
  • 주문/결제 프로세스
  • UI 상태 전이

Claude Code에게:

“주문 상태 다이어그램 만들어줘. 주문접수 → 결제 → 배송 → 완료, 취소 경로도 포함”

→ 1분 후 완성

실제 효과:

  • QA: “취소는 어느 단계까지 가능한가요?”
  • 다이어그램 보면서: “여기까지요”
  • 말보다 명확함!

3. 유스케이스 다이어그램

언제 써요?

  • 요구사항 정리
  • 기능 범위 논의
  • 권한 설계

Claude Code에게:

“이커머스 시스템 유스케이스 다이어그램. Actor: 고객, 관리자”

→ 1분 후 완성

4. 아키텍처 다이어그램

언제 써요?

  • 시스템 구조 설명
  • 기술 스택 공유
  • 신입 온보딩

Claude Code에게:

“우리 시스템 아키텍처 다이어그램. Frontend(React), Backend(Node.js), DB(PostgreSQL)”

→ 1분 후 완성

지난 글에서 말한 CLAUDE.md 활용

Mermaid 스타일 가이드 정의

# CLAUDE.md

## Mermaid Diagram Guidelines

### 시퀀스 다이어그램
- Participant 이름: 한글 사용
- 화살표: 요청(->>), 응답(-->>)
- 주요 단계만 표현 (5-10 단계 목표)

### 상태 다이어그램
- 상태 이름: 한글 명사형
- 전이 조건: 간단명료하게

### 공통 규칙
- 복잡하면 여러 다이어그램으로 분리
- 주석 최소화
- 핵심 플로우만 표현

이렇게 해두면 일관된 스타일로 다이어그램이 나와요.

실무에서 배운 것들

✅ 이렇게 활용하세요

1. 회의 전 미리 준비하지 마세요

예전에는 회의 전에 다이어그램 미리 그렸는데, 회의 중에 다 바뀌더라고요 😅

지금은:

  • 회의 중 필요할 때 만들기
  • 즉석에서 피드백 받으면서 수정
  • 회의 끝나면 최종본 완성

2. PR에 다이어그램 포함

## Architecture Changes
Before:
[다이어그램]

After:
[다이어그램]

리뷰어가 5초 만에 이해해요.

3. 문서와 함께 버전 관리

docs/
├── architecture.md
└── diagrams/
    ├── login-sequence.mmd
    └── order-state.mmd
  • 이미지 말고 .mmd 파일로 저장
  • Git으로 변경 이력 추적
  • 필요할 때 다시 수정

4. 템플릿 재사용

# .claude/templates/sequence-basic.mmd

sequenceDiagram
    participant User
    participant System

    User->>System: 요청
    System-->>User: 응답

자주 쓰는 구조는 템플릿으로 만들어두면 Claude Code가 그걸 기반으로 만들어줘요.

❌ 이렇게 하지 마세요

1. 너무 복잡하게

❌ 모든 단계 다 넣기 (20단계 시퀀스)
✅ 핵심 흐름만 (5-7단계)

복잡하면 여러 다이어그램으로 나누세요.

2. 이미지로 저장

❌ diagram.png
✅ diagram.mmd

텍스트 파일이 버전 관리도 되고, 수정도 쉬워요.

3. 문법 공부하려고 하기

AI한테 시키면 돼요. 문법 외울 필요 없어요!

고정관념을 깨다

예전: “다이어그램 = 시간 많이 걸림 = 중요한 문서에만”

지금: “다이어그램 = 1분이면 됨 = 일상적으로 사용”

  • 간단한 질문에도 다이어그램
  • 채팅에도 다이어그램
  • PR에도 다이어그램

시각화가 기본이 됐어요.

생산성 변화

다이어그램 작성 시간:

  • PowerPoint: 20-30분
  • Mermaid 직접: 10-15분
  • AI + Mermaid: 1-2분

15배 빨라졌어요!

더 중요한 건:

  • 즉각적인 커뮤니케이션
  • 오해 줄어듦
  • 더 나은 의사결정

시리즈 총정리

1편: 컨텍스트 오염 문제와 Clear + CLAUDE.md 해결책 2편: CLAUDE.md 관리 전략과 템플릿 3편: Mermaid로 커뮤니케이션 효율화

핵심 메시지:

  • 최신 기능보다 기본기가 중요
  • 컨텍스트 관리가 전부
  • AI 도구로 생산성 폭발
  • 도구는 생각보다 강력함

Claude Code는 이제:

  • ✅ 코드 작성
  • ✅ 설계 문서
  • ✅ 다이어그램
  • ✅ 팀 커뮤니케이션

업무 전반의 파트너예요.

다음 단계는?

작은 것부터 시작하세요:

  1. 다음 회의에서: “시퀀스 다이어그램 만들어줘” 시도
  2. 다음 PR에서: 다이어그램 하나 포함
  3. 동료와 공유: “이렇게 하니까 편하더라”

효과를 보면 자연스럽게 확장될 거예요!

그리고 Mermaid 문법이 궁금하면 공식 문서(https://mermaid.js.org/)를 참고하세요. 하지만 대부분은 AI에게 물어보면 돼요!

📱 TipSmart에서 실제로 써봤어요

TipSmart 개발할 때 모든 주요 기능에 다이어그램을 만들었어요:

  • 팁 계산 프로세스 (시퀀스)
  • 앱 상태 관리 (상태 다이어그램)
  • MVVM 아키텍처 (컴포넌트 다이어그램)

회의 시간이 절반으로 줄고, 팀원들 이해도가 훨씬 높아졌어요.

App Store에서 TipSmart 다운로드하기 📱

Mermaid + AI, 이제 써보실 건가요? 다음 회의에서 한 번만 써보세요. 바로 느껴지실 거예요!

한 달 반 만에 3부작 시리즈를 완성했네요. 긴 글 읽어주셔서 정말 감사합니다! 🙏

You May Also Enjoy