Claude Code 구현 전 Mermaid 다이어그램으로 계획을 검토하는 방법
How I use Mermaid diagrams to review Claude Code’s plans before implementation
핵심 요약
Claude Code 작업 시 Mermaid 다이어그램을 활용해 복잡한 로직을 시각화하고 토큰을 절약하며 효율적으로 소통하는 워크플로우를 소개합니다.
- 시각적 계획 — 구현 전 다이어그램으로 구조와 데이터 흐름을 명확히 함
- 토큰 절약 — 텍스트로 시스템 전체를 설명하는 대신 다이어그램으로 수정 사항을 전달함
- 지속적 관리 — 다이어그램을 리포지토리에 보관해 향후 세션에서도 참조하도록 함
- 도구 활용 — Mermaid 소스 코드를 활용해 에이전트와 효율적으로 협업함
내가 Claude Code를 쓸 때 보통 하는 방식은, 처음엔 요구사항을 대충 막 적어놓는 것부터 시작해.
일단 코드베이스를 훑어보고 구현 계획을 짜달라고 시키지. 코드를 짜기 전에, 내가 아직 이해가 안 가는 부분은 다이어그램으로 그려달라고 해.
기존 시스템을 건드릴 땐 보통 현재 상태(as-is)랑 변경 후 상태(to-be)를 보여달라고 하고, 아예 새로 만드는 프로그램이면 전체적인 아키텍처부터 확인한 다음에 데이터 흐름을 따로 봐. 만약 컴포넌트 생명주기가 복잡하면 그 부분만 집중적으로 시퀀스 다이어그램이나 상태 다이어그램을 그려달라고 하지.
구조가 눈에 보이면, 시스템 전체를 다시 줄글로 설명할 필요 없이 그냥 컴포넌트 하나나 화살표 하나만 콕 집어서 수정하라고 하면 돼. 이 워크플로우에서 Mermaid가 토큰 아끼는 데는 최고인 듯.
공유하기도 편해. 그냥 다이어그램만 보여주면 될 땐 스크린샷을 보내고, 나중에 수정하거나 재사용해야 할 것 같으면 Mermaid 소스 코드를 보내거든.
남은 문제는 다이어그램이 낡아서 쓸모없어지는 걸 막는 거야. 현재 작업 이후에도 계속 쓸만한 다이어그램이면 리포지토리에 박아두고 에이전트 지침에서 참조하게 만들어. 그래야 나중에 다시 작업할 때 에이전트가 알아서 읽고 업데이트할 확률이 높거든.
내가 이 워크플로우를 정리하고 최근에 써본 다이어그램 툴 몇 개를 비교해둔 글은 여기 있어:
https://nooker.app/@tim/how-diagrams-fit-into-coding-agent-workflows
참고로, 글에 언급된 툴 중 하나인 FlowPeek는 내가 만든 거야. 물론 이 워크플로우 자체는 툴 만들기 전부터 쓰던 거지만.
너희는 Claude Code한테 구현 맡기기 전에 어떤 다이어그램을 그리는 게 제일 도움 된다고 생각해?
