코드베이스 메모리 및 그래프 인텔리전스 (codebase-memory)

코드베이스 메모리 및 그래프 인텔리전스 (codebase-memory)은(는) 무엇을 하나요?

이 스킬은 codebase-memory MCP 지식 그래프를 사용하여 코드를 탐색, 검색, 이해하기 위한 공학적 표준, 운영 절차 및 도구 사용 규약을 정의합니다.

---

핵심 불변 규칙: 인덱스 우선 프로토콜

[!CRITICAL] 인덱스 우선 불변 규칙: 활성 파일 편집 중 디스크 스래싱, zstd 직렬화 오버헤드 및 시스템 끊김을 방지하기 위해 이 워크스페이스에서는 백그라운드 감시 재인덱싱이 영구적으로 비활성화되어 있습니다 (auto_watch = false).

따라서, 에이전트는 코드 지식 그래프에 대한 검색을 실행하기 전에 반드시 인덱스의 최신 상태를 확인하거나 온디맨드 재인덱싱(index_repository)을 트리거해야 합니다.

심볼 찾기, 모듈 이해, 버그 조사, 리팩토링 준비 등의 작업을 할 때는 항상 검색 호출 전에 **인덱스 우선 관문(Index-First Gate)**을 실행하세요.

---

도구 계층 구조: 그래프 우선, 그렙 차선

코드를 발견, 탐색 또는 검토할 때는 다음 우선 순위 계층 구조를 엄격히 준수하세요:

flowchart TD
    Task[코드 발견 / 조사 작업] --> Freshness{인덱스가 최신인가?}
    Freshness -->|아니오 / 알 수 없음 / 편집 후| Sync[index_repository mode: 'fast' 또는 'moderate']
    Freshness -->|예| Strategy{쿼리 유형}
    Sync --> Strategy

    Strategy -->|심볼 / 함수 / 인터페이스| SearchGraph[search_graph BM25 또는 semantic_query]
    Strategy -->|호출자 / 피호출자 / 의존성| TracePath[trace_path callers / callees]
    Strategy -->|변경 영향 범위| DetectChanges[detect_changes diff to impact set]
    Strategy -->|정확한 소스 코드| GetSnippet[get_code_snippet 정밀 라인]
    Strategy -->|시스템 계층 및 허브 모듈| GetArch[get_architecture 높은 중심성 노드]
    Strategy -->|리터럴 문자열 / 비코드 / 에셋| GrepFallback[search_code 또는 run_command grep]

1. search_graph > 텍스트 그렙: 카멜케이스 분할, 레이블 가중치(함수 +10, 경로 +8, 인터페이스 +5) 및 벡터 임베딩을 사용하는 BM25 순위 구조 검색.
2. trace_path > 수동 파일 이동: 다중 홉 호출자 및 피호출자 그래프를 즉시 해석합니다.
3. get_code_snippet > 대용량 파일의 view_file: 시작/종료 라인과 호출자 수를 포함하여 심볼의 정확한 선언과 본문을 검색하며, 에이전트 컨텍스트를 부풀리지 않습니다.
4. detect_changes > 수동 diff 검사: Git diff(since: "HEAD~1", base_branch: "main")를 해당 변경 사항의 전이적 영향 범위에 직접 매핑합니다.
5. 그렙 대체 사용: search_code 또는 run_command(git grep, rg)는 다음 경우에만 사용합니다:
   • 마크다운(.md), 설정(.json) 또는 스타일시트(.css)의 리터럴 텍스트.
   • index_status에서 parse_partial로 명시적으로 플래그된 라인 범위.
   • .cbmignore를 통해 설계상 제외된 파일.

---

표준 운영 워크플로우

1단계: 인덱스 동기화 관문 (필수 첫 번째 작업)

검색 쿼리를 실행하기 전에, 프로젝트 이름을 확인하고 그래프가 최근 파일 시스템 편집 내용을 반영하는지 확인하세요.

1. 프로젝트 이름 식별: 프로젝트 식별자를 모르는 경우 list_projects를 호출하세요:

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   (이 워크스페이스에서 파생된 프로젝트 이름은 "D-Scripts-aminwebsite"입니다.)

2. 상태 확인 또는 인덱스 새로고침: 세션 중에 파일이 생성되거나 수정된 경우 index_repository를 호출하세요:

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • 모드 선택:
     • mode: "fast": 증분 파싱, 필터링된 파일, 시맨틱 벡터 임베딩 없음. 활발한 개발에 적합하며 빠르고 가볍습니다.
     • mode: "moderate": 증분 파싱 + 자연어 개념 연결을 위한 벡터 유사도 임베딩.
   • 커버리지 검사: 응답에서 다음을 확인하세요:
     • parse_partial: 특정 라인 범위에서 파싱 오류가 발생한 파일.
     • skipped: 완전히 건너뛴 파일(예: 바이너리 또는 초대형 파일).

---

2단계: 심볼 및 구조 발견 (search_graph)

함수, 인터페이스, 타입, 컴포넌트 및 경로 정의를 찾습니다.

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• 자연어 발견: 키워드 / BM25 검색에는 query를 사용하세요(예: "theme toggle transition", "locale routing").
• 정확한 이름 패턴: 정규식 필터링에는 name_pattern을 사용하세요(예: ".*Provider.*", ".*Skeleton.*").
• 시맨틱 개념 검색: semantic_query: ["i18n", "language", "switch"](문자열 배열 필요)를 사용하여 어휘 차이를 연결하세요.
• 잘림 처리 (has_more): 응답에서 "has_more": true가 반환되면 "offset": <현재 offset + limit>를 추가하여 페이지네이션하세요.

---

3단계: 관계 추적 및 영향 범위

그 종속성을 검사하지 않고 함수나 인터페이스를 수정하지 마십시오.

1. 호출자 및 피호출자 추적 (trace_path):

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound": 이 함수에 의존하는 모든 호출자를 식별합니다(영향 범위).
   • direction: "outbound": 이 심볼이 호출하는 다운스트림 함수를 식별합니다.
   • direction: "both": 양방향 전체 호출 체인.

2. Git Diff 영향 세트 매핑 (detect_changes): 변경 사항을 커밋하거나 마무리하기 전에 영향 범위를 평가하세요:

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

4단계: 정밀 코드 검색 (get_code_snippet)

view_file로 전체 파일을 보면서 컨텍스트를 소비하는 대신, 정확한 심볼 구현을 검색하세요:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

응답에는 다음이 포함됩니다:

• 정확한 start_line 및 end_line
• 심볼의 깨끗한 소스 코드
• 직접 호출자 및 피호출자 수

---

5단계: 고수준 아키텍처 탐색 (get_architecture)

새로운 하위 시스템에 적응하거나 시스템 토폴로지를 이해할 때:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

최상위 아키텍처 허브 컴포넌트, 중앙 의존성 및 계층 계층 구조를 식별합니다.

---

MCP 지연 도구 참조 매트릭스

기능	도구 이름	필수 매개변수	주요 선택적 매개변수
상태 확인	index_status	project	N/A
인덱싱 트리거	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
프로젝트 목록	list_projects	없음	N/A
심볼 검색	search_graph	project	query, name_pattern, semantic_query, limit, offset
호출 체인 추적	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
소스 검색	get_code_snippet	project, qualified_name	include_neighbors
영향 범위 분석	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
아키텍처 탐색	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
리터럴 텍스트	search_code	project, query	file_pattern, case_sensitive, limit

---

가드레일 및 일반적인 안티패턴

안티패턴	올바른 운영 표준
인덱스 최신 상태 확인 없이 검색	백그라운드 자동 감시가 비활성화되어 있으므로 항상 먼저 index_repository(mode: "fast")를 호출하거나 index_status로 확인하세요.
함수 정의를 찾기 위해 grep 사용	심볼 이름으로 search_graph를 호출하면 정규화된 이름, 정확한 파일 경로, 라인 범위 및 호출자 수가 반환됩니다.
하나의 함수를 보기 위해 파일 1000줄 읽기	심볼의 qualified_name으로 get_code_snippet을 호출하세요.
호출자를 찾기 위해 모든 파일을 직접 읽기	direction: "inbound"와 함께 trace_path를 호출하세요.
그래프가 100% 완전하다고 가정	그래프는 최선의 노력(best-effort)입니다. index_status에 parse_partial 아래 파일이 나열된 경우, 해당 플래그된 라인 범위에 대해서만 텍스트 그렙을 사용하세요.
auto_watch 활성화	절대로 auto_watch를 활성화하지 마십시오. 최상의 대화형 개발 성능을 유지하려면 false로 유지하세요.