GitHub 高级开发者布道师（Senior Developer Advocate）

在把 GitHub Copilot 接入真实项目时，很多开发者都会遇到同一个问题：默认情况下，Copilot 只能看到当前打开文件以及同包内相邻的几个文件。它对你的代码库缺乏整体认知，因此给出的补全建议往往显得「只见树木，不见森林」。

本文介绍几种实用做法，帮助 Copilot 真正理解你的整个代码库，从而给出更贴合项目实际情况的建议。

一、为什么 Copilot 理解代码库很重要

代码补全的质量，取决于模型能获得的上下文。上下文越完整，建议越准确。Copilot 的默认上下文窗口有限，如果你不主动提供信息，它只能基于局部文件推测，这容易导致：

• 命名风格不一致
• 重复造轮子，明明项目里已有现成工具函数
• 忽略了项目特有的架构约定

二、把相关文件同时打开

最直接的办法：在 Copilot Workspace 中，把当前任务涉及的所有相关文件都打开，让 Copilot 在补全时自然看到它们。例如：

• 修改一个被多个模块调用的工具函数时，打开它的全部调用方
• 新增一个服务层文件时，打开同目录下的姊妹文件
• 调试接口时，打开路由定义、控制器、数据模型三件套

打开的文件越多，Copilot 抓取的上下文就越丰富，建议质量随之提升。

三、为 Copilot 提供项目说明（Copilot Instructions）

在仓库根目录添加一份 .github/copilot-instructions.md，描述项目的技术栈、目录结构、命名约定、重要架构决策等。Copilot 在生成补全时会参考这份说明，从而给出更一致、更符合本项目风格的建议。

例如：

# 项目说明

## 技术栈

## 命名约定

## 目录结构

四、使用 #codebase 引用整个仓库

在 Copilot Chat 中，使用 #codebase 关键字可以让 Copilot 把整个代码库纳入上下文，从而基于全局信息回答问题或生成建议。适合用来：

五、使用自定义命令（Custom Instructions / Slash Commands）

为了让 Copilot 的输出更贴合团队习惯，可以为常见任务定义自定义指令，例如：

• 「生成单测」：要求使用项目既有的测试框架与目录结构
• 「写文档」：要求按既定模板输出，包含必需章节
• 「重构」：要求保留对外 API，向内做实现替换

这些指令既可以写在 copilot-instructions.md 里，也可以做成独立的 slash 命令文件。

六、结合 Chat 提问与补全

不要把 Copilot 只当作补全工具。主动在 Copilot Chat 里向它提问，让它先理解上下文，再去补全：

1. 先粘贴或引用关键代码片段
2. 用自然语言描述你想完成的事情
3. 让 Copilot 先复述它理解的上下文，再请求补全或重构

这种「先沟通、后补全」的方式能显著减少返工。

七、避免上下文污染

提供更多信息并不等于越多越好。如果把无关文件都打开，或者说明文档里堆满了与当前任务无关的历史信息，反而会稀释有效上下文。建议：

• 每完成一个任务就关闭不再需要的标签页
• 定期整理 copilot-instructions.md，只保留对当前开发有指导意义的内容
• 为不同子项目或模块维护各自的说明，避免相互干扰

八、检验效果：让 Copilot 解释自己的答案

拿到建议后，可以让 Copilot 反向解释：「请说明你为什么这样写？」如果它给出的理由与项目实际架构一致，说明上下文传递是有效的；如果理由含糊或明显不符合项目情况，就该回头检查上面几步。

九、小结

让 GitHub Copilot 真正理解你的代码库，并不需要什么高深技巧，核心就是：给它足够、相关、整洁的上下文。从打开相关文件、编写项目说明、合理使用 #codebase 与自定义指令这几件事做起，Copilot 的建议质量就会有明显提升。