はじめに
AIコーディング支援を使うと、実装そのものは速くなります。一方で、毎回の指示が場当たり的になると、部品化、検証、セキュリティ、納品手順のような重要な観点が抜けやすくなります。
そこで役に立つのが、AGENTS.md のような固定命令ファイルです。これは単なるメモではなく、AIアシスタントに「このリポジトリでは何を優先し、何を避けるか」を伝える運用ルールとして使えます。
特に、開発で得た知見を次回以降の資産にしたい場合は、実装前、実装中、実装後の判断基準を固定命令に入れておくと効果があります。
こんな場面で使えます
- CodexやClaude CodeなどのAIコーディング支援を継続的に使っている
- 毎回「再利用できる部品があれば残して」と指示するのが面倒
- プロジェクトごとの技術ルールや禁止事項をAIに守らせたい
- 案件固有の指示と、全案件共通の開発方針を分けたい
- 開発資産フォルダ、テンプレート、チェックリストをAIにも参照させたい
実装パターン
固定命令を階層で分ける
固定命令は、すべてを1ファイルに詰め込むより、効かせたい範囲ごとに分けると運用しやすくなります。
| 置き場所 | 役割 |
|---|---|
| グローバル設定の AGENTS.md | どの作業でも守る基本姿勢 |
| プロジェクト直下の AGENTS.md | その案件だけの技術ルール、設計方針、注意点 |
| 開発資産フォルダの AGENTS.md | 資産フォルダ自体の保存ルール、分類ルール |
| 技術カテゴリ別のMarkdown | 具体的な実装パターン、チェックリスト、テンプレート |
全体ルールには、具体的なコードではなく、いつでも守る判断基準を置きます。たとえば次のような内容です。
## 開発資産化の基本方針
- 目の前の実装だけでなく、次回以降の再利用を考える
- 似た処理を毎回ゼロから書かない
- 再利用できそうな関数、クラス、モジュール、設計パターンを部品化候補として扱う
- 案件固有の処理は無理に共通化しない
- 実装後に、資産化できるものがないか振り返る
資産フォルダに置くものを明確にする
AIに「良さそうなものを残して」とだけ伝えると、コード断片や案件固有情報が混ざりやすくなります。保存対象を先に定義しておくと、残すべき情報の粒度が揃います。
## このフォルダに置くもの
- 実装パターン
- 関数・クラス・モジュールのサンプル
- UIパターン
- エラー処理パターン
- デプロイ・納品手順
- 移行時の注意点
- レビュー観点
- AIアシスタントへの固定命令
反対に、置かないものも明示します。
## 置かないもの
- APIキー、トークン、パスワード
- 顧客名や個人情報を含む実データ
- その案件でしか意味がないコード全文
- 使い方が不明な断片コード
- node_modules やビルド成果物
実装後の振り返りを固定手順にする
開発資産化は、思いついたときだけ行うと定着しません。AIに実装を依頼する時点で、最後に次の観点を確認させるとよいです。
## 実装後の確認
1. 今回作った処理に再利用候補はあるか
2. 案件固有情報を外せば他でも使えるか
3. 既存資産に似たものはないか
4. 使う場面、入力、出力、副作用を説明できるか
5. 資産化するなら、1テクニック1ファイルで残せるか
この手順を固定命令に入れておくと、AIが実装だけで終わらず、次回の作業につながる形で締められます。
運用のポイント
AGENTS.mdには、実装コードそのものよりも「判断基準」を書きます。コードは変わりますが、判断基準は複数案件で使い回せるためです。
たとえば「この関数を必ず使う」と書くより、「日付処理はタイムゾーン、空値、表示形式を確認する」と書いたほうが、別の技術スタックでも効きます。
また、グローバルルールと案件ルールを混ぜすぎないことも重要です。全体ルールには普遍的な方針を置き、案件ルールにはフレームワーク、ディレクトリ構成、テストコマンド、デプロイ手順など、そのプロジェクトでだけ必要な情報を置きます。
注意点・ハマりポイント
AGENTS.mdを強くしすぎると、AIが不要な共通化や過剰な抽象化を始めることがあります。固定命令には「案件固有処理は無理に共通化しない」と明記しておくと安全です。
また、開発資産フォルダのパスや社内運用の詳細を公開記事やサンプルにそのまま出さないようにします。公開向けには「任意の開発資産フォルダ」「チーム共有のナレッジベース」のように一般化して説明します。
機密情報の除外ルールも必須です。AIに資産化を任せる場合は、APIキー、顧客名、個人情報、案件固有の業務データを保存しないルールを明文化してください。
まとめ
AGENTS.md は、AIコーディングの品質を安定させるための運用ルールとして使えます。
重要なのは、コード断片を詰め込むことではなく、再利用、検証、資産化、機密情報除外の判断基準を明文化することです。全体ルール、案件ルール、資産フォルダのルールを分けておくと、AIアシスタントが状況に応じて適切な粒度で動きやすくなります。
毎回の実装を一回きりで終わらせず、次の開発を速くする仕組みに変えるための土台として、AGENTS.mdを整備しておく価値があります。