# **6.1 VSCode Copilot 使用指南**

本文档说明如何在 VS Code + GitHub Copilot 中，基于本仓库规范自动生成符合团队标准的文档与代码。

## **1. 目标与适用范围**

1. 适用 IDE：VS Code。
2. 适用插件：GitHub Copilot（含 Chat）。
3. 适用资产：`01-05` 规范文档、`.github` 自定义指令与提示模板。

## **2. 最小配置清单**

确认仓库根目录存在以下路径：

```text
.github/
  copilot-instructions.md
  instructions/
    *.instructions.md
  prompts/
    *.prompt.md
```

说明：
1. `copilot-instructions.md`：全局常驻规则（如中文输出、决策点询问、ADR 先行）。
2. `instructions/*.instructions.md`：按 `applyTo` 自动注入规范。
3. `prompts/*.prompt.md`：阶段性任务模板（P1-P8）。

## **3. Prompt 文件写法（关键）**

`*.prompt.md` 的 frontmatter 推荐最小结构：

```yaml
---
agent: agent
description: "用于生成核心业务代码；关键词：Fat Service、OpenAPI、统一响应"
---
```

规则：
1. 使用 `agent` 字段，不使用已弃用的 `mode`。
2. `description` 必须包含场景关键词，便于 Copilot 检索。

## **4. 日常使用方式**

### **4.1 常驻规则（自动）**

- 进入当前 workspace 后，Copilot 会读取 `.github/copilot-instructions.md` 作为全局约束。

### **4.2 阶段模板（手动触发）**

在 Copilot Chat 输入框中：
1. 输入 `/`。
2. 选择对应 prompt（如 `p1-project-blueprint`、`p4-core-business-code`）。
3. 在 prompt 后补充你的业务需求并发送。

示例：

```text
/p4-core-business-code 请实现“订单创建并扣减库存”接口，技术栈 Django DRF。
```

### **4.3 文件规范（自动注入）**

- 编辑匹配 `applyTo` 的文件时，对应 `.instructions.md` 会参与约束。
- 例如编辑 `*.py` 时，自动应用 Python/DRF 相关规则。

## **5. 推荐工作流（与本仓库规范对齐）**

1. 先调用 `P1/P2` 完成蓝图与设计。
2. 调用 `P3/P4` 生成脚手架与核心代码。
3. 调用 `P5` 补齐自动化测试。
4. 调用 `P6` 执行审查与修复。
5. 调用 `P7` 生成部署流水线。
6. 遗留系统改造时调用 `P8`。

## **6. 常见问题排查**

1. 看不到 prompt：确认文件在 `.github/prompts/` 且后缀为 `.prompt.md`。
2. prompt 无法识别：检查 frontmatter 是否完整，是否使用 `agent`。
3. 规则未生效：检查 `applyTo` 与当前文件路径是否匹配。
4. 仍异常：执行 `Developer: Reload Window` 后重试。

## **7. 与规范文档的映射关系**

1. 全局治理：`02 - Design Standard/2.4`、`05 - Collaboration & Delivery/5.1`。
2. 设计阶段：`02 - Design Standard/2.1~2.3`。
3. 编码阶段：`03 - Coding & Frameworks/*`。
4. 质量阶段：`04 - Quality & Review/*`。
5. 交付阶段：`05 - Collaboration & Delivery/5.2`。

## **8. 输出质量基线**

1. 生成结果必须可执行或可审阅，不输出空泛建议。
2. 发生重大技术分歧时，先询问并记录 ADR。
3. 阶段完成后给出 Conventional Commits 风格提交建议。