vlm-code-context-mcp

완벽한 AI 엔지니어링 팀. 하나의 npm 패키지. 낭비되는 컨텍스트 제로.

📖 시작하기 가이드 — 처음이신가요? 여기서 시작하세요!

제품 책임자(PO). 아키텍트. QA. 보안. 개발자 2명. 스크럼 마스터. 관리자. 리드 개발자. 모두 실제 스프린트를 실행합니다. 모두 당신의 코드베이스와 대화합니다. 모두 단일 SQLite 데이터베이스 안에 있습니다.

npm install vlm-code-context-mcp
npx code-context-mcp setup .
npx code-context-dashboard ./context.db

이 프로젝트의 존재 이유

모든 AI 코딩 도구는 같은 벽에 부딪힙니다. 모델이 유용한 작업을 수행하기 전에 코드베이스를 읽는 것만으로도 컨텍스트 창을 모두 소모해 버립니다. 세션이 끝나면 다음번에 다시 처음부터 시작해야 합니다.

두 번째 문제는 더 심각합니다. 프로세스가 없다는 점입니다. 무엇을, 어떤 순서로, 왜 만들어야 하는지 전혀 모르는 유능한 AI만 남게 됩니다.

vlm-code-context-mcp는 이 두 가지 문제를 모두 해결합니다. 프로젝트 전체를 구조화된 SQLite 데이터베이스로 미리 인덱싱하여 에이전트가 원시 소스 대신 메타데이터를 쿼리하도록 합니다. 224개 파일로 구성된 코드베이스에서 토큰은 25배 적게, 데이터는 26배 적게 사용합니다. 또한 81개의 MCP 도구를 통해 실제 스프린트 의례를 실행하고, 단계별 게이트, 회고, 속도 추적 및 실시간 React 대시보드를 제공하는 완전한 가상 스크럼 팀으로 이 지능을 감쌉니다.

이것은 Claude가 결합된 단순한 작업 추적기가 아닙니다. AI 기반 개발을 위한 운영 체제입니다.

60초 만에 얻을 수 있는 것

Step 1/4 — Indexing files into context.db...
  Indexed 25 files, 142 exports, 87 dependencies

Step 2/4 — Loading scrum schema...
  Created 10 scrum tables

Step 3/4 — Importing team from .claude/agents/...
  Loaded 9 agents, 3 sprints, 24 tickets

Step 4/4 — Writing .mcp.json...
  Configured MCP server entry

=== Setup complete! (my-project) ===

그런 다음 대시보드를 엽니다:

npx code-context-dashboard ./context.db
# Opens at http://localhost:3333

이게 전부입니다. 당신의 AI 팀이 준비되었습니다. API 키도, 외부 서비스도, 클라우드 의존성도 없습니다. 모든 것이 context.db 안에 존재합니다.

팀 구성

각 에이전트는 정의된 역할, 시스템 프롬프트, 책임 범위 내의 도구 접근 권한을 가지며, 티켓 부하와 회고 감정을 바탕으로 도출된 기분 점수를 가집니다. 시스템은 스프린트 전반에 걸쳐 번아웃 신호를 추적합니다.

스프린트 프로세스

스프린트는 자동화된 게이트 체크가 포함된 10개의 강제 단계를 통해 실행됩니다:

preparation → kickoff → planning → implementation → qa → refactoring → retro → review → closed → rest

게이트는 실질적입니다. 티켓이 할당되고 추정되지 않으면 스프린트는 QA 단계로 넘어가지 않습니다. 회고 결과가 기록되지 않으면 스프린트는 종료되지 않습니다. 속도는 모든 스프린트에서 자동으로 추적되며 대시보드에 표시됩니다.

대시보드

6개 페이지. 68개 컴포넌트. 실시간 SSE 업데이트.

티켓 상태 변경, 에이전트 기분 업데이트, 스프린트 단계 전환 등 모든 변경 사항은 SQLite WAL 모니터링을 통해 즉시 대시보드 새로고침을 트리거합니다. 폴링도, 수동 새로고침도 필요 없습니다.

• 스프린트 보드 — 칸반, 계획 보기, QA 게이트 추적기, 번다운 차트

• 코드 탐색기 — 파일 트리, 종속성 그래프, 내보내기/가져오기 맵, 변경 이력

• 프로젝트 관리 — 간트 타임라인, 마일스톤 추적기, 발견 파이프라인, 비전 편집기

• 팀 — 에이전트 상태 카드, 기분 추세, 업무 분담

• 회고 — 카테고리별 결과, 스프린트 간 패턴 분석, 작업 추적

• 마케팅 — 릴리스 노트, 포지셔닝, Remotion 비전 애니메이션

📸 [스크린샷] 📸 [스크린샷]

브리지 계층

에이전트 도구에서 가장 어려운 문제는 양방향 통신, 즉 UI와 AI가 실시간으로 실제로 대화하게 만드는 것입니다.

src/bridge/는 Claude Code를 대시보드에 연결하는 PreToolUse 훅을 구현합니다. UI에서 대기열에 추가된 작업은 실행 중인 Claude Code 세션에 의해 처리됩니다. 이것이 팀을 정적인 보드가 아닌 살아있는 것처럼 느끼게 만드는 요소입니다.

이 부분은 여전히 강화 작업 중입니다. PR을 환영합니다.

컨텍스트 효율성

이 프로젝트 자체 코드베이스(224개 파일, 54K 라인, 2.1 MB)에서 측정된 결과:

방법론: "기능 이해 및 수정" 작업 — 관련 파일 찾기, 내보내기/가져오기/종속성 이해, 최근 변경 사항 검토. MCP가 없으면 에이전트는 약 20개의 원시 파일(평균 9,200자)을 읽습니다. MCP를 사용하면 원시 소스 대신 search_files, find_symbol, get_file_context를 통해 구조화된 메타데이터(요약, 내보내기 목록, 종속성 그래프)를 쿼리합니다.

첫 번째 인덱싱은 비용이 더 듭니다(메타데이터 생성을 위해 파일을 읽어야 함). 이후의 모든 쿼리는 25배 더 저렴합니다. 1회 사용 후 손익분기점에 도달합니다. 절감 효과는 코드베이스 크기에 따라 확장됩니다. 25개 파일 프로젝트는 3배 감소, 224개 파일 프로젝트는 25배 감소를 보입니다.

한눈에 보기

프로젝트 이력

자체 스크럼 프로세스를 통해 완전히 구축되었습니다. 가상 팀은 총 22개의 마일스톤, 69개의 생산적인 스프린트, 211개의 티켓을 완료했으며, 총 534개의 스토리 포인트를 달성했고 스프린트당 약 20포인트의 롤링 속도를 유지하고 있습니다.

19개 스프린트에 걸친 회고 결과

잘된 점 (주요 패턴):

• 발견 우선 접근 방식은 낭비되는 구현을 지속적으로 제거했습니다. 코드를 작성하기 전에 3~4가지 접근 방식을 스파이킹하여 재작업 시간을 절약했습니다(S59, S65, S68).

• 병렬 에이전트 실행은 구현 시간을 획기적으로 단축했습니다. 메인 스레드가 조정하는 동안 4명의 에이전트가 독립적인 티켓을 동시에 작업했습니다(S59, S65, S67).

• 코드 작성 전 연구는 막다른 길을 조기에 발견했습니다. S68은 3가지 후보 브리지 접근 방식(명명된 파이프, 유닉스 소켓, MCP 리소스 구독)을 며칠이 아닌 몇 시간 만에 제거했습니다.

• 스키마 마이그레이션 패턴(schema_versions 테이블)은 점진적인 DB 변경을 안전하고 반복 가능하게 만들었습니다. 7번의 스키마 추가 전반에 걸쳐 회귀 오류가 전혀 없었습니다(S53, S55).

• 병렬 보안 감사는 코드가 배포되기 전에 2개의 HIGH 등급 취약점을 발견했습니다(S68). 구현 후가 아닌 구현과 함께 감사를 실행하는 것이 올바른 패턴입니다.

잘못된 점 (주요 패턴):

• 테스트를 실행하지 않고 완료(DONE)로 표시. 에이전트가 테스트를 작성했지만 실행할 수 없었습니다. 완료로 표시하기 전에 빌드 검증이 이루어져야 합니다(S61, S65, S66).

• 기존 테스트 실패가 실제 회귀를 가리는 노이즈를 생성했습니다. 오래된 스키마 변경으로 인한 낡은 테스트가 계속 나타났습니다(S53, S67, S68).

• 발견 속도가 오해를 불러일으켰습니다. S56은 46sp를 커밋했지만 모든 티켓이 문서화 전용이었습니다. 발견 포인트는 구현과 별도로 추적되어야 합니다.

• 설명이나 수락 기준이 없는 일반적인 티켓 제목은 QA를 불가능하게 만들었습니다. 모든 티켓은 구체적인 범위가 필요합니다(S53).

• 프론트엔드 기술 부채 누적 — 800줄 이상의 컴포넌트, 850개 이상의 인라인 스타일, 테스트 제로. 더 일찍 해결했어야 했습니다(S59).

다음 시도 (주요 실행 항목):

• 각 에이전트가 완료한 후, 티켓을 완료로 표시하기 전에 npm run build를 실행하세요(S65, S66, S67).

• 생성 시 모든 티켓에 수락 기준을 추가하세요(S55).

• 수정 티켓을 생성하기 전에 현재 상태를 확인하세요. 이미 해결된 경우가 있었습니다(S58).

• 모든 새로운 write-MCP-도구는 SSE 알림을 트리거해야 합니다. 체크리스트 항목으로 추가하세요(S53).

• API가 안정화되면 진정한 푸시 기반 브리지 신호를 위해 채널을 구현하세요(S68).

• 발견 포인트를 구현 속도와 별도로 추적하세요(S56).