스펙 문서가 한눈에 들어오지 않을 때, AI에게 그려달라고 했다

얼마 전 신규 개발 서비스의 설계를 검토할 일이 있었다. 스펙 문서는 있었다. 필요한 기능도 적혀 있었고, 주요 흐름도 글로 설명되어 있었다. 그런데 이상하게 한 번에 들어오지 않았다.

문서가 부실했다는 뜻은 아니다. 오히려 문서만 놓고 보면 필요한 정보는 꽤 있었다. 문제는 내가 검토자로서 보고 싶은 형태가 아니었다는 점에 가까웠다. 텍스트를 읽는 것과 설계를 이해한 채 출발하는 것은 다르다.

설계 검토를 할 때 내가 먼저 보고 싶은 것은 “무슨 기능이 있나”가 아니다. 이 서비스가 어떤 큰 덩어리로 나뉘어 있는지, 각 덩어리가 무엇을 책임지는지, 책임의 경계가 어디인지가 먼저 보여야 한다. 그래야 그다음 질문을 할 수 있다.

그래서 AI에게 다시 설명해달라고 하지 않았다. 대신 시각적으로 뽑아달라고 했다. 긴 요약문이 아니라, 검토할 수 있는 화면을 만들어달라고 했다.

처음부터 플로우차트를 본 것은 아니었다

처음부터 데이터 흐름이나 사용자 흐름 플로우차트를 본 것은 아니었다. 먼저 확인한 것은 레이어 간 책임 분리였다.

이 설계가 어떤 레이어들로 나뉘어 있는지, 각 레이어가 어떤 역할을 가져야 하는지, 서로 어디까지 알고 있어야 하는지부터 보고 싶었다. 이 부분이 보이자 설계를 작은 문장들의 목록이 아니라 덩어리 형태의 큰 흐름으로 읽을 수 있었다.

그다음에야 플로우차트가 의미가 있었다. 사용자 요청이 어디서 시작해서 어디를 지나가는지, 데이터가 어디서 만들어지고 어디서 바뀌는지, 상태 변화가 어느 레이어에서 발생하는지를 봤다. 그리고 각 레이어가 그 흐름의 어느 지점에서 개입되는지 확인했다.

순서가 중요했다. 먼저 책임의 경계가 보이고, 그다음 큰 덩어리의 흐름이 보이고, 마지막으로 사용자 흐름과 데이터 흐름이 겹쳐 보였다. 그때부터 “이 설계가 맞는가?”를 제대로 물어볼 수 있었다.

AI에게 설명을 더 받는 것과, 검토 화면을 받는 것은 다르다

AI에게 “이 설계 설명해줘”라고 하면 대개 꽤 그럴듯한 요약을 준다. 하지만 요약은 검토와 다르다. 요약은 내용을 줄여주지만, 검토는 내가 어디를 봐야 하는지 알려줘야 한다.

설계 검토에서 필요한 것은 예쁜 문서가 아니다. 레이어의 경계, 의존성, 흐름, 위험 지점, 모호한 가정이 한 화면 안에서 서로 연결되어 보이는 것이다. 그래야 머릿속에서 따로따로 읽은 문장을 다시 조립하지 않아도 된다.

이 차이는 생각보다 크다. 글로 읽을 때는 “API 레이어에서 처리한다”, “상태는 DB에 저장한다”, “비동기 처리가 필요하다” 같은 문장이 따로 들어온다. 하지만 시각화된 화면에서는 이 문장들이 어디에서 만나고 충돌하는지가 보인다.

나는 이 지점에서 AI의 출력 형식도 일종의 협업 방식이라는 생각을 하게 됐다. 같은 내용을 받아도 Markdown 요약으로 받을 때와 HTML 화면으로 받을 때, 검토자가 할 수 있는 일이 달라진다.

Markdown은 나쁘지 않지만, 모든 검토에 맞지는 않다

최근 Simon Willison이 Thariq Shihipar의 글을 소개하면서, Claude Code에게 Markdown만 시키지 말고 HTML artifact를 만들게 해보자는 이야기를 했다. 인상적이었던 문장은 “Diffs and call-graphs are spatial information; markdown flattens them.”이었다.

차이점(diff), 호출 관계(call graph), 레이어 구조, 데이터 흐름은 모두 공간적인 정보에 가깝다. 어디에서 어디로 이어지는지, 어떤 부분이 가까운지, 어디가 위험한지, 무엇이 바뀌었는지는 평면적인 목록보다 배치와 연결로 볼 때 더 빨리 이해된다.

물론 Markdown은 여전히 좋다. 회고, 요약, 체크리스트, 기록에는 Markdown만 한 것이 없다. 나도 계속 Markdown을 쓴다. 다만 설계나 PR을 검토하는 순간에는 Markdown만으로 부족할 때가 있다. 그때 필요한 것은 글이 아니라 화면이다.

AI가 만든 PR을 볼 때도 같은 문제가 생긴다

이 문제는 설계 검토에서만 생기지 않는다. AI가 만든 PR이나 코드 변경을 볼 때도 비슷한 어려움이 있다.

사람이 만든 PR은 보통 작성자의 맥락이 어느 정도 남아 있다. 왜 이 파일을 바꿨는지, 어떤 문제를 풀고 있었는지, 어떤 부분을 조심해야 하는지가 대화나 PR 본문에 남는 경우가 많다. 반면 AI가 만든 변경은 여러 파일과 여러 주제를 한 번에 건드릴 때가 많다.

리팩터링, 기능 추가, 테스트 수정, 네이밍 변경, 예외 처리 보강이 한 PR 안에 섞일 수 있다. 코드는 돌아갈 수도 있다. 하지만 리뷰어 입장에서는 “그래서 이 PR은 정확히 무엇을 바꾼 것인가?”를 먼저 파악해야 한다.

AI가 코드를 많이 만들수록 리뷰는 더 쉬워지는 것이 아니라, 다른 종류의 어려움을 갖게 된다. 코드를 직접 쓰는 시간은 줄어들 수 있지만, 변경의 구조를 이해하고 통과시킬 책임은 여전히 사람에게 남는다.

그래서 AI가 만든 PR에는 사람 PR보다 더 많은 콘텍스트가 필요할 수 있다. 단순히 긴 PR 본문이 필요하다는 뜻은 아니다. 변경이 전체 코드베이스의 어디를 건드렸는지, 어떤 레이어가 영향을 받는지, 변경 전후 흐름이 어떻게 달라졌는지 보여주는 검토 화면이 필요하다는 뜻이다.

좋은 AI 시각화는 예쁜 그림이 아니다

여기서 중요한 것은 “시각화”라는 말을 너무 넓게 쓰지 않는 것이다. 예쁜 다이어그램이나 그럴듯한 카드 UI를 만들자는 이야기가 아니다.

좋은 AI 시각화는 검토자의 이해 순서를 따라가는 화면이다. 내가 먼저 보고 싶은 것이 레이어 책임이라면, 그걸 먼저 보여줘야 한다. 그다음 큰 흐름을 보고 싶다면, 설계를 덩어리 단위로 묶어줘야 한다. 그 후에 데이터 흐름과 사용자 흐름을 보고 싶다면, 플로우차트가 그 순서에 맞게 나와야 한다.

반대로 처음부터 모든 것을 한 장에 다 넣은 복잡한 그림은 도움이 되지 않는다. 시각화도 결국 질문의 순서가 있어야 한다. “무엇을 검토하려고 하는가”가 빠진 그림은 장식에 가깝다.

AI에게 그림을 그려달라고 할 때 중요한 건 예쁘게 만드는 게 아니라, 내가 검토하는 순서대로 보이게 만드는 것이다.

내가 실제로 써볼 프롬프트

다음에 비슷한 설계 검토를 한다면, 나는 이런 식으로 요청할 것 같다.

이 신규 서비스 스펙을 검토하기 위한 단일 HTML 파일을 만들어줘.
목적은 스펙을 예쁘게 요약하는 것이 아니라, 설계자가 전체 구조를 한눈에 이해하고 레이어별로 검토할 수 있게 만드는 것이다.
 
포함할 것:
- 전체 서비스의 레이어 구조를 시각적으로 보여줘
- 각 레이어의 책임과 경계를 먼저 분리해서 표시해줘
- 설계를 세부 파일 목록이 아니라 큰 덩어리/흐름 단위로 읽을 수 있게 묶어줘
- 사용자 요청/데이터/상태 변화의 주요 흐름을 플로우차트로 보여줘
- 각 흐름에서 어떤 레이어가 어느 지점에 개입되는지 표시해줘
- 레이어 간 의존성과 위험한 결합을 표시해줘
- 스펙에서 모호하거나 빠진 가정을 따로 모아줘
- 구현 전에 먼저 검토해야 할 체크리스트를 만들어줘
- 문제가 될 수 있는 확장성/운영/보안/테스트 포인트를 severity별로 표시해줘
 
외부 라이브러리 없이 self-contained HTML/CSS/JS로 작성해줘.

PR 리뷰라면 조금 다르게 요청할 수 있다.

이 PR을 검토하기 위한 단일 HTML 파일을 만들어줘.
목적은 예쁘게 꾸미는 것이 아니라, 리뷰어가 변경의 구조와 위험 지점을 빠르게 파악하는 것이다.
 
포함할 것:
- 이 PR이 전체 코드베이스의 어느 영역을 건드렸는지 지도처럼 보여줘
- 변경 전/후 주요 플로우차트를 그려줘
- 영향받는 레이어를 UI / API / DB / Infra / Test 등으로 나눠 표시해줘
- 위험 지점은 severity별로 색을 구분해줘
- 각 리스크는 근거가 되는 파일명과 함수명을 같이 표시해줘
- 리뷰어가 먼저 봐야 할 체크리스트를 만들어줘
- 아직 확인되지 않은 가정과 질문을 따로 모아줘
 
외부 라이브러리 없이 self-contained HTML/CSS/JS로 작성해줘.

결국 중요한 것은 사람이 통과시킬 수 있는 형태인가

AI가 더 많은 결과물을 만들수록, 사람에게 필요한 능력도 조금 바뀐다. 전에는 내가 직접 만드는 능력이 중요했다면, 이제는 AI가 만든 것을 이해하고, 검토하고, 통과시키거나 되돌리는 능력이 더 중요해진다.

그 과정에서 출력 형식은 사소한 문제가 아니다. 같은 내용을 받아도 내가 검토할 수 없는 형태라면 결국 다시 읽고, 다시 묻고, 다시 정리해야 한다. 반대로 처음부터 검토 가능한 형태로 받으면 사람은 더 빨리 판단할 수 있다.

스펙 문서가 한눈에 들어오지 않을 때, 나는 이제 “설명해줘”보다 “검토할 수 있게 그려줘”라고 먼저 말하게 될 것 같다.

AI에게 더 많은 답을 받는 것보다 중요한 것은, 내가 더 잘 판단할 수 있는 형태로 되돌려받는 것이다.