문서의 홍수에서 벗어나기: 스마트한 문서 파이프라인 구축하기

15개의 Notion 페이지, 8개의 Markdown 파일, 잊고 있었던 Google Doc 폴더, 그리고 분명히 "어딘가에 기록되어 있다"는 결정 사항들로 가득 찬 3개의 Slack 채널이 있을 때의 그 기분을 아시나요? 네, 맞습니다.

저는 지난 한 달 동안 Claude API와 몇 가지 기본적인 도구를 사용하여 팀을 위한 간단한 문서 파이프라인 (document pipeline)을 구축했고, 이것이 우리의 작업 방식(ship)을 묘하게 변화시켰습니다. 그래서 실제로 효과가 있었던 방법들을 공유하고자 합니다.

아무도 입 밖으로 내고 싶어 하지 않는 문제

문서화 (Documentation) 자체가 문제는 아닙니다. 문제는 그것을 찾는 것과 최신 상태로 유지하는 것입니다. 누군가가 그 아름다운 아키텍처 문서 (architecture doc)를 작성했을 때쯤이면, 코드는 이미 세 번이나 바뀌어 있습니다. 여러분의 설계 결정 사항들은 오래된 Slack 스레드 속에 살아 있습니다. API 변경 사항은 아무도 읽지 않는 PR (Pull Request) 속에 파묻힙니다.

우리는 맥락 (context)을 찾기 위해 파헤치는 과정에서 속도 (velocity)를 잃고 있었습니다.

제가 실제로 구축한 것

생각보다 간단합니다:

1. 단일 진실 공급원 (One source of truth) — 모든 것이 하나의 폴더에 모입니다 (저희는 GitHub + Markdown을 사용하지만, Notion도 가능합니다).
2. AI 기반 검색 (AI-powered search) — Claude가 문서를 인덱싱 (index)하고 질문에 답합니다.
3. 자동 생성 요약 (Auto-generated summaries) — 수동 작업 없이 핵심 문서를 최신 상태로 유지합니다.
4. 스마트 링크 (Smart linking) — AI가 여러분이 존재조차 잊었을지도 모르는 관련 문서 간의 연결 고리를 제안합니다.

거창한 인프라 (infrastructure)도, ML (Machine Learning) 학습도 필요 없습니다. 그저 스마트한 API가 스마트한 일을 수행할 뿐입니다.

실제 작동 방식

새로운 개발자를 온보딩 (onboarding)한다고 가정해 봅시다. 예전 방식은 제가 이론적으로 어딘가에 적혀 있을 내용들을 45분 동안 설명하는 것이었습니다.

새로운 방식은 이렇습니다: 그들이 우리의 문서 봇 (doc bot)에게 "큐 (queue)에서 비동기 작업 (async tasks)을 어떻게 처리하나요?"라고 묻습니다. Claude는 우리의 문서 폴더를 검색하여 관련 파일 3개를 찾아내고, 맥락을 결합하여 실제로 이해가 되는 2분짜리 답변을 제공합니다.

아키텍처 결정 사항도 마찬가지입니다. GitHub 이슈 (issues)를 뒤지는 대신 이렇게 물어보세요: "세션 저장소로 Postgres 대신 DynamoDB를 선택한 이유가 무엇인가요?" 그러면 AI는 ADR (Architecture Decision Record, 결정 기록), 관련 PR, 그리고 우리가 수용했던 트레이드오프 (trade-offs)를 찾아냅니다.

실제 구현

제가 실제로 운영하고 있는 것은 다음과 같습니다:

import os
import json
from pathlib import Path
...

매우 단순합니다. 벡터 데이터베이스 (vector databases)도, 화려한 임베딩 (embeddings)도 (아직은) 사용하지 않습니다. 그저 Claude가 실제 문서를 읽고 질문에 답할 뿐입니다.

전통적인 문서 방식이 통하지 않을 때 이 방식이 작동하는 이유

솔직히 말해서, 개발자들은 문서를 읽지 않습니다. 우리는 특정 문제에 대한 해답을 읽습니다. 이 방식은 그 관점을 뒤집습니다. 완벽한 문서를 유지하는 대신 (그것은 불가능합니다), 검색 가능한 문서를 유지합니다. AI가 점들을 연결하는 작업을 수행합니다.

여러분의 문서는 더 거칠고, 대화체이며, 덜 다듬어져 있어도 됩니다. 왜냐하면 이제 문서는 인간이 선형적으로 읽기 위한 것이 아니라, AI가 종합할 수 있는 지식 베이스 (knowledge base)이기 때문입니다.

우리는 온보딩 (onboarding) 시간을 2주에서 3일로 단축했습니다. 문서가 더 좋아졌기 때문이 아니라, 이제 정보를 실제로 찾아낼 수 있기 때문입니다.

실제로 중요한 것들

제가 다르게 시도해 볼 것들:

• 문서에 네임스페이스 (Namespace) 지정하기 (저희는 /architecture, /api, /runbooks, /decisions 와 같은 폴더를 사용합니다)
• ADR (Architecture Decision Records, 아키텍처 결정 기록)을 작고 최신 상태로 유지하기 — 이것들은 컨텍스트 (context) 측면에서 매우 가치가 높습니다
• 오래된 문서를 삭제하지 말고, 단순히 사용 중단 (deprecated) 상태로 표시하기 — AI는 전체 컨텍스트가 있을 때 더 잘 작동합니다
• 요약 작업을 매일이 아닌 매달 실행하기 (API 비용이 쌓입니다)

비용 현실:
이 시스템을 운영하는 데 Claude API 비용으로 월 약 40달러가 듭니다. 절약된 시간에 비하면 믿기지 않을 정도로 저렴합니다.

한 가지 주의사항:
Claude는 종합(synthesis)에는 능숙하지만 완벽하지는 않습니다. 중요한 정보는 항상 검증하십시오. 하지만 "이게 어떻게 작동하는지 다시 알려줘"와 같은 질문에는 완벽합니다.

다음 단계

저희는 곧 다음 기능들을 추가할 예정입니다:

• 코드 주석으로부터의 자동 문서 생성
• 문서가 실제 동작과 어긋날 때 발생하는 스마트 알림
• 사람들이 컨텍스트 스위칭 (context-switching) 없이 질문할 수 있는 Slack 봇

하지만 솔직히 말하면? 이 기본적인 설정만으로도 이미 문서화 문제의 80%를 해결하고 있습니다.

직접 시도해 보세요

필요한 것:

1. 한곳에 모아둔 문서 (거친 형태라도 괜찮습니다)
2. Anthropic API 키
3. 위의 스크립트를 적용할 30분의 시간

당신의 엉망진창인 문서 더미에 이를 던져 넣고 어떤 일이 일어나는지 확인해 보세요. 정보가 실제로 '찾기 쉬워질 (findable)' 때 얼마나 더 나아지는지 확인하면 아마 놀라게 될 것입니다.

미래의 당신(그리고 당신의 다음 채용 인력)이 당신에게 고마워할 것입니다.