GitHub Copilot の `@ files ` を使って Copilot に見てもらいたいファイルを効率的に伝える
製造ビジネステクノロジー部の小林です。
GitHub Copilot (CLI や Chat) を使っている際に、
「このファイルを見ながら修正してほしい」
「この設定ファイルの内容を説明してほしい」
といった場面が出てきますよね。
今まで私はファイル名をコピペしていましたが、チームメンバーから「@files 便利ですよ！」と教えてもらいました。
調べてみると、@ を使ってファイル指定を指定できることがわかりました。
プロンプトに @<読み込ませたいファイル> と書くだけで、そのファイルの内容が Copilot のコンテキストとして渡されます。
この記事では、@ を使ったファイル指定方法を紹介します。
前提
今回は GitHub Copilot CLI を利用して動作確認をします。
@ files とは
公式ドキュメントには以下のように記載されています。
プロンプトに特定のファイルを追加するには、
@に続けてファイルへの相対パスを指定します。例えば、Explain @config/ci/ci-required-checks.ymlやFix the bug in @src/app.jsなどです。これにより、ファイルの内容が Copilot のコンテキストとしてプロンプトに追加されます。
つまり、書き方はシンプルに以下の通りです。
<やりたいこと> @<ファイルへの相対パス>
たとえば、
@README.md の内容を説明して
→ README.md の内容を読み込んで、何が書かれているか説明してもらうプロンプトです。
@src/app.js のバグを修正して
→ src/app.js の内容を渡して、バグを見つけて修正してもらうプロンプトです。
@lambda/handler/index.ts のコードをレビューして
→ lambda/handler/index.ts を渡して、コードレビューをしてもらうプロンプトです。
Tab 補完でファイルを選択できる
@ を入力してファイルパスを書き始めると、プロンプトボックスの下にパスの候補が表示されます。
矢印キーで選択し、 Tab を押すと、パスが自動補完されます。長いパスを手で入力する必要がないので便利です。
実際のユースケース
ファイルの内容を説明させる
設定ファイルや初めて触るコードファイルを渡して、内容を説明させることができます。
@.github/workflows/deploy.yml の内容を説明して
バグ修正を依頼する
特定のファイルを指定してバグ修正を依頼できます。
@src/app.js のバグを修正して
エラーメッセージも一緒に渡すと、より精度の高い修正を提案してくれます。
@lambda/handler/index.ts でエラーが発生しています。TypeError: Cannot read properties of undefined (reading 'id') というエラーを修正して
複数ファイルを同時に指定する
@ は複数指定することもできます。関連するファイルをまとめて渡すことで、ファイル間の関係を踏まえた回答が得られます。
@lambda/handler/index.ts と @lambda/database/connection.ts を見て、データベース接続の処理を改善する方法を提案して
画像ファイルも渡せる
テキストファイルだけでなく、画像ファイルも渡すことができます。スクリーンショットやエラー画像を添えて質問するといった使い方が可能です。
@error-screenshot.png のエラーを見て原因を教えて
@ を使わなくてもファイルを読んでくれる？実際に試してみた
実は @ を使わなくても、ファイル名や相対パスをそのまま書くだけで Copilot がファイルを読んでくれることがあります。
試しに以下の 3 パターンで同じファイルをレビューさせてみました。
パターン ① ファイル名だけ
subscriptionHandler.ts のソースをレビューして
パターン ② 相対パスで指定
lambda/handler/subscriptionHandler.ts のソースをレビューして
パターン ③ @を使って指定
@lambda/handler/subscriptionHandler.ts のソースをレビューして
結果は 3 パターンともファイルを読んでレビューできました
一方、よく見るとパターン ①② では Copilot が内部でファイルを探すツールを呼び出しているのが分かります。
● Searching the repo for subscriptionHandler.ts to open and review.
Running glob + reporting intent in parallel.
● Search (glob)
│ "**/subscriptionHandler.ts"
└ 1 file found
● Read subscriptionHandler.ts
一方、@ を使ったパターン ③ ではファイル検索をスキップして直接読み込んでいます。
● Reading the file to review its code, find issues, and suggest improvements.
● Read subscriptionHandler.ts
@ を使うメリット 確実性とトークンの節約
@ なしでも読めることが多いですが、たまに読めないこともあります。プロジェクト構成によってはファイルを見つけられないケースもあるので、確実に読み込ませたいときは @ を使うのが安心です。
そしてもう一つ重要なのがトークンの節約です。
@ なしの場合、Copilot は glob 検索 → ファイル読み込みという 2 回分のツール呼び出しを行い、その結果がすべてコンテキストウィンドウに記録されます。@ を使えば検索をスキップしてファイル内容だけが渡されるので、その分トークンを節約できます。
1 回の差は小さいですが、長いセッションで何度もファイルを参照すると、積み重なって大きな消費量になります。 公式ドキュメントでも「ツール呼び出しの結果はコンテキストウィンドウに蓄積され、特にファイル読み込みを伴う場合は特に大きくなる可能性がある」と言及されています。
まとめ
@ でのファイル指定を使うことで、Copilot CLI がよりプロジェクトの文脈を理解した回答を返してくれるようになります。特に複数ファイルを組み合わせた修正や説明を求めるときに重宝します。ぜひ実際に試してみてください！
参考リンク
