아프니까 개발자다 아프니까 개발자다

잃어버린 Visio 파일 하나에서 시작된 프로젝트mermaid는 2014년 스웨덴 개발자 Knut Sveidqvist가 만든 오픈소스다. 계기는 단순하지만 상징적이었다 — 중요한 Visio 파일을 잃어버렸다. 바이너리 .vsdx는 diff가 안 되고, Git에 올려도 변경 이력을 추적할 수 없고, 노트북이 바뀌면 같이 사라진다. 아키텍처가 바뀔 때마다 누군가 GUI를 열어 박스를 다시 그려야 하는 구조였다.Sveidqvist의 통찰은 한 줄이다. "문서가 코드라면 다이어그램도 코드여야 한다." 첫 버전은 flowchart와 sequence 두 종류만 지원했고, 문법은 Markdown처럼 소문자 중심으로 설계했다. 이름은 당시 자녀들이 보던 『인어공주(The Little Mermaid)』에서 따왔다.202..

Javadoc에서 영감 받은 UML 도구PlantUML은 프랑스 개발자 Arnaud Roques가 2009년 4월 17일 SourceForge에 공개한 오픈소스 Java 컴포넌트다. 당시 그는 "Web Sequence Diagrams" 사이트를 보고 "Javadoc처럼 텍스트에서 다이어그램을 자동 생성하자"는 아이디어를 UML 전체로 확장했다.출발점 동기는 세 가지였다. 첫째, Rational Rose 같은 GUI 도구가 코드 변경을 못 따라가서 다이어그램이 낡아버리는 문제. 둘째, Microsoft Word 문서용 다이어그램 자동 생성 수요. 셋째, 위키·코드 주석에 UML을 직접 삽입해 애자일 문화에 녹이는 것. 결과적으로 PlantUML은 mermaid보다 5년 먼저 나온 "Diagram-as-Co..

"수동 유지 불가능" 앞에서 선택한 길함수 수백 개, 클래스 수십 개, 공개 API 전부에 수동으로 설명서를 붙이는 건 유지보수가 불가능하다. 6개월만 지나도 시그니처가 바뀌고 문서는 그대로 거짓말을 한다. 그래서 자동 생성 도구가 필요하다. Python 생태계에서 2008년에 등장해 지금도 사실상 표준인 도구가 바로 Sphinx다.Sphinx의 핵심은 한 문장으로 요약된다. "코드 안의 docstring을 읽어서 HTML 문서 사이트로 자동 변환한다". 함수 설명을 코드 옆에 한 번 쓰면, CI가 돌 때마다 자동으로 사이트가 갱신된다. 사람은 docstring만 쓰고, Sphinx가 나머지를 다 한다.Sphinx가 왜 나왔는가 — 해결하려던 3가지 문제Sphinx는 Georg Brandl이 Python..

코드 위키 시리즈, 실전으로 넘어가다지금까지 코드 위키의 구성 요소를 하나씩 다뤘다 — architecture.md, data-pipeline.md, ADR, 모듈 문서. 이론은 충분하다. 이번에는 실제 프로젝트에 코드 위키를 만들어 본 결과를 공유한다.대상 프로젝트는 개인 지식 금고(2,269개 마크다운 파일)를 벡터 DB로 인덱싱하고 검색하는 로컬 RAG 시스템이다. 12개 Python 모듈, 10개 운영 스크립트, 3가지 AI 모델이 협업하는 시스템에 7개 문서를 작성했다. 각 문서의 하이라이트를 보여주면서, 왜 그 내용이 중요한지를 설명한다.1. index.md — 네비게이션 허브코드 위키의 진입점이다. 실제 문서에서 발췌한 페이지 목록이다:## 페이지 목록- 시스템 아키텍처 (architectu..

코드 위키 시리즈를 마무리하며이 시리즈에서 지금까지 다룬 문서들이 있다:architecture.md — 레이어 구분, HLD, 데이터 모델, 외부 의존성, 설정 관리data-pipeline.md — 파이프라인 흐름도, 단계별 입출력, 캐시 전략ADR — 설계 결정의 맥락과 트레이드오프이 문서들이 프로젝트의 숲을 보여준다면, 이번에 다룰 모듈 문서는 나무를 보여준다. 개별 모듈이 무엇을 하고, 어떤 함수가 핵심이며, 어떤 패턴으로 외부 자원을 사용하는지를 정리하는 문서다.모듈 문서가 필요한 이유"코드를 읽으면 되지, 왜 따로 문서를 쓰나?"라는 반론이 있을 수 있다. 사실 대부분의 모듈은 코드와 docstring만으로 충분하다. 모듈 문서가 필요한 건 다음 조건에 해당하는 모듈이다:파이프라인의 진입점 — ..

코드는 "무엇"을 보여주지만, "왜"는 보여주지 않는다git blame을 하면 누가, 언제 이 코드를 작성했는지는 알 수 있다. 하지만 당시 어떤 대안이 있었고, 왜 이 방법을 택했는지는 알 수 없다. 커밋 메시지에 "PostgreSQL → SQLite로 변경"이라고 적혀 있어도, 왜 PostgreSQL을 버렸는지, 어떤 트레이드오프를 감수했는지는 사라진다.이 간극을 메우는 문서가 ADR(Architecture Decision Record)이다. "이 프로젝트에서 왜 이런 선택을 했는가"를 짧고 구조화된 형식으로 기록한다.ADR의 기원: Michael Nygard는 누구인가ADR이라는 형식을 처음 제안한 사람은 Michael T. Nygard다. 2011년에 쓴 블로그 글 "Documenting Arch..

아키텍처 문서만으로는 부족하다이전 글에서 아키텍처 문서(architecture.md)에 담아야 할 핵심 항목을 정리했다. 레이어 구분, HLD, 데이터 모델, 외부 의존성, 설정 관리 — 이 다섯 가지가 프로젝트의 정적인 구조를 보여준다.그런데 파이프라인 기반 프로젝트에서는 한 가지가 빠져있다. 데이터가 단계별로 어떻게 변환되며 흐르는가? 이건 HLD로는 표현하기 어렵다. HLD는 컴포넌트 간 의존 관계를 보여주지만, "A 모듈의 출력이 어떤 형태로 B 모듈에 전달되는지", "중간에 캐시가 언제 끼어드는지"는 알려주지 않는다.이 간극을 메우는 것이 데이터 파이프라인 문서(data-pipeline.md)다. 이 글에서는 실제 사이드 프로젝트의 파이프라인 문서를 바탕으로, 어떤 내용을 담아야 하는지를 정리한..

아키텍처 문서, 왜 다시 이야기하나아키텍처 문서는 오래된 주제다. 그런데 2025-2026년 들어 이 문서의 독자가 달라졌다. 사람만 읽는 게 아니라, AI 코딩 에이전트도 읽는다. 그런데 에이전트가 아키텍처 문서를 "알아서 찾아 읽는" 건 아니다. 실제로는 다음과 같은 3단계를 거친다.AI 에이전트가 프로젝트를 이해하는 과정1단계: 도구가 하드코딩된 지침 파일을 읽는다. 각 도구는 프로젝트 루트에서 자신만의 설정 파일을 자동으로 로딩한다. 이건 LLM의 학습이 아니라 도구 프레임워크의 동작이다.도구자동 로딩 파일Claude CodeCLAUDE.mdCursor.cursorrules, .cursor/rules/Cline.clinerules (파일 또는 디렉토리)2단계: 에이전트가 탐색을 시작한다. 사용자가..