Prompt Files

Prompt files（提示词文件）不是收藏提示词的文件夹，而是把重复工作变成可调用命令。VS Code 官方文档把它描述为独立 Markdown 文件：你在 Chat 里手动调用，它再把任务目标、上下文和执行约束交给 Copilot。

1. 它解决什么问题

Prompt file 适合把团队会反复发出的 Chat 请求标准化。例如：

• 生成 PR 描述。
• 为一次重构补回归测试。
• 按发布检查清单复检文档。
• 为新组件生成最小实现。
• 对 REST API 做安全审查。
• 把迁移任务拆成计划、diff、测试和回滚。

它和 custom instructions 的区别很关键：

• Custom instructions 自动应用，适合项目长期规则。
• Prompt files 手动调用，适合重复但不是每次都需要的任务。
• 普通 prompt 适合一次性问题，不需要沉淀。

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，让调用者知道这个命令解决什么问题。

一个最小可用例子：

---
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。

本章自检

写完一个 prompt file 后，用这 5 个问题检查：

1. 它是否解决一个会重复出现的具体任务？
2. 它是否明确说明输入、过程、边界和输出？
3. 它是否没有写入密钥、客户数据或内部敏感地址？
4. 它是否只在需要时调用，而不是伪装成长期规则？
5. 它是否能用一个真实 diff、issue 或文档变更跑通？

通过标准：团队成员不用口头解释，也能用同一个 prompt file 得到结构相近、可验证的结果。

官方来源

• Use prompt files in VS Code —— VS Code 官方 prompt file 位置、格式和 frontmatter。
• Customization —— VS Code 官方定制能力总览。
• About customizing GitHub Copilot responses —— GitHub 官方响应定制概念页。

接下来去哪