使用 AGENTS.md 檔案自訂 Gemini

使用一或多個 AGENTS.md 檔案，為 Android Studio 內建 Gemini 提供自訂指令。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 檔案。

AGENTS.md 檔案和技能有何不同？

技能代表隨選專業知識，會在要求符合技能說明時叫用，而 AGENTS.md 中的內容則會加到每個提示的開頭。建議使用技能執行特定工作，並使用 AGENTS.md 檔案影響代理的一般行為。如要進一步瞭解技能，請參閱「Android 技能簡介」。