https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-best-practices
GitHub Copilot CLI 最佳实践
了解如何充分利用 GitHub Copilot CLI。
简介
GitHub Copilot CLI 是一款终端原生的 AI 编程助手，它将 Agent（智能体）能力直接带到了你的命令行中。Copilot CLI 可以像聊天机器人一样运行并回答你的问题，但它真正的强大之处在于能够作为你的编程伙伴自主工作，允许你委派任务并监督它的工作。
本文提供了充分利用 Copilot CLI 的技巧，包括如何有效使用各种 CLI 命令，以及如何管理 CLI 对文件的访问权限。你可以将这些技巧作为起点，然后通过尝试找出最适合你工作流的方式。
[!NOTE]
GitHub Copilot CLI 在不断发展中。请使用/help命令查看最新信息。
1. 自定义你的环境
使用自定义指令文件
Copilot CLI 会自动从多个路径读取指令，这允许你定义组织级的标准和特定于仓库的约定。
支持的路径（按发现顺序）：
| 路径 (Location) | 作用域 (Scope) |
|---|---|
~/.copilot/copilot-instructions.md |
所有会话 (全局) |
.github/copilot-instructions.md |
仓库级别 |
.github/instructions/**/*.instructions.md |
仓库级别 (模块化) |
AGENTS.md (在 Git 根目录或当前工作目录) |
仓库级别 |
Copilot.md, GEMINI.md, CODEX.md |
仓库级别 |
最佳实践
仓库级的指令始终优先于全局指令。利用这一点来强制执行团队约定。例如，下面是一个简单的 .github/copilot-instructions.md 文件：
## Build Commands
- `npm run build` - Build the project
- `npm run test` - Run all tests
- `npm run lint:fix` - Fix linting issues## Code Style
- Use TypeScript strict mode
- Prefer functional components over class components
- Always add JSDoc comments for public APIs## Workflow
- Run `npm run lint:fix && npm test` after making changes
- Commit messages follow conventional commits format
- Create feature branches from `main`
[!TIP]
保持指令简明扼要且具有可执行性。冗长的指令会稀释其有效性。
了解更多信息，请参阅 About customizing GitHub Copilot responses。
配置允许的工具
管理 Copilot 可以在无需询问权限的情况下运行哪些工具。当 Copilot 请求执行某项操作的权限时，你可以选择 Allow once（允许一次），或者 Always allow（始终允许）将该工具添加到当前及未来会话的允许名单中。
要重置之前批准的工具，请使用：
/reset-allowed-tools
你也可以通过 CLI 标志预先配置允许的工具：
copilot --allow-tool 'shell(git:*)' --deny-tool 'shell(git push)'
常见的权限模式：
shell(git:*)— 允许所有 Git 命令shell(npm run:*)— 允许所有 npm 脚本shell(npm run test:*)— 允许 npm 测试命令write— 允许文件写入
选择你偏好的模型
使用 /model 根据任务的复杂程度从可用模型中进行选择：
| 模型 | 最适合的场景 | 权衡代价 |
|---|---|---|
| Claude Opus 4.5 (默认) | 复杂的架构、高难度调试、细微的重构 | 能力最强，但会消耗更多的 premium requests |
| Claude Sonnet 4.5 | 日常编码、绝大多数常规任务 | 速度快，性价比高，能很好地处理大部分工作 |
| GPT-5.2 Codex | 代码生成、代码审查、直接的代码实现 | 非常适合用于审查由其他模型生成的代码 |
建议：
- Opus 4.5 非常适合需要深度推理、复杂系统设计、微妙 Bug 排查或广泛上下文理解的任务。
- 对于注重速度和成本效益的常规任务，切换到 Sonnet 4.5 ——它能高效处理绝大多数的日常编码工作。
- 使用 Codex 进行大量的代码生成，或者作为“第二意见”来审查其他模型生成的代码。
随着任务复杂度的变化，你可以在会话中随时使用 /model 切换模型。
2. 编码前先计划
计划模式 (Plan mode)
当给定一个具体的计划去遵循时，模型的成功率会更高。 在计划模式下，Copilot 会在编写任何代码之前创建一个结构化的实现计划。
按下 Shift+Tab 可在普通模式和计划模式之间切换。在计划模式下，你输入的所有提示词都将触发计划工作流。
或者，你也可以在普通模式下使用 /plan 命令来达到相同的效果。
示例提示词（在普通模式下）：
/plan Add OAuth2 authentication with Google and GitHub providers
执行过程：
- Copilot 会分析你的请求和代码库。
- 提出澄清问题以对齐需求和方法。
- 创建一个带有复选框的结构化实现计划。
- 将计划保存到你会话文件夹中的
plan.md。 - 等待你的批准然后再进行代码实现。
你可以按下 Ctrl+y 在默认的 Markdown 编辑器中查看和编辑该计划。
计划输出示例：
# Implementation Plan: OAuth2 Authentication## Overview
Add social authentication using OAuth2 with Google and GitHub providers.## Tasks
- [ ] Install dependencies (passport, passport-google-oauth20, passport-github2)
- [ ] Create authentication routes in `/api/auth`
- [ ] Implement passport strategies for each provider
- [ ] Add session management middleware
- [ ] Create login/logout UI components
- [ ] Add environment variables for OAuth credentials
- [ ] Write integration tests## Detailed Steps
1. **Dependencies**: Add to package.json...
2. **Routes**: Create `/api/auth/google` and `/api/auth/github`...
何时使用计划模式
| 场景 | 是否使用计划模式？ |
|---|---|
| 复杂的多文件更改 | |
| 涉及多处的重构 | |
| 新功能实现 | |
| 快速修复 Bug | |
| 单文件更改 |
探索 → 计划 → 编码 → 提交 工作流
为了在复杂任务中获得最佳效果：
-
探索 (Explore):
Read the authentication files but don't write code yet -
计划 (Plan):
/plan Implement password reset flow -
审查 (Review):
检查计划，提出修改建议
-
实现 (Implement):
Proceed with the plan -
验证 (Verify):
Run the tests and fix any failures -
提交 (Commit):
Commit these changes with a descriptive message
3. 利用无限会话
自动上下文窗口管理
Copilot CLI 具备无限会话 (infinite sessions) 功能。你无需担心上下文耗尽。系统通过智能压缩（总结对话历史并保留关键信息）来自动管理上下文。
会话存储位置：
~/.copilot/session-state/{session-id}/
├── events.jsonl # Full session history
├── workspace.yaml # Metadata
├── plan.md # Implementation plan (if created)
├── checkpoints/ # Compaction history
└── files/ # Persistent artifacts
[!NOTE]
如果你需要手动触发压缩，请使用/compact。由于系统会自动处理，通常很少需要这样做。
会话管理命令
要查看有关当前 CLI 会话的信息，请输入：
/session
要查看所有会话检查点 (checkpoints) 的列表，请输入：
/session checkpoints
[!NOTE]
当会话上下文被压缩时，系统会创建一个检查点，允许你查看 Copilot 创建的上下文摘要。
要查看特定检查点的详细信息，请输入：
/session checkpoints NUMBER
其中 NUMBER 指定了你要显示的检查点编号。
要查看当前会话期间创建的任何临时文件（例如，由 Copilot 创建但不应保存到仓库的工件），请输入：
/session files
要查看当前的计划（如果 Copilot 已生成），请输入：
/session plan
最佳实践：保持会话专注
虽然无限会话允许长时间运行的工作，但专注的会话能产生更好的结果：
- 在不相关的任务之间使用
/clear或/new。 - 这会重置上下文并提高响应质量。
- 可以把它想象成与同事开始一段全新的对话。
/context 命令
使用 /context 可视化当前的上下文使用情况。它会显示以下明细：
- 系统/工具 Token 数
- 消息历史 Token 数
- 可用的剩余空间
- 缓冲区分配
4. 高效委派工作
/delegate 命令
将工作移交给云端的 Copilot 编码 Agent 运行。 这在以下场景中极其强大：
- 可以异步运行的任务。
- 对其他仓库的更改。
- 你不想干等的长时间运行的操作。
示例提示词：
/delegate Add dark mode support to the settings page
执行过程：
- 你的请求被发送给 Copilot 编码 Agent。
- Agent 会创建一个包含这些更改的 Pull Request (PR)。
- 你可以在本地继续工作，同时云端 Agent 会在后台处理。
何时使用 /delegate
使用 /delegate |
本地工作 |
|---|---|
| 切线任务 (Tangential tasks) | 核心功能开发 |
| 文档更新 | Bug 调试 |
| 独立模块的重构 | 交互式的探索 |
5. 常见工作流
代码库熟悉 (Onboarding)
加入新项目时，将 Copilot CLI 作为你的结对编程伙伴。例如，你可以问 Copilot：
How is logging configured in this project?What's the pattern for adding a new API endpoint?Explain the authentication flowWhere are the database migrations?
测试驱动开发 (TDD)
与 Copilot CLI 结对开发测试。
Write failing tests for the user registration flow- 审查并批准测试。
Now implement code to make all tests pass- 审查代码实现。
Commit with message "feat: add user registration"
代码审查辅助
/review Use Opus 4.5 and Codex 5.2 to review the changes in my current branch against `main`. Focus on potential bugs and security issues.
Git 操作
Copilot 非常擅长 Git 工作流：
What changes went into version `2.3.0`?Create a PR for this branch with a detailed descriptionRebase this branch against `main`Resolve the merge conflicts in `package.json`
Bug 排查
The `/api/users` endpoint returns 500 errors intermittently. Search the codebase and logs to identify the root cause.
重构
-
/plan Migrate all class components to functional components with hooks然后回答 Copilot 提出的问题。审查它创建的计划，并在必要时要求 Copilot 进行修改。当你对计划感到满意时，可以输入：
Implement this plan
6. 高级模式
跨多个仓库工作
Copilot CLI 提供了灵活的多仓库工作流——这是团队在微服务、Monorepos（单体仓库）或相关项目上工作时的一个关键差异化优势。
选项 1：从父目录运行
# Navigate to a parent directory containing multiple repos
cd ~/projects
copilot
Copilot 现在可以同时访问并在所有子仓库中工作。这非常适合：
- 微服务架构
- 在相关仓库间进行协同更改
- 跨项目重构共享模式
选项 2：使用 /add-dir 扩展访问权限
# Start in one repo, then add others (requires full paths)
copilot
/add-dir /Users/me/projects/backend-service
/add-dir /Users/me/projects/shared-libs
/add-dir /Users/me/projects/documentation
查看和管理允许的目录：
/list-dirs
示例工作流：协同 API 更改
I need to update the user authentication API. The changes span:- @/Users/me/projects/api-gateway (routing changes)
- @/Users/me/projects/auth-service (core logic)
- @/Users/me/projects/frontend (client updates)Start by showing me the current auth flow across all three repos.
这种多仓库能力支持：
- 横切面重构（在所有地方更新一个共享模式）
- 伴随客户端更新的 API 契约变更
- 引用多个代码库的文档编写
- 跨 Monorepo 的依赖升级
在 UI 开发中使用图片
Copilot 可以处理视觉参考。只需拖拽图片直接放入 CLI 输入框，或引用图片文件即可：
Implement this design: @mockup.png
Match the layout and spacing exactly
复杂迁移的检查清单
针对大规模更改：
Run the linter and write all errors to `migration-checklist.md` as a checklist.
Then fix each issue one by one, checking them off as you go.
7. 团队规范
推荐的仓库设置
-
创建
.github/copilot-instructions.md，包含：- 构建和测试命令
- 代码风格指南
- 提交前的必要检查项
- 架构决策
-
建立约定，针对：
- 何时使用
/plan（复杂功能、重构） - 何时使用
/delegate（切线任务） - 有 AI 辅助的代码审查流程
- 何时使用
安全注意事项
- Copilot CLI 需要你明确批准潜在的破坏性操作。
- 在接受之前，审查所有建议的更改。
- 谨慎使用权限白名单。
- 永远不要提交密钥 (Secrets)。Copilot 在设计上会避免这种情况，但始终需要你核体验证。
衡量生产力
追踪以下指标：
- 从提出 Issue 到创建 Pull Request 的耗时
- 合并前的迭代次数
- 代码审查的反馈周期
- 测试覆盖率的提升
获取帮助
在命令行中，你可以通过使用以下命令显示帮助：copilot -h。
如需有关各主题的帮助，请输入：
copilot help TOPIC
其中 TOPIC 可以是以下之一：config、commands、environment、logging 或 permissions。
在 CLI 内部
如需在 CLI 内部获取帮助，请输入：
/help
要查看使用统计信息，请输入：
/usage
要向 GitHub 提交有关 Copilot CLI 的私人反馈、提交错误报告或功能请求，请输入：
/feedback
延伸阅读
- About GitHub Copilot CLI
- Using GitHub Copilot CLI
- GitHub Copilot CLI command reference
- Copilot plans and pricing