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

22개 repo의 위키를 만들어 놓고 봤더니 한 가지가 마음에 안 들었다. "단촐하다." 내용이 풍부한 Rich 그룹 5개 repo만 8개 섹션 표준에 가까웠고, 거의 빈 Bare 그룹 4개 repo는 dependencies.md 한 페이지뿐이다. 같은 도구로 인덱싱했는데 격차가 너무 컸다. DeepWiki.com(Cognition)·Google CodeWiki는 한 repo당 평균 8개 섹션(Overview / Structure / Architecture / API / Subsystems / Operations / Testing / Glossary) + 페이지당 mermaid 3-5개를 floor로 두는데, 우리는 한참 부족했다.해결책은 단순해 보였다 — "자동 생성 페이지 종류를 늘리자." 그런데 어..

SQL을 한 번이라도 써 본 사람이라면 다음 같은 표현이 익숙할 것이다.SELECT name FROM users WHERE id = 42;표(table)에서 조건에 맞는 행을 골라 컬럼 값을 가져온다. 데이터가 표 형태로 정리돼 있을 때 가장 자연스러운 표현이다.그런데 데이터가 표가 아니라 관계의 그물일 때는 어떨까? 사람 A가 B와 친구이고 B는 C·D와 친구이고 D는 다시 A와 친구라면, "A에서 출발해 친구의 친구의 친구로 3홉 안에 도달 가능한 모든 사람"을 묻는 SQL은 의외로 어색하다. 같은 테이블을 자기 자신과 세 번 JOIN하고 중복을 걸러야 한다. 표라는 모양 자체가 관계의 자연스러운 표현이 아닌 자리가 분명히 있다.이런 자리를 위해 만들어진 게 그래프 쿼리 언어, 그 중 가장 널리 쓰이..

코드 위키 도구들이 다이어그램을 많이 쓴다는 얘기는 이전 글에서 했다. "얼마나 많이?"에 답해 본 적은 없었다. 그래서 직접 세 보았다.2026-05 기준 deepwiki.com/facebook/react 위키는 sub-page 34개로 구성되어 있고 그 안에 mermaid 다이어그램 115개가 들어가 있다(페이지당 평균 약 3.4개). expressjs/express 위키는 32 페이지에 221개(페이지당 평균 약 6.9개). DeepWiki는 SPA 방식이라 한 URL에 위키 전체 페이로드가 같이 실려 오는데, 그 페이로드를 그대로 grep해서 ```mermaid 블록을 센 결과다.한 위키 전체에 다이어그램 100~200개라는 게 처음엔 비현실적으로 들리지만, 큰 코드 베이스를 설명할 때 흔한 분량..

코드 위키 AI 도구들이 GitHub repo를 받아서 위키를 자동 생성할 때, 거의 공통으로 다음 8개 섹션을 만든다.Overview · Structure · Architecture · API · Subsystems · Operations · Testing · Glossary.처음 보면 그냥 목차처럼 보이지만, 사실 이 8섹션은 "코드를 처음 보는 사람이 어디서부터 봐야 하는가"라는 질문에 대한 누적된 답이다. 위키나 docs 폴더가 흔히 자유 형식인데, 이 셋업은 읽는 사람의 경로를 미리 설계해 둔 것이다. 그리고 이 구조는 사람뿐 아니라 AI 에이전트가 코드를 이해하는 데도 결정적인 도움이 된다. 이 글은 8섹션을 하나씩 풀어 — 무엇이고 왜 거기 있고 어떤 효과가 있는지 — 설명한다.왜 굳이 8개..

2024년 4월에 Cognition Labs(같은 회사의 AI 소프트웨어 엔지니어 Devin으로 유명한)가 deepwiki.com을 공개했다. GitHub repo URL 앞에 prefix만 붙이면 LLM이 자동 생성한 위키가 떠오르는 서비스이다. 곧 커뮤니티에서 deepwiki-open이 self-host 버전을 들고 등장했고, 2025년 11월에는 Google이 codewiki.google로 비슷한 영역에 들어왔다.세 도구는 첫인상이 거의 똑같다. "GitHub repo 던지면 LLM이 8섹션짜리 위키 만들어 줌"이라는 한 줄 컨셉. 그런데 막상 깊이 보면 누가 만들었고, 어디서 돌고, 어떤 LLM을 어떻게 쓰는지가 완전히 다르다. 이 글은 그 세 가지를 정직하게 비교하는 글이다 — 어느 게 "더 좋..