diff --git a/06 - IDE & AI Tooling/6.1 VSCode Copilot 使用指南.md b/06 - IDE & AI Tooling/6.1 VSCode Copilot 使用指南.md new file mode 100644 index 0000000..b36ee02 --- /dev/null +++ b/06 - IDE & AI Tooling/6.1 VSCode Copilot 使用指南.md @@ -0,0 +1,96 @@ +# **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 风格提交建议。 diff --git a/06 - IDE & AI Tooling/README.md b/06 - IDE & AI Tooling/README.md new file mode 100644 index 0000000..46a99e2 --- /dev/null +++ b/06 - IDE & AI Tooling/README.md @@ -0,0 +1,19 @@ +# **06 - IDE & AI Tooling (工具落地指南)** + +本目录用于沉淀“在不同 IDE/插件/工具中,如何复用本仓库规范文档与提示模板”的标准操作手册。 + +## **当前已支持** + +1. `6.1 VSCode Copilot 使用指南.md` + +## **后续规划** + +1. Cursor 使用指南 +2. JetBrains + AI 插件使用指南 +3. 其他企业内 AI 平台适配指南 + +## **统一目标** + +1. 所有工具都能复用 `01-05` 的正式规范。 +2. 通过标准提示词或自定义配置,稳定输出符合团队红线的文档与代码。 +3. 减少“手动贴上下文”的重复劳动。 diff --git a/README.md b/README.md index 7625140..1ddeb6b 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,12 @@ * 🌿 **5.1 版本控制与代码提交规范**:确立常驻三分支模型 (main/test/dev)、Angular 提交规范及 SemVer 版本号管理。 * 🚀 **5.2 CI/CD 与环境部署规范**:定义多环境隔离标准及基于 Jenkinsfile 的全自动化流水线与卡点策略。 +### **📂 06 \- IDE & AI Tooling (工具落地指南)** + +沉淀“在不同 IDE/插件/工具中如何复用本仓库规范”的标准操作手册,先从 VS Code Copilot 场景开始。 + +* 🤖 **6.1 VSCode Copilot 使用指南**:说明如何基于 `.github` 指令与提示模板自动生成符合团队规范的文档与代码。 + ### **📂 ref (历史参考资料,仅供借鉴)** `ref/` 目录用于存放历史规范、外部参考文档或迁移期材料,**仅用于对照和借鉴**。 @@ -114,6 +120,7 @@ description: "用于生成核心业务代码;关键词:Fat Service、OpenAPI 1. **快速上手**:请优先阅读 `03 - Coding & Frameworks` 目录下的相关语言与框架规范,确保首个提交符合团队红线。 2. **架构设计与选型**:在引入新技术或进行微服务拆分前,请先查阅 `02 - Design Standard/2.4 项目文档与架构决策规范.md`,并编写 ADR 文档。 3. **参考资料边界**:`ref/` 目录仅供历史对照,不参与规范门禁与日常执行。 +4. **工具落地查阅**:如需按 IDE/插件查看实操方式,请阅读 `06 - IDE & AI Tooling/` 下对应指南(当前已提供 VSCode Copilot)。 ---