序文
GitHub Copilot を使用して .NET プロジェクトを開発する場合、生成されたコードは基本的に要件を満たしていますが、非同期メソッド、コメント、名前付け、ファイル エンコーディングは常に再調整する必要があるという状況に遭遇したことはありませんか?
これらの要件は、個別に見ると複雑ではありませんが、会話のたびに繰り返されると少し面倒になります。より適切なアプローチは、共通の規約を 1 つにまとめることです。 副操縦士の指示これをプロジェクトに伴うメンテナンスのデフォルトのガイダンスにします。
最初に説明する必要があります:これはチーム開発テンプレートであり、.NET の唯一の公式仕様ではありません。 非同期、ロギング、および例外処理は一般的な慣行を指します。中国語のコメント、ドキュメントの範囲、ファイルのエンコードなどの要件は、チームの習慣やプロジェクトのツールチェーンと一致している必要があります。
副操縦士の指示とは
コパイロット命令は、プロジェクトのアーキテクチャ、コーディング スタイル、依存関係の制約、検証要件を記述する自然言語で書かれたカスタム命令です。
ウェアハウスのルートディレクトリに作成されます .github/copilot-instructions.md以下を貼り付けます。
MyProject/
├── .github/
│ └── copilot-instructions.md
├── src/
├── tests/
├── .editorconfig
└── MyProject.sln
サポートされているコパイロット機能では、このドキュメントは現在のウェアハウス関連リクエストのコンテキストを自動的に追加して、繰り返しの指示を減らします。
Visual Studio の Copilot Chat、VS Code、JetBrains IDE、Copilot クラウド エージェントと GitHub のコード レビューはすべて、リポジトリ レベルのディレクティブをサポートしています。特定の機能は、クライアント、プラグインのバージョン、および使用シナリオによって異なります。
GitHub Copilot は、さまざまな種類のカスタム命令をサポートしています。
ここで説明するのはチャット、エージェント、コード レビューなどの機能であり、エディターでの入力中に表示されるインライン コード補完の提案ではありません。
指令は強制メカニズムではありませんこれは、Copilot が要件を理解するのに役立ちますが、コンパイラー、アナライザー、テスト、人間によるレビューに代わるものではありません。
直接コピーできる簡潔で実用的な副操縦士の指示
次のテンプレートは、特定のフレームワーク バージョンにバインドされておらず、ASP.NET Core、クラス ライブラリ、コンソール、WinForms、WPF などの一般的な C#/.NET プロジェクトの開始点として使用できます。
このうち、中国語のコメントなどの要件はチームの好みであり、不要なエントリは削除できます。
# .NET Copilot Instructions## 基本原则
- 遵循项目现有架构，优先复用已有实现
- 只修改与当前任务相关的代码，不顺手重构或格式化无关代码
- 使用项目目标框架和 C# 语言版本支持的语法与 API，以实际生效的构建配置为准
- 命名、格式和编码优先遵循项目明确配置及团队规范；没有明确规定时，修改已有文件保持其风格，新建文件遵循本规范
- 未经任务授权或确认，不引入新的 NuGet 包
- 不手工修改自动生成文件，除非当前任务明确要求且生成流程允许
## 异步规范
- 异步方法通常以 Async 结尾，优先返回 Task 或 Task<T>；实现接口、重写成员及框架约定的入口遵循原有签名
- ASP.NET Core MVC 控制器 Action 的命名遵循项目约定；使用 CreatedAtAction 等 API 时，确保传入名称与实际 Action 名称一致
- ConfigureAwait 的用法遵循项目约定；无明确约定时，不依赖调用上下文的通用类库代码优先使用 ConfigureAwait(false)，ASP.NET Core 常规应用代码通常可省略
- await 后需要直接访问 UI 控件时，保留上下文捕获，或显式调度回 UI 线程后再访问
- 不使用 .Result、.Wait()、.GetAwaiter().GetResult() 阻塞异步调用；除事件处理器外，不使用 async void
- 支持取消的异步操作在适用时接收 CancellationToken 并向下传递，该参数通常放在参数列表最后
- I/O 操作优先使用真正的异步 API，不用 Task.Run 包装同步 I/O 来冒充异步
## 注释规范
- 新增注释使用简洁明了的中文，注释末尾不使用中文句号
- 新增或修改的 public/protected 类型和成员按项目文档要求提供 XML 注释，说明用途、参数和返回值（适用时）
- 实现接口或重写成员时，可按项目约定复用已有文档或使用 <inheritdoc/>
- 非直观实现和关键业务约束添加必要注释，重点解释原因，不逐行复述代码
- 修改代码时同步更新相关注释
## 文件编码
- 优先遵循 .editorconfig 和项目工具链的编码要求
- 未规定时，新建文本文件使用 UTF-8；是否带 BOM 按文件类型和工具链确定，JSON 默认使用 UTF-8（无 BOM）
- 无明确配置或转换要求时，修改已有文件保持原有编码和换行风格
- 不对无关文件批量转换编码或换行符
## 命名与代码风格
- 类型、方法、属性、事件和常量使用 PascalCase；参数和局部变量使用 camelCase
- 私有实例字段使用 _camelCase；接口名称以 I 开头；静态字段遵循项目约定
- 启用可空引用类型时正确标注可空性，不滥用 ! 或 null! 抑制警告
- 方法保持单一职责，优先保证可读性，不为满足固定行数机械拆分
- 普通短字符串组合优先使用字符串内插；日志使用结构化消息模板，不使用字符串内插
- 不静默忽略未处理的异常，不用默认值将失败伪装成成功；在 catch 中原样重新抛出当前异常时使用 throw;，不使用 throw ex;
## 验证要求
- 行为变更应在适用时补充或更新测试
- 使用项目已有命令执行相关构建、测试和格式检查，不擅自引入新的验证工具
- 无法执行验证时，明确说明未执行的项目及原因，不声称验证通过
要約する
コパイロット指示の価値は、口頭で繰り返し強調された要件を、プロジェクト保守のためのデフォルトのガイダンスに変えることです。
実際の .NET 命令は網羅的である必要はありません。最初に変更の境界を明確にし、次に非同期、注釈、エンコードおよび命名方法について合意し、最後に検証方法を説明します。自動で確認できる内容については、 .editorconfigフォーマットツール、パーサー、テストツール。
指示により、Copilot はチームをより深く理解できるようになり、ツールにより結果の信頼性が高まります。 多くの場合、最初に巨大で絶対的なルールを書き出すよりも、小さくて明確なテンプレートから始めて、プロジェクトの実際の状況に基づいて調整する方が効果的です。
