チーム開発でcopilot-instructions.mdを導入してみたら、コードレビューの負担が減った
チーム開発でcopilot-instructions.mdを導入してみたら、コードレビューの負担が減った
前提
この記事では、vscodeで github copilotを使った開発環境での話をしてますが
他のAI エディタを使用している方も基本的に同じ機能があるので読み替えていただけたらと思います！
はじめに
こんにちは！
現在業務でNext.jsを使ったwebアプリケーションを開発しています。
チームメンバーは私含め5名です。
チーム内で私が1番Next.jsやReactを触った経験が長いため、コードレビューのほとんどを担当させていただいています。
ただ、他のメンバーがNext.js、Reactの経験がある方が他におらず、メンバー内やPRのたびにコードの品質が結構異なるという現象が起きており、レビューやリファクタリングの負担が大きいことが課題でした。
特にAI駆動で開発していたこともあり、出力されるコードの形式や品質がバラバラなことが大きな原因だと思っています。
そこで今回、GitHub Copilotの.github/copilot-instructions.mdという機能を使って、チーム全体のコーディング規約やベストプラクティスを記載し整備したところ、コードレビューにおいて予想以上の効果があったので共有します。
(その他AI エディタをお使いの方も同様の機能があると思います。)
課題：チーム開発での知識共有の難しさ
まず以下のような課題を感じていました：
1. レビューで同じ指摘を繰り返す
- 以前PRで指摘したことを、別のメンバーが再度同じミスをしてしまう
- レビュアーも「この前も説明したな...」と感じながら、丁寧に同じフィードバックを書く必要がある
- ベストプラクティスやプロジェクト固有のパターンが浸透しづらい
2. メンバーへのナレッジ共有コスト
- プロジェクト特有の規約を口頭やSlackで説明→時間がかかる
- 作業状況によっては質問しづらい雰囲気が生まれることも
- ドキュメントを用意し共有しても、読まれない／読んでも実装時に忘れる
3. コードの一貫性を保つのが大変
- メンバーごとやPR毎に書き方が違う
- レビューで統一を図るも、レビュアーの負担が大きい
- 後から見返すと「なぜここだけ違う書き方?」となる
解決策：copilot-instructions.mdでAIに教育
そこで、GitHub Copilotが自動で読み込んでくれる.github/copilot-instructions.mdに、プロジェクトのルールを記載することにしてみました。
copilot-instructions.mdって何？
.github/copilot-instructions.mdは、GitHubリポジトリに配置するだけで、GitHub Copilotが自動的に読み取り、コード提案に反映してくれるファイルです。
- チーム全員が同じファイルを共有
- 特別な設定不要（リポジトリに置くだけ）
- コード補完、チャット提案、コードレビュー、すべてに効果
何を書いたか
例えば私たちは以下のような内容を記載しました：
- Next.js 15、React19のベストプラクティス
- 基本的なAPIの実装内容
- エラーハンドリングの対応
- セキュリティチェックリスト
- パフォーマンス最適化のポイント
具体的に何が変わったか
1. コード補完が「プロジェクトの正解」を提案してくれる
例えば、新しいAPI関数を書き始めると：
export async function getAlarmData() {
// ここまで書くと、Copilotが自動で提案
// → Result<T>パターンを使ったコード
// → 規約に沿った実装を提案してくれる
}
開発者はタブキーを押すだけで、規約に沿ったコードが書けるようになりました。
2. チャットで質問すると、プロジェクト固有の回答が返ってくる
従来：
- 開発者「Next.js 15でparamsってどう取得するんだっけ?」
- Slack → 先輩に質問 → 回答待ち → 実装
現在：
- 開発者「Next.js 15でparamsってどう取得するんだっけ?」
- GitHub Copilot Chat → 即座に「このプロジェクトではparams = await params」と提案
- そのまま実装
3. レビュー指摘が「本質的な内容」に集中できる
導入前のレビュー：
- [ ] Result<T>パターンを使ってください
- [ ] try-catchを追加してください
- [ ] 認証チェックを追加してください
- [ ] この変数名をキャメルケースにしてください
- [ ] ロジックがちょっと複雑なので、関数に分けませんか?（本質的な指摘）
導入後のレビュー：
- [ ] ロジックがちょっと複雑なので、関数に分けませんか?
基本的な規約はAIが守ってくれるので、レビュアーは設計やロジックの妥当性に集中できるようになりました。
実装のポイント
どうやって書いたか
-
既存のレビュー指摘を集めた
- 過去のPRコメントから頻出の指摘をピックアップ
- 「何度も説明している内容」を優先
-
❌/✅形式で具体例を書いた
- 文章だけだと伝わりにくい
- 良い例・悪い例を並べて比較
-
継続的に更新
- 新しいパターンが生まれたら追加
- メンバーが困った点があれば即座に追記
こんなチームにおすすめ
以下のようなチームには、効果があるかもしれません
✅ バイブコーディングを行っている
✅ 特定の領域の経験が浅いメンバーがいる
✅ 新メンバーの参加が多い
✅ プロジェクト固有のパターンがある
✅ レビューで同じ指摘を繰り返している
✅ コードの一貫性を高めたい
まとめ
GitHub Copilotの.github/copilot-instructions.mdを導入したことで：
- ✅ レビュー時間が減った
- ✅ メンバーの理解度が上がった
- ✅ 基本的な規約違反が減った
- ✅ レビューが本質的な内容に集中できるようになった
初期コストはほんの少しかかりますが、チームの生産性向上効果は感じました
特に、「以前も指摘したことを再度説明する」という負担が減り、開発スピードが上がったと思います。
また、今回チーム開発でのメリットについて記載しましたが、個人開発でも同じように恩恵を得れると思います。
私自身まだまだ使いこなせていないと思いますし、触れてない機能もたくさんあると思うので引き続き勉強します！
Discussion