優れたエージェントの書き方.md: 2500 以上のコードベースからの経験の要約。 核となる考え方は、「あなたは役に立つプログラミングアシスタントです」といった漠然とした指示は効果がないということです。本当に効果的なのは、例えば「あなたはReactコンポーネント専用のテストを作成し、具体的な例に従い、ソースコードを一切変更しないテストエンジニアです」と明確に述べるなど、具体的な役割の定義です。 agents.md ファイルは、インテリジェント エージェントを定義するための完全な作業マニュアルとして機能します。役割の配置、テクノロジ スタックの知識、プロジェクト ファイルの構造、ワークフロー、実行可能コマンド、コード スタイルの例、そして最も重要な、明確な運用境界が含まれます。 分析により、成功した agents.md ファイルが一般的に以下の 5 つの重要な要素に従っていることが明らかになりました。 1. コマンドのプレフィックスを付けると、ツール名だけでなく、npm test、pytest -v などの完全なコマンド パラメータとオプションを含む実行可能コマンドがファイルの先頭に配置されます。 2. テキストではなくコード例を使用してください。3つの説明的な段落よりも、実際のコードスニペットの方が効果的です。期待される出力スタイルを直接示してください。 3. 明確な境界を設定し、機密情報、ベンダー ディレクトリ、本番環境の構成など、AI が絶対に触れてはいけないコンテンツを明示的に伝えます。「キーを送信しない」は最も一般的で効果的な制約です。 4. 具体的なテクノロジー スタックは、一般的な「React プロジェクト」ではなく、「React 18 + TypeScript、Vite および Tailwind CSS を使用」と記述し、バージョン番号と主要な依存関係を含める必要があります。 5. コマンド、テスト、プロジェクト構造、コード スタイル、Git ワークフロー、運用境界という 6 つのコア領域をカバーします。これらの領域をカバーすることで、構成ファイルが最上位レベルになります。 実践的な例では、ドキュメントインテリジェンスエージェントの完全な構成例を示し、上記の原則を実際のシナリオに適用する方法を示します。この構成には以下が含まれます。 • 役割を定義する: 技術ドキュメントの専門家、Markdown と TypeScript に精通している • プロジェクトに関する知識：特定のテクノロジースタックのバージョンとファイルディレクトリ構造。 • 使用可能なコマンド：`npm run docs:build` および `npx markdownlint docs/` • 3 段階の境界システム: 常に行うべきこと、最初に尋ねること、絶対に禁止すること。 構築する価値のある専用のインテリジェントエージェント @docs-agent: コードを読み取り、ドキュメントを生成し、docs/ ディレクトリにのみ書き込みます。 @test-agent: テストを書くとき、失敗したテストケースは削除しないでください。 @lint-agent: ロジックを変更せずにコードのフォーマットを修正します。 @api-agent: API エンドポイントを構築し、データベース スキーマを変更する前に相談が必要です。 @dev-deploy-agent: 開発環境のみのローカルビルドとデプロイメントを処理します。 実装の推奨事項としては、単純なタスクから始め、「汎用ヘルパー」の構築は避け、関数ドキュメントの作成、ユニットテストの追加、コードエラーの修正など、具体的なタスクを選択してください。 最も合理的な設定は、エージェント名、簡単な説明、そして具体的なロール定義の3つの要素だけで済みます。Copilot を利用して初期設定を生成し、実際のプロジェクトに合わせて調整することも可能です。 肝心なのは、エージェント設定ファイルは一度に全てを計画するのではなく、段階的に改善していく必要があるということです。まずはシンプルな設定から始め、テストを行い、エージェントがエラーに遭遇するたびに詳細を追加していきます。成功の鍵は、漠然とした指示ではなく、具体的な役割の定義と詳細な操作マニュアルを提供することです。 ブログアドレス:
