.NETやAzure・Microsoft製品で学んだことや気づいたことを共有しよう

@ochtum(オクトゥム)Team Coffee

プロンプトを頑張るな、リポジトリを育てろ：GitHub Copilotが迷わないコードベース設計

Last updated at 2026-07-08Posted at 2026-07-08

※お役に立てたらストック、いいねをよろしくお願いします！！

＜📝本記事のターゲット層＞

GitHub Copilotに毎回プロジェクト前提を説明している開発者
CopilotやAI Agentの出力がリポジトリの暗黙知とズレることに困っている人
README、設計ドキュメント、custom instructionsを整備したいテックリード
AI時代のリポジトリ設計・ドキュメント設計を考えたい人
AGENTS.md、DESIGN.md、.github/copilot-instructions.md の使い分けを知りたい人

🔷 毎回AIに説明しているなら、リポジトリ設計が負けている

GitHub CopilotやAI Agentに作業を頼むたびに、こんな前提を毎回書いていないでしょうか。

このプロジェクトはVanilla JSです。
React化しないでください。
DB更新は禁止です。
テストはこのコマンドで実行してください。
金額計算はdecimalを使ってください。

もちろん、AIに前提を渡すこと自体は大事です。
ただし、毎回同じことを書いているなら、それは「プロンプトがまだ足りない」のではなく、リポジトリ側にAIが読める前提知識が足りていないのかもしれません。

プロンプトに毎回書く運用には、いくつかつらい点があります。

依頼文がどんどん長くなる
人によって説明の粒度が変わる
チームでレビューしづらい
ルールが変わったときに更新漏れが起きる
新しく参加した人にも、AIにも、同じ説明を何度もすることになる

ここで発想を切り替えます。

「AIに毎回説明する」のではなく、「AIが読みに来られる場所に置く」。

この「置き場所」が、リポジトリです。
AI時代の良いリポジトリは、人間だけでなくAIにも読みやすいリポジトリです。README、設計ドキュメント、テスト方針、Copilot向けcustom instructions、Agent向け手順を整えることで、毎回のプロンプトを短くしつつ、出力のブレを減らせます。

🔷 AIが迷うリポジトリの特徴

AIが迷うリポジトリは、だいたい人間も迷います。

たとえば、以下のような状態です。

README.md が古い
ビルド手順や起動方法が書いていない
命名規則が暗黙知になっている
テストコマンドが分からない
画面とAPIの対応が分からない
ディレクトリごとの責務が分からない
業務用語の意味がコードだけでは読み取れない
触ってはいけない領域が明文化されていない
「なぜこの設計なのか」の判断履歴が残っていない

人間なら、Slackで聞いたり、詳しい人に口頭で確認したりできます。
しかしAI Agentは、基本的にはリポジトリ内の情報と、依頼時に与えられたコンテキストから判断します。

つまり、リポジトリに前提が置かれていないと、AIはコードの表面だけを見て「それっぽい変更」をしてしまいます。

たとえば、既存画面がVanilla JSで作られているのに、AIが勝手にReactコンポーネントを足す。金額計算で decimal を使うべきなのに、double や float に寄せる。更新系SQLを慎重に扱う文化があるのに、通常の変更と同じ重さで扱う。

こうしたズレは、AIの性能だけの問題ではありません。
リポジトリに「このチームでは何を正とするか」が書かれていないことが原因になる場合があります。

🔷 AIが迷わないリポジトリの基本セット

まずは、毎回チャットで説明している暗黙知を、リポジトリ内のファイルに移していきます。

毎回チャットで説明している前提知識は、リポジトリに置くことでAIにも人間にも再利用できるチーム資産になる。

ポイントは、AI向けの情報を特別扱いしすぎないことです。
人間のオンボーディングに必要な情報は、AIにとっても重要なコンテキストになります。

基本セットとしては、例えば以下のように分けると扱いやすいです。

ファイル	役割
`README.md`	プロジェクト概要、起動方法
`.github/copilot-instructions.md`	全体ルール
`.github/instructions/csharp.instructions.md`	C#固有ルール
`.github/instructions/frontend.instructions.md`	HTML/CSS/Vanilla JSルール
`.github/instructions/sql.instructions.md`	SQL、DBアクセス、更新系SQLのルール
`AGENTS.md`	AI coding agent向けのコンテキスト、作業ルール、検証指示
`DESIGN.md`	UIのデザインシステム、色、タイポグラフィ、余白、コンポーネント方針
`docs/architecture.md`	アーキテクチャと責務分担
`docs/adr/*.md`	設計判断の記録
`docs/testing.md`	テスト方針、実行コマンド
`docs/domain-glossary.md`	業務用語

UIを持つプロダクトでは、ここに DESIGN.md も加えると整理しやすくなります。
DESIGN.md は、Google Labsが公開しているGoogle Stitch由来の形式で、AI coding agentに視覚的なデザインシステムを伝えるためのMarkdownファイルです。色、タイポグラフィ、余白、角丸、コンポーネントの意図などを、YAML front matterとMarkdown本文で記述できます。

🔹 GitHub Copilot向けの置き場所

GitHub Docsでは、リポジトリ全体向けのcustom instructionsとして .github/copilot-instructions.md を作成する手順が案内されています。
また、パス固有のcustom instructionsは .github/instructions 配下、またはその下位に置く NAME.instructions.md ファイルとして指定できます。

2026年7月時点のGitHub Docsでは、パス固有のcustom instructionsについて、GitHub.com上ではCopilot cloud agentとCopilot code review向けにサポートされると説明されています。リポジトリ全体のcustom instructionsとパス固有のcustom instructionsの両方が条件に合う場合は、両方の指示が使われます。

🔹 VS Codeでの使い分け

VS Code Docsでは、まず .github/copilot-instructions.md をプロジェクト全体のルールとして用意し、ファイル種別やフレームワークごとに違うルールが必要になったら .instructions.md を追加する、という考え方が示されています。

さらに、複数のAI Agentを使う場合は AGENTS.md を使う選択肢も紹介されています。AGENTS.md はVS Codeでもワークスペースルートのファイルとして検出され、チャットリクエストに適用される仕組みとして説明されています。

※対応範囲はGitHub Copilot、VS Code、組織設定、プラン、利用画面によって変わる可能性があります。公開前や運用開始前には、必ず公式ドキュメントの最新情報を確認してください。

🔷 何をどこに書くべきか

AI向けの情報設計で大事なのは、何でも1ファイルに詰め込まないことです。

README.md に全部を書くと長くなりすぎます。
逆に、AGENTS.md に業務仕様や設計判断まで全部入れると、agent向けの作業ルールとして読みづらくなります。

情報の寿命と適用範囲で置き場所を分けると、リポジトリが育てやすくなります。

repository-root/
  README.md
  AGENTS.md
  DESIGN.md
  .github/
    copilot-instructions.md
    instructions/
      csharp.instructions.md
      frontend.instructions.md
      sql.instructions.md
      testing.instructions.md
  docs/
    architecture.md
    testing.md
    domain-glossary.md
    adr/
      0001-use-vanilla-js.md
      0002-money-as-decimal.md

この構成を図にすると、次のような役割分担になります。

AIが読めるリポジトリでは、入口、開発ルール、Agent向け指示、設計・業務知識、UIデザイン文脈を分けて置く。

🔹 README.md: 人間とAIの入口

README.md には、プロジェクトの概要、起動方法、よく使うコマンド、主要ディレクトリの説明を書きます。

ここは新しく入った人が最初に読む場所です。AIにとっても、プロジェクトの全体像をつかむ入口になります。

# サンプル

## 概要

このリポジトリは、C#バックエンドとVanilla JSフロントエンドで構成されています。

## よく使うコマンド

- ビルド: `dotnet build`
- テスト: `dotnet test`
- フロントエンドLint: `npm run lint`

## ディレクトリ構成

- `src/Web`: Webアプリケーション
- `src/Application`: ユースケースとサービス
- `src/Infrastructure`: データベースアクセス
- `docs`: アーキテクチャ、テスト、業務知識

🔹 .github/copilot-instructions.md: 全体ルール

.github/copilot-instructions.md には、リポジトリ全体で常に守ってほしいルールを書きます。

たとえば、技術スタック、命名規則、アーキテクチャ上の原則、セキュリティ上の注意、避けてほしい実装方針などです。

# リポジトリ全体のCopilot向け指示

- このプロジェクトはバックエンドにC#、フロントエンドにVanilla JSを使います。
- Controllersは薄く保ち、ビジネスロジックはService層に置きます。
- 明示的に依頼されない限り、ReactやVueを導入しないでください。
- 金額計算には `decimal` を使ってください。
- データベース更新SQLは、レビュー重要度の高い変更として扱ってください。
- 新しい抽象化を増やす前に、既存の実装パターンを優先してください。

ここに書く内容は「どの作業でもだいたい効いてほしいルール」に絞るのがおすすめです。

🔹 .github/instructions/*.instructions.md: 領域別ルール

.github/instructions/*.instructions.md には、C#、フロントエンド、SQL、テストなど、領域別のルールを書きます。

VS Codeの .instructions.md では、frontmatterの applyTo で適用対象を指定できます。

---
applyTo: "**/*.{html,css,js}"
---

# フロントエンド向け指示

- 既存のVanilla JS構成を維持してください。
- 画面をReactへ移行しないでください。
- 既存のCSS命名規則に合わせてください。
- 既存のイベントハンドラの構成を再利用してください。

このように分けておくと、フロントエンドの作業ではフロントエンドのルール、SQLの作業ではSQLのルールを参照しやすくなります。

🔹 AGENTS.md: Agent向けコンテキストと作業ルール

AGENTS.md は、AI coding agent向けのコンテキストと指示を書くための、予測可能な場所です。
「Agent向け作業手順」と言っても間違いではありませんが、それだけだと少し狭いです。実際には、プロジェクト概要、セットアップ、ビルド・テストコマンド、コード規約、セキュリティ上の注意、PR時のレビュー観点など、agentが安全に作業するための情報を書きます。

GitHub Changelogでは、Copilot coding agentが AGENTS.md custom instructionsをサポートし、ルートの単一ファイルだけでなく、特定ディレクトリ向けのネストした AGENTS.md も使えると説明されています。AGENTS.md公式サイトでも、プロジェクト概要、ビルド・テストコマンド、コードスタイル、テスト指示、セキュリティ上の注意などを書く例が紹介されています。

# Agent向け指示

## ビルドとテスト

- バックエンド変更を完了する前に、バックエンドテストを実行してください。
- UI変更を完了する前に、フロントエンドのLintを実行してください。

## 安全策

- タスクで明示されていない限り、データベースマイグレーションファイルを変更しないでください。
- タスクで明示されていない限り、CSV出力の挙動を変更しないでください。

## レビュー観点

- 金額計算、日付処理、更新SQLに影響する変更は、完了報告で明示してください。

AGENTS.md は、AI向けの作業ルールであると同時に、人間の開発者にとっても「このリポジトリで安全に作業するための手引き」になります。

🔹 DESIGN.md: UIのデザインシステムを置く場所

DESIGN.md は、UIを持つプロダクトで特に効きます。
Google Labsの google-labs-code/design.md リポジトリでは、DESIGN.md は「coding agentsに視覚的アイデンティティを説明するための形式」と説明されています。Googleのブログでも、Stitchの DESIGN.md はデザインルールをプロジェクト間でexport/importでき、AI agentが色の意図を推測せず理解できるようにするものとして紹介されています。

たとえば、次のような情報を DESIGN.md に置きます。

---
name: サンプル管理画面
colors:
  primary: "#1A5E2A"
  accent: "#1976D2"
  surface: "#F7FAF8"
typography:
  body:
    fontFamily: "Noto Sans JP"
    fontSize: "16px"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"
---

## 見た目の方針

- マーケティングページ風ではなく、落ち着いた業務UIにしてください。
- 主要アクションには `primary` を使ってください。
- 新しいアクセントカラーを追加する場合は、このファイルも更新してください。
- カードは `md` の角丸を使い、影は控えめにしてください。

AGENTS.md が「このリポジトリでどう作業するか」を伝える場所だとすると、DESIGN.md は「このプロダクトのUIをどう見せるか」を伝える場所です。
UI生成や画面改修をAIに任せるなら、README.md や AGENTS.md だけでなく、DESIGN.md も候補に入れておくとよいです。

🔹 docs/: 設計・業務知識を置く場所

docs/ には、チャットの短い指示に詰め込むには重い情報を置きます。

docs/architecture.md: アーキテクチャ、責務分担、依存方向
docs/adr/*.md: 設計判断の記録
docs/testing.md: テスト方針、実行コマンド、確認観点
docs/domain-glossary.md: 業務用語、略語、ドメイン固有の意味

業務用語や設計判断は、コードだけを見ても分からないことがあります。
AIがそれっぽく補完してしまう前に、リポジトリ内に「正しい前提」を置いておくことが大切です。

🔷 C# の例で見る、AIが読めるルール化

ここからは、C# の例で考えてみます。

たとえば、次のような暗黙知があるとします。

Controllersは薄くする
ビジネスロジックはService層に置く
SQL直書きは禁止
日付はJST基準
金額計算は decimal
既存のVanilla JS構成を維持する
React化しない
更新系SQLは必ずレビュー対象

これを毎回プロンプトに書くのは、かなり大変です。
しかも、誰かが書き忘れると、その瞬間にAIの出力がズレます。

そこで、リポジトリ内に以下のように分散して置きます。

🔹 全体ルールはcopilot-instructionsへ

# リポジトリ全体のCopilot向け指示

- このプロジェクトはバックエンドにC#、フロントエンドにVanilla JSを使います。
- Controllersは薄く保ち、ビジネスロジックはService層に置きます。
- 明示的に依頼されない限り、ReactやVueを導入しないでください。
- 金額計算には `decimal` を使ってください。
- データベース更新SQLは、レビュー重要度の高い変更として扱ってください。
- 新しい抽象化を増やす前に、既存の実装パターンを優先してください。

ここでは、プロジェクト全体で常に守ってほしい考え方を書きます。

「React化しない」「金額は decimal」「既存パターンを優先する」といったルールは、いろいろな作業で効いてほしいので、全体ルールに向いています。

🔹 フロントエンド固有ルールはinstructionsへ

---
applyTo: "**/*.{html,css,js}"
---

# フロントエンド向け指示

- 既存のVanilla JS構成を維持してください。
- 画面をReactへ移行しないでください。
- 既存のCSS命名規則に合わせてください。
- 既存のイベントハンドラの構成を再利用してください。

フロントエンドの話だけを全体ルールに入れすぎると、C#やSQLの作業時にもノイズになります。
領域別に分けることで、ルールの見通しがよくなります。

🔹 作業ルールと安全策はAGENTS.mdへ

# Agent向け指示

## ビルドとテスト

- バックエンド変更を完了する前に、バックエンドテストを実行してください。
- UI変更を完了する前に、フロントエンドのLintを実行してください。

## 安全策

- タスクで明示されていない限り、データベースマイグレーションファイルを変更しないでください。
- タスクで明示されていない限り、CSV出力の挙動を変更しないでください。

## レビュー観点

- 金額計算、日付処理、更新SQLに影響する変更は、完了報告で明示してください。

ここには、作業の最後に何を確認するか、どこを触ってはいけないか、レビュー時に何を強調するかを書きます。

💡 Tips: 「禁止」だけでなく「代わりに何をするか」も書く

AI向けのルールを書くときは、「禁止」だけで終わらせないほうが実用的です。

たとえば、次のように書くと、AIが次の選択肢を取りやすくなります。

- ControllersにSQLを直接書かないでください。
- データベースアクセスには既存のRepositoryクラスを使ってください。
- 新しいクエリが必要な場合は、`Infrastructure/Repositories` 配下に追加してください。

「SQL直書き禁止」だけだと、AIはどこに書けばよいか迷います。
「代わりに既存のRepository層を使う」と書くことで、望ましい方向へ誘導できます。

❓ 困ったときは: ルールが効いていないように見える場合

custom instructionsや AGENTS.md を置いたのに期待どおりにならない場合は、以下を確認してみてください。

ファイルの置き場所が正しいか
対象のツールや画面がその形式に対応しているか
組織設定やリポジトリ設定で無効化されていないか
ルールが長すぎて重要点が埋もれていないか
競合する指示を別ファイルに書いていないか
チャットで明示した依頼内容とリポジトリ内ルールが矛盾していないか

特に、対応範囲はGitHub Copilotの利用画面やVS Code側の設定で変わる可能性があります。
「ファイルを置けばすべてのAIが必ず同じ挙動をする」とは考えず、実際の作業フローで効き方を確認しながら育てていくのが安全です。

✅ まとめ: AI時代の良いリポジトリは、人間にも優しい

この記事では、GitHub CopilotやAI Agentに毎回同じ説明を書かないために、リポジトリ側へ前提知識を置く考え方を紹介しました。

要点をまとめます。

毎回同じ前提をプロンプトに書く運用は、属人化しやすい
AIが迷う場所は、人間の新規参加者も迷いやすい
README.md は人間とAIの入口になる
.github/copilot-instructions.md にはリポジトリ全体のルールを書く
.github/instructions/*.instructions.md には領域別のルールを書く
AGENTS.md にはAI coding agent向けのコンテキスト、作業ルール、検証方法、禁止事項を書く
DESIGN.md にはUIのデザインシステム、色、タイポグラフィ、コンポーネント方針を書く
docs/ には設計判断、業務用語、テスト方針などの深い知識を置く

最初から完璧なドキュメントセットを作る必要はありません。

まずは .github/copilot-instructions.md に、毎回チャットで書いている前提を5つだけ移してみてください。
次に README.md を更新し、必要に応じて .instructions.md、AGENTS.md、UIがあるなら DESIGN.md を追加していくと、無理なく育てられます。

プロンプトを頑張るほど、前提知識は個人の手元に閉じやすくなります。
リポジトリに置けば、チームでレビューでき、更新でき、再利用できます。

これからは、AIに毎回説明するのではなく、AIが読めるリポジトリに育てる。
そのほうが、AIにも人間にも優しいコードベースになります。

🔷 参考URL

※お役に立てたらストック、いいねをよろしくお願いします！！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up