발표에서 확인된 핵심 사실

로컬 폴더의 마크다운 문서를 AI 에이전트에게 그대로 입력하면 맥락 누락이나 참조 오류가 자주 발생한다. 파일 간의 연결 관계를 AI가 정확히 인지하지 못하는 한계 때문이다. Agent Docs for Markdown(에이전트 닥스 포 마크다운)은 로컬 마크다운 폴더를 AI 에이전트용 LLM 위키(LLM Wiki)로 변환해 주는 VS Code(비주얼 스튜디오 코드) 확장 도구다.

이 도구는 단순한 검색이나 미리보기 기능을 넘어선다. 문서 사이의 관계와 AI 에이전트의 작업 흐름을 함께 관리하는 것을 목표로 한다. 개별 문서의 파편화된 정보를 구조화된 지식 베이스로 전환한다.

데이터 관리는 로컬 워크스페이스 내에서 모두 이루어진다. 모든 인덱스와 문서를 외부 서버가 아닌 로컬 환경에서 처리한다. 작성된 마크다운 내용은 독립 실행형 HTML 또는 블로그용 HTML로 내보낼 수 있다.

인덱싱, Focus/Hop 탐색, Workspace

로컬 폴더의 마크다운 문서를 AI 에이전트에게 그대로 읽히면 참조 오류와 맥락 누락이 빈번하게 발생한다. Agent Docs for Markdown은 이를 해결하기 위해 로컬 폴더를 소스 그래프 기반의 LLM 위키로 변환하는 VS Code 확장 도구다. 문서와 링크 관계를 Source Graph(문서 간 연결 구조를 인덱싱하는 기술)로 인덱싱하여 데이터 간 상관관계를 정의한다. 단순한 파일 나열이 아니라 문서 간의 유기적 연결망을 구축해 LLM이 정보의 계층과 흐름을 파악하게 한다.

특정 문서를 기점으로 관련 문서를 확장해 나가는 Focus/Hop(중심 문서 설정 및 인접 문서 탐색 기능) 탐색을 지원한다. Workspace Cleanup Audit(워크스페이스 정밀 진단 기능)을 통해 깨진 링크나 고립된 문서, 중복 생성물 등 검색 효율을 저해하는 제외 후보를 식별한다. AI 에이전트가 참조할 문서의 우선순위와 영향 범위를 정확히 파악하게 함으로써 할루시네이션을 억제하고 문서 갱신 정확도를 높이는 판단 기준을 제공한다.

Claude, Codex, Gemini, Cursor 등 다양한 LLM 에이전트에 마크다운 전용 스킬 설치가 가능하다. 에이전트는 문서 수정 전 업데이트 범위를 사전에 확인하거나 워크스페이스 내 깨진 링크를 직접 찾아내는 작업을 수행한다. 리서치 노트를 보고서 형태로 재구성하는 등의 요청을 처리하며 에이전트의 문서 핸들링 능력을 확장하여 단순 텍스트 생성을 넘어선 문서 구조 최적화를 가능하게 한다.

AI 에이전트가 로컬 Markdown 폴더를 그대로 사용할 때

단순히 마크다운 폴더를 AI 에이전트에게 제공하면 지식 베이스가 자동으로 구축될 것이라는 믿음이 있었다. 하지만 로컬 폴더를 그대로 읽게 하면 서로 연결된 문서를 놓치거나 깨진 링크 및 고립된 문서를 그대로 참조하는 오류가 빈번하게 발생한다. 특히 빌드 결과물과 에이전트 설정 파일까지 검색 범위에 포함되어 정보의 순도가 낮아지는 문제가 나타난다. AI 에이전트가 유사한 성격의 문서들 사이에서 어떤 것이 기준 문서인지 판단하지 못해 참조의 정확도가 떨어진다.

이러한 연결 누락과 판단 오류를 해결하기 위해 에이전트 스킬을 관리 중심의 markdown-manager(문서 관리 스킬)와 작성 중심의 markdown-writer(문서 작성 스킬)로 이원화했다. markdown-manager는 문서 검색과 링크 점검을 수행하며 Source Graph(문서 간의 관계를 분석한 인덱스)를 탐색한다. 이를 통해 기준 문서를 정확히 판단하고 특정 내용을 수정했을 때 영향이 미치는 범위를 확인하는 작업을 담당한다. 관리 전용 스킬을 통해 에이전트가 참조할 문서의 우선순위를 명확히 설정하고 불필요한 파일의 간섭을 차단한다.

markdown-writer는 리서치 노트를 보고서나 블로그 글 형태로 재구성하는 역할에 집중한다. 최종적으로 HTML로 내보내기 전 렌더링 결과가 의도대로 출력되는지 점검하는 기능을 수행한다. 관리와 작성 역할을 엄격히 분리하여 에이전트가 문서의 구조적 무결성을 유지하는 동시에 콘텐츠 생산성을 높이는 체계를 구축했다. AI 에이전트가 참조할 문서의 영향 범위를 정확히 파악하는 것은 할루시네이션을 줄이고 문서 갱신 정확도를 높이는 실질적인 기준이 된다.

단순한 텍스트 나열은 AI 에이전트의 참조 오류와 맥락 누락을 유발한다. Agent Docs for Markdown은 소스 그래프 인덱싱과 Focus, Hop 탐색을 통해 문서 간의 관계를 구조화하여 이 문제를 해결한다.

결국 AI 에이전트의 신뢰도는 데이터의 양이 아니라 참조 문서의 우선순위와 영향 범위를 얼마나 정밀하게 제어하느냐로 결정된다. 할루시네이션을 줄이기 위해 본문의 설정 기준에 따라 로컬 마크다운 폴더의 인덱싱 구조를 최적화하는 것이 실질적인 해결책이다.