팀에서 AI 에이전트를 운영하기 시작하면서 한 가지 문제가 생겼습니다. AI에게 우리 시스템에 대한 정확한 컨텍스트를 어떻게 전달할 것인가.
Git 레포지토리에 Markdown 문서를 쌓고 관련된 문서끼리 링크를 걸었습니다. 벡터DB도, 임베딩도, 별도의 검색 시스템도 없었습니다. AI 에이전트가 읽고 참고하게 하려는 목적이었지만, 사람이 필요한 지식을 찾고 관리하기 쉽게 만들고 싶기도 했습니다.
이렇게 문서를 연결하고, AI 에이전트가 읽고 갱신 PR을 올리는 방식은 Andrej Karpathy가 소개한 LLM Wiki와 비슷합니다.
하지만 문서에 링크가 존재한다고 해서 AI가 그 구조를 탐색에 활용하는 것은 아닙니다. 실제로 운영 중인 에이전트는 주로 rg로 검색하고 필요한 파일을 읽으며 문서를 찾습니다. 그렇다면 현재 문서에 걸어둔 링크를 AI가 직접 따라갈 수 있게 하면, 검색만 사용할 때보다 필요한 문서를 더 잘 찾을 수 있을까요? 토큰도 줄일 수 있을까요?
그래서 실제로 운영 중인 지식베이스를 대상으로, rg 검색과 링크를 따라가는 탐색을 비교해봤습니다.
실험 설정
대상은 실제로 쓰고 있는 지식 베이스입니다. markdown 문서 43개, 문서끼리 걸린 내부 링크 285개. 문서를 노드로, 링크를 엣지로 보면 하나의 그래프가 됩니다. 실험에는 실제 문서 본문을 사용했지만, 이 글에서는 본문을 공개하지 않고 링크 구조와 문서 제목만 보여줍니다.
이런 링크 방식은 옵시디언의 [[문서]] 링크와 그래프뷰로 익숙할 겁니다. 하지만 예쁜 그래프뷰와 별개로, 이 링크가 실제 탐색 품질을 높이는지는 다른 문제입니다.
Obsidian 그래프뷰로 본 실제 지식베이스의 링크 구조. README가 가장 큰 허브로 나타납니다.
각 문서에는 함께 봐야 할 시스템과 운영 문서를 교차 링크해두었습니다. 관련성은 담겨 있지만, 링크 자체에 “의존한다”, “데이터를 전달한다”, “장애를 조사한다” 같은 관계의 종류가 명시되지는 않습니다.
그래서 이 글의 질문은 지금 운영 중인 Markdown 지식베이스의 실제 링크 구조가 AI 탐색에 도움이 되는가입니다. 사람이 문서를 오가며 남긴 관련성 신호를 AI가 실제로 활용할 수 있는지 확인했습니다.
검증 방법은 단순합니다. “어떤 주제에 대한 문서를 찾아라"는 질문 15개를 만들고, 각 질문의 정답 문서 집합을 먼저 정했습니다. 넓은 주제 탐색, 구체적인 작업, 개요와 세부 문서가 함께 필요한 질문, 문서 이름과 표현이 다른 질문을 섞었습니다.
| 질문 유형 | 질문 예 | 정답 문서 |
|---|---|---|
| 넓은 주제 (5) | 온보딩 / PII·보안 / CDC·스트리밍 / Jira / 데이터 웨어하우스 | 각 2~4종 |
| 구체 작업 (4) | “VPN이 안 될 때” / “대시보드 데이터 이상 조사” / “AWS CLI 접근” / “Jenkins 빌드 문제” | 각 1~2종 |
| 개요 + 세부 (3) | “전체 아키텍처 개요” / “기술 스택·레포 구성” / “데이터 수집→저장 전체 흐름” | 개요 + 세부 2~3종 |
| 키워드 미스매치 (3) | “개인정보 요청 처리” / “서버에 원격 코드 실행” / “마케팅 데이터는 어디서 오나” | 각 1~3종 |
여기서 “찾았다"는 탐색 중에 읽은 모든 문서가 아니라, 탐색을 마친 뒤 AI가 최종적으로 선택한 문서 집합을 뜻합니다. 지표는 두 가지입니다.
- recall(재현율): 정답 문서를 얼마나 놓치지 않고 찾았나.
찾은 정답 문서 수 / 전체 정답 문서 수 - precision(정밀도): 최종 선택한 문서 중 실제 정답이 얼마나 되나.
찾은 정답 문서 수 / 최종 선택한 전체 문서 수
정답 문서는 링크 구조와 무관하게, 순수하게 주제와 실제 문서 내용을 기준으로 정했습니다. 링크를 정답으로 삼으면 “링크가 링크를 잘 찾더라"는 순환논리가 되기 때문입니다.
실험은 OpenAI API로 실행했습니다.
AI 에이전트처럼 문서를 탐색하게 해봤다
팀에서 운영하는 OpenClaw 기반 AI 에이전트는 실제로 문서를 찾을 때, 파일시스템에 마운트된 지식 레포에서 탐색 상황에 따라 rg 검색과 Markdown 파일 읽기를 반복합니다. 이 실제 탐색 방식과 비슷하게 실험을 구성해, 링크가 도움이 되는지 비교했습니다.
세 조건 모두 README를 먼저 읽고 시작했습니다. 이후 각 조건에서 제공한 도구 안에서 AI가 다음 행동을 선택하게 했습니다.
| 조건 | AI가 쓸 수 있는 도구 |
|---|---|
| 검색 | rg로 찾고 필요한 문서를 read |
| 링크 | 현재 문서의 링크 목록을 보고 필요한 문서를 read |
| 둘 다 | rg, 링크 목록, read 모두 사용 가능 |
세 조건 모두 문서 안의 링크는 그대로 유지했습니다. 비교한 것은 링크의 존재 여부가 아니라, 검색 도구와 전용 링크 탐색 도구를 각각 또는 함께 제공했을 때의 차이입니다.
rg 결과는 파일 8개, 파일당 세 줄, 줄당 120자로 제한해 검색 결과가 지나치게 길어지지 않도록 했습니다. 링크 목록은 링크 텍스트와 대상 경로를 함께 돌려줬습니다. 에이전트 루프는 최대 15단계, 문서 읽기 상한은 README를 제외하고 8개로 설정했습니다.
채점은 AI가 done(selected_files)로 제출한 최종 문서 집합을 기준으로 했습니다. 제한에 도달해 done을 호출하지 못한 실행은, 그때까지 읽은 문서를 최종 선택으로 처리했습니다.
4개 모델을 세 조건에서 각각 세 번 실행했습니다. 총 실행은 36회이고, 질문 단위로는 모두 540회입니다. 아래 recall은 세 번의 평균과 표준편차이고, precision과 토큰은 평균입니다.
토큰은 질문 하나를 해결하는 동안 각 API 호출에 입력된 prompt token을 누적한 뒤, 15개 질문과 3회 반복에 대해 평균낸 값입니다. 모델 출력 token은 포함하지 않았습니다.
| 모델 | 조건 | recall | precision | 입력 토큰 |
|---|---|---|---|---|
gpt-4o-mini | 검색 | 0.68 ± 0.06 | 0.36 | 16.0k |
| 링크 | 0.80 ± 0.02 | 0.38 | 22.5k | |
| 둘 다 | 0.79 ± 0.04 | 0.41 | 15.1k | |
gpt-4o | 검색 | 0.73 ± 0.04 | 0.51 | 13.5k |
| 링크 | 0.74 ± 0.03 | 0.56 | 13.1k | |
| 둘 다 | 0.79 ± 0.06 | 0.45 | 21.4k | |
gpt-5.4-mini | 검색 | 0.85 ± 0.03 | 0.35 | 17.4k |
| 링크 | 0.86 ± 0.02 | 0.38 | 14.2k | |
| 둘 다 | 0.84 ± 0.01 | 0.31 | 18.1k | |
gpt-5.5 | 검색 | 0.97 ± 0.01 | 0.38 | 46.9k |
| 링크 | 0.90 ± 0.01 | 0.37 | 23.1k | |
| 둘 다 | 0.99 ± 0.02 | 0.38 | 37.8k |
(굵게 표시한 값이 각 모델에서 recall이 가장 높았던 조건입니다.)
모델마다 양상이 달랐습니다. 가장 뚜렷한 차이는 gpt-4o-mini에서 나왔습니다. 검색 조건의 recall은 0.68이었는데, 링크 조건에서는 0.80으로 올랐습니다. 반면 gpt-4o와 gpt-5.4-mini의 조건별 차이는 작았습니다. 세 번의 반복으로 관찰한 경향이지만, 이 정도만으로 모델 크기에 따른 일반 법칙을 말할 수는 없습니다.
gpt-5.5에서는 검색 조건이 recall 0.97로 링크 조건(0.90)보다 높았습니다. 이 모델은 문항당 rg를 여덟 번 넘게 부르며 필요한 문서를 넓게 찾았습니다.
둘 다 쓴 조건의 recall은 세 모델에서 검색 조건보다 높았고, gpt-5.4-mini에서는 0.01 낮았습니다. gpt-5.5는 이때 문항당 rg 5.2회, 링크 목록 2.3회를 사용했습니다. 두 도구를 함께 제공했을 때 링크를 무시하지 않고 실제 탐색에 사용한 것입니다. 다만 토큰 비용은 일관되지 않았습니다. 링크 조건이 gpt-5.5에서는 가장 적은 토큰을 썼지만 그만큼 문서를 덜 찾았고, 둘 다 쓰면 토큰은 모델마다 늘기도 줄기도 했습니다.
precision은 0.31~0.56으로 recall보다 낮았습니다. 예를 들어 gpt-5.5의 두 도구 조건은 recall 0.99였지만 precision은 0.38이었습니다. 필요한 문서는 거의 빠뜨리지 않았지만, 최종 선택에는 정답 외 문서도 적지 않게 들어갔다는 뜻입니다. 이 실험은 문서 탐색과 선택을 측정한 것이며, 그 문서를 바탕으로 만든 최종 답변의 정확도까지 평가하지는 않았습니다.
문서 링크는 AI 탐색에 도움이 됐을까
이번 실험에서는 도움이 되는 경우가 있었습니다. 기존 링크를 탐색 경로로 제공했을 때 일부 모델은 검색만 사용할 때보다 정답 문서를 더 많이 찾았습니다. 하지만 효과는 모델마다 달랐고, 검색과 링크를 함께 제공해도 항상 더 좋아지지는 않았습니다. 입력 토큰 역시 일관되게 줄지 않았습니다.
이번에 비교한 것은 문서에 링크가 있는 경우와 없는 경우가 아닙니다. 모든 조건에서 같은 원본 문서를 사용하되, AI가 기존 링크 구조를 탐색 경로로 활용할 수 있게 했을 때의 효과를 비교했습니다. 따라서 이 결과만으로 문서 링크 자체가 불필요하다거나, 링크를 추가해도 효과가 없다고 결론 내릴 수는 없습니다.
제가 내린 실무적인 결론은 조금 더 좁습니다. 현재로서는 AI 탐색을 위해 링크에 더 많은 시간을 쓸 이유는 충분하지 않았습니다. 사람이 문서를 찾고 관리하는 데 유용한 링크는 계속 유지하되, AI 성능 향상만을 목적으로 링크를 추가하는 데까지 시간을 쓰지는 않으려 합니다.
한계도 있습니다. 문서 43개와 질문 15개로 한 작은 실험이고, 각 조건을 세 번씩 반복했지만 그 이상은 아닙니다. 문서 간 관련성은 링크로 남겼지만, 의존성이나 원인·결과를 촘촘히 모델링한 지식그래프는 아닙니다. 따라서 이 결과는 그런 그래프의 효과까지 부정하지 않습니다. 대신, Git 위의 Markdown 문서와 관련 문서 링크로 실제 운영하는 지식베이스에서는 어떤 일이 벌어지는지 보여줍니다.
다음에는 시스템·파이프라인·테이블 같은 엔티티와 관계를 명시적으로 모델링하고, 그래프DB와 GraphRAG를 통해 그 관계를 탐색에 활용해보려 합니다. 문서 간 링크로 연결한 Markdown 지식베이스와 어떤 차이가 있는지 확인해볼 생각입니다.