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

This is the long-form blog cut of a note I originally posted on LinkedIn. The claims, numbers, and product names are the same; the formatting is for reading on the site.

Context

Original framing (translated in place for key technical posts; substance preserved):

에이전트한테 마이크로 서비스 전체를 리팩토링시켰습니다.

하지만 PR 이 올라왔는데 서비스 간 호출 흐름이 머릿속에 안 그려지더라고요. 로그를 한 줄씩 읽으면서 “이게 맞나?” 되뇌는 시간이 코딩 시간보다 길었습니다.

실제로 터미널 출력만으로 전체 그림을 잡는 건 한계가 있어요. 시각화를 붙이고 나서야 코드 흐름이 한눈에 잡혔고 동료한테 설명하는 시간도 절반으로 줄었습니다.

1️⃣ visual-explainer: 터미널 ASCII 출력을 브라우저용 인터랙티브 HTML 페이지로 전환

github repo: https://lnkd.in/g7Zw9XVT

에이전트에게 아키텍처를 그려달라고 하면 모노스페이스 박스가 나옵니다. 노드 5개만 넘어가도 눈이 미끄러져요.

visual-explainer 는 같은 요청을 Mermaid 다이어그램이 포함된 HTML 페이지로 만들어줍니다. 다크모드 전환과 줌/팬이 기본으로 들어있고 빌드 스텝이나 외부 의존성 없이 브라우저만 있으면 동작해요.

에이전트한테 마이크로 서비스 전체를 리팩토링시켰습니다.

하지만 PR 이 올라왔는데 서비스 간 호출 흐름이 머릿속에 안 그려지더라고요. 로그를 한 줄씩 읽으면서 “이게 맞나?” 되뇌는 시간이 코딩 시간보다 길었습니다.

실제로 터미널 출력만으로 전체 그림을 잡는 건 한계가 있어요. 시각화를 붙이고 나서야 코드 흐름이 한눈에 잡혔고 동료한테 설명하는 시간도 절반으로 줄었습니다.

1️⃣ visual-explainer: 터미널 ASCII 출력을 브라우저용 인터랙티브 HTML 페이지로 전환

github repo: https://lnkd.in/g7Zw9XVT

에이전트에게 아키텍처를 그려달라고 하면 모노스페이스 박스가 나옵니다. 노드 5개만 넘어가도 눈이 미끄러져요.

visual-explainer 는 같은 요청을 Mermaid 다이어그램이 포함된 HTML 페이지로 만들어줍니다. 다크모드 전환과 줌/팬이 기본으로 들어있고 빌드 스텝이나 외부 의존성 없이 브라우저만 있으면 동작해요.

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

2️⃣ Excalidraw MCP: 채팅 안에서 실시간으로 그려지는 손그림 다이어그램

github repo: https://lnkd.in/gWPnWMdt

MCP 서버 주소 mcp.excalidraw.com 하나만 등록하면 설치 없이 바로 쓸 수 있습니다.

스트리밍으로 그림이 그려지는 걸 처음 봤을 때 솔직히 놀랐어요. 정식 다이어그램 도구와 달리 손그림 스타일이라 동료에게 구조를 설명할 때 오히려 부담이 적습니다.

• Claude Desktop 과 VS Code 에서 모두 동작 • 카메라 뷰포트 자동 조절과 풀스크린 편집 모드 지원 • MCP Apps 확장 기반이라 채팅 안에서 바로 인터랙티브 편집 가능

3️⃣ beautiful-mermaid: 기본 렌더링이 투박한 Mermaid 다이어그램을 느낌 있게 제작

github repo: https://lnkd.in/gRkizduS

Mermaid 문법은 좋은데 기본 렌더링이 투박합니다. 색상 하나 바꾸려면 CSS 클래스를 뒤져야 해요.

beautiful-mermaid 는 bg 와 fg 색상 2개만 넣으면 나머지 것에 대해 색상과 텍스트 밝기를 color-mix() 로 자동 파생합니다. 또한 15개 사전 구현된 테마가 있고 이를 한 줄로 적용할 수 있습니다.

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

4️⃣ Zara Zhang 의 “Claude Teacher” 프롬프트: 프로젝트마다 나만의 해설서가 자동으로 쌓이는 구조

Her x post: https://lnkd.in/gMWkcGH9

CLAUDE.md 에 한 문단만 추가합니다. 프로젝트를 끝낼 때마다 FOR[이름].md 파일을 만들어서 프로젝트 전체를 쉬운 말로 정리하라는 지시예요.

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

프롬프트가 요구하는 항목: • 기술 아키텍처와 코드베이스 구조 간 연결 관계 • 사용한 기술 스택과 왜 그 기술을 선택했는지 결정 이유 • 작업 중 만난 버그와 해결 과정 그리고 앞으로 피해야 할 함정 • 좋은 엔지니어가 어떻게 생각하고 일하는지에 대한 실전 교훈

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

5️⃣ Boris Cherny 의 “학습용 Claude Code” 설정: 일을 시키고 그 다음엔 설명도 시켜라

Claude Code 를 만든 Boris Cherny 가 직접 공유한 팁입니다.

/config 에서 Explanatory 출력 스타일을 켜면 코드를 바꿀 때마다 왜 그렇게 했는지를 같이 설명합니다.

Learning 스타일은 한 발 더 나가서 일부 작업을 멈추고 직접 코딩해보라고 시켜요. 낯선 코드베이스는 HTML 슬라이드로 만들어달라고 하면 프레젠테이션처럼 훑을 수 있고 반복 학습 스킬을 만들면 내가 이해한 걸 설명하고 빈 곳을 채워주는 구조도 됩니다.

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

AI 에이전트에게 일만 시키는 단계는 이미 지났습니다. Boris 가 강조한 건 명확해요. 일을 시키고 그 다음엔 시각화하고 설명하게 만들어라.

AI가 모든 것을 다 하는 시대에 사람이 해야 할 일은 이해하는 겁니다. 그리고 시각은 인간이 가장 빠르게 정보를 처리하는 방식 중 하나입니다. AI에 인간의 시각을 더하면 우리의 능력은 100배가 됩니다.

Links

• https://lnkd.in/g7Zw9XVT
• https://lnkd.in/gWPnWMdt
• https://lnkd.in/gRkizduS
• https://lnkd.in/gMWkcGH9