# Maguyva의 작동 방식

Canonical source: https://maguyva.ai/ko/docs/how-it-works

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

GitHub 저장소를 연결하면 Maguyva가 이를 에이전트가 필요할 때 활용할 수 있는 여러 검색 가능한 뷰로 변환합니다. 파일 전체를 컨텍스트에 쏟아붓는 대신, 모델은 심볼, 구조, 문서, 의존성, 그리고 랭킹된 코드 조각을 실제 코드에 근거해 조회할 수 있습니다.

저장소를 연결하면 Maguyva는 코드, 문서, 매니페스트, 심볼, 의존성 메타데이터에 대해 클라우드 수집 파이프라인을 실행합니다. 목표는 모든 에이전트 실행이 저장소를 처음부터 다시 발견하게 하는 대신, 지속적인 코드 메모리를 한 번에 구축하는 것입니다.

이 파이프라인은 정확한 텍스트 검색, 시맨틱 검색, 심볼 및 참조 조회, 구조적 뷰, 의존성 그래프 분석 등 여러 전문 데이터 레이어를 만들어냅니다. 서로 다른 질문은 서로 다른 레이어로 라우팅됩니다.

Maguyva는 5가지 검색 기능을 제공합니다: semantic, AST, symbol, dependency, text. intelligent_search에서는 의미, 텍스트, 구조, 그래프의 네 가지 검색 방식을 사용할 수 있습니다. 기본 auto/balanced는 의도를 높은 확신으로 판별할 수 있는 정의 질문을 구조적 검색으로, 참조 또는 영향 질문을 그래프로, 정확히 일치하는 항목을 찾는 질문을 텍스트로 라우팅합니다. 그 외 질문에는 의미 기반 검색과 인덱싱된 텍스트를 사용합니다. 네 가지 검색 방식을 모두 요청하려면 mode=hybrid 또는 auto와 quality=thorough를 사용하세요. 명시적으로 지정한 mode가 quality보다 우선합니다. language_filter는 auto/hybrid에서 그래프를 제외하며, 명시적 mode=graph와 함께 사용하면 거부됩니다. 여러 방식의 결과를 통합하고 쿼리와의 관련성에 따라 순위를 매깁니다.

비공개 저장소 뷰는 지원되는 languages and text-based technologies에 대한 공개 참조 데이터와 나란히 제공됩니다. 에이전트는 MCP 도구를 통해 전체 시스템에 접근하며, 계획 및 검증 단계에서 적극적으로 활용하거나 편집 중 스팟 체크로 사용할 수 있습니다.

### 1. 저장소 수집

- **코드 구조 분석**: 파일을 심볼, 참조, 아키텍처 경계로 파싱합니다
- **의존성 해석**: 파일, 모듈, 심볼이 서로 어떻게 의존하는지 매핑합니다
- **문서 통합**: 저장소 문서와 관련 참조 자료를 코드와 함께 가져옵니다

### 라우팅과 랭킹

- **관련성 스코어링**: 검색 모드와 품질 프리셋에 따라 검색 근거를 선택한 뒤 쿼리 관련성에 따라 일치 항목의 순위를 매깁니다
- **노이즈 제거**: 중복 일치를 줄이고 파일별 청크 수를 제한하여 한 파일이 결과 창을 채우지 않도록 합니다
- **컨텍스트 우선순위 지정**: 기본적으로 결과 범위를 제한하고 관련성을 유지합니다. 중요도 부스팅은 아키텍처를 살펴볼 때 boost_by_importance=true로 명시적으로 활성화하는 옵션이며, 기본 순위 정책이 아닙니다

### 저장된 표현

- **시맨틱 검색**: 정확한 단어가 달라도 개념적으로 유사한 코드와 문서를 찾아냅니다
- **심볼 및 구조적 뷰**: 정확한 심볼 조회, 참조, AST 형태의 질문을 지원합니다
- **의존성 그래프 분석**: 코드베이스 전반에서 호출자, 임포트, 영향 범위를 추적합니다

### 보안 기능

- **전송 보안**: 서비스 연결은 HTTPS/TLS를 사용합니다
- **관리형 스토리지**: 인덱싱된 데이터는 저장 시 스토리지 수준 암호화가 적용된 관리형 인프라에 저장됩니다
- **네임스페이스 격리**: 저장소 데이터는 파이프라인과 데이터베이스 쿼리 경로 전반에서 워크스페이스와 네임스페이스 단위로 범위가 지정됩니다
- **접근 제어**: 저장소 접근은 조직 및 네임스페이스 경계에 의해 제한됩니다

### 기대할 수 있는 것

- **더 정확한 계획 수립**: 에이전트가 코딩을 시작하기 전에 실제 저장소를 기준으로 접근 방식을 검증할 수 있습니다
- **더 안전한 리팩터링**: 영향 범위와 의존성 점검을 통해 피할 수 있는 오류를 줄입니다
- **낮은 토큰 낭비**: 파일 전체 대신 관련 있는 조각만 반환됩니다
- **더 빠른 저장소 이해**: 모델이 매 실행마다 프로젝트 구조를 다시 파악하는 대신, 근거에 기반한 답을 빠르게 얻습니다

### 자동 업데이트

- **저장소 동기화**: 코드가 변경되면 GitHub 동기화 작업을 통해 갱신됩니다
- **증분 처리**: 효율성을 위해 변경된 파일만 처리합니다
- **브랜치 인식 컨텍스트**: git 브랜치별로 별도의 인덱스를 유지하여 에이전트가 각 브랜치에 맞는 컨텍스트를 보게 합니다

Maguyva는 클라우드 호스팅 MCP 서버 형태로 제공됩니다. 에이전트는 모델이 아키텍처를 처음부터 기억하는 데 의존하는 대신, 필요한 관점에 맞는 도구를 호출합니다. 위의 네 가지 영역은 구체적인 도구들을 묶어서 보여주는 뷰입니다: 시맨틱 검색은 `semantic_search`와 `intelligent_search`, 심볼 조회는 `find_symbol`과 `get_task_context`, 구조적 검색은 `structural_search`와 `text_pattern_search`, 의존성 그래프는 `dependency_search`와 `analyze_dependencies`를 포괄하며, 보조 유틸리티로 `get_file`, `repository_context`, `ask_maguyva`가 함께 제공됩니다. 전체 11개 도구는 [MCP API 레퍼런스](https://maguyva.ai/docs/mcp-api)를 참조하세요.

성능은 코드베이스 크기와 쿼리 복잡도에 따라 달라집니다. Maguyva는 파일 전체를 쏟아붓기보다 가장 관련성 높은 컨텍스트를 제공하는 데 집중합니다. 지원 언어 및 클라이언트는 [호환성](https://maguyva.ai/docs/compatibility)를 참조하세요.

결과는 코드베이스의 크기, 복잡도, 그리고 AI 에이전트가 처리하는 쿼리 유형에 따라 달라집니다.

Maguyva 포털에서 GitHub 저장소를 연결하세요. 코드가 변경되면 GitHub 동기화 작업을 통해 인덱스가 갱신됩니다. 포털에서 API 사용 현황도 확인할 수 있습니다.