こんにちは。ACS事業部の越川です。
コーディングツール（GitHub Copilot CLI、Claude Code、Cline、Cursorなど）を使っていて、こんな経験はないでしょうか。
- 毎回「変数名はキャメルケースで」と伝えている
- 毎回「エラーハンドリングはこのパターンで」と指示している
- 前回指摘したはずのコーディング規約違反が、次のセッションでまた起きる
これはAIの問題ではなく、指示の仕方の問題です。毎回ゼロから指示を押し込むのではなく、文脈を蓄積してAIが自ら引き出せる状態にする。そのために使うのがインストラクションファイルです。
本記事では、インストラクションファイルの構造と書き方を、私自身の実践を交えて具体的に共有します。
- インストラクションファイルとは
- インストラクションに書くべきこと
- フィードバックを蓄積する仕組み
- 応用: 技術ブログの執筆にも使える
- まとめ — インストラクションは「育てる」もの
- 参考資料
- ACS 事業部のご紹介
インストラクションファイルとは
コーディングツールには、プロジェクトのルートに置いたファイルを自動的に読み込む機能があります。
| ツール | ファイル名 |
|---|---|
| Claude Code | CLAUDE.md |
| GitHub Copilot CLI | .github/copilot-instructions.md |
| Cline | .clinerules |
| Cursor | .cursorrules |
ファイル名は異なりますが、役割は同じです。プロジェクトの文脈・ルール・方針を書いておくことで、AIがそれを参照して動く。毎回口頭で伝える代わりに、ドキュメントとして残す。これだけで協働の質が変わります。
インストラクションに書くべきこと
コーディング規約
チームで統一したいルールを書きます。
- 変数名はキャメルケース、定数はアッパースネークケース
- エラーハンドリングは Result 型を使用し、例外はスローしない
- コメントは「なぜ」を書く。「何をしているか」はコードで表現する
- テストファイルは対象ファイルと同じディレクトリに {name}.test.ts で配置
プロジェクト固有の文脈
AIが知らない、プロジェクト固有の情報を補います。
- APIのベースURLは環境変数 API_BASE_URL から取得する - 認証トークンは Authorization ヘッダーに Bearer 形式で付与 - DBスキーマの変更は必ずマイグレーションファイルを作成する - 外部APIのレート制限は100req/min。リトライは指数バックオフで実装
ワークフロー
チームの開発フローを記載します。
- ブランチ戦略: main → feature/{issue-number}-{description}
- コミットメッセージ: Conventional Commits に従う
- PRはdraft作成 → セルフレビュー → レビュー依頼の順
- CIが通らないPRはマージしない
ポイント: 「何を書くか」ではなく「なぜそうするか」
インストラクションには、単なるルールの羅列ではなく背景や理由を書くことが重要です。
悪い例: - 技術名は正式名称で書く 良い例: - 技術スタック名は必ず正式名称を使うこと （例: ×「Copilot CLI」→ ○「GitHub Copilot CLI」）。省略・略称は不可
理由や具体例があると、AIは未知のケースでも正しく判断できます。「Copilot CLI」はNGと書いてあれば、「Cursor」を「CSR」と略すこともしなくなる。ルールの意図を理解させることで、明示していないケースにも対応できるようになります。
フィードバックを蓄積する仕組み
インストラクションファイルと並んで重要なのが、フィードバックの記録です。
コードレビューで指摘を受けたとき、その場で直すだけで終わっていないでしょうか。同じ指摘を次のPRでも受けているなら、それは仕組みの問題です。
lessons-learned.md を作る
指摘と学びをセットで記録するファイルを用意します。
## 2026/03/10 - PR #42: ユーザー認証APIの実装 ### エラーレスポンスの形式統一 - **指摘**: エラー時のレスポンス形式が既存APIと異なっていた - **学び**: エラーレスポンスは { error: { code, message } } の形式に統一する ### テストのアサーション - **指摘**: ステータスコードだけでなくレスポンスボディも検証すべき - **学び**: APIテストではステータスコード + ボディの両方を必ずアサートする
なぜ記憶ではなくファイルに残すのか
人間は忘れます。先週受けた指摘を、今週も正確に覚えている保証はありません。しかしファイルに残しておけば、AIが毎回読み込んでくれます。同じ指摘を二度受けない仕組みがこれです。
さらに、フィードバックが蓄積されていくと、繰り返し出てくるパターンが見えてきます。そのパターンはインストラクションファイルのルールに昇格させます。こうしてインストラクション自体が進化していきます。
応用: 技術ブログの執筆にも使える
この仕組みはコーディングに限りません。私はAPC技術ブログの執筆でも同じアプローチを取っています。
blog/
├── CLAUDE.md # 執筆ルール・コンプライアンス・ワークフロー
├── lessons-learned.md # 記事ごとのフィードバック蓄積
├── ideas.md # ネタ帳（ステータス管理付き）
├── templates/
│ └── acs-footer.md # 記事末尾テンプレート
└── {YYYYMMDD}_{title}/ # 記事フォルダ（1フォルダ = 1記事）
├── article.md # 記事本文
├── references.md # エビデンス・出典
└── header.png # サムネイル画像
CLAUDE.mdには執筆ガイド、コンプライアンスルール、はてなブログ固有の記法の注意点を記載しています。lessons-learned.mdにはレビューで受けた指摘を記録しています。
1作目の記事を書いたときにいくつかの指摘を受けました。「読者は外部エンジニアなのに社内向けの表現が混在している」「ツール固有の問題とLLM全般の特性を区別すべき」など。これらをlessons-learned.mdに記録したところ、2作目ではこれらの指摘がゼロになりました。
コーディングもドキュメント作成も、やっていることは同じです。プロジェクトの文脈をファイルに残し、AIがそれを参照して動く。テキスト処理であれば何にでも応用できます。
まとめ — インストラクションは「育てる」もの
インストラクションファイルは、一度作って終わりではありません。
- まず作る: 数行でいい。プロジェクトの基本ルールを書く
- フィードバックを記録する: コードレビューの指摘をlessons-learned.mdに残す
- パターンを昇格させる: 繰り返し出てくるルールはインストラクションに反映する
- 日々の業務で自然に育つ: コードを書く中で文脈が蓄積される
毎回ゼロから指示するのではなく、文脈を育てて、AIが自ら引き出せる状態を作る。新しいツールを導入するのではなく、今あるツールとの付き合い方を変える。それだけで、AIとの協働は回を重ねるごとに良くなっていきます。
参考資料
- 社内イベント「ゆるっと GitHub Copilot 活用トーク」でGitHub Copilot CLIの活用法を語ってきた: https://techblog.ap-com.co.jp/entry/2026/03/10/120000
- AI議事録の固有名詞誤変換、専用ツールを使わずコーディングツールで解決した話: https://techblog.ap-com.co.jp/entry/2026/03/11/150000
ACS 事業部のご紹介
私の所属する ACS 事業部では、開発者ポータル Backstage、Azure AI Service などを活用し、Platform Engineering ＋ AI の推進・内製化を支援しています。
www.ap-com.co.jp www.ap-com.co.jp www.ap-com.co.jp
また、GitHub パートナーとしてお客様に GitHub ソリューションの導入支援を行っています。 GitHub Copilot などのトレーニングなども行っておりますので、ご興味を持っていただけましたらぜひお声がけいただけますと幸いです。
一緒に働いていただける仲間も募集中です！ ご興味持っていただけましたらぜひお声がけください。
