편하니까 위키에 썼는데, 왜 안티패턴이라는 걸까요
GitHub 저장소를 만들면 'Wiki' 탭이 기본으로 보여요. 클릭 몇 번이면 페이지가 생기고, 마크다운으로 바로 쓸 수 있고, 별도 설정도 없어서 많은 팀이 '일단 여기 문서 쓰자'로 시작하죠. 그런데 개발자 마이클 힙(Michael Heap)이 'GitHub 위키는 안티패턴이다'라는 글을 통해 이 습관을 정면으로 비판했어요. 안티패턴이 뭐냐면, 언뜻 보기엔 합리적인 해결책 같은데 실제로 써보면 문제를 더 키우는 방식을 말해요. 처음엔 편한데 나중에 발목을 잡는 것들이죠.
이 글의 핵심 주장은 간단해요. 문서를 코드와 떨어뜨려 놓으면 문서는 반드시 썩는다는 거예요. 그리고 GitHub 위키는 구조적으로 문서를 코드와 떨어뜨려 놓게 설계되어 있다는 거고요. 왜 그런지 하나씩 풀어볼게요.
위키는 사실 별개의 저장소예요
많은 분이 모르는 사실인데, GitHub 위키는 내 저장소의 일부가 아니에요. 뒤에서는 내저장소.wiki.git이라는 완전히 별개의 Git 저장소로 관리돼요. 이게 왜 문제냐면, 코드와 문서가 서로 다른 히스토리를 가진다는 뜻이거든요.
예를 들어볼게요. API 응답 형식을 바꾸는 PR을 올렸어요. 코드 리뷰를 받고, 테스트를 통과하고, 머지했죠. 그런데 위키에 있는 API 문서는요? 그건 별도로 가서 따로 고쳐야 해요. PR 안에 포함시킬 수가 없으니까요. 그러면 어떻게 될까요? 바쁘면 까먹고, 까먹은 문서는 틀린 정보를 담은 채로 남아요. 몇 달 뒤 신입이 그 문서를 보고 코드를 짜다가 '문서랑 다르잖아요'라고 물어보는 상황이 생기는 거죠. 문서가 코드와 같은 PR 안에 있으면 리뷰어가 '문서도 고쳐야 하지 않나요?'라고 자연스럽게 물어볼 수 있어요. 위키에선 그 기회 자체가 없어요.
같은 이유로 브랜치나 버전 개념도 없어요. 우리 라이브러리 2.x 버전 문서와 3.x 버전 문서를 위키에서 관리하려면 페이지 이름에 수동으로 버전을 붙여야 해요. 코드 저장소에 문서가 있으면 그냥 태그를 체크아웃하면 그 시점의 문서가 나오는데 말이죠.
리뷰도, 자동화도, 포크도 안 돼요
위키는 PR(풀 리퀘스트) 흐름을 안 타요. 쓰기 권한이 있는 사람이 편집 버튼을 누르면 그대로 저장돼요. 코드는 한 줄 바꿔도 리뷰를 받는데, 문서는 아무나 아무 때나 고칠 수 있는 셈이죠. 공개 저장소에서 설정을 잘못 두면 GitHub 계정만 있으면 누구나 편집할 수 있는 상태가 되기도 해요.
CI, 그러니까 자동 검사도 못 돌려요. 저장소 안에 문서가 있으면 깨진 링크 검사, 맞춤법 검사, 문서 스타일 린트를 PR마다 자동으로 실행할 수 있어요. 위키는 그런 파이프라인 바깥에 있어요. 그리고 누군가 저장소를 포크하면 코드는 따라가지만 위키는 안 따라가요. 오픈소스 프로젝트라면 꽤 치명적이죠. 저장소를 클론해서 오프라인에서 보려 해도 위키는 따로 클론해야 하고요. GitHub의 코드 검색에도 위키 내용은 잘 걸리지 않아서, 뭔가 찾을 때 두 군데를 뒤져야 해요.
그럼 대안은 뭔가요: 문서를 코드처럼
이 글이 제안하는 방향은 흔히 docs as code라고 불러요. 문서를 코드와 똑같이 취급하자는 거예요. 구체적으로는 이렇게 해요.
먼저 저장소 안에 docs/ 폴더를 만들고 마크다운으로 문서를 써요. 간단한 프로젝트는 README 하나로 충분하고요. 설계 결정을 기록하는 ADR(Architecture Decision Record)도 이 폴더에 두면 '왜 이렇게 만들었지?'라는 질문에 대한 답이 코드 히스토리와 함께 남아요. 문서 변경은 코드 변경과 같은 PR에 넣어서 같이 리뷰받아요.
보기 좋은 사이트가 필요하면 MkDocs, Docusaurus, VitePress 같은 도구로 docs/ 폴더를 정적 사이트로 만들어서 GitHub Pages에 배포하면 돼요. 설정 파일 하나에 GitHub Actions 워크플로 하나면 PR이 머지될 때마다 문서 사이트가 자동으로 갱신돼요. 여기에 markdownlint나 링크 체커를 붙이면 문서 품질도 자동으로 지켜지고요.
물론 위키가 항상 나쁜 건 아니에요. 혼자 쓰는 개인 프로젝트에서 메모 남기듯 쓰거나, 코드와 무관한 회의록이나 온보딩 안내처럼 개발자가 아닌 사람들이 자주 편집하는 문서라면 위키의 낮은 진입장벽이 장점이 될 수 있어요. 핵심은 '코드가 바뀌면 같이 바뀌어야 하는 문서'는 반드시 코드 옆에 있어야 한다는 거예요.
한국 개발자에게 주는 시사점
국내 회사들은 GitHub 위키보다 노션이나 컨플루언스를 많이 쓰는데요, 사실 같은 문제를 더 심하게 겪고 있어요. 노션에 있는 API 명세와 실제 코드가 다른 경험, 다들 한 번쯤 있으시죠? 문서가 코드에서 멀어질수록 썩는 속도는 빨라져요. 기획 문서나 회의록은 노션에 두더라도, API 명세, 설정 가이드, 아키텍처 설명처럼 코드와 함께 움직여야 하는 문서는 저장소 안으로 옮기는 걸 진지하게 고민해볼 만해요.
그리고 요즘 특히 중요한 이유가 하나 더 생겼어요. AI 코딩 도구들이에요. Claude Code나 Cursor 같은 에이전트는 저장소 안의 파일을 읽어요. docs/ 폴더에 있는 설계 문서, README, CLAUDE.md나 AGENTS.md 같은 안내 파일은 에이전트가 참고해서 더 나은 코드를 만들어줘요. 그런데 위키나 노션에 있는 문서는 에이전트가 볼 수 없어요. 문서를 코드 옆에 두는 게 이제는 사람만을 위한 게 아니라 AI 동료를 위한 일이기도 한 거죠.
정리하면
한 줄로 정리하면, 코드와 함께 바뀌어야 하는 문서는 코드와 같은 저장소, 같은 PR, 같은 리뷰를 거쳐야 살아남는다는 거예요.
여러분 팀은 문서를 어디에 두고 계세요? 위키나 노션에서 저장소 안으로 문서를 옮겨본 경험이 있다면, 실제로 문서가 덜 썩던가요? 반대로 저장소 안 문서가 오히려 안 읽히더라는 경험도 궁금해요.
🔗 출처: Hacker News