AIコーディングエージェントと AGENTS.md
AIコーディングアシスタント—Claude、GitHub Copilot、Cursorなど—は、フレームワークの慣習を理解することで、PowerPortalsProポータルをより正確に構築・カスタマイズできます。それを自動化するために、PowerPortalsProテンプレートから生成されるすべてのプロジェクトは、ルートに AGENTS.md ファイルを付属させます。
AGENTS.md とは何でしょうか?
AGENTS.md これは、AIコーディングツールが自動的に読み取り、プロジェクトの慣習を学習してコードを書く前に行う、単純なMarkdownの命令ファイルです。これは新興のクロスツール標準であり、同じファイルがClaude、GitHub Copilot、Cursorなどで採用されているため、ツールごとに一つのガイダンスセットを維持するのです。PowerPortalsProテンプレートはフレームワークに合わせた AGENTS.md を生成し、エージェントはデータアクセス、認証、保存ロジックを手作業で行うのではなく、フレームワークのコンポーネントやサービスから機能を組み立てる方法を知りやすくします。
注記
ガイダンスはスタックごとに異なります。Reactテンプレートから生成されたプロジェクトはReactに特化した
AGENTS.mdを、BlazorプロジェクトはBlazorに特化したものを出荷します。それぞれがそのスタックのコンポーネント、サービス、パターンを記述します。
それが生きている場所
ファイルは生成されたソリューションのルート上にあり、プロジェクトの隣にあるため、リポジトリ上で開いたAIツールは設定なしでもこのファイルを見つけられます:
中身は何だ
生成された AGENTS.md は、このドキュメントサイトがカバーしている慣習を、エージェントがすべてのタスクで読み取る常に文脈内の参照にまとめます。
- 黄金律 — データアクセス、認証、セーブのロジックを手作業で行わないこと;エディタをレコードコンテキストにバインドし、色やユーザー向けの文字列をハードコーディングしないでください。
- アーキテクチャとプロジェクトレイアウト — ホストプロジェクトとクライアントプロジェクトがどのように連携し、ページやコンポーネントがどこにあるか。
- データおよび編集パターン — レコードの読み込み、レコードコンテキスト+フィールドエディタモデル、グリッドコンポーネント。
- コンパクトなコンポーネント参照 — ほとんどのコンポーネントのプロップやパラメータを表示し、それ以外はタイプとIntelliSenseへのポインタがあります。
- セキュリティ — 正確なページングとパフォーマンスのためにソースからデータをフィルタリングすること;許可ハンドラーは執行層です。
- ローカリゼーションとテーマ — 文字列キーの規則とデザイントークンルール。
- 開発ワークフローと落とし穴 — プロジェクトの運営方法と避けるべきミス。
効果的に使う
いくつかの習慣はこのガイドから最大限に活用できます:
- まず係員に読ませてください。 ほとんどのツールは自動的に読み込み
AGENTS.md。もしそうでなければ、機能をリクエストする前にアシスタントに指示してください。 - タイプとIntelliSenseに頼りましょう。 ガイドは意図的に簡潔にまとめられており、任意のコンポーネントやサービスの表面全体に対して、エージェントはTypeScriptの定義(React)やXML-docのIntelliSense(Blazor)を読むことができます。
- このサイトを参照してください。 エージェントに、デモのライブ例やAPIの参照を指示して、コピー可能なパターンを探してください。
- 出力を見直しましょう。 このガイドはエージェントの精度を高めますが、レビューの代わりにはなりません。特に生成されたセキュリティルールやデータフィルタリングを確認してください。
例えば、このようなリクエストはエージェントに慣用句コードを生成するために必要なすべての情報を提供します:
自分のものにしてください
AGENTS.md リポジトリ内の普通のファイルです — 編集してください。自分でテーブルや関係、ドメインルール、命名規則、プロジェクト固有のパターンを追加し、エージェント がフレームワークだけでなく ポータルを学習できるようにします。ファイルがあなたのコードベースをよく反映すればするほど、生成されるコードも良くなります。
ヒント
AGENTS.mdを生きたドキュメントとして扱いましょう。新しい慣習を確立したり、繰り返されるミスに遭遇したら、ファイルに一行を追加して、今後のAIセッションが恩恵を受けられるようにしましょう。