Go to Qiita Advent Calendar Top
LoginSignup
10
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 7

metaps Advent Calendar 2025

@h_minato

【GitHub Copilot】copilot-instructionsを形骸化させないための実践的運用ガイド

Last updated at Posted at 2025-12-06

はじめに

GitHub Copilotを日常的に使っている方の中には、ルールファイルであるcopilot-instructions.md（以下、instructions）の存在は知っているけれど、どのタイミングで何を書けば良いのか迷っている方もいるのではないでしょうか。
instructionsを一度書いたきりメンテナンスしていない、あるいは活用しきれていないと感じている方に向けて、実践的な運用ルールを紹介します。

本記事で扱う copilot-instructions.md は、リポジトリのルート直下の .github/ ディレクトリ配下に配置するファイルを想定しています（例: .github/copilot-instructions.md）。

GitHub Copilotでいう instructions は「AIの振る舞いを制御するルールファイル」です。
これは各AIエージェントツールにも共通して存在するため、下記のような別ツールでも応用できます。

AIエージェントツール ルールファイル 参考
Cursor .cursor/rules/*.mdc or AGENTS.md https://cursor.com/ja/docs/context/rules
Claude Code CLAUDE.md https://code.claude.com/docs/ja/memory
OpenAI Codex AGENTS.md https://developers.openai.com/codex/guides/agents-md/

この記事の対象

この記事は以下のような方を対象としています。

  • instructionsを初めに作成しただけでメンテナンスしていない方
  • GitHub Copilot使いたてで、instructionsの効果的な使い方を知りたい方
  • Copilotの提案に対して同じ指摘を繰り返している方
  • instructionsに何を書くべきか判断基準が分からない方

「二回ルール」の提案

Copilotが提案した内容に対して、同じ指摘を二回したら、instructionsに指摘内容を追記する。

これが私が実践している判断基準です。

なぜ「二回」なのか。一回目の指摘は、たまたま発生した個別のケースかもしれません。
しかし二回目が来たとき、それはパターンとして認識すべきサインです。

この「二回ルール」を導入してから、提案される内容の品質が明らかに向上しました。
Copilotの提案精度が上がり、設計段階から望ましい実装パターンを提示してくれるようになったためです。

実践例1：既存実装の活用

問題

新機能を実装する際、プロジェクト内に既にapp/Utils/StringHelper.phpというUtilクラスが存在しているにもかかわらず、Copilotがその存在に気づかず新規メソッドを提案してしまうケースが発生しました。

php
// 既に存在するStringHelper
// app/Utils/StringHelper.php
class StringHelper
{
    public static function formatFullName(string $firstName, string $lastName): string
    {
        return $firstName . ' ' . $lastName;
    }
}

❌Before（Copilotの挙動）

php
// Copilotの提案：既存実装を無視して新規メソッドを作成
class UserService
{
    public function displayUserInfo(User $user): void
    {
        $fullName = $user->firstName . ' ' . $user->lastName;
        echo "User: " . $fullName;
    }
}

instructionsへの追記

## 実装の基本方針
- 新機能の実装前に、必ず既存実装を調査すること
- 既存実装が見つかった場合は、新規作成ではなく活用・拡張する方針をとること
- 類似機能を実装する場合は、既存のutilsディレクトリやヘルパー関数を確認すること

✅After（改善後の提案）

php
// Copilotの提案：既存のStringHelperを直接活用
use App\Utils\StringHelper;

class UserService
{
    public function displayUserInfo(User $user): void
    {
        $fullName = StringHelper::formatFullName($user->firstName, $user->lastName);
        echo "User: " . $fullName;
    }
}

効果

Copilotが既存のUtilクラスのメソッドを直接活用する提案をするようになりました。
不要なラッパーメソッドを作成せず、既存実装を直接利用する方向でコードを生成してくれます。コードの一貫性が向上し、レビュー時の指摘も減少しました。

実践例2：コードの共通化

問題

ユーザー登録と問い合わせフォームでメールアドレスのバリデーションロジックが重複して実装されているケースが発生しました。
同じロジックが複数箇所に存在すると、修正時に全箇所を変更する必要があり、バグの温床になります。

❌Before（Copilotの挙動）

php
// Copilotの提案：各所で重複したバリデーションロジック
class UserRegistrationService
{
    public function register(string $email, string $password): void
    {
        // メールアドレスのバリデーション
        $pattern = '/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/';
        if (preg_match($pattern, $email) !== 1) {
            throw new InvalidArgumentException('Invalid email format');
        }

        // ユーザー登録処理
        // ...
    }
}

class ContactFormService
{
    public function submit(string $email, string $message): void
    {
        // メールアドレスのバリデーション（重複）
        $pattern = '/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/';
        if (preg_match($pattern, $email) !== 1) {
            throw new InvalidArgumentException('Invalid email format');
        }

        // 問い合わせ送信処理
        // ...
    }
}

instructionsへの追記

## コード品質の基準
- 3行以上の重複コードがある場合は共通化を検討すること
- 重複が見つかった場合は、関数やメソッドとして切り出すこと
- 共通化したコードは適切な場所（utils、helpersなど）に配置すること

✅After（改善後の提案）

php
// 共通化されたバリデーションヘルパー
// app/Utils/ValidationHelper.php
class ValidationHelper
{
    public static function validateEmail(string $email): bool
    {
        $pattern = '/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/';
        return preg_match($pattern, $email) === 1;
    }
}

// Copilotの提案：共通メソッドを直接利用
use App\Utils\ValidationHelper;

class UserRegistrationService
{
    public function register(string $email, string $password): void
    {
        // 共通化されたバリデーションを利用
        if (!ValidationHelper::validateEmail($email)) {
            throw new InvalidArgumentException('Invalid email format');
        }

        // ユーザー登録処理
        // ...
    }
}

class ContactFormService
{
    public function submit(string $email, string $message): void
    {
        // 共通化されたバリデーションを利用
        if (!ValidationHelper::validateEmail($email)) {
            throw new InvalidArgumentException('Invalid email format');
        }

        // 問い合わせ送信処理
        // ...
    }
}

効果

設計段階から共通化された状態で提案されるため、後からのリファクタリング工数が削減されました。
修正が必要になった場合も、ValidationHelperの一箇所を変更すれば済むようになりました。

実践例3：ドキュメントへの目次追加

問題

Copilotにドキュメントを生成してもらう際、目次が含まれていないケースが発生しました。
目次がないため、特定のセクション（例：エラーハンドリング）を探す際に、ドキュメント全体をスクロールして探す必要があり、内容の確認に工数が発生していました。

❌Before（Copilotの挙動）

# API仕様書

## 概要
このAPIは...

## エンドポイント一覧
### GET /users
...

### POST /users
...

## エラーハンドリング
...

## 認証
...

instructionsへの追記

## ドキュメント作成の基準
- mdファイルでドキュメントを生成する際は、ファイル先頭に目次を作成すること
- 目次の各項目はクリックしてジャンプできるようにすること
- 目次は見出しレベル2（##）以下を対象にすること

✅After（改善後の提案）

# API仕様書

## 目次
- [概要](#概要)
- [エンドポイント一覧](#エンドポイント一覧)
  - [GET /users](#get-users)
  - [POST /users](#post-users)
- [エラーハンドリング](#エラーハンドリング)
- [認証](#認証)

## 概要
このAPIは...

## エンドポイント一覧
### GET /users
...

### POST /users
...

## エラーハンドリング
...

## 認証
...

効果

Copilotが生成するドキュメントには必ず目次が含まれるようになりました。
目次から直接該当セクションにジャンプできるため、ドキュメントの確認工数が削減されました。

instructionsメンテナンスのコツ

小さく始める

最初から完璧なinstructionsを作ろうとせず、問題に遭遇したら追記する運用をおすすめします。
気になった点はその都度書き加えて、後から不要なルールを整理する運用が効果的です。

定期的なメンテナンス

目安として、一ヶ月に一度は instructions 全体を読み返し、現在のプロジェクト内容とズレていないか確認することをおすすめします。

矛盾した指示を避ける

instructionsに追記する際は、既存のルールと矛盾しないか確認してください。
たとえば「コメントは最低限記載すること」と「詳細なコメントを必ず書くこと」のような矛盾した指示があると、Copilotがどちらに従うべきか判断できなくなります。

矛盾が発生した場合は、優先度を明示するか、どちらかを削除・修正します。
定期的にメンテナンスする際に、矛盾点がないかチェックすることをおすすめします。

まとめ

「二回ルール」を実践することで、instructionsを効果的に運用できます。

始め方はシンプルです。提案内容に対して同じ指摘をした場合はinstructionsに追記する。
そして効果を確認しながら、継続的に改善していくだけです。

instructionsを活用して、より効率的な開発を実現してください。

おまけ：instructions例

参考として、筆者が使用しているinstructionsの一部を抜粋して紹介します。
(全体像や主要ディレクトリ等の部分に関しては例として記載しています。)

記事で紹介した「二回ルール」を実践して積み上げたものです。
※ そのままコピペして使うのではなく、プロジェクトの規模・設計方針に合わせてカスタマイズすることをおすすめします。

instructions例（クリックで開く） 
## 全体像 / アーキテクチャ
- 技術スタック: PHP 8.3, Laravel 11, MySQL 8.0
- アーキテクチャ: MVCモデルを採用したRESTful APIサーバー
- フロントエンドはNext.jsで構築されており、APIレスポンスはJSON形式で統一する

## 主要ディレクトリ
- `app/Utils`: 汎用的なヘルパー関数（ビジネスロジックを含まない）
- `app/Services`: ビジネスロジックを集約するサービス層

## コード規約
- コーディング規約はPSR-12に準拠すること
- ネストを深くしないため、Early Return（早期リターン）を積極的に採用すること
- 変数は `$camelCase`、クラス名は `PascalCase`、定数は `UPPER_SNAKE_CASE` とする

## 実装の基本方針
- 新機能の実装前に、必ず既存実装を調査すること
- 既存実装が見つかった場合は、新規作成ではなく活用・拡張する方針をとること
- 類似機能を実装する場合は、既存のutilsディレクトリやヘルパー関数を確認すること

## コード品質の基準
- 3行以上の重複コードがある場合は共通化を検討すること
- 重複が見つかった場合は、関数やメソッドとして切り出すこと
- 共通化したコードは適切な場所（utils、helpersなど）に配置すること

## ドキュメント作成の基準
- mdファイルでドキュメントを生成する際は、ファイル先頭に目次を作成すること
- 目次の各項目はクリックしてジャンプできるようにすること
- 目次は見出しレベル2（##）以下を対象にすること

## その他
- 返答は必ず日本語で返答すること。
- 設計書を元に実装する際に、設計書に存在しない変更・挙動を指示する場合は、コードだけでなく設計書側の更新も必ずセットで提案・実施すること。
- 不明な点は積極的に質問する
- 選択肢にはそれぞれ、推奨度と理由を提示する
  - 推奨度は⭐の5段階評価
10
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
10
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?