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

Canonical source: https://maguyva.ai/ko/for-gemini

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).

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

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

## 레이어로 이루어진 스택

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

### GEMINI.md

Gemini가 이 저장소에서 어떻게 행동해야 하는지.

### MCP

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

### Maguyva

근거 있는 저장소 사실을 반환하는 MCP 서버.

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

에이전트는 좌석 비용을 내지 않습니다. [요금제 보기](https://maguyva.ai/ko/pricing)

## 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가 도구와 컨텍스트에 접근하는 방식. [(스펙)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: Gemini가 코드베이스에 질문할 때 보는 것. 파일 경로와 줄 번호가 포함된 시맨틱, AST, 그래프, 텍스트 검색 결과입니다.

> GEMINI.md는 Gemini에게 *어떻게 작업할지* 알려줍니다.
> Maguyva는 Gemini에게 *작업의 출발점*을 제공합니다.

## 세 가지 워크플로

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

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

```text
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의 기억이 아니라 실제 그래프에 근거해 돌아옵니다.

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

```text
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는 테스트 목보다 실제 구현을 위에 올려 랭킹합니다.

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

```text
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만 줄, 카드 등록 불필요.

### 01. maguyva.ai에서 저장소 인덱싱하기

답을 검증할 수 있도록 잘 아는 저장소를 선택하세요.

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

`~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}
```

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

회사 전체로 시작하지 마세요. 저장소 하나와 검증 가능한 질문 하나로 시작하세요.

## 이미 알고 있는 저장소 하나를 인덱싱하세요.

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