AI 에이전트에게 일을 시킨 다음, 인간이 해야 할 일은 시각화입니다

에이전트한테 마이크로서비스 전체를 리팩토링시켰습니다. PR이 올라왔는데 서비스 간 호출 흐름이 머릿속에 그려지지 않았습니다. 로그를 한 줄씩 읽으면서 “이게 맞나?” 되뇌는 시간이 코딩 시간보다 길었습니다.

터미널 출력만으로 전체 그림을 잡는 건 한계가 있습니다. 시각화를 붙이고 나서야 코드 흐름이 한눈에 잡혔고, 동료에게 설명하는 시간도 절반으로 줄었습니다. 지금부터 소개하는 도구 다섯 가지는 모두 이 문제를 서로 다른 각도에서 풀고 있습니다.

터미널 ASCII를 브라우저로 옮기면 전체 그림이 잡힌다

에이전트에게 아키텍처를 그려달라고 하면 모노스페이스 박스가 나옵니다. 노드 5개만 넘어가도 눈이 미끄러집니다. visual-explainer는 같은 요청을 Mermaid 다이어그램이 포함된 HTML 페이지로 만들어 줍니다. 다크모드 전환과 줌/팬이 기본으로 들어 있고, 빌드 스텝이나 외부 의존성 없이 브라우저만 있으면 동작합니다.

• /diff-review: 코드 변경과 아키텍처 비교를 한 화면에 출력합니다.
• /project-recap: 며칠 전 프로젝트에 복귀할 때 맥락 복구 스냅샷을 생성합니다.
• /generate-slides: 같은 결과물을 슬라이드 덱으로 변환할 수 있습니다.
• 자동 전환: 4행 이상 테이블을 터미널에 찍으려 하면 HTML 렌더링으로 자동 전환됩니다.

채팅 안에서 실시간으로 다이어그램이 그려진다

Excalidraw MCP는 MCP 서버 주소 하나만 등록하면 설치 없이 바로 쓸 수 있습니다. 스트리밍으로 그림이 그려지는 걸 처음 봤을 때 솔직히 놀랐습니다. 정식 다이어그램 도구와 달리 손그림 스타일이라 동료에게 구조를 설명할 때 오히려 부담이 적습니다.

• 멀티 환경 지원: Claude Desktop과 VS Code에서 모두 동작합니다.
• 카메라 자동 조절: 뷰포트 자동 조절과 풀스크린 편집 모드를 지원합니다.
• 인터랙티브 편집: MCP Apps 확장 기반이라 채팅 안에서 바로 편집할 수 있습니다.

한 가지 한계는 복잡한 시퀀스 다이어그램에는 Mermaid 문법이 더 적합하다는 점입니다. 손그림 스타일은 아키텍처 개요나 플로우 설명에 강점이 있고, 세밀한 호출 순서를 표현하려면 다른 도구와 조합해야 합니다.

Mermaid 다이어그램을 투박함에서 꺼내는 법

Mermaid 문법은 좋은데 기본 렌더링이 투박합니다. 색상 하나 바꾸려면 CSS 클래스를 뒤져야 합니다. beautiful-mermaid는 배경색과 전경색 2개만 넣으면 나머지 색상과 텍스트 밝기를 color-mix()로 자동 파생합니다. 15개 사전 구현 테마가 있고 한 줄로 적용할 수 있습니다.

• 깜빡임 제로: SVG 렌더링이 동기식이라 React useMemo() 안에서 깜빡임 없이 동작합니다.
• CLI 내장 가능: 터미널용 ASCII/Unicode 출력도 지원해서 CLI 도구에 다이어그램을 내장할 수 있습니다.
• 서버 사이드 호환: DOM 의존성이 없어서 서버 사이드에서도 돌아갑니다.
• 에디터 테마 연동: Shiki 연동으로 VS Code 테마를 다이어그램에 그대로 적용할 수 있습니다.

일을 시키고 해설서까지 쓰게 하는 구조

Zara Zhang이 공유한 “Claude Teacher” 프롬프트는 CLAUDE.md에 한 문단만 추가하는 방식입니다. 프로젝트를 끝낼 때마다 FOR[이름].md 파일을 만들어서 프로젝트 전체를 쉬운 말로 정리하라는 지시입니다.

이 접근이 유효한 이유는 단순합니다. AI 에이전트는 코드를 짜면서 아키텍처와 결정 이유를 이미 알고 있습니다. 그 정보를 명시적으로 꺼내라고 시키는 것뿐입니다.

• 아키텍처 연결: 기술 아키텍처와 코드베이스 구조 간 연결 관계를 설명합니다.
• 결정 이유: 사용한 기술 스택과 왜 그 기술을 선택했는지를 기록합니다.
• 실전 교훈: 작업 중 만난 버그, 해결 과정, 앞으로 피해야 할 함정을 정리합니다.
• 엔지니어 사고방식: 좋은 엔지니어가 어떻게 생각하고 일하는지에 대한 교훈을 담습니다.

지루한 기술 문서가 아니라 비유와 에피소드가 섞인 읽을거리로 쓰라고 못 박았기 때문에, 실제 결과물은 온보딩 자료로 바로 쓸 수 있는 수준이 됩니다.

코드를 생성하고 끝이 아니라 설명까지 시켜야 한다

Claude Code를 만든 Boris Cherny가 직접 공유한 팁입니다. /config에서 Explanatory 출력 스타일을 켜면 코드를 바꿀 때마다 왜 그렇게 했는지를 같이 설명합니다. Learning 스타일은 한 발 더 나가서 일부 작업을 멈추고 직접 코딩해 보라고 시킵니다.

낯선 코드베이스는 HTML 슬라이드로 만들어달라고 하면 프레젠테이션처럼 훑을 수 있습니다. 반복 학습 스킬을 만들면 본인이 이해한 걸 설명하고 빈 곳을 채워 주는 구조도 가능합니다.

• Before: 코드 생성, 동작 확인, 구조 이해 안 됨
• After: 코드 생성, 시각화 + 설명 요청, 구조 체득, 다음 프로젝트에 응용

AI 에이전트에게 일만 시키는 단계는 이미 지났습니다. 일을 시키고 그 다음에는 시각화하고 설명하게 만들어야 합니다. AI가 모든 것을 대신하는 시대에 사람이 해야 할 일은 이해하는 것입니다. 시각은 인간이 가장 빠르게 정보를 처리하는 방식 중 하나이고, AI에 인간의 시각을 더하면 능력의 차원이 달라집니다.