typed JSON으로 기술 시스템 다이어그램을 만들고 HTML·SVG로 내보내는 문서 도구가 검증 완료를 표시했습니다. 화면은 반듯했고, 선은 서로 부딪히지 않았습니다. 저는 그때 그림보다 먼저 “무엇을 검증한 건가?”를 확인했습니다.
이번에 살펴본 것은 기술 문서용 다이어그램 도구입니다. 입력은 에이전트가 작성한 typed JSON IR이고, 출력은 SVG와 JavaScript를 포함한 하나의 HTML입니다. architecture, workflow, sequence, data flow, lifecycle처럼 시스템의 구조와 흐름을 그립니다. 일반 산문을 예쁘게 꾸미는 편집기와는 검사해야 할 대상부터 다릅니다.
README와 사용 설명서만 읽고 판단하지 않으려고 설치 없이 실행했습니다. doctor는 전체 항목을 통과했고, demo HTML은 715,216바이트로 생성됐습니다. architecture 예제에 showcase 검증을 걸었을 때도 9개 검사가 모두 통과했고 composition 오류와 경고는 0개였습니다. 이 결과가 말해 주는 것은 분명합니다. 필수 필드가 있고, 선이 겹치지 않고, 라벨이 도형 밖으로 튀어나오지 않는다는 뜻입니다.
검증의 범위를 시스템의 의미까지 넓히면 결론은 달라집니다. 이 도구가 확인하는 것은 입력 형식과 도형 배치입니다. source-evidence 기능도 고정한 공개 커밋에 특정 파일과 줄이 실제로 있는지를 확인할 뿐입니다. 그 파일을 읽고 그려 넣은 사람이 컴포넌트의 역할을 잘못 해석했는지, 화살표의 방향을 반대로 이해했는지, 승인 절차를 한 단계 빼먹었는지는 별도의 사실 검토가 필요합니다.
여기서 도구의 장점이 오히려 위험으로 뒤집힐 수 있습니다. 잘못 이해한 시스템 구조를 깔끔하게 배치한 그림은 엉성한 메모보다 더 설득력 있어 보입니다. 박스 간격이 일정하고 경계선이 정돈되어 있으면 독자는 내용까지 확인됐다고 느끼기 쉽습니다. 그림의 문법을 통과한 결과를 시스템의 진실을 보증한 결과로 읽기 때문입니다.
따라서 적합성은 기능 목록이 아니라 문서의 질문으로 판단해야 합니다. 신뢰 경계, 재시도 순서, 데이터 이동 경로처럼 한 장의 구조가 이해를 크게 돕는 문서라면 후보가 됩니다. 반대로 회의록, 조사 요약, 일반적인 위키 본문을 대체할 이유는 없습니다. 그런 글의 핵심은 도형 배치가 아니라 출처를 읽고 주장과 근거를 맞추는 일이기 때문입니다.
채택 여부를 정한다면 실제 기술 문서 2~3건으로 작은 시험을 해야 합니다. 같은 내용을 Mermaid로도 만들고, 사실 오류 수와 수동 수정 시간, 독자가 구조를 이해하는 정도, 문서에 삽입하는 비용을 비교해야 합니다. validator 통과 여부는 그 비교표의 한 칸으로 남겨 두는 편이 맞습니다.
결론은 조건부 채택입니다. 이 도구는 구조를 잘 그리는 검증형 산출기이지, 그 구조가 현실을 정확히 설명한다고 보증하는 판정기는 아닙니다. 완성된 그림을 보고 안심하는 순간, 검토자는 도형의 통과 여부와 화살표의 사실 여부를 다시 나눠 봐야 합니다.