문서는 쓸모없고, 낡았다.

정확히는, 지금의 서비스를 설명하지 못하는 문서가 그렇다.

처음부터 틀린 문서는 아니었을 것이다. 만들어질 당시에는 서비스의 구조와 흐름을 제대로 담고 있었을지도 모른다. 그러다 새로운 기능이 추가되고, 책임이 분리되고, 다른 시스템과의 연결이 늘어나는 동안 문서는 작성된 순간에 그대로 머물렀다.

서비스는 가만히 있지 않는다. 운영 과정에서 발견한 문제를 고치고 새로운 요구사항을 받아들이며 계속 개선되고 확장된다.

문서는 그렇지 않다. 코드와 설정은 서비스가 동작하려면 함께 바뀌어야 하지만, 문서는 고치지 않아도 빌드가 깨지지 않고 배포도 막히지 않는다. 그렇게 서비스가 앞으로 나아가는 동안 문서는 현실에서 조금씩 멀어진다.

살아 움직이는 서비스를 설명하려면 문서도 함께 움직여야 한다. 서비스가 바뀌면 문서도 바뀌고, 구조가 달라지면 다이어그램도 다시 그려야 한다. 필요할 때 현재의 모습을 확인할 수 있어야 문서는 쓸모를 유지한다.

문제는 서비스와 문서를 계속 동기화하는 비용이다.

나는 이 비용을 AI로 낮출 수 있는지 확인하기 위해 flowcast를 만들고 있다.

새 서비스를 맡을 때마다 같은 자리에서 시작했다

새 서비스를 맡을 때마다 이 문제를 반복해서 만났다. 담당이 정해지고 저장소를 열면 실행 방법은 적혀 있지만, 정작 서비스를 이해할 수 있는 문서는 없었다. 위키에 그림이 남아 있어도 지금 구조와 맞는지 아무도 장담하지 못했다.

문서가 없어도 코드 레벨은 어떻게든 따라갈 수 있다. 클래스와 호출 관계를 좇다 보면, 시간이 걸릴 뿐 서비스가 무슨 일을 하는지는 어느 정도 드러난다. “문서가 없으면 코드가 문서”라는 말이 아주 틀린 건 아니다. 적어도 코드 레벨에서는 그렇다.

문제는 서비스 경계 바깥의 흐름이다. 요청이 어느 존에서 시작해 어떤 게이트웨이와 큐를 거쳐 다른 서비스로 넘어가는지는 코드 한 곳을 읽는다고 나오지 않는다. 설정 파일과 방화벽 규칙, 배포 스크립트, 그리고 “그건 옆 팀에 물어봐야 한다”는 사람의 기억에 흩어져 있다.

게다가 이 흐름에는 여러 사람이 얽혀 있다. 개발자뿐 아니라 인프라 담당자, 다른 서비스 담당자, 그리고 “이 결제가 어디를 거쳐 나가느냐”를 묻는 업무 담당자도 같은 구조를 이해해야 한다. 그래서 모두가 함께 볼 수 있는 그림 한 장이 절실한데, 정작 그 그림을 믿기 어렵다.

문서를 만드는 순간보다 그다음이 어렵다

그림이 없으면 새로 만들면 된다고 생각했다. 다이어그램을 하나 그려 위키에 올리고 나면 거기서 끝이 아니다. 유지보수가 시작된다.

서비스 경계를 리팩터링하거나 큐를 추가하거나 내부 API 이름을 바꾸면 코드는 달라지지만 위키 속 그림은 그대로 남는다. 누가 일부러 방치해서가 아니다. 그림을 고치는 일은 늘 더 급한 일에 밀린다.

수작업 다이어그램의 진짜 비용은 처음 그릴 때보다 두 번째 수정에서 드러난다. 한 장을 그리는 일은 할 만하다. 구조나 스타일이 바뀌어 여러 장을 다시 손봐야 하면 그때부터 관련된 그림을 하나씩 찾아 같은 작업을 반복하게 된다. 낡은 그림은 이 비용 구조가 만든 결과다.

여기서 생각이 하나 바뀌었다.

다이어그램은 독립된 산출물이 아니라 추적 가능한 근거의 파생물이어야 한다.

근거가 되는 코드나 설정, 원문 없이 떠 있는 그림은 나중에 고치려고 해도 무엇을 기준으로 확인해야 할지 알 수 없다. 확인할 수 없으니 고치기 어렵고, 고치기 어려우니 낡는다. 예쁜 그림 한 장보다 출처를 되짚을 수 있는 그림이 더 중요한 이유다.

그런데 출처를 연결한다고 문제가 끝나는 것은 아니다. 서비스가 바뀔 때마다 사람이 다시 자료를 읽고 그림을 고쳐야 한다면 동기화 비용은 여전히 사람의 몫이다.

사람만으로는 변화의 속도를 따라가기 어렵다

문서화가 중요하다는 데 반대하는 사람은 없다. 회고 때마다 나오는 말이고, 다음 일정이 시작되면 먼저 밀리는 항목일 뿐이다.

나도 한동안 개인 시간을 내서 이 간격을 메우려고 했다. 담당 서비스의 흐름을 그려보고, 다른 팀에 물어 빈칸을 채우고, 여러 그림의 스타일을 맞췄다. 그렇게 다 그리고 나면 서비스는 다시 달라져 있었다. 살아 움직이는 서비스를 정지된 그림으로 계속 따라가는 방식에는 한계가 있었다.

그래서 질문을 바꿔보기로 했다.

사람이 문서를 더 열심히 관리하는 대신, AI를 잘 활용해 동기화 비용을 낮출 수는 없을까?

그림이 항상 답인 것은 아니다

여기서 왜 하필 그림인지도 짚어볼 필요가 있다.

그림이 글보다 기억에 잘 남는다는 것은 인지심리학에서 오래 다뤄진 주제다. dual coding theory는 시각 정보와 언어 정보가 분리되면서도 연결된 체계로 처리된다고 본다. Shepard의 1967년 실험에서는 수백 장의 그림을 다시 봤을 때 알아보는 재인 정확도가 90%대 후반에 이르렀다.

그렇다고 이 결과를 “다이어그램이 복잡한 구조를 더 잘 이해하게 한다”는 주장으로 곧장 옮길 수는 없다. 소프트웨어 아키텍처를 직접 대상으로 한 Heijstek 등의 통제 실험에서는 그래픽과 텍스트 중 어느 쪽도 유의하게 더 효율적이지 않았다. 오히려 텍스트 위주로 본 참가자들이 토폴로지 관련 문항에서 더 높은 점수를 받았다.

그림이 언제나 글보다 나은 것은 아니다. 중요한 것은 표현 수단의 서열이 아니라 정보의 성격에 맞는 표현을 선택하는 일이다. 서비스 사이의 경계와 경로처럼 공간적이고 구조적인 정보는 글만으로 전달하면 독자가 머릿속에서 다시 조립해야 한다. 반대로 잘못 그린 그림은 그럴듯한 오해를 더 빠르게 퍼뜨린다.

그래서 목표는 그림을 많이 만드는 것이 아니다. 근거를 되짚을 수 있고, 변경되면 적은 비용으로 다시 만들 수 있는 그림을 만드는 것이다.

기존 접근에서 한 걸음 더 가보기

다이어그램을 서비스 변화와 함께 관리하려는 접근은 이미 있다. 그중 하나가 diagrams-as-code다. 그림을 텍스트로 코드 옆에 두고 버전 관리하며 필요할 때 다시 렌더하는 방식이다. C4 model, PlantUML, Mermaid 같은 모델과 도구가 이 계보에 있다.

그림을 PR에서 diff로 확인하고 코드 변경과 함께 갱신한다는 점에서 유지보수 문제에 잘 맞는다. 하지만 내 문제의 절반은 남는다. 그 텍스트를 누군가는 여전히 손으로 써야 하고, 그러려면 그전에 시스템을 이미 이해하고 있어야 한다.

diagrams-as-code가 그림을 관리하는 비용을 낮춘다면, 그보다 앞선 저작 과정에도 AI를 활용해볼 수 있지 않을까. 사람이 코드와 설정, 기존 문서를 매번 처음부터 읽고 흐름을 옮기는 대신 AI가 먼저 자료를 읽어 초안을 만들게 하는 것이다. 사람의 역할은 빈 화면에서 작성하는 쪽에서, AI가 만든 결과의 근거를 확인하고 잘못된 부분을 바로잡는 쪽으로 옮겨간다.

이 접근이 동기화를 자동으로 해결해주지는 않는다. 다만 문서를 다시 만드는 비용을 낮춘다면, 서비스가 바뀔 때 문서를 갱신하는 일을 지금보다 더 자주 시도할 수 있다.

이 접근을 확인하기 위해 flowcast를 만들고 있다

이 가능성을 확인해보기 위해 만들고 있는 것이 flowcast다.

현재 flowcast에서는 확정된 흐름 문서와 명세, 설명, PPT 같은 입력 자료를 다이어그램 단위로 나눈다. 그리고 검토와 수정, 재생성까지 잇는 구조를 시험하고 있다. 에이전트가 자료에서 관계를 추출해 중간 표현을 만들고 다이어그램으로 렌더하는 방식이다. 각 다이어그램에는 근거가 된 원문의 경로를 남겨 검토할 때 출처를 되짚을 수 있게 하려 한다.

필요한 관점부터 스킬로 만들고 있다

flowcast를 처음부터 프로젝트 시각화 도구로 설계한 것은 아니다. 출발점은 내가 실제 프로젝트를 이해하고 설명하는 데 필요했던 그림이었다.

필요한 그림이 하나 생길 때마다 그 관점을 다루는 방법을 별도의 스킬로 만들었다. 지금의 flowcast는 입력을 다이어그램 단위로 나누고, 무엇을 보여줘야 하는지에 따라 이 스킬들을 선택해 연결한다. 하나의 자료에서 여러 그림이 필요하면 각각의 스킬이 맡을 단위로 나눠 동시에 처리한다.

만들면서 프로젝트를 시각화한다는 의미도 조금씩 넓어졌다. 여기서 프로젝트는 일정이나 Issue, WBS 같은 관리 현황을 뜻하지 않는다. 내가 보고 싶은 것은 코드와 설정, 컴포넌트와 인프라, 요청과 데이터가 함께 움직이는 소프트웨어 프로젝트 자체다.

하나의 프로젝트도 질문에 따라 필요한 그림이 달라진다.

지금 있는 것은 이 셋뿐이다. 소스 구조나 의존성, 데이터 흐름처럼 더 다뤄야 할 관점이 남아 있지만 아직 이름만 붙여둔 단계라 약속처럼 늘어놓지는 않겠다.

위에서 본 시퀀스가 서비스의 동작을 시간순으로 본 것이라면, 실행 환경(topology)과 구성(component)은 다른 질문에 답하는 관점이다. 세 예시는 같은 시스템이 아니라 관점마다 다른 합성 예제이고, flowcast로 그리면 각각 아래처럼 보인다.

세 관점을 직접 움직여 가며 보고 싶다면 flowcast 예제 갤러리에 인터랙티브 버전이 있다.

앞으로도 모든 정보를 한 장에 욱여넣는 거대한 스킬을 만들 생각은 없다. 프로젝트를 이해하면서 생기는 질문마다 적합한 관점을 작은 스킬로 만들고, flowcast가 필요한 관점을 선택하고 조합하게 하는 방향을 생각하고 있다.

아직 스킬로 만들지 않았지만 가장 확인해보고 싶은 관점은 변화다. 코드나 설정이 바뀌었을 때 영향을 받는 흐름과 다이어그램을 찾아내 다시 생성하고, 사람이 변경 내용과 근거를 검토한다. 이것이 된다면 서비스와 문서 사이의 간격을 지금보다 적은 비용으로 줄일 수 있다. 낡은 문서라는 처음의 문제로 그대로 돌아오는 셈이다.

결국 만들고 싶은 것은 그림을 그리는 스킬 하나가 아니다. 소프트웨어 프로젝트를 여러 관점에서 읽고, 프로젝트가 변하면 그 관점도 다시 갱신할 수 있는 시각화 스킬의 집합이다.

물론 AI가 그린 그림을 그대로 믿을 수는 없다. 입력 문서가 이미 낡았을 수도 있고, 코드만으로 드러나지 않는 운영 정보도 있으며, AI가 관계를 잘못 추론할 수도 있다. 사람의 검토와 판단은 여전히 필요하다.

그래서 flowcast는 낡은 문서 문제의 해결책이라고 말할 수 없다. AI를 잘 활용하면 더 적은 비용으로 서비스와 문서 사이의 간격을 줄일 수 있는지, 그 접근이 실제로 쓸 만한지 확인해보려고 만들고 있는 도구다.

각 스킬이 어떤 자료를 읽고, 어떻게 관점을 나누고, 어떤 방식으로 근거를 확인하는지는 다음 편들의 몫으로 남겨둔다. 이번 글에서 세워두고 싶은 출발점은 하나다.

서비스가 살아 움직인다면 문서도 함께 움직여야 한다. 나는 AI가 그 동기화 비용을 얼마나 낮출 수 있는지 확인해보려 한다.