사전 공개: 저는 이 글의 후반부에서 다루는 지식 및 운영자 프리미티브 (operator primitives)를 제공하는 agentproto를 개발했습니다. 전반부에서 다루는 문제는 그 자체로 독립적인 주제이며, 가이드(walkthrough)는 실제 확인 가능한 명령어를 사용합니다. 수정 사항이 있다면 언제든 이슈(issue)를 남겨주세요.

Claude Code를 여세요. Codex를 여세요. 동일한 리포지토리(repo)에서 저렴한 로컬 모델 (local model)을 여세요. 그리고 세 모델 모두에게 당신의 코드베이스 (codebase)에 대해 동일한 질문을 던져보세요. 예를 들어, 당신의 재시도 컨벤션 (retry convention), 배포 런북 (deploy runbook), 혹은 특정 서비스가 왜 현재와 같은 구조를 갖게 되었는지에 대해 물어보세요.

당신은 유창하고 자신감 넘치며, 거의 동일한 세 가지 답변을 받게 될 것입니다. 그리고 세 답변 모두 똑같은 방식으로 틀릴 것입니다. 그들은 '합리적인' 팀이 어떻게 하는지는 설명하겠지만, '당신의' 팀이 어떻게 하는지는 설명하지 못할 것입니다. 그들은 모두 동일한 공개 인터넷 데이터로 학습된 동일한 프론티어 가중치 (frontier weights)를 실행하고 있으므로, 기본 상태(out of the box)에서는 모두 정확히 똑같은 것만을 알고 있습니다.

다른 것은 다 잊더라도 이것 하나만은 기억하세요:
가중치 (weights)는 모두의 것입니다. 당신의 지식 베이스 (knowledge base)만이 스택 (stack)에서 유일하게 '당신의 것'이며, 에이전트를 인터넷의 평균이 아닌 당신만의 것으로 만드는 유일한 요소입니다.

모델은 더 이상 차별화 요소가 아닙니다

벤치마크 (benchmarks)를 두고 논쟁하는 동안 대부분의 사람들이 놓친 변화가 여기 있습니다. 최고 모델과 10위 모델 사이의 격차가 좁혀지고 있습니다 — 이 허브 게시물은 Stanford AI Index의 증거를 제시합니다 (1위와 10위 사이의 격차가 1년 만에 11.9%에서 5.4%로 감소했습니다). 가중치 (weights)가 수렴할 때, 가중치는 더 이상 당신의 경쟁 우위 (edge)가 되지 못합니다.

그것을 대체하는 것은 시스템 디자인 (system design)입니다. 에이전트의 진화에 관한 널리 인용되는 2026년 에세이는 이를 직설적으로 표현했습니다: 에이전트의 역량은 모델 품질 (model quality)에서 시스템 디자인 (system design)으로 이동했습니다 — 즉, 영리한 프롬프트 (prompt)를 작성하는 것에서 모델이 무엇을 '볼 수 있는지'를 엔지니어링하는 것으로 변화했습니다. 영리한 프롬프트는 이제 범용화된 상품 (commodity)입니다. 컨텍스트 (context)는 그렇지 않습니다.

시장 전체를 재정의하는 증거. 에이전트 프레임워크 (agent frameworks)의 프로덕션 준비성 (production-readiness) 비교에서, 테스트된 모든 오케스트레이션 (orchestration) 스타일 전반에 걸쳐 공통적으로 나타난 한 가지 발견이 있습니다: 오케스트레이션 방식과 관계없이, 검색 품질 (retrieval quality)이 지식-에이전트 (knowledge-agent)의 성능을 지배합니다. 세계 최고의 플래너-워커-저지 (planner-worker-judge) 토폴로지 (topology)를 가질 수도 있겠지만, 만약 에이전트가 당신의 세계가 아닌 인터넷의 평균적인 정보로부터 검색을 수행한다면, 그것은 낯선 사람처럼 대답할 것입니다.

따라서 흥미로운 질문은 "어떤 모델인가?"에서 "다른 누구도 모르는 무엇을 알고 있는가?"로 바뀌었습니다. 여기서 JetBrains의 프레임링 (framing)이 유용합니다: 어떤 에이전트들은 액션 우선 (action-first) (그 가치는 그들이 _하는 것_에 있음)이며, 어떤 에이전트들은 데이터 우선 (data-first) (그 가치는 그들이 _접근할 수 있는 것_에 있음)입니다. 당신의 팀을 위한 코딩 에이전트는 당신이 그렇게 설계했든 아니든 데이터 우선 (data-first)입니다.

불편한 사실: 만약 당신의 지식을 에이전트에 연결하지 않았다면, 당신은 낯선 사람을 배포하고 있는 것입니다.

당신의 에이전트는 어느 단계에 있습니까?

무언가를 구축하기 전에 자가 진단을 수행하십시오. 세 가지 단계가 있으며, 대부분의 팀은 인지하지 못한 채 처음 두 단계에 머물러 있습니다.

Tier 0 — 지식 베이스 (knowledge base) 없음. 에이전트는 사전 학습 (pre-training) 단계에서 알았던 것만을 압니다: 공개된 GitHub, Stack Overflow, 특정 컷오프 (cutoff) 시점까지의 문서들. 당신의 세계에 대해 물으면 에이전트는 가장 가까운 공개 사례에 맞춰 패턴 매칭 (pattern-matches)을 수행합니다. 그것은 자신만만하며 일반적입니다. 한계: 인터넷에 이미 존재하는 것이 아니라면 단 하나도 알지 못할 것입니다.

Tier 1 — 컨텍스트 (context)에 붙여넣기. 런북 (runbook), 컨벤션 문서 (conventions doc), 몇 개의 과거 PR (pull requests)을 프롬프트 (또는 CLAUDE.md)에 쏟아붓고 희망을 거는 방식입니다. 컨텍스트가 가득 차기 전까지는 작동합니다. Anthropic의 컨텍스트 엔지니어링 (context-engineering) 포스트는 왜 이것이 한계에 부딪히는지에 대해 명확히 설명합니다: 당신은 컨텍스트를 유한한 주의 예산 (finite attention budget)으로 취급해야 합니다. 왜냐하면 윈도우 (window)가 커질수록 회상 (recall) 능력이 저하되기 때문입니다 ("컨텍스트 부패 (context rot)").

왜 Tier 1은 한계가 명확한지(hard ceiling) 설명합니다. 같은 글에서 해결책을 제시하고 있습니다. 즉, 모든 것을 미리 로드하는 것이 아니라 가볍게 참조하고 필요할 때만 검색해야 합니다. 전체 지식 기반(knowledge base)을 모든 프롬프트에 붙여넣는 것은 정확히 반(反)패턴입니다. 비용이 많이 들고, 부패하며, 몇 개의 문서 이상으로는 확장되지 않습니다. 당신이 붙여넣는 KB는 곧 잘리게 될 KB입니다.

Tier 2 — 검색 가능한 서비스형 지식 기반. 당신의 지식이 한 곳에 존재하고, 인덱싱되며, 모든 에이전트가 필요할 때마다 이를 *쿼리(query)*합니다. 이 과정에서 질문과 관련된 세 개의 관련 항목만 가져오고, 그 출처도 함께 제공됩니다. 이것이 제대로 수행된 적시 검색(just-in-time retrieval)이며, 실행하는 모든 에이전트와 공유될 수 있습니다.

Tier 1에서 Tier 2로의 도약이 핵심입니다. 그리고 이는 the files-with-contracts piece에서 지적한 '누가 에이전트를 장비하는가'라는 질문을 지식에 직접 겨냥하고 있습니다. 이제 구축해 봅시다.

1단계 — 어디서 찾아야 하는지 이미 아는 오퍼레이터(operator)

패키징된 형태부터 시작해야 목표를 보여줄 수 있습니다. agentproto에서 오퍼레이터(operator) (AIP-9 OPERATOR.md)는 페르소나에 정책, 그리고 일련의 바인딩된 도구(bound tools)가 결합된 것입니다. 이 도구 중 하나가 지식 바인딩입니다.

# operators/house-engineer/OPERATOR.md — persona + policies + a KB binding
---
name: House Engineer
...

이 knowledgeViews 블록이 무엇을 하는지 읽어보세요. 이 블록은 오퍼레이터를 당신의 엔지니어링 코퍼스(engineering corpus)로 범위 제한하며, 중요한 태그들로 필터링합니다. 페르소나는 어떻게 답변할지를 결정하고, 정책들은 무엇을 할 수 있는지 결정하며, 지식 뷰는 무엇을 알고 있는지를 결정합니다. 세 가지 분리된 관심사(concerns), 하나의 파일입니다.

이것은 모의(mock)가 아닌 실제 형태입니다. agentproto 자체 코퍼스(corpus)에 포함된 리서치 오퍼레이터(research operators)인 source-scout, research-analyst는 정확히 다음과 같은 구조를 가집니다: tools: [knowledge-query, ...]와 더불어 도메인 및 품질 점수(quality score)에 의해 범위가 지정된 metadata.corpus.knowledgeViews 바인딩입니다. 오퍼레이터는 _패키징(packaging)_입니다. 그 밑에는 도구(tool)가 있으며, 도구는 어떤 에이전트(agent)로든 이식될 수 있는 부분입니다.

**오퍼레이터는

출처(Provenance)는 장식이 아니라 기능입니다. 모든 항목은 그것이 추출된 런북(runbook), 인시던트(incident), 또는 PR(Pull Request)과 같은 source(출처)를 포함합니다. 이것이 바로 외부 검증 — 감독 사다리(supervision ladder)의 핵심 목적 — 이 나중에 답변을 검증할 수 있게 해줍니다. LLM-as-a-judge 문헌에서는 RAG(검색 증강 생성)를 두 가지 측면, 즉 입력되는 컨텍스트의 관련성(context relevance)과 출력되는 충실도(faithfulness)(답변이 실제로 검색된 출처를 따랐는가, 아니면 벗어났는가?)로 평가합니다. 출처가 없다면, 충실도 검증도 없습니다.

단 하나의 계약(contract), 단 하나의 드라이버(driver), 그리고 이제 데몬(daemon)을 탑재하는 모든 에이전트는 당신의 세계로부터 답변할 수 있습니다. 이를 서비스하세요.

3단계 — 당신의 지식이 있을 때와 없을 때, 동일한 질문

데몬을 시작합니다. 데몬은 당신의 tools/와 drivers/를 읽어 knowledge.search를 포함하여 MCP(Model Context Protocol)를 통해 제공합니다.

npm i -g @agentproto/cli
agentproto serve                 # 모든 에이전트에 /mcp 게이트웨이를 제공합니다

이제 도구가
있는 에이전트를 생성하고, 과거의 인시던트로 인해 설정된 컨벤션(convention)처럼 오직 당신의 문서로만 알 수 있는 것을 물어보세요:

agentproto sessions start codex --cwd . \
  --prompt "What's our retry policy for the payments queue? Use knowledge.search."

→ 인시던트 #2026-04(게이트웨이 타임아웃 시 이중 결제)에 따라, 결제 재시도는 지터(jittered)가 적용된 백오프(backoff)와 함께 최대 3회로 제한되며, 멱등성 키(idempotency key) 없이는 절대 결제를 재시도하지 않습니다. 출처: runbooks/payments-queue.md, incidents/2026-04.md

이제 동일한 에이전트에게 동일한 질문을, 도구
없이
물어보겠습니다:

agentproto sessions start codex --cwd . \
  --prompt "What's our retry policy for the payments queue?"

→ 일반적인 접근 방식은 3~5회의 재시도와 마지막 시도 후 데드 레터 큐(dead-letter queue)를 사용하는 지수 백오프(exponential backoff)입니다…

두 번째 답변이 틀린 것은 아닙니다. 그것은 인터넷의 평균일 뿐이며, 어디에서든 어떤 에이전트를 사용하더라도 얻게 될 결과물과 정확히 일치합니다. 첫 번째 답변은 당신이 4월에 배포했던 이중 결제 문제를 알고 있습니다. 왜냐하면 당신의 인시던트(incident) 파일을 읽었기 때문입니다. 그 차이(delta) — 즉, 지식 베이스(knowledge base)를 통해서만 배울 수 있는 실제 과거의 인시던트 — 가 바로 일반적인 에이전트와 당신만의 에이전트를 가르는 결정적인 차이입니다.

구조적으로 벤더에 종속되지 않음(Cross-vendor, by construction). 그것이 Codex였습니다. 동일한 데몬(daemon)에서 Claude Code를 가리키거나 Hermes를 통해 저렴한 로컬 모델을 가리키더라도, 이들은 동일한 knowledge.search를 호출합니다. 왜냐하면 이는 특정 벤더의 설정(config)에 내장된 것이 아니라 MCP를 통해 제공되기 때문입니다. KB(지식 베이스) 도구를 한 번만 작성하면, 당신의 플릿(fleet)에 있는 모든 에이전트가 당신의 세계를 상속받습니다.

Guilde의 평행 이론: 동일한 프리미티브(primitive), 패키징된 형태

솔직하게 말씀드리겠습니다. 과장하는 것은 독자를 잃는 지름길이기 때문입니다. 저희의 AI 기업 제품인 Guilde에서는 에이전트에 지식 베이스를 연결하는 것이 _하나의 패키징된 단계(one packaged step)_입니다. 즉, 오퍼레이터(operator)가 부착된 코퍼스(corpus)와 함께 배포되며, 단 한 번의 명령으로 특정 범위(scope)에 적용할 수 있습니다. 페르소나(Persona), 정책(policies), 지식(knowledge)이 한 번에 완료됩니다.

당신이 agentproto에서 수동으로 구축한 것은 바로 그 동일한 프리미티브를 한 단계 아래 수준에서 구현한 것입니다: 즉, 오퍼레이터(Step 1)와 제공되는 지식 도구(Step 2)의 조합입니다. Guilde는 이를 '한 번의 명령'으로 패키징한 것이며, agentproto는 별도의 플랫폼을 채택할 필요 없이 당신의 자체 리포지토리(repo)와 머신에서 오늘 바로 실행할 수 있는 '프리미티브로부터의 경로(from-primitives path)'입니다.

agentproto가 아직 _하지 못하는 것_을 솔직하게 밝힙니다. 오픈 CLI에는 단일 apply-knowledge-pack 동사가 없습니다. 당신은 도구(tool), 드라이버(driver), 오퍼레이터를 세 개의 파일로 직접 연결해야 합니다. 이는 패키징된 버전보다 조립(assembly) 과정이 더 많음을 의미합니다. 하지만 이는 또한 완전히 검사 가능하며 완전히 당신의 소유라는 것을 의미합니다. 에이전트에 연결할 가장 민감한 요소인 지식 베이스의 경우, 이는 종종 당신이 기꺼이 감수하고자 하는 트레이드오프(trade-off)이기도 합니다.

어느 쪽이든 프리미티브는 동일합니다: 쿼리가 가능한 지식 도구를 가진 오퍼레이터. 한 제품은 이를 패키징하여 제공하고, 다른 제품은 부품을 직접 전달합니다.

솔직한 한계점

지식 베이스 (Knowledge base)는 마법이 아니며, 세 가지 주의 사항이 이를 현실적으로 만들어 줍니다.

잘못된 지식 베이스 (KB)는 지식 베이스가 없는 것보다 더 나쁩니다. 만약 당신의 지식 베이스에 오래된 관습 (stale convention)이 포함되어 있다면, 에이전트는 이를 올바른 정보와 동일한 확신을 가지고 진술할 것입니다. 심지어 이제는 '출처'까지 첨부되어 있어, 더욱 설득력 있고 더욱 위험해집니다. 이것이 바로 앞서 언급한 충실도 검사 (faithfulness check)가 중요한 이유입니다. 검색 품질 (retrieval quality)이 승패를 결정짓는 핵심이며, 지식 베이스는 한 번 채워 넣으면 끝나는 양동이가 아니라 당신이 지속적으로 관리해야 하는 산물입니다.

에이전트가 스스로의 지식 베이스를 작성하게 두지 마세요. ETH Zurich의 연구 (Gloaguen et al.)에 따르면, LLM이 생성한 AGENTS.md 파일은 아무런 이득을 주지 못하며 오히려 성공률을 낮출 수 있음이 밝혀졌습니다. 실제 장애 사례 (incidents), 런북 (runbooks), 그리고 결정 사항들을 바탕으로 큐레이션된 지식 베이스는 당신의 것이지만, 에이전트가 스스로에 대해 환각 (hallucination)을 일으켜 만든 지식 베이스는 그저 당신의 리포지토리 (repo) 이름만 붙어 있는 인터넷의 평균치일 뿐입니다. 문서를 큐레이션하듯 지식 베이스를 큐레이션하세요. 왜냐하면 그것이 바로 지식 베이스의 본질이기 때문입니다.

그리고 이것은 당신이 연결할 가장 민감한 요소입니다. 당신의 장애 사례, 당신의 관습, 당신의 내부 결정 사항들 — 이것들은 바로 당신의 네트워크를 벗어나지 않기를 바라는 데이터들입니다. 위에서 언급한 network.egress: [] 드라이버는 단순한 세부 사항이 아닙니다. 이 패턴 전체가 로컬 (locally)에서 실행되어야 하는 이유입니다. 당신의 지식은 바로 그것이 비공개이기 때문에 당신만의 경쟁 우위가 되는 것이며, 따라서 그 지식을 제공하는 도구 또한 그 상태를 유지해야 합니다.

지식은 당신이 소유하는 부분입니다