사전 공개: 저는 agentproto와 그 코퍼스(corpus) 툴링을 개발했으며, 본 가이드에서는 이를 사용합니다. 명령어는 실제이며 확인 가능합니다. 전반부에서 언급된 문제는 모든 RAG 설정이 직면하는 문제입니다. 수정 사항이 있다면 이슈를 남겨주세요.

조언은 어디에나 있으며 완벽하게 들립니다: 에이전트에게 지식을 제공하세요 — 그냥 문서 폴더에 대해 RAG (Retrieval-Augmented Generation)를 수행하면 됩니다. 그래서 당신은 리트리버(retriever)를 docs/ 폴더로 지정하고, 청크(chunks)를 임베딩(embed)한 뒤 연결합니다. 그러면 에이전트는 당신의 시스템에 관한 질문에 답하기 시작합니다.

그러다 당신이 중요한 것을 질문하면, 에이전트는 유창하고 자신감 넘치는 문단을 내놓습니다 — 하지만 그것이 사실인지 당신은 알 길이 없습니다. 왜냐하면 그것이 어디에서 왔는지 알 수 없기 때문입니다. 그것이 현재의 런북(runbook)에서 온 것인가요, 아니면 2024년에 방치한 설계 문서(design doc)에서 온 것인가요? 그 재시도(retry) 횟수가 실제 값인가요, 아니면 코사인 유사도(cosine similarity) 점수가 우연히 높게 나온 오래된 README의 청크인가요? 당신은 알 수 없습니다. 에이전트도 마찬가지입니다.

그것이 바로 당신에게 지식 베이스(knowledge base)가 없다는 신호입니다. 당신은 문서 더미에 대한 검색 인덱스(search index)를 가지고 있을 뿐이며, 이는 전혀 다르고 훨씬 더 약한 것입니다.

다른 것은 다 잊더라도 이것 하나만은 기억하세요:
문서 폴더는 지식 베이스가 아닙니다. 지식 베이스를 만드는 것은 바로 _출처(provenance)_입니다. 모든 사실이 어떤 소스에서 왔는지 알고 있어야 하며, 그래야 에이전트가 이를 인용할 수 있고 당신이 확인할 수 있습니다.

문서 덤프(doc dump)가 할 수 없는 두 가지

마크다운(markdown) 폴더가 지식 베이스로서 실패하는 데에는 두 가지 구조적인 이유가 있으며, 임베딩(embeddings)을 아무리 개선해도 이 중 어느 것도 해결되지 않습니다.

사실(facts)이 아닌 산문(prose)을 검색합니다. 문서는 한 번에 여러 가지에 대해 서술하는 문장들의 벽입니다. 이를 청킹(chunking)하면 임의의 조각들이 생깁니다 — 재시도(retries)에 관한 문단의 절반이 로깅(logging)에 관한 문단의 시작 부분과 붙어버리는 식입니다. 에이전트는 정답에 '가까운' 내용을 얻고 나머지를 재구성하는데, 이것이 바로 '자신감 있지만 틀린(confident-but-wrong)' 답변이 발생하는 정확한 지점입니다. 지식의 단위는 512-토큰(token) 윈도우가 아니라 _주장(claim)_이어야 합니다.

모든 정보가 어디에서 왔는지 잊어버립니다. 일단 청크(chunk)가 임베딩(embedding)되면, 그것은 그저 떠다니는 문자열일 뿐입니다. "이것은 runbooks/payments.md에서 가져온 것이며, 지난 4월 사고 당시 마지막으로 수정되었습니다"라고 연결해 줄 실마리가 없습니다. 따라서 에이전트(agent)는 인용할 수 없고, 더 심각하게는 — _당신_이 감사(audit)할 수 없습니다. 감사할 수 없는 지식 베이스(knowledge base)는 신뢰할 수 없는 지식 베이스이며, 이는 에이전트가 확신을 가지고 틀린 답을 내놓는 순간 그것이 부채(liability)가 된다는 것을 의미합니다.

두 문제 모두 해결책은 동일하며, 그것은 더 화려한 리트리버(retriever)를 사용하는 것이 아닙니다. 그것은 바로 **파이프라인(pipeline)**입니다. 무언가가 정보를 쿼리(query)하기 전에, 소스(source)를 원자적이고 출처가 명시된 주장(claim)으로 변환하는 것입니다. 그 파이프라인이 바로 코퍼스(corpus)와 폴더를 구분 짓는 요소입니다.

당신의 "지식 베이스"는 실제로 무엇으로 구성되어 있습니까?

구축하기 전의 자신을 떠올려 보십시오. 네 가지 정직한 답변이 있습니다.

없음. 에이전트는 사전 학습(pre-training) 데이터와 당신이 붙여넣은 것에 의존하여 작동합니다. 기본적으로 일반적(generic)입니다. 한계: 이미 공개된 정보가 아닌 것은 결코 알지 못합니다.

문서 폴더 + RAG. 유사도(similarity)에 따라 청크를 검색합니다. 아무것도 없는 것보다는 낫지만, 이것이 바로 이 글에서 다루고자 하는 함정입니다. 출처(provenance)가 없고, 중복 제거(dedup)가 없으며, 주장의 개념도 없습니다. 즉, 이름을 밝힐 수 없는 소스로부터 답변합니다. 한계: 확신에 차 있지만 검증할 수 없으며, 문서가 노후화되는 즉시 쓸모없어집니다.

수동으로 관리되는 위키(wiki). 실제 사람이 유지 관리하며 종종 품질도 좋지만, 이는 에이전트가 주장 단위로 쿼리하기 위한 것이 아니라 _사람_이 읽기 위해 작성된 것입니다. 또한 아무도 수정하지 않는 사이 정보가 노후화됩니다. 한계: 높은 품질, 낮은 쿼리 가능성(queryability), 수동 유지 관리.

정제되고 출처가 명시된 코퍼스(corpus). 출처가 첨부된 상태로 가져온 소스, 주장(claim) 수준의 항목으로 정제된 데이터, 각 항목이 자신의 출처를 지니며 주제별로 쿼리 가능한 형태입니다. 이것이 바로 에이전트가 인용할 수 있고 당신이 감사할 수 있는 방식이며, 단 네 개의 명령어로 가능합니다.

당신은 어디에 있습니까? 만약 당신의 정직한 답변이 _"문서 폴더 기반의 RAG"_라면, 당신은 확신에 차 있지만 검증할 수 없는 설정을 가지고 있는 것입니다. 이는 가장 위험한 유형인데, 왜냐하면 잘못된 정보를 아주 태연하게 말하기 직전까지는 제대로 작동하는 것처럼 느껴지기 때문입니다. 이 글의 나머지 내용은 그 데이터 더미를 코퍼스로 바꾸는 방법을 다룹니다.

Step 1: 가져오기(import), 그리고 영수증 보관하기

먼저 소스(sources)를 코퍼스 워크스페이스(corpus workspace)로 가져오는 것부터 시작하세요. 여기서 타협할 수 없는 원칙은 각 소스가 어디에서 왔는지에 대한 연결 고리(thread)를 유지해야 한다는 점입니다.

npm i -g @agentproto/corpus-cli

# AIP-10 워크스페이스 스캐폴딩 (일반적인 연구 프리셋, 시드 노이즈 없음)
...

가져온 모든 소스는 originalUrl — 즉 출처(provenance) 연결 고리를 포함하는 AIP-10 레코드로 저장됩니다. 기사는 readability를 통해 들어오고, 유료 페이지(walled page)는 브라우저를 통해 경로를 지정하며, 녹화된 장애 리뷰(incident review)나 비디오 아키텍처 강연은 전사(transcription)를 통해 들어옵니다 — 동일한 워크스페이스, 동일한 출처를 가지므로, 팀이 말로만 했던 결정이 인용 가능한 소스가 됩니다. 가져오기(Import)는 재개 가능합니다. 다시 실행하면 이미 포함된 항목은 건너뛰므로, 코퍼스를 새로 구축하는 대신 확장해 나갈 수 있습니다.

Step 2: 증류(distill) — 문서를 주장(claims)으로 변환하기

이 단계는 폴더 및 RAG(Retrieval-Augmented Generation) 설정이 완전히 건너뛰는 단계이며, 가장 중요한 단계입니다. 증류(Distillation)는 각 소스를 읽고 원자적(atomic)인 주장 수준(claim-level)의 항목을 생성하며, 소스당 대략 7개 정도의 항목이 생성되고 각 항목은 출처를 포함합니다.

# 저렴하면서도 강력함: OpenRouter를 통해 오픈 모델에서 증류 (프런티어 모델 크레딧 절약)
corpus distill knowledge/house --engine opencode -m openrouter/deepseek/deepseek-v4-pro

이제 지식의 단위는 청크(chunk)가 아니라 주장(claim)입니다. _"결제 재시도는 멱등성 키(idempotency key)를 사용하여 최대 3회로 제한됨, 2026-04 장애 기준"_은 단순히 근처에 임베딩된 문단의 조각이 아니라, 하나의 출처를 가진 하나의 항목이 됩니다. 에이전트(agent)가 이를 검색할 때, 에이전트는 사실 및 그 기원을 함께 검색하게 되며, 이를 통해 "일반적인 접근 방식은..." 대신 _"2026-04 장애에 따르면..."_이라고 답변할 수 있게 됩니다. 출처(Provenance)는 더 이상 메타데이터가 아니라 답변 그 자체가 됩니다.

왜 근거가 있는 주장(claims)이 청크(chunks)보다 나은가. Anthropic의 컨텍스트 엔지니어링(context-engineering) 가이드는 텍스트의 벽을 미리 로드하는 대신, 작업 컨텍스트를 작게 유지하고 고신호 사실(high-signal facts)을 **적시(just in time)**에 검색하는 것입니다. 문서를 대상으로 적시 검색을 수행할 수는 없습니다. 문서가 너무 크고 너무 많은 내용을 담고 있기 때문입니다. 하지만 주장(claim)을 대상으로는 가능합니다. 증류(Distillation)는 지식을 적절한 입도(grain)로 검색 가능하게 만드는 핵심입니다.

3단계: 코퍼스(corpus)를 게이트(gate) 하세요 — 지식 베이스는 채워지는 것이 아니라 유지되는 것입니다

문서 더미는 한 번 채워두고 잊어버리는 방식입니다. 반면 코퍼스(corpus)는 여러분이 관리하는 산출물(artifact)이며, 따라서 어떤 것이 이를 신뢰하기 전에 품질 게이트(quality gate)를 거쳐야 합니다.

corpus validate knowledge/house    # 스키마 유효 소스, 오류 0개
corpus lint knowledge/house        # 구조적 점검
corpus knowledge knowledge/house --tags incidents --max 20   # 에이전트가 가져올 내용을 미리 보기

여기서 잡아내야 할 두 가지 실패 모드가 있습니다. 이들은 코퍼스를 조용히 오염시키기 때문입니다. 첫째는 **잘못된 스크래핑(bad scrape)**입니다. 검색기(retriever)가 본문 대신 쿠키 벽(cookie-wall)이나 네비게이션 메뉴를 긁어오는 경우인데, 이는 여전히 확신에 찬 어조의 항목으로 증류되어 버립니다. 자체 플래그(예: "콘텐츠가 일치하지 않음", 주제와 벗어난 명사)를 grep으로 찾아내어 demoted/ 폴더로 격리함으로써 에이전트에게 전달되지 않도록 하세요. 둘째는 **커버리지(coverage)**입니다. 여러분이 중요하게 생각하는 각 주제에 대해 코퍼스가 실제로 출처가 있는 주장(sourced claims)을 보유하고 있는지, 아니면 해당 태그가 비어 있는지 확인해야 합니다. 지금 발견한 공백은 나중에 에이전트가 추측으로 메우지 못할 공백이 됩니다.

이것이 바로 문서 덤프(doc-dump) 방식에는 없었던 규율입니다: 여러분의 지식 베이스는 가장 품질이 낮은 소스만큼만 가치가 있으므로, 소스를 점검해야 합니다.

4단계: 서빙(serve)하세요 — 모든 에이전트에게, 주장(claim) 단위로, 출처를 포함하여

이제 코퍼스는 도구가 됩니다. 방금 구축한 워크스페이스를 가리키는 knowledge.search 드라이버를 통해 이를 뒷받침하고, MCP를 통해 서빙하세요. 전체 계약 및 드라이버 패턴(contract-and-driver pattern)은 자체 가이드를 참조하시기 바랍니다. 하지만 그 대가는 단 하나의 환경 변수와 하나의 명령어로 돌아옵니다:

CORPUS_WS=knowledge/house agentproto serve   # 모든 에이전트에게 knowledge.search를 제공합니다

데몬 (daemon)을 마운트하는 모든 에이전트 — Claude Code, Codex, 저렴한 로컬 모델 등 — 는 이제 동일하게 정제되고 출처가 명시된 코퍼스 (corpus)를 쿼리합니다. 그리고 드라이버가 로컬 파일을 읽기 때문에, 당신의 지식은 절대 기기를 떠나지 않습니다. 그들 중 누구에게든 당신의 재시도 정책 (retry policy)을 물어보면, incident 2026-04가 첨부된 답변이 돌아옵니다. 그 인용 (citation)은 장식이 아닙니다. 회의적인 검토자(사람 또는 에이전트)가 답변을 맹신하는 대신 출처와 대조하여 확인할 수 있게 해주는 핵심 요소입니다.

솔직한 이면

코퍼스 (corpus)는 실제 산출물 (artifact)이므로, 실제 유지보수와 실제 실패 모드 (failure modes)가 존재합니다.

잘못된 코퍼스는 코퍼스가 없는 것보다 더 나쁩니다. 오래된 주장이 최신 주장과 동일한 확신을 가지고 검색됩니다. 심지어 이제는 출처까지 첨부되어 있어, 더욱 설득력 있고 더욱 위험해집니다. 당신을 구원하는 것은 출처 (provenance)입니다. 모든 주장이 그 기원을 명시하기 때문에, 잘못된 답변은 추적할 수 없는 익명의 환각 (hallucination)이 아니라, 오래된 출처로 추적 (traceable) 가능하며 수정할 수 있습니다. 문서를 관리하듯 코퍼스를 관리하십시오. 그것이 코퍼스의 본질이기 때문입니다.

에이전트가 당신의 지식 베이스 (knowledge base)를 작성하게 두지 마십시오. 실제 런북 (runbooks), 인시던트 (incidents), 그리고 결정 사항들로부터 정제된 코퍼스는 당신의 것이지만, 에이전트가 자신에 대해 생성한 코퍼스는 당신의 리포지토리 (repo) 이름만 붙은 인터넷의 평균치일 뿐입니다. 당신이 책임질 수 있는 출처로부터 정제하십시오. 핵심은 지식이 합성 (synthesized)되는 것이 아니라 획득 (earned) 되어야 한다는 점입니다.

그리고 공정한 비교입니다. 관리형 RAG 제품과 벤더의 검색 (retrieval) 서비스는 설정이 덜 필요합니다. 만약

이제 모두가 동일한 모델을 대여하여 사용하므로, 스택(stack)에서 진정으로 당신만의 것이 되는 부분은 에이전트가 무엇을 '알고 있는가'입니다. 그리고 이는 에이전트가 알고 있는 내용이 실제일 때만 유효합니다. 검색기 (retriever) 뒤에 놓인 문서 폴더는 이름을 붙일 수도, 확인할 수도 없는 출처로부터 유창한 답변을 제공하지만, 이는 지식 베이스 (knowledge base)가 존재하는 목적과 정반대되는 것입니다.

해결책은 더 나은 임베딩 모델 (embedding model)을 사용하는 것이 아닙니다. 그것은 파이프라인 (pipeline)입니다. 출처 (provenance)를 온전하게 유지하며 소스를 가져오고, 검색하기에 충분히 작고 인용하기에 충분히 정직한 주장 (claims)으로 이를 증류 (distill)하며, 그 결과물을 하나의 산출물 (artifact)로서 게이트 (gate)하고, 실행되는 모든 에이전트에게 이를 제공하는 것입니다. 이 네 가지 명령만 있다면, 당신의 에이전트는 더 이상 무더기에서 추측하지 않고, 모든 사실이 정확히 어디에서 왔는지 알려줄 수 있는 코퍼스 (corpus)로부터 답변하기 시작할 것입니다.

에이전트에게 지식을 부여하십시오. 다만 그 지식이 자신의 작업 과정을 증명할 수 있는 종류인지 확인하십시오.

만약 증류 (distill) 단계 없이 출처를 유지하는 방식으로 지식 베이스를 구축했거나, 혹은 폴더 기반 RAG를 진정으로 감사 가능하게 (auditable) 만들었다면, 어디인지 알려주십시오. 제가 그 부분을 수정하겠습니다.

작성자: agentproto (Apache-2.0, source) 유지관리자 — 코딩 에이전트를 실행하고 관리하기 위한 로컬, 크로스 벤더 데몬 (cross-vendor daemon). 저희의 /compare 페이지와 동일한 계약을 따릅니다: 날짜가 명시된 사실, 명시된 강점, 이슈에 따른 수정. 잘못된 내용이 있나요? 이슈를 제기해 주세요.

agentproto를 공개적으로 구축 중입니다 — X에서 @theagentproto와 @agentik_ai를 팔로우하세요.