Docs-as-Code로 사이드 프로젝트 문서화하기 — 코드 위키 실전 적용기

사이드 프로젝트에 문서가 없으면 생기는 일

사이드 프로젝트를 몇 달 방치하다 다시 열면, 내가 짠 코드인데도 "이게 뭐였지?" 하게 된다. README에 설치 방법 세 줄 적어둔 게 전부라, 어디서부터 손대야 할지 감이 안 온다. 함수 이름으로 역할을 유추하고, git log로 당시의 의도를 추적하는 고고학이 시작된다.

이건 혼자 작업해도 마찬가지고, AI 코딩 에이전트를 쓸 때는 더 심각하다. Claude Code나 Cursor 같은 도구에 "이 프로젝트 구조 파악해줘"라고 하면, 코드를 전부 읽긴 하지만 왜 이런 설계를 했는지는 코드만으로 알 수 없다. 결국 매 세션마다 같은 설명을 반복하게 된다.

이 문제의 해법이 바로 코드 위키(Code Wiki)다. 코드와 함께 버전 관리되는, 살아있는 문서 체계.

코드 위키란: Confluence에서 Docs-as-Code로

전통적으로 개발 문서는 Confluence나 Notion 같은 외부 플랫폼에 작성했다. 문제는 코드와 문서가 분리되면서 싱크가 깨진다는 것이다. API가 바뀌어도 Confluence 문서는 옛날 버전 그대로고, 누가 업데이트해야 하는지도 불분명하다.

Docs-as-Code는 이 문제에 대한 답이다. 핵심 원칙:

• 문서를 마크다운으로 작성하고 코드와 같은 Git 저장소에 보관
• 코드 리뷰와 동일한 PR 리뷰 프로세스를 문서에도 적용
• CI에서 링크 검증, 맞춤법 체크 등 자동화 (docs site를 운영한다면 빌드·배포도 포함)
• 코드 변경 시 관련 문서도 함께 수정 — 같은 PR에 포함하여 문서 누락 방지

2025-2026년 기준으로 AWS, Azure, Google Cloud 모두 Docs-as-Code를 공식 권장하고 있고, Spotify의 Backstage TechDocs는 이미 5,000개 이상의 문서 사이트를 이 방식으로 운영 중이다.

다만, 같은 PR에 코드와 문서를 함께 넣는 것이 항상 정답은 아니다. AI가 코드 리뷰를 대신하는 시대에 사람이 집중해서 봐야 할 것은 오히려 문서 쪽인데, 코드와 문서가 한 PR에 섞여 있으면 리뷰어가 마크다운 파일을 찾아내야 하는 부담이 생긴다. 프로젝트 규모와 리뷰 문화에 따라 문서 전용 PR을 분리하는 것이 더 효율적일 수 있다.

2026년 코드 위키의 새로운 트렌드

1. ADR (Architecture Decision Records)

ADR은 "왜 이 기술/구조를 선택했는가"를 기록하는 문서다. Michael Nygard가 제안한 형식으로, 간결한 구조를 가진다:

# ADR-0001: 제목
## Status: Accepted
## Context: 어떤 상황이었나
## Decision: 무엇을 결정했나
## Consequences: 결과와 트레이드오프

코드는 "무엇(what)"을 보여주지만, "왜(why)"는 보여주지 않는다. 6개월 뒤에 git blame으로 누가 이 구조를 만들었는지는 알 수 있지만, 당시 어떤 대안을 검토했고 왜 이것을 택했는지는 알 수 없다. ADR이 이 간극을 메운다. 예를 들어 이런 식이다:

# ADR-0002: DB를 PostgreSQL 대신 SQLite로 선택
## Status: Accepted (2026-02-10)
## Context
사이드 프로젝트라 서버 한 대에서 돌린다. 사용자는 나 혼자.
PostgreSQL을 쓰면 별도 DB 서버를 관리해야 하고, 백업도 번거롭다.
## Decision
SQLite를 사용한다. DB 파일 하나로 관리.
## Consequences
- 설치/배포가 단순해짐 — DB 서버 운영 부담 제로
- 백업이 파일 복사 한 번으로 끝남
- 동시 쓰기가 많아지면 병목이 생길 수 있음
- 나중에 사용자가 늘면 PostgreSQL로 마이그레이션 필요

이처럼 ADR은 "무엇을 선택했는가"보다 "무엇을 포기했고 왜 그랬는가"를 기록하는 데 가치가 있다.

Azure는 2024년 10월부터 Well-Architected Framework에 ADR을 공식 포함했고, Google Cloud도 ADR 구현 가이드를 발행했다.

2. AI 에이전트 친화적 문서

2025년부터 급부상한 트렌드가 CLAUDE.md, AGENTS.md 같은 AI 에이전트용 지침 파일이다. AI 코딩 도구가 프로젝트에 진입할 때 가장 먼저 읽는 파일로, 프로젝트의 규칙·제약·워크플로우를 알려준다.

기존 README가 사람을 위한 온보딩 문서라면, CLAUDE.md는 AI 에이전트를 위한 온보딩 문서다. 둘은 보완적이지, 대체 관계가 아니다.

Anthropic의 2026 Agentic Coding Trends Report에 따르면 글로벌 개발자의 82%가 일상적으로 AI 코딩 도구를 사용하고 있어서, AI 친화적 문서는 선택이 아닌 필수가 되고 있다.

모든 Repo에 코드 위키가 필요할까?

결론부터 말하면, 아니다. 프로젝트 규모와 특성에 따라 차등 적용하는 게 맞다.

프로젝트 규모	권장 문서 수준	구체적으로
소형 (< 1,000 LOC)	README만	설치 방법, 사용법, 라이선스
중형 (1K-50K LOC)	README + 핵심 문서	+ 아키텍처 다이어그램, 주요 ADR 2-3개
대형 (50K+ LOC)	Docs-as-Code 풀셋	+ 모듈별 가이드, 파이프라인 문서, ADR 전체

핵심 판단 기준은 "3개월 뒤의 내가 이 코드를 열었을 때 30분 안에 작업을 시작할 수 있는가?"다. 100줄짜리 유틸리티 스크립트에 ADR을 쓸 필요는 없다. 하지만 여러 모듈이 파이프라인으로 연결된 프로젝트라면, 데이터가 어떤 경로로 흐르는지 문서 없이는 파악하기 어렵다.

실전 적용: 10,000줄 프로젝트에 코드 위키를 만들다

이론만으로는 감이 안 와서, 직접 만들어봤다. 대상은 약 10,000줄 규모의 사이드 프로젝트 — 가족 사진을 AI로 분석하여 포토북을 자동 생성하는 시스템이다. 15개 이상의 모듈이 파이프라인으로 연결되어 있고, Immich(사진 저장소), vLLM(LLM 추론), GPU 스케줄러 등 외부 시스템과 연동된다.

적용한 구조

docs/
├── README.md              # 위키 진입점 + 목차 + Quick Start
├── architecture.md        # 시스템 아키텍처 (Mermaid 다이어그램)
├── data-pipeline.md       # 데이터 흐름 (5단계)
├── modules/               # 핵심 모듈 설명 (6개)
│   ├── extractor.md
│   ├── grouper.md
│   ├── narrator.md
│   └── ...
├── adr/                   # Architecture Decision Records (5개)
│   ├── 0001-immich-as-photo-backend.md
│   ├── 0002-vllm-local-llm-for-narrative.md
│   └── ...
└── contributing.md        # 개발 가이드

총 15개 마크다운 파일. 프로젝트의 코드 라인 수 대비 약 1.5%의 문서량이다.

가장 가치가 높았던 문서 3가지

1. 아키텍처 다이어그램 (architecture.md)

Mermaid로 그린 시스템 구조도가 가장 유용했다. "이 프로젝트가 뭘 하는 건지"를 30초 만에 파악할 수 있게 해준다. GitHub이 마크다운 내 Mermaid를 네이티브로 렌더링해주므로, 별도 도구 없이 Git에 커밋하면 바로 보인다.

```mermaid
graph TB
    Immich --> Extractor --> Filter --> Grouper --> Narrator --> Renderer
```

2. 데이터 파이프라인 문서 (data-pipeline.md)

파이프라인 프로젝트에서는 데이터가 어떻게 변환되며 흐르는지가 핵심이다. 각 단계의 입력/출력과 캐시 전략을 정리하니, 디버깅할 때 "어디서 잘못됐을까"를 빠르게 좁힐 수 있게 되었다. 특히 캐시 파일 목록(photo_records.json, narrative_cache.json 등)과 각각의 생성 시점을 표로 정리한 것이 실용적이었다.

3. ADR (Architecture Decision Records)

처음 써봤는데, 생각보다 쓰는 데 시간이 오래 걸리지 않는다. ADR 하나당 10-15분이면 충분하다. 작성하면서 오히려 과거의 결정을 정리하는 과정에서 "이건 왜 이렇게 했더라?"라는 질문에 스스로 답하게 되어 프로젝트 이해도가 올라갔다.

예를 들어 "시간 기반 이벤트 클러스터링" ADR을 쓰면서, 위치 기반이나 ML 기반 접근을 왜 택하지 않았는지를 정리했다. 나중에 이 로직을 개선할 때 같은 대안을 다시 검토하는 삽질을 막을 수 있다.

모듈 문서는 어디까지?

15개 이상의 모듈 전부에 상세 문서를 쓰지는 않았다. 핵심 6개만 선별했다:

• 파이프라인의 진입점 (extractor)
• 핵심 로직이 복잡한 모듈 (grouper, narrator)
• 가장 큰 파일 (server — 2,000줄)
• 고유한 워크플로우가 있는 모듈 (travel-book, renderer-book)

나머지 모듈은 docstring과 타입 힌트만으로 충분했다. 모듈 문서는 목적, 주요 함수, 입출력, 설정값 정도만 정리하면 된다.

코드 위키 작성 시 핵심 팁

1. "무엇"이 아니라 "왜"를 적어라

코드가 이미 "무엇(what)"을 말해주고 있다. 문서에는 코드만으로 알 수 없는 것 — 설계 의도, 대안 분석, 트레이드오프 — 을 적어야 한다. 함수 시그니처를 복사해 붙이는 건 문서가 아니라 노이즈다.

2. 다이어그램을 먼저 그려라

아키텍처 문서를 글로만 쓰면 읽는 사람도 쓰는 사람도 괴롭다. Mermaid 다이어그램 하나가 2페이지 텍스트를 대체한다. GitHub, GitLab 모두 마크다운 내 Mermaid를 네이티브로 지원하므로 진입장벽도 낮다.

3. ADR은 거창하지 않아도 된다

ADR이라는 이름이 무겁게 들리지만, 실제로는 짧은 메모에 가깝다. Status, Context, Decision, Consequences 네 섹션만 채우면 된다. 한 건당 A4 반 페이지 정도. 모든 결정을 기록할 필요도 없다 — 한 달 뒤에 "왜 이랬지?"라고 물을 만한 것만 적으면 된다.

4. 유지보수 전략을 세워라

문서의 가장 큰 적은 낡은 문서다. 부정확한 문서는 문서가 없는 것보다 나쁘다. 몇 가지 방법:

• 코드 PR에 문서 변경도 포함하도록 습관화
• 각 문서에 마지막 업데이트 날짜 표시
• CI에서 깨진 링크 자동 검출 (markdown-link-check 등)
• 분기별로 문서 전체를 한번 훑는 "문서 감수" 습관

5. 과하게 쓰지 마라

문서도 코드처럼 유지보수 대상이다. 쓸수록 좋은 게 아니라, 유지할 수 있는 만큼만 쓰는 게 맞다. 10,000줄 프로젝트에 코드 위키가 20,000줄이면 그건 이미 실패한 문서화다. 프로젝트 LOC의 1-3% 정도가 적정한 문서량이라는 경험칙이 있다.

Anti-Pattern: 이것만은 피하자

• Confluence에만 문서를 보관 — 코드와 분리되면 결국 낡는다
• 코드 스타일을 문서에 기록 — 린터/포매터로 자동화해야지 문서로 강제하면 안 된다
• 자동 생성 가능한 API 문서를 수동 유지 — Sphinx, TypeDoc 같은 도구를 쓸 것
• 모든 함수에 대한 설명서 작성 — 유지보수 불가능, 타입 힌트와 docstring으로 대체
• 문서 리뷰 프로세스 부재 — 아무나 마음대로 수정하면 일관성이 무너진다

프로젝트 규모별 실전 가이드

정리하면 이런 단계별 접근을 추천한다:

단계	문서	소요 시간	적용 프로젝트
Level 0	README.md만	30분	모든 프로젝트
Level 1	+ 아키텍처 다이어그램	1시간	3개 이상 모듈
Level 2	+ ADR 2-3개	2시간	중요한 설계 결정이 있는 프로젝트
Level 3	+ 파이프라인 문서 + 핵심 모듈 가이드	반나절	5,000 LOC 이상
Level 4	+ 기여 가이드 + 전체 docs/ 구조	하루	팀 프로젝트 또는 10,000 LOC 이상

개인 사이드 프로젝트라면 Level 2까지면 충분하다. Level 3-4는 팀 프로젝트이거나, AI 에이전트가 자주 작업하는 프로젝트에 적합하다.

마무리: 문서는 미래의 나에게 보내는 편지

코드 위키는 거창한 시스템이 아니다. docs/ 디렉토리에 마크다운 파일 몇 개를 넣고, 코드와 함께 커밋하는 것이 전부다. 중요한 건 "시작하는 것"이지 "완벽하게 쓰는 것"이 아니다.

아키텍처 다이어그램 하나, ADR 두 개, 파이프라인 문서 하나. 이 정도면 3개월 뒤의 내가 — 또는 AI 코딩 에이전트가 — 이 프로젝트에 돌아왔을 때, 고고학 대신 코딩을 시작할 수 있다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.