copilot-instructions.md 與專案記憶

GitHub Copilot CLI 不只讀自己的守則檔，還直接看得懂你放在專案裡的 AGENTS.md、CLAUDE.md、GEMINI.md——但「誰贏誰」這件事，它給了一個跟 Codex CLI 完全相反的答案。

想像你換了一位新助理，本來擔心得把公司規矩重講一遍給他聽。結果這位助理翻了翻抽屜，發現：「咦，你前一位助理留的守則手冊我看得懂，你朋友公司用的守則格式我也認得，不用你重寫。」——這正是 GitHub Copilot CLI 在「專案記憶」這件事上最特別的地方：它除了有自己的守則檔格式，還直接讀取三套競品的記憶檔，不用你搬家重寫一份。

但方便的背後藏著一個地雷：這位新助理如果同時翻到好幾份規矩、內容還互相打架，他要聽誰的？這一章你會學到：

• Copilot CLI 支援的五種指示檔案格式，包括直接讀取 AGENTS.md（Codex CLI 標準）、CLAUDE.md（Claude Code 標準）、GEMINI.md（Gemini CLI 標準）；
• 它會去哪些資料夾找這些檔案；
• 多份檔案疊在一起時，Copilot CLI 官方給的合併規則——跟 Codex CLI「近者覆寫」正好相反，這是四方對照裡張力最大的一組，務必看清楚；
• 用 @ 在指示檔裡引用其他檔案的語法；
• 怎麼確認這次 session 真的把你寫的守則讀進去了；
• 改完守則檔，這個對話讀不讀得到（跟 Codex CLI 是同一個坑）；
• 老實告訴你官方文件沒寫的地方——大小上限查無數字；
• 簡單認識第三層機制：Custom Agents（.agent.md）。

5.1 五種指示檔案，一次讀懂

在看五種格式的名稱之前，先弄清楚你為什麼要學這一章——傳統做法是，你每開一次新對話，就得把專案的寫碼風格、不能碰的禁區、團隊慣例，重新跟 AI 助手講一次；記憶檔案這個機制存在的意義，就是讓 agent 每次啟動都自動把這些脈絡讀進去，不用你再重講一次。省下來的不是「記住檔案格式」這件事本身，而是你反覆口頭解釋的時間成本。接下來的五種格式，都是「怎麼把這份脈絡寫下來、放對地方」的技術細節。

先記住官方那句最關鍵的定性：Copilot CLI 支援的指示檔案，官方文件用一張表格「Types of custom instructions」逐一列出，翻成中文整理如下：

(料源：official，Add custom instructions for Copilot CLI，「Types of custom instructions」段落逐字查證)

拆開來看，重點有兩個：

1. AGENTS.md 是開放標準的一環。 Copilot CLI 讀它是因為 AGENTS.md 本身是跨工具的開放格式（agentsmd/agents.md 這個規範專案維護），Codex CLI 也是這套標準的採用者——這在本站 Codex 單元的第 5 章已經介紹過。
2. CLAUDE.md 多查一個路徑：.claude/CLAUDE.md。 Claude Code 使用者習慣把設定放在 .claude/ 資料夾底下，官方文件明講 Copilot CLI 會多檢查這個備選路徑——這是官方原文逐字寫明的細節。

翻成白話最實用的一句結論：如果你原本是 Claude Code 或 Codex CLI 的使用者，不用重寫任何東西，直接把 Copilot CLI 加進同一個專案，它會自動讀你既有的 CLAUDE.md 或 AGENTS.md。 這對「同時用好幾套終端機 agent」的讀者是很實用的一句話。

5.2 去哪裡找：探索範圍（standard locations）

知道有哪些檔名還不夠，Copilot CLI 還得知道去哪些資料夾找。官方原文：

Unless noted in the table below, Copilot CLI discovers repository and agent instruction files in the standard locations: the repository root, the current working directory, intermediate directories between them, and any directories nested in the path of a file it is working on.

翻成白話，探索範圍是四塊拼起來的：

• 儲存庫根目錄（通常是有 .git 的那一層）
• 你目前所在的工作目錄
• 根目錄到你目前位置之間，沿途所有中繼資料夾
• 外加：它正在處理的那個檔案，其所在路徑上任何巢狀資料夾

前三塊跟 Codex CLI「從 Git 根目錄一路走到你現在的位置」的概念高度重疊；但第四塊是 Copilot CLI 特有的——如果你叫它改一個路徑很深的檔案，那個檔案自己所在路徑上的巢狀守則檔，也會一併被納入探索範圍，不只看你「人在哪裡」，還看「它正在動哪個檔案」。

(料源：official，同上文件「Where Copilot CLI looks for custom instructions」段落)

5.3 全部合併、不分先後——這跟 Codex CLI 的規則正好相反

這是本章必須用力畫重點的地方，也是四套工具對照起來張力最大的一組差異。

Codex CLI 官方明講「近者覆寫」（越靠近你目前位置的檔案，優先權越高，會蓋過遠的）；Claude Code 也有明確的路徑限定疊加規則。Copilot CLI 官方給的答案完全相反：它不定義優先順序。

官方原文（「How multiple instruction files interact」段落）：

When multiple applicable user-level and repository instruction files exist, Copilot CLI combines their instructions. It removes duplicate copies of identical user-level copilot-instructions.md, repository-wide, and agent instructions, but does not define a general precedence order between these files. Avoid conflicting instructions.

翻成白話：

• 會不會全部讀進去：會。多份符合條件的指示檔，Copilot CLI 會全部合併。
• 會不會去重複：會。完全相同內容的檔案（例如一模一樣的使用者層 copilot-instructions.md），重複的副本會被移除。
• 誰贏誰：官方明講不定義。既不是「近者覆寫遠者」，也不是「先讀到的贏」，官方直接把責任丟回給你——「請自行避免寫出互相衝突的指示」。

5.4 @ 引用其他檔案（限相對路徑）

指示檔案裡也能用 @ 把另一個檔案的內容整份拉進來，不用手動複製貼上。官方原文（「Referencing other files」段落）：

use @ followed by a relative path to include another file. Copilot CLI reads the referenced file immediately

(料源：official)

@../shared/coding-style.md

限制只有一條，但很重要：

Absolute paths and paths beginning with ~/ are not loaded

翻成白話：只能用相對路徑。寫絕對路徑（例如 /Users/你的帳號/...）或用 ~/ 開頭的路徑，Copilot CLI 不會載入——這點在多人協作的專案裡特別重要，因為絕對路徑在別人的電腦上根本對不上，Copilot CLI 乾脆直接不支援，逼你只能寫可攜的相對路徑。

5.5 怎麼確認真的讀到了：/instructions

守則寫好了，怎麼知道 Copilot CLI 這次 session 真的把它讀進去？不用用力猜，官方直接內建一個查詢指令：

(料源：official)

/instructions

官方原文：「Use the /instructions command to view the instruction files discovered for the current session」——打開互動畫面輸入這行，就會直接列出這個 session 實際載入了哪些指示檔。

5.6 改完守則檔，這個對話還讀不到——要重開 session

跟 Codex CLI 一樣的坑：改指示檔的內容，不會立刻反映在正在進行中的對話裡。官方原文：

Changes you make to custom instructions files are not immediately available for use in active CLI sessions. To apply your changes, exit the current session and then either resume it (for example, run copilot --continue), or start a new session (for example, use /new from within an interactive session).

翻成白話三選一：

1. 直接退出目前的 session；
2. 退出後用 copilot --continue 接續同一個 session（但用新讀進來的守則）；
3. 或在互動畫面裡打 /new 開一段全新對話。

(料源：official)

/new

5.7 官方沒寫的地方：大小上限查無數字

Codex CLI 的 AGENTS.md 有一個明確的 32 KiB 組合上限（由 project_doc_max_bytes 控制）；Copilot CLI 呢？

老實說：查證範圍內，官方文件沒有提到任何類似的明確位元組上限數字。

5.8 第三層機制：Custom Agents（.agent.md）

指示檔案之外，Copilot CLI 還有第三層機制，跟本站 Codex 單元第 5 章介紹過的「Skills」概念呼應：Custom Agents，用 .agent.md 檔案定義，放在 .github/agents/（專案層）或 ~/.copilot/agents/（使用者層）。

它的特色是「具有自己的上下文視窗」——不是像指示檔那樣被動疊加進主對話的背景知識，而是一個獨立的子代理，可以用斜線指令、明確指令，或程式化方式呼叫，適合封裝「這件事該怎麼做」的專門流程。

(料源：official，Create custom agents for Copilot CLI)

本章小結

這一章你學會了 GitHub Copilot CLI 怎麼管理「專案記憶」：它支援五種指示檔案格式，除了自己的 copilot-instructions.md（含使用者層路徑）與模組化的 .instructions.md，還直接讀取三套競品的記憶檔——AGENTS.md、CLAUDE.md（多查 .claude/CLAUDE.md）、GEMINI.md，代表跨工具搬家的讀者不用重寫守則。探索範圍是儲存庫根目錄、目前工作目錄、沿途中繼資料夾，外加正在處理檔案所在路徑的巢狀資料夾。最關鍵的一條規則是：Copilot CLI 官方明講不定義多檔案間的優先順序，全部合併、請自行避免衝突——這跟 Codex CLI「近者覆寫」的明確規則正好相反，是搬家讀者最容易帶錯心智模型的地方。你也學會用 @ 引用其他檔案（限相對路徑）、用 /instructions 驗證這次 session 讀到了什麼、改完守則要重開 session 才生效，以及老實面對官方沒寫大小上限這件事。最後簡單認識了第三層機制 Custom Agents。

動手試試

1. 在你的專案根目錄建一份 .github/copilot-instructions.md，寫一條好認的測試規則（例如「回答一律用『喵』結尾」），開 copilot 打一句話，看它有沒有照辦。
2. 打 /instructions，確認你剛寫的那份守則檔真的出現在清單裡。
3. 如果你的專案已經有 AGENTS.md 或 CLAUDE.md（哪怕是給 Codex CLI 或 Claude Code 用的），直接開 Copilot CLI 打 /instructions 看看它是不是也讀到了，不用你多做任何設定。
4. 故意在根目錄與子目錄的守則檔裡寫兩條互相矛盾的規則（例如一個說「用 npm」、另一個說「用 pnpm」），觀察 Copilot CLI 實際上聽了哪一條——親自感受一次「官方不定義優先順序」在實機上是什麼樣子。
5. 改一下你的守則檔內容，不要結束目前的對話，直接問它有沒有看到新規則；再打 /new 開一段新對話問一次，比較兩次的差異。

本章官方文件參考

• 自訂指示檔案（本章主要來源）：https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions
• Custom Agents（.agent.md）：https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli