---
title: "Prompt Files"
description: "把重複的 Copilot Chat 任務沉澱成可呼叫、可審查、可維護的 .prompt.md 檔案。"
verifiedAt: "2026-05-06"
---

Prompt files（提示詞檔案）不是收藏提示詞的資料夾，而是把重複工作變成可呼叫命令。VS Code 官方文件把它描述為獨立 Markdown 檔案：你在 Chat 裡手動呼叫，它再把任務目標、上下文和執行約束交給 Copilot。

> [!IMPORTANT]
> 一句話決策：**長期規則寫 instructions，重複任務寫 prompt file，一次性問題直接問**。三個層級混用是商業專案裡 Copilot 不穩定的最常見原因。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能判斷一個任務是否值得做成 `.prompt.md`，並能寫出不會汙染長期上下文的 prompt file。

## 1. 它解決什麼問題

Prompt file 適合把團隊會反覆發出的 Chat 請求標準化。例如：

- 生成 PR 描述。
- 為一次重構補回歸測試。
- 按釋出檢查清單複檢文件。
- 為新元件生成最小實現。
- 對 REST API 做安全審查。
- 把遷移任務拆成計劃、diff、測試和回復。

它和 custom instructions 的區別很關鍵：

- **Custom instructions** 自動應用，適合專案長期規則。
- **Prompt files** 手動呼叫，適合重複但不是每次都需要的任務。
- **普通 prompt** 適合一次性問題，不需要沉澱。

```mermaid
flowchart TD
    Task["要告訴 Copilot 的內容"] --> Stable{"每次任務都必須遵守?"}
    Stable -->|是| Instruction["寫進 instructions"]
    Stable -->|否| Repeat{"同類任務會重複出現?"}
    Repeat -->|否| Adhoc["直接在 Chat 裡提問"]
    Repeat -->|是| NeedsScript{"需要指令碼、示例或資源?"}
    NeedsScript -->|否| PromptFile["寫成 prompt file"]
    NeedsScript -->|是| Skill["升級為 agent skill"]

    style Instruction fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style PromptFile fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style Skill fill:#fef3c7,stroke:#d97706,stroke-width:2px
```

## 2. 放在哪裡

VS Code 官方預設位置：

- 工作區級 prompt files：`.github/prompts/`
- 使用者級 prompt files：VS Code 使用者資料，跟隨當前 profile

團隊教程裡預設推薦先放工作區級 `.github/prompts/`。理由很簡單：它能跟程式碼一起 code review，也能讓新人開啟儲存庫後直接複用。

如果是隻屬於個人的寫作習慣、提交偏好、解釋風格，不要塞進儲存庫。放到使用者級，避免把個人工作流誤當成團隊規範。

## 3. 檔案格式

Prompt file 使用 `.prompt.md` 副檔名。YAML frontmatter 是可選的，但商業專案建議至少寫 `description`，讓呼叫者知道這個命令解決什麼問題。

一個最小可用例子：

```md
---
description: "Add regression tests"
agent: "agent"
tools:
  - "search/codebase"
---

Review the current diff and add regression tests for the changed behavior.

Use these constraints:

- Prefer focused tests that fail before the fix.
- Do not rewrite unrelated tests.
- Mention any behavior that cannot be tested locally.
```

官方支援的常用 frontmatter 欄位包括：

- `description`：prompt 的簡短說明。
- `name`：在 Chat 輸入 `/` 後使用的名稱；未指定時用檔名。
- `argument-hint`：提示呼叫者應該補什麼引數。
- `agent`：執行 prompt 的 agent，例如 `ask`、`agent`、`plan` 或自定義 agent。
- `model`：指定執行模型；不指定時使用當前模型選擇器。
- `tools`：限制或宣告這個 prompt 可用的工具。

正文就是正常 Markdown。需要引用儲存庫檔案時，用相對連結；需要引用工具時，VS Code 支援 `#tool:<tool-name>` 語法。

## 4. 寫作結構

高質量 prompt file 通常有 5 個塊：

1. **目標**：這次任務要交付什麼。
2. **輸入**：呼叫者必須提供什麼路徑、issue、diff、日誌或限制。
3. **過程**：Copilot 應該先看什麼，再改什麼，再驗證什麼。
4. **邊界**：哪些檔案、行為、許可權不能碰。
5. **輸出**：最後必須給哪些證據，例如測試命令、風險、回復方式。

不要寫成口號。比如“寫得專業一點”沒有工程含義；“按當前 diff 生成 PR description，包含使用者影響、測試證據和回復說明”才可執行。

## 5. 適合沉澱的任務

優先沉澱這些：

- **PR 模板化**：從 diff 生成變更摘要、測試證據、風險提示。
- **測試補齊**：針對 bug fix 生成最小回歸測試。
- **文件複檢**：檢查 frontmatter、連結、標題層級、移動端可讀性。
- **遷移計劃**：把升級任務拆成依賴、步驟、驗證和回復。
- **安全審查**：圍繞認證、授權、輸入校驗、日誌脫敏出清單。
- **釋出前 QA**：要求 Copilot 只基於 build、lint、screenshot 和 diff 下結論。

暫時不要沉澱這些：

- 一次性追問。
- 已經過期的臨時事故背景。
- 金鑰、內部地址、客戶資料。
- 和儲存庫事實無關的個人偏好。
- 會要求 Copilot 自動執行危險操作的 prompt。

<details>
<summary>深讀：prompt file 為什麼不能替代 instructions</summary>

Prompt file 是手動呼叫的任務入口，不會自動給所有請求加規則。如果你把測試框架、程式碼風格、目錄邊界只寫進 prompt file，Copilot 在普通 Chat、inline edit 或 agent mode 裡仍然可能不知道這些約束。

穩定規則應該進 instructions；只有當任務本身需要一套可重複步驟時，才寫 prompt file。
</details>

## 本章自檢

寫完一個 prompt file 後，用這 5 個問題檢查：

1. 它是否解決一個會重複出現的具體任務？
2. 它是否明確說明輸入、過程、邊界和輸出？
3. 它是否沒有寫入金鑰、客戶資料或內部敏感地址？
4. 它是否只在需要時呼叫，而不是偽裝成長期規則？
5. 它是否能用一個真實 diff、issue 或文件變更跑通？

透過標準：團隊成員不用口頭解釋，也能用同一個 prompt file 得到結構相近、可驗證的結果。

## 官方來源

- [Use prompt files in VS Code](https://code.visualstudio.com/docs/copilot/customization/prompt-files) —— VS Code 官方 prompt file 位置、格式和 frontmatter。
- [Customization](https://code.visualstudio.com/docs/copilot/concepts/customization) —— VS Code 官方定製能力總覽。
- [About customizing GitHub Copilot responses](https://docs.github.com/en/copilot/concepts/prompting/response-customization) —— GitHub 官方響應定製概念頁。

## 接下來去哪

<Cards>
  <Card title="儲存庫自定義指令" description="把長期穩定規則放回 instructions。" href="/zh-Hant/docs/github-copilot/official/06-context-customization/repository-instructions" />
  <Card title="Skills、Hooks、Plugins" description="當 prompt file 需要指令碼、資源或分發時繼續升級。" href="/zh-Hant/docs/github-copilot/official/06-context-customization/skills-hooks-plugins" />
</Cards>
