使用 AGENTS.md 檔案自訂 Gemini

使用一或多個 AGENTS.md 檔案，為 Gemini 版 Android Studio 提供自訂指令。AGENTS.md 檔案會與程式碼基底中的其他檔案放在一起，因此您可以輕鬆將這些檔案簽入版本控管系統 (VCS)，並與整個團隊分享專案專屬的操作說明、程式碼樣式規則和其他指引。

首先，請按照下列步驟操作：

  1. 在專案的檔案系統中，於任意位置建立 AGENTS.md 檔案。提交查詢時，Gemini 會掃描目前目錄和所有上層目錄中的 AGENTS.md 檔案。詳情請參閱「AGENTS.md 檔案的運作方式」。

  2. 新增指示。使用 Markdown 撰寫操作說明。為方便閱讀，建議使用標題和項目符號列出不同規則。查看範例操作說明。

  3. 將檔案儲存並提交至 VCS，與團隊共用。

管理 AGENTS.md 檔案做為背景資訊

您可以使用對話面板中的「內容」抽屜，套用或移除 AGENTS.md 檔案，做為特定查詢的背景資訊。「檔案」AGENTS.md選項包含目前目錄及其上層目錄中的所有 AGENTS.md 檔案。

將 AGENTS.md 檔案做為背景資訊管理
圖 1. 將 AGENTS.md 檔案做為背景資訊。

範例操作說明

你可以使用 AGENTS.md 檔案向代理程式提供指令。以下列舉部分範例，但您提供的操作說明應適用於您的專案。

  • 「主要活動為 /path/to/MainActivity.kt。」
  • 「支援在畫面之間導覽的程式碼是 path/to/navigation/UiNavigation.kt」
  • 「處理 HTTP 要求的程式碼位於 <path>。」
  • 專案架構
    • 「將所有商業邏輯放在 ViewModel 中。」
    • 「請務必遵循官方架構建議，包括使用分層架構。使用單向資料流 (UDF)、ViewModel、生命週期感知方法收集 UI 狀態，以及其他建議。」
  • 偏好的程式庫：「使用 <程式庫名稱> 程式庫進行導覽。」
  • 為常見的 API 服務或內部術語定義預留位置名稱：「主要後端服務稱為『PhotoSift-API』。」
  • 公司樣式指南：「所有新的 UI 元件都必須使用 Jetpack Compose 建構。請勿建議以 XML 為基礎的版面配置。

將 AGENTS.md 檔案模組化

您可以將大型 AGENTS.md 檔案細分成較小的檔案，以便在不同情境中重複使用：

  1. 將一組指令分開，並儲存到另一個 Markdown 檔案，例如 style-guidance.md。

  2. 在 AGENTS.md 檔案中參照較小的 Markdown 檔案，方法是使用 @ 符號，後面加上要匯入的檔案路徑。系統支援下列路徑格式：

    • 相對路徑：
      • @./file.md - 從相同目錄匯入
      • @../file.md - 從父項目錄匯入
      • @./subdirectory/file.md - 從子目錄匯入
    • 絕對路徑：@/absolute/path/to/file.md

舉例來說，下列 AGENTS.md 檔案會參照另外兩個指令檔案：

# My AGENTS.md

You are an experienced Android app developer.

@./get-started.md

## Coding style

@./shared/style-guidance.md

AGENTS.md 檔案的運作方式

Gemini 會自動掃描目前目錄和上層目錄中的 AGENTS.md 檔案，並將檔案內容新增至每個提示的開頭做為序文。如果您在提交查詢時未開啟任何檔案，系統預設會納入專案根目錄中的 AGENTS.md 檔案 (如有)。

AGENTS.md 檔案和規則有何不同？

您也可以透過規則，為所有提示定義適用的指示和偏好設定。不過，規則是在 IntelliJ 檔案 /.idea/project.prompts.xml 中定義，而 AGENTS.md 檔案會儲存在原始碼旁，且與 IDE 無關。如果主要目的是與團隊分享操作說明，建議使用 AGENTS.md 檔案。