본문으로 건너뛰기

Gemini CLI 사용자를 위해

GEMINI.md는 Gemini에게 여러분의 규칙을 알려줍니다.
코드는 알려주지 않습니다.

GEMINI.md는 작업 컨텍스트를 설정합니다. MCP는 Gemini가 도구에 손을 뻗을 수 있게 합니다. Maguyva는 Gemini에게 리포지토리의 조회 가능한 지도를 제공하는 MCP 서버이므로, 첫 편집이 파일 구조에 대한 추측으로 시작되지 않습니다.

무료로 시작하기Gemini 설정 방법 보기

Free 등급: 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄, 카드 등록 불필요.

GEMINI.md는 컨텍스트입니다. MCP는 통로입니다. Maguyva는 지도입니다.

레이어로 이루어진 스택

네 가지 개념. 각각 하나의 역할을 합니다.

// 컨텍스트

GEMINI.md

Gemini가 이 리포지토리에서 어떻게 행동해야 하는지.

// 전송 계층

MCP

Gemini가 외부 도구와 컨텍스트에 접근하는 방법.

// 코드베이스

Maguyva

근거 있는 리포지토리 사실을 반환하는 MCP 서버.

// 누가 비용을 내는가

좌석이 아니라 워크스페이스

에이전트는 좌석 비용을 내지 않습니다. 요금제 보기

GEMINI.md는 작업 컨텍스트입니다. 그대로 활용하세요.

영구적인 지침은 GEMINI.md에 두어야 합니다. 다음과 같은 내용에 적합한 곳입니다:

  • Gemini가 실행해야 할 빌드, 테스트, 린트 명령어.
  • 디렉터리 범위로 한정된 “항상 X를 해라 / 절대 Y를 하지 마라” 가드레일.
  • 네이밍 관례와 리팩터링 선호 방식.
  • 정본 의사결정 로그와 아키텍처 노트에 대한 링크.

간결하게 유지하세요. 범위를 정하세요. 커밋하세요.

하지만 GEMINI.md는 리포지토리의 모든 심볼, 파일, 호출 지점을 조회 가능한 인덱스로 담도록 설계된 적이 없습니다.

GEMINI.md 단독으로는 한계에 부딪히는 지점

네 가지 실패 양상, 카드마다 하나씩.

// 컨텍스트는 인덱스가 아닙니다

Gemini에게 어떻게 작업할지 알려주는 것은 무엇이 존재하는지 알려주는 것과 다릅니다. 낯선 패키지에서의 첫 편집은 파일 경로와 함수 이름에 대한 추측이 됩니다. GEMINI.md는 모든 심볼을 나열할 수 없고, 그러길 원하지도 않을 것입니다.

// 문서는 코드에서 멀어집니다

큐 토폴로지를 설명하는 GEMINI.md 블록은 누군가 새로운 컨슈머를 도입하기 전까지는 맞습니다. 이제 코드가 진실의 원천이고 문서는 확신에 찬 채로 낡아 있습니다. Gemini는 틀린 쪽을 읽습니다.

// 이름 변경은 그래프 문제입니다

“이 클래스를 참조하는 곳은 어디인가?”라는 질문은 마크다운 파일로는 답할 수 없습니다. Gemini는 모노레포 전체에 grep을 걸고 운에 맡기거나, 호출 지점을 채팅에 붙여넣어 달라고 요청합니다.

// 컨텍스트 윈도우는 공짜가 아닙니다

큰 윈도우가 조회 가능한 인덱스와 같은 것은 아닙니다. Gemini가 "충분히 안다"고 여길 때까지 GEMINI.md를 불러와도, 결국 추론 예산을 정적 컨텍스트 분량과 맞바꾸는 셈입니다.

세 레이어가 맞물리는 방식

Gemini 사용자는 이미 이런 구조로 생각하고 있습니다. 이 페이지는 그것을 명확하게 보여줄 뿐입니다.

GEMINI.md

컨텍스트

Gemini가 행동하는 방식

MCP

통로

접근하는 방식

Maguyva

코드베이스 사실

보는 것

  • GEMINI.md Gemini가 이 리포지토리에서 행동하는 방식.
  • MCP Gemini가 도구와 컨텍스트에 접근하는 방식. (스펙)
  • Maguyva Gemini가 코드베이스에 질문할 때 보는 것. 파일 경로와 줄 번호가 포함된 시맨틱, AST, 그래프, 텍스트 검색 결과입니다.

GEMINI.md는 Gemini에게 어떻게 작업할지 알려줍니다.

Maguyva는 Gemini에게 작업의 출발점을 제공합니다.

세 가지 워크플로

Gemini에 특화되어 있습니다. Gemini의 grep이 아니라 실제 호출 그래프에 근거합니다.

// workflow 01

공유 클래스 이름을 바꾸기 전에 모든 의존 항목부터 찾기

gemini> PaymentClient → BillingClient로 이름 변경

graph::callers(PaymentClient)            7개 패키지에 걸친 12개 참조
graph::importers(src/payments/client.ts)  9개 임포터
graph::extends(PaymentClient)             2개 서브클래스 (RetryClient, MockClient)

→ Gemini가 파일 목록을 인라인으로 포함한 21건의 편집 마이그레이션을 제안합니다.
[exit 0]

Gemini는 편집을 시작하기 전에 Maguyva에게 의존 항목을 요청합니다. 마이그레이션 목록은 Gemini의 기억이 아니라 실제 그래프에 근거해 돌아옵니다.

// workflow 02

테스트 스텁이 아니라 실제 구현 찾기

gemini> normalizePhoneNumber는 E.164를 어떻게 처리하나요?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← 실제 구현
  test/util/phone.spec.ts:14  jest.mock(...)      ← 스텁
[exit 0]

이름은 거짓말을 합니다. 목(mock)은 실제 코드를 가립니다. Maguyva는 테스트 목보다 실제 구현을 위에 올려 랭킹합니다.

// workflow 03

리팩터링 전에 영향 범위 확인하기

gemini> QueueDispatcher.publish를 호출하는 곳은 어디인가요?

graph::callers(QueueDispatcher.publish)
  3 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]

패키지를 넘나드는 호출 지점이 인라인으로 드러납니다. 변경 사항은 Gemini의 grep이 아니라 실제 임포터에 근거합니다.

Gemini CLI에서 설정하기

세 단계로 끝. Free 등급: 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄, 카드 등록 불필요.

  1. // step 01

    maguyva.ai에서 리포지토리 인덱싱하기

    답을 검증할 수 있도록 잘 아는 리포지토리를 선택하세요.

  2. // step 02

    Gemini CLI 설정에서 Maguyva를 MCP 서버로 추가하기

    // ~/.gemini/settings.json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

  3. // step 03

    이미 답을 알고 있는 질문 하나 해보기

    회사 전체로 시작하지 마세요. 리포지토리 하나와 검증 가능한 질문 하나로 시작하세요.

셀프서브 가입 가능.

이미 알고 있는 리포지토리 하나를 인덱싱하세요.

MCP를 통해 Gemini를 연결하세요. 답을 검증할 수 있는 질문 하나를 해보세요.

첫 저장소 인덱싱하기호환성 문서 보기

무료 플랜: 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄, 카드 등록 불필요.