# GEMINI.md beritahu Gemini peraturan anda. Bukan kod anda.

Canonical source: https://maguyva.ai/ms/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 tetapkan konteks kerja. MCP bagi Gemini capai alat. Maguyva ialah pelayan MCP yang bagi Gemini peta repo anda yang boleh ditanya, supaya suntingan pertama bukan tekaan struktur fail.

> GEMINI.md konteksnya. MCP saluran perantaraannya. Maguyva petanya.

## Stack berlapis

Empat idea. Setiap satu buat satu kerja.

### GEMINI.md

Macam mana Gemini patut berkelakuan pada repo ini.

### MCP

Macam mana Gemini mencapai alat luaran dan konteks.

### Maguyva

Pelayan MCP yang pulangkan fakta repo yang terbukti.

### Ruang kerja, bukan pengguna

Tiada caj per pengguna untuk ejen. [Lihat harga](https://maguyva.ai/ms/pricing)

## GEMINI.md ialah konteks kerja. Gunakannya.

Arahan kekal patut berada dalam `GEMINI.md`. Ia tempat yang betul untuk:

- Arahan binaan, ujian, dan lint yang Gemini patut jalankan.
- Sekatan “sentiasa buat X / jangan sekali buat Y” yang terhad kepada satu direktori.
- Konvensyen penamaan dan keutamaan refactor.
- Petunjuk kepada log keputusan kanonik dan nota seni bina.

Kekalkan ia ringkas. Skopkan ia. Commit ia.

Tapi `GEMINI.md` tak pernah direka untuk jadi indeks yang boleh ditanya untuk setiap simbol, fail, dan tapak panggilan dalam repo anda.

## Di mana GEMINI.md sahaja tidak lagi mencukupi

Empat mod kegagalan, satu setiap kad.

### // konteks bukan indeks

Beritahu Gemini *macam mana nak bekerja* tak beritahu ia *apa yang wujud*. Suntingan pertama pada pakej yang tak biasa adalah tekaan tentang laluan fail dan nama fungsi. GEMINI.md tak boleh senaraikan setiap simbol, dan anda pun tak nak ia begitu.

### // dokumen menyimpang daripada kod

Blok GEMINI.md yang terangkan topologi queue anda betul sehingga seseorang perkenalkan consumer baharu. Kod kini sumber kebenaran dan dokumen itu basi dengan yakin. Gemini baca yang salah.

### // tukar nama ialah masalah graf

“Apa yang rujuk class ini?” tak boleh dijawab daripada fail markdown. Gemini sama ada grep-and-berharap merentasi monorepo atau minta anda tampal tapak panggilan ke dalam chat.

### // tetingkap konteks bukan percuma

Tetingkap konteks yang besar tak sama dengan indeks yang boleh ditanya. Muatkan GEMINI.md sehingga Gemini “cukup tahu” tetap tukar bajet penaakulan dengan jumlah konteks statik.

## Macam mana tiga lapisan ini bercantum

Pengguna Gemini dah pun berfikir dalam bentuk ini. Halaman ini patut jelaskannya.

- **GEMINI.md**: konteks (macam mana Gemini berkelakuan)
- **MCP**: saluran (macam mana ia mencapai alat)
- **Maguyva**: fakta pangkalan kod (apa yang ia nampak)

- **GEMINI.md**: macam mana Gemini berkelakuan pada repo ini.
- **MCP**: macam mana Gemini mencapai alat dan konteks. [(spesifikasi)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: apa yang Gemini nampak bila ia tanya pangkalan kod satu soalan. Carian semantik, AST, graf, dan teks dipulangkan dengan laluan fail dan nombor baris.

> GEMINI.md beritahu Gemini *macam mana nak bekerja*.
> Maguyva bagi Gemini *sesuatu untuk dijadikan asas kerja*.

## Tiga aliran kerja

Khusus Gemini. Terbukti berdasarkan graf panggilan sebenar, bukan grep Gemini.

### 01. Tukar nama class yang dikongsi, cari setiap dependen dahulu

```text
gemini> tukar nama PaymentClient → BillingClient

graph::callers(PaymentClient)            12 rujukan merentasi 7 pakej
graph::importers(src/payments/client.ts)  9 pengimport
graph::extends(PaymentClient)             2 subkelas (RetryClient, MockClient)

→ Gemini cadangkan migrasi 21-suntingan dengan senarai fail terus.
[exit 0]
```

Gemini tanya Maguyva untuk dependen *sebelum* ia mula menyunting. Senarai migrasi berdasarkan graf sebenar, bukan ingatan Gemini.

### 02. Cari implementasi sebenar, bukan stub ujian

```text
gemini> macam mana normalizePhoneNumber uruskan E.164?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← impl sebenar
  test/util/phone.spec.ts:14  jest.mock(...)      ← stub
[exit 0]
```

Nama boleh menipu. Mock membayangi kod sebenar. Maguyva susun implementasi sebenar di atas mock ujian.

### 03. Semak lingkungan impak sebelum refactor

```text
gemini> apa yang panggil QueueDispatcher.publish?

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

Tapak panggilan merentas pakej tertonjol terus. Diff itu berasaskan pengimport sebenar, bukan grep Gemini.

## Sediakan Gemini CLI

Tiga langkah. Peringkat Free: 3 repositori, Sehingga 50K baris repo terindeks, tanpa kad.

### 01. Indeks repo di maguyva.ai

Pilih satu yang anda kenal betul-betul, supaya anda boleh sahkan jawapannya.

### 02. Tambah Maguyva sebagai pelayan MCP dalam tetapan Gemini CLI anda

`~/.gemini/settings.json`

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

### 03. Tanya satu soalan yang anda dah tahu jawapannya

Jangan mula dengan seluruh syarikat anda. Mula dengan satu repo dan satu soalan yang boleh disahkan.

## Indeks satu repo yang anda dah kenal.

Sambung Gemini melalui MCP. Tanya satu soalan yang anda boleh sahkan jawapannya.