「움직이는 지식 기반」을 「사용되는 도구」로 만들기 — VSCode 플러그인 + MCP의 제로 설정 설계

지난 기사에서는 MCP × bge-m3를 활용한 사내 지식 기반(Knowledge Base)을 구축한 이야기를 썼습니다. 하지만 기술적으로 동작하는 것과 실제로 팀에서 사용되는 것은 별개의 문제입니다. 이 기사는 「동작하는 것」을 「사용되는 것」으로 바꾸기 위한 설계에 관한 이야기입니다.

도구가 사장되는 이유는 「도입 마찰」

사내 도구가 죽는 가장 흔한 방식은 **「모두가 좋다고 말하지만, 아무도 사용하지 않는다」**입니다. 플러그인 설치, MCP 설정, 지식 기반 연결——어느 한 곳이라도 번거로우면 사용자는 「좋네, 다음에 써봐야지」라고 말하며 멈춰 서고, 다시는 시도하지 않습니다.

따라서 승부처는 「설득」이 아니라, 도입 마찰을 거의 제로(Zero)로 만드는 것입니다.

3개 층으로 디커플링(Decoupling)하기

설계의 중추는 업데이트 빈도가 다른 것들을 3개 층으로 나누어 느슨하게 결합(Loosely Coupled)하는 것입니다.

층	내용	업데이트 빈도
콘텐츠 층	지식 (md) + git	높음 (규범이 바뀔 때마다)
능력 층	MCP + 파서 (Parser)	낮음
액세스 층	VSCode 플러그인	낮음

포인트는 「플러그인 업데이트」와 「지식 업데이트」를 절대로 결합시키지 않는 것입니다. 규범을 미세하게 수정할 때마다 플러그인을 재배포한다면, 운영은 파탄 나고 「제로 설정 운영」은 무너집니다. 플러그인은 기동 시에 최신 지식 버전을 자동으로 가져오는 설계로 하여, 지식이 바뀌어도 사용자는 아무것도 하지 않아도 되는 상태로 만듭니다.

제로 설정 = 「설치하면 즉시 사용 가능」

「원클릭 설치」가 정말로 효과를 발휘하는 것은 설치하는 그 순간이 아니라, 설치한 후에 아무런 설정도 필요 없다는 점입니다.

• API 키를 입력하지 않는다
• 모델을 선택하지 않는다
• 프로젝트 경로를 매칭시키지 않는다

「설치하면 즉시 사용 가능」——이것이 외부 사용자가 정말로 사용해 줄 것인가를 결정짓는 경계선입니다.

md + git을 지식과 의사결정 기록 모두에 사용하기

• 지식 원천을 md로, 버전을 git으로 관리. 규범·토큰·컴포넌트 문서의 변경이 모두 diff·이력·롤백(Rollback) 가능해짐
• 「지식 기반이 업데이트되었다」는 것이 git 상의 1회의 업데이트로서 명확하게 추적 가능
• 의사결정 기록도 md로 하여, 지식과 동일한 버전 관리에 포함. 기록이 별도로 관리되지 않음

MCP는 로컬 프로젝트의 지식 기반 역할도 담당

VSCode 플러그인과 MCP는 역할이 다릅니다.

• 플러그인: 코드를 작성하면서 사내 규범을 참조하거나 / 컴포넌트 코드를 생성함
• MCP: AI 에이전트에게 「이 프로젝트의 로컬 문맥(Context)」을 이해시킴

두 가지는 서로 다른 용도를 담당하므로, 둘 다 구현하는 것은 올바르며 충돌하지 않습니다.

채택 전략: 전사 일제 도입을 하지 않는다

지식 관리 시스템은 「전사적으로 사용하지 않으면 가치가 나오지 않는다 → 전사 도입에는 부장·임원급의 정치적 자본이 필요하다 → 거기서 막힌다」라는 방식으로 사장됩니다. 이를 피하기 위한 설계로 만들었습니다.

• 단일 팀에서 즉시 성립: 전사 일제 도입을 필요로 하지 않음
• 바텀업(Bottom-up)으로 자연 확산: 사용하면 이득을 보는 팀으로부터 자발적으로 퍼짐
• 외부 이용이 내부 채택을 견인: 컴포넌트 라이브러리를 사용 중인 외부 프로젝트가 이 도구를 채택하면, 그것이 내부 채택을 이끌어냄

첫 번째 단계는 「넓게 공표하고 자발적으로 오기를 기다리는 것」이 아니라, 협력적인 프로젝트를 1~2개 선정하여 직접 연결까지 챙겨주며, "사용해서 효과가 나오고 있다"는 견본을 하나 만드는 것이라고 생각합니다.

기업 지식 기반의 전형적인 사인과 이 설계의 대응

| 전형적인 사인 | 이 설계에서의 회피 |
| :--- | : |
| 외부 API 의존 → 비용 통제 불능·데이터 유출 | bge-m3 ONNX의 로컬 추론·완전 오프라인 |
| 순수 벡터 검색 → 정확도 부족 | 어휘 + 의미의 하이브리드 + 의도 강하(Intent Downgrading) 방지 |
| 수동 유지보수 → 아무도 업데이트하지 않음 | git hook으로 자동 동기화 |
| 전사 도입이 전제 → 정치적 문제로 막힘 | 단일 팀에서 성립, 바텀업 |
| 기술 스택 고정 → 한 팀밖에 구제 못 함 | 플러그형(Pluggable) 파서 |
| 느림 → 사용자가 이탈함 | 약 50ms/query |
| 지표가 없음 → 가치를 증명할 수 없음 | P@1·토큰(Token) 절감률·지연 시간(Latency) 등 모두 정량화 |

기술적으로 동작하는 것을 만드는 것은 절반입니다. 나머지 절반은 마찰을 없애고, 층을 디커플링하며, 단일 팀으로부터 자연스럽게 퍼지는 경로를 설계하는 것입니다. 후자를 설계에 녹여내야 비로소 지식 기반은 「계속 사용되는 도구」가 됩니다.