AI 에이전트 팀의 공유 뇌(Wiki) 구축하기: Markdown과 Git으로 컨텍스트 일관성 유지하는 법 (github.com)
목차(4)
한줄 요약
AI 에이전트 여럿이 공유 Wiki(Markdown + Git)를 뇌삼아 협업하면 컨텍스트 단절 문제를 구조적으로 해결할 수 있다.
무엇이 달라지나?
멀티 AI 에이전트 협업의 가장 큰 골칫거리는 항상 같은 곳에서 발생한다. 에이전트 A가 내린 결정을 에이전트 B가 모른다. 세션이 바뀌면 이전 맥락이 사라진다. 사람이 중간에서 계속 컨텍스트를 손으로 이어붙여야 한다. 결국 자율화라는 말이 무색해진다.
GitHub에 공개된 오픈소스 프로젝트 wuphf는 이 문제를 정면으로 건드린다. 프로젝트 설명 자체가 "AI 직원들을 위한 Slack, 공유 뇌를 가진"이라고 표현할 정도다. Claude, Codex 같은 서로 다른 AI 모델이 하나의 공유 지식 저장소를 바라보며 자율적으로 협업하는 구조를 목표로 한다.
핵심 아이디어는 단순하다. Wiki를 에이전트들의 외부 기억 장치로 쓴다. 특정 에이전트가 내린 판단, 수집한 정보, 진행 상태를 Markdown 문서로 기록하고, Git으로 버전을 관리한다. 다른 에이전트는 세션 시작 시 이 Wiki를 읽어 현재 상태를 복원한다. 컨텍스트가 모델의 컨텍스트 윈도우가 아니라 파일 시스템에 영구적으로 살아있는 셈이다.
리포지토리 구조를 보면 .cursor/rules, .windsurf 같은 디렉터리가 존재하는데, 이는 AI 코딩 환경별로 에이전트 행동 규칙을 별도로 정의하고 있다는 것을 보여준다. 단순히 "AI끼리 채팅하게 한다"는 수준이 아니라, 각 에이전트가 어떤 역할로 어떻게 행동해야 하는지를 구조적으로 규정하는 방식이다.
벤치마크 관련 커밋 내용을 보면 Wiki 내 관계형 쿼리 정확도를 95% 이상으로 끌어올리는 작업이 진행됐다. BM25 기반 검색에 그래프 탐색을 결합해 "누가 이 프로젝트를 리드하는가"와 같은 관계 질문에 정확히 답할 수 있도록 하는 쿼리 리라이터를 구현했다는 점이 흥미롭다. 에이전트가 Wiki를 단순히 읽는 것이 아니라 구조화된 형태로 질의하는 수준까지 고려하고 있는 것이다.
실무에서 어떤 의미인가?
이 접근법이 시사하는 바는 기술적 세부사항보다 설계 철학에 있다.
첫째, AI 에이전트의 상태는 외부화해야 한다. LLM의 컨텍스트 윈도우는 세션이 끝나면 사라진다. 진짜 자율 운영을 원한다면 에이전트의 기억을 코드베이스 안에 함께 버전 관리해야 한다. Markdown과 Git은 이를 위한 가장 낮은 마찰의 조합이다.
둘째, 에이전트 간 통신 채널보다 공유 상태가 더 중요하다. 에이전트끼리 실시간 메시지를 주고받는 아키텍처는 복잡도가 높다. 반면 "모두가 같은 파일을 읽고 쓴다"는 모델은 디버깅도 쉽고, 사람이 개입하기도 쉽다.
셋째, Git의 커밋 로그가 에이전트 감사 로그가 된다. wuphf 리포지토리의 커밋 메시지를 보면 "Co-Authored-By: Claude Opus 4.7"처럼 AI가 기여자로 명시되어 있다. Git 히스토리 자체가 어떤 AI가 무엇을 결정했는지 추적하는 감사 기록이 되는 구조다.
이 패턴은 현재 많은 팀이 실험적으로 도입하는 방향과 일치한다. AI 에이전트를 단순한 툴이 아니라 코드베이스에 기여하는 비동기 팀원으로 다루는 방식이다.
도입 전 체크포인트
이 구조를 실제 프로젝트에 적용하려면 몇 가지를 먼저 점검해야 한다.
Wiki 쓰기 권한 정책을 명확히 해라. 여러 에이전트가 동시에 같은 파일을 수정하면 충돌이 발생한다. 에이전트별로 담당 문서 영역을 분리하거나, Pull Request 기반으로 변경을 통제하는 규칙이 필요하다.
쿼리 구조를 미리 설계해라. 단순 텍스트 덩어리로 Wiki를 쌓으면 나중에 에이전트가 관계 정보를 정확히 추출하기 어렵다. wuphf가 관계형 쿼리 리라이터를 별도로 구현한 이유가 여기 있다. 처음부터 구조화된 Markdown 형식과 메타데이터 규칙을 정해두는 것이 유리하다.
에이전트 역할 정의를 코드로 관리해라. .cursor/rules처럼 에이전트가 따라야 할 행동 규칙을 파일로 버전 관리하면, 에이전트 동작이 변경될 때 코드 리뷰와 동일한 프로세스로 검토할 수 있다. 암묵적 프롬프트 관리에서 벗어나는 첫걸음이다.
컨텍스트 비용을 계산해라. Wiki가 커질수록 에이전트가 세션 시작 시 읽어야 하는 문서량이 늘어난다. 토큰 비용과 레이턴시 모두 증가한다. 적절한 인덱싱이나 요약 전략을 함께 설계하지 않으면 규모가 커질 때 병목이 발생한다.
자주 묻는 질문
Q.wuphf는 어떤 AI 모델을 지원하나?
리포지토리 설명 기준으로 Claude, Codex, OpenAI 계열 모델을 함께 사용하는 구조를 상정하고 있다. 특정 모델에 종속된 구조가 아니라, Markdown 기반 Wiki라는 모델 중립적인 인터페이스를 공유 상태로 쓰기 때문에 이론적으로는 다양한 LLM을 혼합해 쓸 수 있다. 다만 각 모델의 특성에 맞게 에이전트 역할과 쿼리 방식을 별도로 튜닝해야 한다.
Q.Markdown + Git 방식이 벡터DB 기반 RAG와 어떻게 다른가?
벡터DB 기반 RAG는 의미 유사도로 관련 문서를 검색하는 데 강점이 있지만, 변경 이력 추적과 충돌 관리가 약하다. Markdown + Git은 버전 관리와 감사 로그가 기본으로 따라오고, 사람이 직접 읽고 수정하기 쉽다는 장점이 있다. wuphf는 BM25 검색에 그래프 기반 관계 탐색을 더하는 방식으로 두 접근법의 중간 지점을 찾으려는 것으로 보인다. 어느 쪽이 낫다기보다 용도와 팀 운영 방식에 따라 선택이 달라진다.
Q.이 구조에서 사람 개발자의 역할은 어디인가?
에이전트가 자율적으로 Wiki를 업데이트하고 코드를 작성하더라도, Pull Request 기반 리뷰 프로세스를 유지하면 사람의 승인 단계를 구조적으로 보존할 수 있다. wuphf의 커밋 히스토리를 보면 AI가 작성한 커밋도 동일한 PR 프로세스를 거치는 방식으로 운영되고 있다. 완전 자율화보다는 "사람과 AI의 비동기 협업"을 현실적인 목표로 잡는 편이 지금 단계에서는 안전하다.