코드 에이전트를 위한 LLM Wiki — 1인 하네스의 외장 두뇌 만들기

코드 에이전트로 작업하는 시간이 늘수록 매 세션마다 같은 컨텍스트를 다시 설명하는 일이 부담이 됐다. 특히 하나의 서비스를 Agent, Core, Mobile 세 레포로 나눠 개발하다 보면 문제가 더 커진다. Agent에서 응답 포맷을 바꾸면 Core가 알아야 하고 Core의 API 계약이 바뀌면 Mobile도 따라와야 한다.

기존에도 옵시디언 볼트와 Apidog를 쓰고 있었다. 하지만 둘 다 정제된 산출물을 담는 도구에 가까웠다. 결정의 결과는 남지만 왜 그렇게 결정했는지와 어떤 대안을 버렸는지는 잘 남지 않았다.

그래서 별도 git 레포에 LLM Wiki를 만들었다. 카파시(Andrej Karpathy)가 2026년 4월에 공개한 llm-wiki 패턴에서 아이디어를 얻었지만 목적은 조금 다르다. 자료를 정리하는 위키가 아니라 코드 에이전트와 사람이 같이 읽는 개발 워크플로우용 외장 두뇌를 만드는 것이었다.

이 글은 1인 하네스 엔지니어링 시리즈의 첫 번째 글이다. 여기서는 코드 에이전트가 공유할 지식 저장소를 만든 이야기를 다룬다.

문제 상황 — 한 시스템, 세 레포, 세 에이전트

요즘 진행 중인 개인 챗봇 프로젝트는 세 개의 레포로 나뉘어 있다.

레포	역할	기술
Agent	AI 추론 (의도 분석, 응답 생성)	Python / Google ADK
Core	비즈니스 로직, API, 데이터	Kotlin / Spring WebFlux
Mobile	iOS/Android 클라이언트	Kotlin Multiplatform

세 레포 각각에서 코드 에이전트를 띄워 동시에 작업한다. Agent에서 새 응답 포맷을 만들면 Core가 그걸 알아야 한다. Mobile은 그걸 어떻게 그릴지 알아야 한다. API 하나가 추가되면 Core가 정의하고 Mobile이 호출한다.

이때 사용하는 쪽이 매번 다른 레포 소스를 직접 읽게 시키는 건 너무 비효율적이다. 토큰도 많이 먹는다. 컨텍스트가 노이즈로 채워진다.

세 에이전트가 같은 페이지에서 일하려면 어딘가에 “공유 컨텍스트”가 있어야 한다.

그 전에 쓰던 두 가지의 한계

이 문제를 풀기 위해 그 전에 쓰던 두 도구가 있었다.

옵시디언 개인 볼트

학습 노트, 회고, 정리된 지식을 모아두는 용도로 오래 써왔다. 코드 에이전트에게 컨텍스트를 줄 때 여기 있는 글을 참조하게 하기도 했다.

문제는 이 볼트가 “완성된 글”의 저장소라는 점이다. 정리가 어느 정도 끝난 후에 올리니까 결정에 도달하기까지의 과정과 대안 검토 그리고 실패한 접근이 빠져있다. 에이전트는 결과만 보고 “왜 이렇게 됐는지” 모른다.

Apidog

API 스펙을 팀과 공유하는 용도로 썼다. MCP 연동도 있어서 에이전트가 API 정의를 직접 읽을 수도 있었다. 그런데 매번 코드와 싱크를 맞추는 비용이 컸다. 등록하는 사람마다 형식이 달라서 일관성이 떨어졌다.

무엇보다 Apidog는 API만 다룬다. API가 왜 그렇게 설계됐는지 어떤 대안을 검토했는지 어떤 제약이 있었는지는 담을 곳이 없다.

두 도구 모두 “정제된 산출물”을 위한 도구다. “진행 중인 사고”를 담는 도구가 아니었다.

카파시의 llm-wiki

2026년 4월 카파시가 GitHub gist로 llm-wiki.md라는 idea file을 공개했다. 핵심 아이디어는 단순하다. 사람이 위키를 만들고 LLM이 그걸 참조하는 게 아니라 LLM이 위키를 만들고 유지하게 한다.

raw 자료(논문, 기사, 이미지)를 폴더에 던져두면 LLM이 읽고 정리해서 옵시디언 위키로 만든다. 카파시 본인은 한 글자도 직접 쓰지 않았는데 한 주제에 100개 글, 40만 단어가 쌓였다고 한다. RAG와 다른 점은 매 질문마다 재발견하는 게 아니라 사전에 합성된 지식을 누적한다는 점이다.

찾던 패턴과 거의 일치했다. 다만 내가 필요했던 것은 리서치 결과물이 아니라 작업 중인 결정의 누적이었다. 그래서 구조는 비슷하지만 운영 방식은 다르게 가져갔다.

출발점의 차이

카파시의 케이스	내 케이스
학습/리서치 큐레이션	개발 워크플로우 협업 컨텍스트
raw 문서를 LLM이 읽고 정리	작업 중 의사결정/설계가 누적
LLM이 본문 거의 다 작성	사람과 LLM이 같이 작성
”내가 모은 자료를 어떻게 정리시킬까"	"여러 에이전트가 어떻게 같은 페이지에서 일할까”

같은 도구지만 쓰는 결이 다르다. 카파시 쪽은 위키 자체가 학습의 결과물이라 자료를 넣을수록 풍부해진다. 내 쪽은 위키가 작업의 부산물이라 결정이 쌓일 때마다 한 줄씩 길어진다. 그래서 위키에 들어가는 글의 모양도 다르다. 카파시는 정리된 요약문이 들어가지만 내 위키엔 의사결정 이력과 미해결 질문이 같이 들어간다.

이 차이를 염두에 두고 위키 구조를 짰다.

LLM Wiki 설계

별도 레포(llm-wiki)를 git에 두고 다음과 같이 구조화했다.

llm-wiki/
├── index.md                    # 루트 진입점
├── projects/
│   └── <project-name>/
│       ├── index.md            # 프로젝트 진입점
│       ├── architecture.md
│       ├── chat-response-design.md
│       └── ...
├── knowledge/                  # 프로젝트 무관한 지식
│   ├── adk-multi-agent-patterns.md
│   ├── llm-product-ux.md
│   └── ...
└── ideas/                      # 탐색, 아이디어
    └── ...

핵심 결정 네 가지

모든 프로젝트는 디렉토리로 시작한다. 단일 문서로 시작하는 프로젝트라도 projects/<name>/index.md로 만든다. 나중에 문서가 늘어나도 위치가 안 바뀐다.
index.md는 진입점이자 라우터다. 프로젝트 개요와 관련 문서 링크. 에이전트가 먼저 읽는 곳이다.
위키 링크로 그래프 구조를 만든다. 옵시디언 [[file]] 문법을 그대로 사용한다. 같은 디렉토리는 [[file]]. 다른 디렉토리는 [[../knowledge/file]] 같은 상대경로로 쓴다.
프론트매터 컨벤션을 강제한다. date, tags, 필요시 project. 에이전트가 메타데이터로 검색/필터링할 수 있다.

루트 index.md는 모든 프로젝트와 지식 문서의 목차 역할을 한다. 에이전트가 새 세션에서 프로젝트를 처음 만나면 여기서 시작한다.

메모리 vs 위키 — 어디에 뭘 두는가

Claude Code에는 auto memory라는 기능이 있다. MEMORY.md에 인덱스를 두고 개별 메모리 파일에 사용자 선호, 프로젝트 컨텍스트, 피드백을 저장한다. LLM Wiki와 어떻게 분담하느냐가 처음에 헷갈렸는데 다음과 같이 정리했다.

구분	메모리 (auto memory)	위키 (LLM Wiki)
단위	단편적 사실, 선호	구조화된 문서
예시	”이 사용자는 쉼표 안 쓰는 글을 선호"	"채팅 응답 설계 v10 — Timezone 처리, Redis 캐싱 결정”
수명	점진 업데이트	버전으로 진화
접근	매 세션 자동 로딩	필요할 때 명시적으로 읽기

메모리는 매 세션 자동으로 로드된다. 위키는 필요할 때 명시적으로 읽는다. 플랜은 또 다르다. 현재 세션 안에서만 살아있고 끝나면 사라진다.

이 분리가 명확해지니 “이걸 메모리에 넣을까 위키에 넣을까” 고민이 사라졌다.

실제로 써보니

가장 효과를 본 사례는 세 레포 공용 계약 문서다. 문제는 세 레포가 같은 응답 포맷을 서로 다르게 이해할 수 있다는 점이었다. Agent는 응답을 만들고 Core는 그 응답을 API와 SSE로 흘려보내고 Mobile은 그것을 화면에 그린다.

채팅 응답 설계 문서 하나를 위키에 두고 첫 줄에 이렇게 명시했다.

이 문서는 Agent / Core / Mobile 세 팀의 공용 계약(contract) 문서입니다. 변경 시 세 쪽 모두에게 영향이 가므로 합의 후 업데이트하세요.

각 레포의 코드 에이전트는 작업 시작 시 이 문서를 먼저 읽는다. SSE event 포맷, fragment 구조, error 처리, sessionId 전달 방식 같은 게 모두 여기 정의되어 있다. 한쪽에서 포맷을 바꾸면 이 문서를 먼저 갱신한다. 다른 쪽 에이전트는 다음 세션에서 변경된 문서를 읽고 따라간다.

이 문서는 v6에서 시작해서 현재 v10까지 왔다. 각 버전마다 무엇이 왜 바뀌었는지가 문서 안에 남아있다. 효과는 “문서를 찾을 수 있다”보다 “결정의 이유를 다시 설명할 수 있다”에서 컸다. 새 세션에서 에이전트에게 “v8에서 v9으로 갈 때 왜 endpoint를 분리했지?”라고 물으면 현재 코드만 읽을 때보다 훨씬 빠르게 맥락을 회복한다.

컨텍스트 회복 흐름

새 세션이 시작되면 에이전트는 다음 순서로 컨텍스트를 빌드업한다.

CLAUDE.md / auto memory → 작업 규칙, 사용자 선호 (자동 로딩)
LLM Wiki 루트 index.md → 프로젝트 목록 확인
해당 프로젝트 index.md → 프로젝트 개요와 관련 문서 링크
작업과 관련된 의사결정 문서 → 깊이 읽기

이 4단계만 거치면 세션이 끊겨도 다음 세션에서 같은 위치로 돌아온다. 휘발성인 세션 위에 영속성 있는 위키가 깔려 있다.

팀으로 확장한다면 — 하네스 엔지니어링

여기까지가 1인 워크플로우 얘기였다. 그런데 이 방식을 팀에서 쓰려면 추가로 풀어야 할 문제가 꽤 있다.

먼저 솔직히 말하면 이 다음 내용은 가설이다. 프리랜서로 챗봇 개발 협업은 해봤어도 코드 에이전트를 팀 단위에서 어떻게 제어하고 컨벤션을 합의할지에 대한 경험은 아직 없다. 1인으로 검증한 구조를 팀으로 가져갈 때 무엇이 더 필요할지 상상해본 결과다.

Anthropic이 Effective harnesses for long-running agents에서 말한 “하네스 엔지니어링”이 정확히 이 영역이다. 에이전트가 새 세션에서 빠르게 상태를 이해하고 일할 수 있도록 환경/도구/메모리 구조를 짜는 일. Anthropic이 핵심 패턴으로 제시한 게 claude-progress.txt + git history 조합인데 llm-wiki도 같은 결의 도구다.

1인일 때는 내가 컨벤션과 거버넌스를 머리에 다 담고 있으니 위키가 단순해도 동작한다. 팀일 때는 그게 안 된다. 새로 필요해질 것들은 다음과 같다.

차원	1인	팀
스토리지	개인 git 레포	공용 git 레포 + branch protection + PR 리뷰
개인/공유 분리	모두 한 곳	`personal/` vs `shared/` 또는 별도 vault
컨벤션	내가 알아서	frontmatter schema 강제, lint, CI
충돌 관리	거의 없음	하나의 결정 = 하나의 파일 (ADR 패턴)
거버넌스	내 책임	author, last-verified, superseded 메타데이터
자동화 hook	수동 업데이트	세션 종료 / PR 머지 시 위키 업데이트 자동화
온보딩	불필요	root index가 진입점, 사용법 메타 문서
보안/권한	다 git 푸시	secret/customer data 분리, 민감 결정 access control

이렇게 되면 단순한 마크다운 디렉토리로는 부족하다. 결정 단위로 파일을 작게 쪼개야 머지 충돌이 안 난다. frontmatter에 author/status/superseded를 넣어야 어떤 결정이 살아있는지 알 수 있다. CI에서 형식을 검증해야 컨벤션이 무너지지 않는다.

1인 하네스도 결국 하네스다

1인일 때도 사실 하네스를 만들고 있다. 단지 사용자가 한 명이라 거버넌스 부담이 없을 뿐이다.

처음부터 팀에서 쓸 수 있는 수준의 컨벤션과 메타데이터를 갖춰두면 나중에 팀이 합류했을 때 그대로 확장된다. LLM Wiki를 메모 정리가 아니라 하네스 설계로 보면 1인 단계에서도 우선순위가 달라진다. 한 줄짜리 결정을 어디에 둘지, frontmatter에 뭘 넣을지 고민하는 시간이 늘어나는 대신 나중에 다시 정리하는 시간이 줄어든다.

마무리

LLM Wiki를 만들고 나서 가장 달라진 점은 문서가 늘어난 것이 아니라 새 세션이 시작될 때 컨텍스트를 회복하는 방식이 바뀐 것이다. 에이전트는 더 이상 레포 전체를 다시 훑으면서 추측하지 않는다. 프로젝트 index를 읽고 관련 계약 문서를 따라가고 이전 결정의 이유를 확인한다.

아직은 1인 환경이라 거버넌스를 엄격하게 걸 필요는 없다. 하지만 이 구조는 이미 작은 하네스다. 에이전트가 어디서 시작하고 무엇을 믿고 어떤 결정을 갱신해야 하는지를 정해주기 때문이다.

다음 문제는 도구였다. LLM Wiki로 공유 컨텍스트를 만들고 나니 그 위에서 어떤 에이전트 프레임워크와 자동화 도구를 실제로 들일지 기준이 필요해졌다.

1인 하네스 엔지니어링 시리즈

현재: 코드 에이전트를 위한 LLM Wiki
다음: 1인 하네스 엔지니어링 — 도구가 늘어날 때 기준 세우기
이후: Hermes Agent 도입기 — LLM Wiki 위에 자율 실행 루프 얹기