비개발자 창업자(및 그의 LLM)와 프로젝트의 모든 Git 문서를 공유하는 방법: 400줄의 코드로 Notion 없이 구현하기

진행 중인 '파운더 스프린트(Sprint Fondateur)'에서 CEO는 비개발자 리더입니다. 그는 프로젝트를 이끌고, 제품 결정을 내리며, 로드맵을 채워나갑니다. 그리고 그는 매일 함께 작업하는 개인용 LLM(이 경우에는 Claude)을 보유하고 있습니다. 프로젝트 시작 2주 후, 제 질문은 이것이었습니다. 그의 프로젝트 메모리는 어디에 저장되어 있는가? 만약 그것이 Notion에 저장된다면, 저는 이미 그 결말을 알고 있습니다. 코드와 분리된 사일로(Silo)가 되어 조용히 표류하고, LLM(그의 것과 나의 것 모두)과 대화할 수 없게 될 것입니다.

저는 Notion을 거절했습니다. Notion이 나빠서가 아닙니다. 많은 팀에게 매우 훌륭한 도구입니다. 하지만 이 특정한 맥락에서는 프로젝트 문서가 기술적 ADR(Architecture Decision Records), 데이터 모델, 회의록과 동일한 위치에 있어야 합니다. 즉, git 리포지토리(repo) 안에 있어야 합니다. 문제는 비개발자 창업자는 GitHub 계정도 없고, Git CLI도 없으며, 배우고 싶어 하지도 않는다는 점입니다. 또한 그의 Claude 세션은 기본적으로 이 메모리를 어디에서 가져와야 하는지 알지 못합니다.

그래서 저는 이 문제를 해결하는 작은 시스템을 두 시간 만에 작성했습니다. 첫 번째는 커스텀 스킬(skill custom)을 통해 어떤 LLM이든 다룰 수 있도록 리포지토리의 모든 문서를 zip 파일로 제공하는 HTTP 엔드포인트입니다. 그리고 두 번째 스킬은 창업자가 GitHub를 전혀 열지 않고도 GitHub PR(Pull Request)을 통해 수정을 제안할 수 있게 해줍니다. 이 글에서는 이 패턴과 제가 내린 기술적 결정, 그리고 제가 감수하는 한계점들에 대해 설명합니다.

이전 기사의 후속편

저는 이미 Astro Starlight, OpenDesigner 및 docs.client.com 서브도메인을 통해 클라이언트에게 웹 읽기용으로 동일한 문서를 게시하는 방법을 설명했습니다. 해당 흐름은 '열람'을 다룹니다. 여기서 설명하는 것은 LLM 채널을 다룹니다. 즉, 창업자의 AI 메모리에 직접 정보를 공급하고 문서를 편집 가능하게 만드는 방법입니다. 두 흐름은 공존하며 서로 다른 두 가지 용도로 사용됩니다.

(이 프로젝트에서) 제가 Notion을 거절한 이유

맥락을 먼저 짚고 넘어갈 필요가 있습니다. Sprint Fondateur 팀은 아주 작습니다. 비개발자 창업자 한 명, 기술 담당인 저, 그리고 가끔씩 지원해 주는 친구 컨설턴트 두 명(아키텍트, CDP IT)이 전부입니다. 프로젝트 문서에는 제품 결정 사항, 기술 ADR (Architecture Decision Records), 데이터 모델, 전략 회의 회의록, 디스커버리 (discovery) 노트, 로드맵 등이 포함되어 있습니다. 규모가 더 큰 회사라면 Notion이나 Confluence에 담겨 있었을 모든 자료들입니다.

이러한 구체적인 상황에서 Notion은 다섯 가지 문제를 야기합니다:

코드와 분리된 사일로 (Silo). 기술적 결정이 변경되는 즉시 Notion 페이지는 뒤처지게 됩니다. 커밋 (commit)이 상황을 바꿀 때 아무도 Notion을 업데이트할 생각을 하지 않습니다. 개발 흐름 (flow) 안에 있지 않기 때문입니다.
멤버당 계정 필요. 친구인 아키텍트나 새로운 임시 협력업체를 온보딩 (onboard)할 때 즉각적인 마찰이 발생합니다.
월간 구독료. 3~4명 규모의 팀에게는 반복적인 비용입니다. 절대적인 금액은 미미할지라도, 다른 용도로는 쓰이지 않는 비용입니다.
벤더 종속 (Vendor lock-in). 프로젝트를 매각하거나 팀을 이전해야 할 때, 데이터를 내보내고(export), 형식을 재조정하고(reformat), 마이그레이션(migrate)해야 합니다.
네이티브 LLM 통합 부재. 리포지토리 (repo)에서 코딩하는 저의 Claude Code도, 창업자의 개인용 Claude도 특수한 파이프라인 (plumbing) 없이는 Notion을 읽을 수 없습니다. 이는 에이전틱 흐름 (agentic flow) 밖에 격리된 워크스페이스 (workspace)라는 뜻입니다.

하지만 "모든 것을 git 리포지토리에 넣는다"는 대안은 창업자를 배제하게 됩니다. 그는 git clone도, gh pr create도 할 줄 모르며, 배울 의지도 없습니다. 그리고 배울 의지가 없는 것은 당연합니다. 그의 업무는 Git이 아니기 때문입니다. 그의 업무는 결정을 내리고, 프로젝트의 모든 것을 알고 있는 LLM (Large Language Model)과 그 결정을 대조하는 것입니다.

따라서 해결해야 할 진짜 문제는 인간적인 의미의 "문서를 어떻게 공유할 것인가"가 아닙니다. 그것은 바로 창업자의 LLM에 제 Claude Code 세션을 구동하는 것과 정확히 동일한 메모리 (memory)를 공급하고, 그가 그 메모리에 기여할 수 있는 수단을 제공하는 것입니다.

해결책, URL 하나로

저는 프로젝트 API에 엔드포인트 (endpoint)를 노출했습니다:

GET /_internal/memory/{uuid}

해당 {uuid}는 정적 UUID v4이며, Signal을 통해 창업자에게 단 한 번 공유됩니다. 이 엔드포인트는 다음을 포함하는 ZIP 파일을 반환합니다:

레포지토리(repo)의 모든 문서 (docs/**/*.md)
자동 생성된 llms.txt (2024년 말 Jeremy Howard / Answer.AI가 만든 오픈 표준으로, 이미 Anthropic, Vercel, FastAPI, Tailwind에서 채택함)
Claude 측에서의 설치 방법을 설명하는 README.md
두 개의 커스텀 Claude 스킬 (custom skills): memory-update 및 memory-pr
스킬에 즉석에서 주입되는 GitHub Fine-grained PAT (Personal Access Token)

운영 흐름(operational flow)은 다음과 같습니다:

Claude (창업자 측)
        │
        │  /memory-update
...

창업자 측의 설정은 5분이면 충분합니다. 처음 한 번 URL을 Claude에 붙여넣고 /memory-update를 실행하면 끝납니다. 이후 자신의 메모리를 업데이트(새로운 결정 사항, 새로운 ADR 등)하려면 원할 때마다 /memory-update를 다시 실행하면 됩니다. 수정을 제안하려면 변경하고 싶은 내용을 자연어(natural language)로 설명하기만 하면 되며, /memory-pr 스킬이 대신 Git 작업을 수행합니다.

개발자 측(나, 나의 Claude Code 세션)에서는 아무것도 변하지 않습니다. 이전과 마찬가지로 레포지토리에 직접 접근합니다. 이것은 마이그레이션(migration)이 아니라 동일한 레포지토리 위에 구축된 서비스 계층(service layer)입니다.

이 모든 것을 제공하는 Symfony 컨트롤러(controller)는 약 50줄 정도의 코드로 이루어져 있습니다. 로직은 다음과 같습니다: 환경 변수와 constant_time_equals를 사용하여 UUID 검증, 속도 제한 (rate-limiting), docs/ 읽기, llms.txt 즉석 생성, 전체 패키징, ZIP 스트리밍. curl 명령어 하나로 테스트가 가능합니다:

curl -o memory.zip https://api.projet.com/_internal/memory/<uuid>
# 200 + 약 130ms 만에 345 KB의 zip 파일 반환

...

Un accès scopé : UUID statique, PAT GitHub fine-grained et bundle verrouillé

논의할 가치가 있는 기술적 결정들

이 부분은 제가 내부적으로 더 많은 논의가 있을 것이라 예상했던 지점이었지만, 실제로는 단순성(simplicity)이라는 제약 조건 때문에 각 선택이 꽤 빠르게 결정되었습니다.

OAuth 대신 정적 UUID 사용. UUID v4는 122비트의 엔트로피(entropy)를 가집니다. 합리적인 시간 내에 무차별 대입 공격(bruteforce)으로 뚫는 것은 불가능합니다. 비밀 서명(secret signature)은 그 자체로 URL이며, Signal을 통해 비공개로 공유됩니다. 창업자를 위한 설정은 OAuth도, 계정도 필요 없이 오직 URL 하나면 끝납니다. 서버 측에서는 IP당 분당 10회로 속도 제한(rate-limit)을 걸고, 감사를 위해 모든 접속을 로그(log)로 남깁니다. 만약 내일이라도 이 방식이 너무 가볍다고 느껴진다면 GitHub App OAuth로 전환하겠지만, 지금 단계에서는 오버엔지니어링(over-engineering)이 될 것입니다.

zip 파일에 번들링된 GitHub fine-grained PAT. 단일 리포지토리(repo)에 대해 Contents: R/W + Pull requests: R/W 권한만 부여합니다. 만료 기간은 90일이며, Makefile을 통해 분기별로 교체(rotation)합니다. zip 파일이 유출될 경우 최악의 시나리오는 공격자가 단일 리포지토리에 PR(Pull Request)을 생성하는 것입니다. 하지만 이러한 PR은 인간의 검증 없이는 머지(merge)되지 않으며, 일괄적으로 닫거나 삭제하기 매우 쉽고, PAT는 두 번의 클릭만으로 취소할 수 있습니다. 프로덕션(prod)에 대한 위험도, 비밀 정보(secrets)에 대한 위험도 없습니다(PAT는 GitHub Actions 워크플로우나 리포지토리 비밀 정보를 읽을 수 없습니다). 이는 제한적이고 되돌릴 수 있는 위험입니다.

파일 화이트리스트(whitelist) 미사용. 만약 문서가 docs/ 디렉토리에 있다면 공유가 가능합니다. 간단한 규칙을 정했습니다: 비공개 문서는 docs/internal/에 넣거나 _private_로 시작합니다. 저는 파일별 허용 목록(allow-list) 방식을 선호하지 않습니다. 이는 지속적인 유지보수를 요구하며, 결국 항상 문서를 누락하게 되고, 누군가 새로운 유형의 문서를 처음 추가할 때 아무도 그것을 화이트리스트에 추가할 생각을 하지 않기 때문입니다. 디렉토리 컨벤션(convention)을 사용하는 것이 트리(tree) 구조에서 눈으로 확인하기에 훨씬 직관적입니다.

서버 측 기본 거부 (Default-deny côté serveur). 만약 환경 변수(env variable) MEMORY_SHARE_UUID 또는 MEMORY_SHARE_GITHUB_PAT가 설정되어 있지 않다면 (로컬 개발 및 CI 환경의 기본 케이스), 엔드포인트(endpoint)는 503 memory_share_not_configured를 응답합니다. 이를 통해 프리뷰 서브도메인(preview subdomain)으로 유출될 수 있는 개발 환경의 문서가 실수로 노출될 가능성을 완전히 차단합니다. 프로덕션(prod) 설정은 배포 파이프라인(deployment pipeline) 내에서 환경 변수를 통해 명시적으로만 이루어집니다.

보너스로 제공되는 llms.txt. 이 파일은 zip 파일 안에 포함되어 있으며, 공개 도메인의 루트(root)에서도 제공될 수 있습니다. 프로젝트의 마케팅 사이트가 출시되면, ChatGPT, Perplexity 및 기타 AI 크롤러(crawlers)들이 수동 작업 없이도 문서 요약본을 직접 읽을 수 있습니다. 이는 무료로 얻을 수 있는 이점입니다. llms.txt 형식은 개방적이고 생성하기 간단하며, Anthropic, Vercel, FastAPI, Tailwind는 이미 자신들의 공개 문서에서 이 형식을 노출하고 있습니다. Mintlify는 유료 플랜에서 이를 자동으로 생성해 주지만, 저는 PHP 30줄로 이를 생성합니다.

기대 효과 및 한계 — 솔직한 부분

이 글을 쓰는 시점에 V1 코딩은 완료되었습니다. PHP 테스트 스위트(test suite)를 통과했으며 (1026개 테스트 통과), 현재 프로젝트 기준 345 KB 페이로드(payload)에 대해 zip 생성에 약 130ms가 소요됩니다. 또한 제 개인 Claude 세션에서 두 가지 스킬(skills)을 수동으로 테스트했습니다. 하지만 아직 이 URL을 창업자에게 전달하지는 않았습니다. 따라서 아래에 나열할 이점들은 이미 리포지토리(repo)에서 이 문서를 직접 소비하고 있는 저의 Claude Code 세션에서 관찰한 내용을 바탕으로 한 **추론(extrapolations)**입니다.

기대하는 이점.

창업자가 자연어로 프로젝트의 기억을 질문할 수 있습니다. "5월 12일 회의 결정 사항을 알려줘" → 그러면 그의 LLM이 노트의 마크다운 (Markdown)을 읽고 요약합니다.
더 이상 Notion ↔ 코드 간의 동기화 불일치가 발생하지 않습니다. 문서는 코드를 변경하는 커밋 (Commit)과 함께 진화합니다. git log가 곧 히스토리입니다.
개발자가 아닌 새로운 협업자의 온보딩 (Onboarding) = Signal URL 하나면 끝납니다. 라이선스도, 계정 생성도, 개별 권한 관리도 필요 없습니다.
한계 비용이 제로에 가깝습니다. Git 저장소 (Repo)는 이미 존재합니다. PAT (Personal Access Token)는 무료입니다. llms.txt는 서버 측에서 30ms 만에 생성됩니다.
창업자의 LLM과 저의 LLM이 동일한 소스에 의해 공급됩니다. 이는 기획 회의에서 발생하는 "아, 저는 ~인 줄 알았는데요..."와 같은 유형의 오해를 획기적으로 줄여줄 것입니다.
네이티브 감사 추적 (Audit trail): 누가 어떤 변경을 제안했는지, 언제, 누구에 의해 승인되었는지 — 이것은 git log + GitHub PR 리뷰 (PR review)입니다. 그 어떤 Notion 히스토리보다 낫습니다.

감수하는 한계점들.

창업자가 마크다운 (Markdown)을 직접 작성하지 않습니다. 그는 LLM에게 구두로 말하고, LLM이 구조를 잡습니다. WYSIWYG 에디터보다는 덜 직접적입니다. 하지만 창업자가 이미 항상 Claude와 함께 작업하고 있기 때문에, 그에게 있어 노력의 비대칭성은 무시할 수 있는 수준이며 저는 이를 수용합니다.
정적 PAT (Personal Access Token)는 90일마다 수동 로테이션 (Rotation)을 강제합니다. 이를 위한 Makefile을 만들어 두었지만, 이는 자동화가 아닌 인간의 규율에 의존하는 부분입니다. 만약 제가 한 분기 동안 잊어버린다면 /memory-pr은 작동을 멈출 것이고, 창업자가 저에게 핑 (Ping)을 보낼 것이며, 저는 로테이션을 수행할 것입니다.
만약 창업자가 UUID URL을 분실하면, 개인적으로 다시 보내주어야 합니다. 셀프 서비스 복구 포털은 없습니다. 이는 의도된 설계로, 수동 인증 확인을 강제합니다.
감사 로그 (Audit log)는 기본적입니다 (액세스당 하나의 Mongo 문서). 대시보드는 없습니다. 나중에 볼륨이 커지면 반복 개선 (Iterate)할 문제입니다.
고려 중인 V2 버전이지만 우선순위는 낮습니다: 창업자가 LLM을 사용할 수 없는 상황을 위한 읽기 전용 웹 UI, 서버 측 검색 (Server-side search), 더 큰 팀을 위한 GitHub App OAuth 등이 있습니다. 현재 진행 중인 어떤 프로젝트에서도 이것들이 필요하지는 않습니다.

재현 가능한 패턴

« 서버 엔드포인트(endpoint) → 문서 zip + LLM 스킬(skills) + 범위가 제한된 PAT » 패턴은 HTTP 백엔드를 사용하는 어떤 스택에서도 약 1일의 개발 기간이면 재현 가능합니다. Symfony, FastAPI, Express, Rails 등 무엇이든 상관없습니다. 필요한 것은 다음과 같습니다:

서명된 URL(정적 UUID 또는 JWT 등)로 인증되는 엔드포인트(endpoint).
docs/ 디렉토리를 읽고, llms.txt를 생성하며, zip 파일을 패키징하는 함수.
짧은 만료 기간을 가진 GitHub fine-grained PAT(Personal Access Token)로, 번들(bundle)에 즉석에서 주입됩니다.
클라이언트 측의 두 가지 LLM 스킬(메모리 읽기 + PR 제안).

Notion이 오버헤드(overhead)가 되는 소규모 팀(개발자 1명 + 비개발자 1~5명)에 적합합니다. 문서별로 세밀한 권한 관리가 필요한 대규모 팀(20명 이상)에는 적합하지 않습니다. 그런 경우에는 셀프 호스팅(self-hosted)된 Outline이나 GitBook이 더 적절할 것입니다. 하지만 비개발자 창업자가 매일 프로젝트를 이끄는 초기 단계(early-stage) 스타트업 세그먼트에서는, 이것이 저의 기본 설정(default)이 되었습니다.