ai-steering-files

AI ステアリングファイル

概要

AI ステアリングファイルは、コーディングエージェントにプロジェクトでの作業方法を伝える、リポジトリ内のコンテキストドキュメントです。繰り返し発生する曖昧さをなくせる最小限のファイルを追加し、エージェントが推測せずに行動できるよう、具体的な内容に保ちます。

使用するタイミング

次の場合にこのスキルを使用します。

• AI コーディングエージェント向けのリポジトリ指示を追加または改訂するとき
• AGENTS.md、ツール固有の指示ファイル、製品または技術のコンテキストファイルから選ぶとき
• エージェントが十分なコマンド、制約、例を得られるリポジトリになっているか監査するとき
• 独自のメモリ、構文、または適用範囲のルールを必要とする新しいエージェントツールを導入するとき

一度限りのチャット指示、一時的な実装メモ、リポジトリに根拠のない一般的なアドバイスには使用しないでください。

ワークフロー

1. 新しいファイルを作成する前に、既存のステアリングファイルを確認します。すでに存在する AGENTS.md、CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、.cursor/rules/*.mdc、PRODUCT.md、ANALYTICS.md、TECH.md、STRUCTURE.md、VISION.md、DESIGN.md を読みます。
2. 指示を置く、最も適用範囲の狭い適切な場所を選びます。リポジトリ全体に適用されるベンダー中立のルールは AGENTS.md に、ツール固有のルールはそのツールのファイルに、パスに限定されるルールはパス限定のルールファイルに記載します。
3. リポジトリに関する具体的な事実を記載します。正確なコマンド、正確なパス、信頼できる例、既知の制約、レビュー時の要件を含めます。
4. 長いサードパーティのドキュメントを複製するのではなく、リンクと簡潔な要約を優先します。
5. 編集時に古くなった指針や重複する指針を削除します。ファイル間で内容が矛盾すると、エージェントはランダムに選ぶことになります。
6. 記載したコマンドやパスを検証します。コマンドをローカルで実行できない場合は、その理由をファイルに記載します。

ファイルの選び方

ファイル	使用する場面	含める内容
AGENTS.md	リポジトリ内のすべてのコーディングエージェントにルールを適用する場合。	プロジェクトの概要、ワークフロー、正確なインストール／テスト／ビルドコマンド、ブランチポリシー、レビュー時の要件、承認が必要なリスクの高い操作。
PRODUCT.md	実装上の選択に製品のコンテキストが必要な場合。	ユーザー、課題、主要なワークフロー、ビジネス目標、成功基準、対象範囲内および対象範囲外の境界。
ANALYTICS.md	製品の動作を測定する方法について、エージェントに長期的に維持される取り決めが必要な場合。	正式なメトリクスとファネル、イベントとプロパティのスキーマ、ID とアトリビューションのルール、プライバシーの境界、検証、スキーマの進化。
TECH.md	エージェントに技術スタックと統合の制約が必要な場合。	フレームワーク、ランタイム、優先するライブラリ、外部サービス、デプロイ先、サポート対象のコマンド。
STRUCTURE.md	エージェントがファイルを誤った場所に置き続ける場合。	ディレクトリ構成、責任範囲の境界、インポートのルール、命名規則、配置ルール。
VISION.md	長期的な方向性を個別の仕様書より長く維持する必要がある場合。	長期的な製品ビジョン、非目標、目指す方向性、逸脱させてはならないこと、成果レベルの成功基準。
DESIGN.md	エージェントが UI を生成し、デザインシステムの指針が必要な場合。	トークン、タイポグラフィ、余白、レイアウトの制約、コンポーネントのパターン、アクセシビリティのルール、避けるべきビジュアルパターン。
CLAUDE.md	Claude Code に永続的なツール固有の指針が必要な場合。	Claude 固有のワークフローに関するメモ、ビルド／テストの要件、エスカレーションの境界、Claude が特別に扱うべきパス。
GEMINI.md	Gemini CLI に永続的なツール固有の指針が必要な場合。	Gemini 固有のプロジェクトコンテキスト、規約、コマンド、ファイルの優先順位。
.github/copilot-instructions.md	GitHub Copilot にリポジトリ全体の指示が必要な場合。	ビルド／テストコマンド、コーディング標準、制約、レビューの指針、正式な例へのリンク。
.cursor/rules/*.mdc	Cursor のルールを特定のファイルやワークフローにのみ適用する場合。	適用範囲、glob、対象範囲の規約、例、自動適用と手動適用の動作。

品質基準

優れたステアリングファイルは、次の条件を満たします。

• ファイルが何を制御し、誰が読むべきかを説明している
• 曖昧な好みではなく、エージェントが実行できるコマンドを含んでいる
• リポジトリ内にある例を示している
• 安全性、データ、パフォーマンス、アクセシビリティ、製品、デプロイに関わる重要な制約を明記している
• 実際の作業中に読み返せる長さに収まっている

よくある間違い

間違い	修正方法
すべてのファイルにあらゆる好みを追加する。	共通ルールは AGENTS.md に記載し、ツール固有のファイルには違いだけを追加します。
一般的なエージェント向けの助言を書く。	プロジェクト固有のパス、コマンド、例に置き換えます。
外部ドキュメントを長々とコピーする。	このプロジェクトに関係する内容を要約し、一次資料へのリンクを記載します。
一時的な作業のために新しいファイルを作成する。	一時的なメモはタスク、Issue、または計画に残します。ステアリングファイルは長期的に使うものです。
ファイル間の矛盾を放置する。	1つのファイルを正式な参照先とし、他のファイルからはそこを参照します。

最終確認

完了する前に、次の点を確認してください。

• 選んだファイルがガイダンスの適用範囲に合っている
• ファイル名とパスが、大文字と小文字を含めて正確である
• インストール、テスト、Lint、ビルド、デプロイのコマンドが最新である
• 例とリンクが正しく機能する
• そのファイルが何であるかだけでなく、いつ追加する価値があるかも説明している