Agent.MD 設定の総点検：GPT-6 Astra 向け公式 Skills と AGENTS.md 刷新実践ガイド

これまで長い間、Codex などの coding agent に期待通りのコードを安定して出力させるため、開発者はリポジトリ内に大量のガイドルールを積み上げるのが常でした。極めて詳細な操作手順書（レシピ）、変更前にすべてのアーキテクチャドキュメントの通読を義務付けるルール、そして一手ごとに停止して確認を求める防御的な指示などです。

しかし、基盤モデルが GPT-6 Astra へと進化したことで、かつて有効だったこれらの設定は一転して「負の遺産」になりつつあります。過去の設定が支援から足かせへと変わった根本的な理由は、モデル能力の世代交代にあります。Astra では理解力、安全アラインメント、コンテキスト認識が大幅に向上しており、従来の「過保護な足場組み」はコンテキスト空間を大きく圧迫するだけでなく、ルール同士の衝突や無関係なフローの誤検知を招き、さらには高度な安全意識を持つモデルを不必要に停滞させる原因にもなります。

本ガイドでは、リポジトリに残る過去の設定を体系的に整理・刷新する手順を解説します。自身のプロジェクトと照らし合わせながら、skills、AGENTS.md、権限境界からタスク prompt まで、段階的に改造を進めることができます。

なぜモデルが強化されると、過去の設定が足かせになるのか？

具体的なファイルの修正に入る前に、公式が提示する一連のリファクタリング提案の基本思想を理解しておく必要があります。それは、「過保護な制約から自律的な判断とオンデマンドなルーティングへの移行」です。

過去1年間の典型的な設定には、強力なモデルにおいてより顕著になる3つの欠点が存在します。

第1に、コンテキスト汚染と切り捨て（トランケーション）のリスクです。多くのチームがプロジェクトに数十もの skills を設定し、各 skill に長文の説明を記述しています。登録されたスキルの総数が多すぎると、Codex はモデルへ提示する説明の要約を強制的に短縮します。その結果、モデルが目にする説明文は末尾が欠落した不完全なものとなり、さらに類似したキーワードの重複も重なって、無関係なスキルを誤選択しやすくなります。そして、巨大な誤ったスキルファイルがいったん読み込まれると、早期にコンテキストの圧縮（compaction）が引き起こされ、本来必要な開発コンテキストが押し出されてしまいます。

第2に、厳格な手順指定による高度な推論の制約です。旧世代のモデルは抜け漏れが発生しやすかったため、一歩ずつの手順を記したレシピ（recipes）による誘導が必要でした。しかし、Astra の曖昧なセマンティクスや複雑なビジネスロジックに対する理解力は従来を遥かに凌駕しています。過度に詳細な指示手順は不要であるばかりか、かえってモデルの柔軟な思考空間を狭めてしまいます。

第3に、アラインメント特性に起因する過度な保守性です。Astra は現時点で最もアラインメントが進み、判断力に優れたモデルであり、操作の安全性が確認できない限り無暗に前進しません。もしリポジトリのルールファイル内に、かつて旧モデルを縛るために書かれた厳しい警告（例：「承認なしにいかなる操作も実行してはならない」）が残っていると、Astra はそれを極めて厳密に遵守します。その結果、完全に安全なローカルテストや定常的な修正作業であっても、頻繁に停止して確認を求めるようになってしまいます。

これらの変化を踏まえると、改修の方向性は極めて明確です。入り口を軽量化し、参照をピンポイント化し、権限を明確に委譲し、完了基準をクローズドループにすることです。

ステップ1：skills の軽量化と再構築

まず変更対象の本質を確認しましょう。skill とは本質的に Markdown ファイルとして保存されたプロンプトであり、リソースやスクリプトと一緒にパッケージ化して配布できます。特定の一連のワークフローを案内したり、特定のアプリケーションを扱う際の手順を提供したりするのに最適です。

リポジトリ内のスキル定義ファイルを点検します。公式は最近 $skill-creator の組み込みガイドラインを更新しており、その中核となる要求はスキルの全面的なスリム化です。

トリガー説明文の精簡：skill の名前と説明（description）は、モデルのコンテキスト内に常駐するインデックスです。説明は極力短く保ち、どのような場面で呼び出す必要があるかのみを明記します。網羅性を過剰に気にして、関連モジュールの単語をすべて説明文に詰め込むような記述は避けてください。

Bad な書き方：

Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.

Good な書き方：

Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.

解説：Bad な書き方では、クエリ作成、モデル変更、永続化処理のすべてがトリガー条件に含まれてしまっています。そのため、Agent がデータベース関連のコードに少し触れただけで、migration スキル全体が誤ってコンテキストへ読み込まれてしまいます。Good な書き方では対象を「migration の追加・変更、またはロールアウトのレビュー」に絞り込んでいるため、実際にマイグレーションを処理する際にのみトリガーされます。

段階的開示（Progressive Disclosure）の実践：スキルの内容を読み込むこと自体もコンテキストを消費します。複数のフローを含む複雑なスキルでは、ルートドキュメントは極めて簡潔な「ルーター（Router）」としての役割のみにとどめ、必要に応じて二次ドキュメントや具体的なスクリプトを参照するよう案内すべきです。すべての操作手順をルートファイルへ詰め込んではいけません。

操作レシピの整理とマルチモデル環境への配慮：手取り足取り指示する過剰な手順案内を削除し、Astra 本来の理解力を活かします。ただしチームの協業環境には注意が必要です。リポジトリ内で他の開発者の Agent が GPT-5.6 Sol や Luna などの旧モデルを稼働させている場合、旧モデル向けの強い制約を外すと影響が出る可能性があります。共有スキルを更新する際は、プロジェクト内の利用モデル構成を考慮してください。

修正後の確認方法：Codex が読み込む skills 一覧を確認し、各説明文が切り詰められず完全に表示されていることを確認します。また、通常のデータベースクエリやビジネスロジックを記述する際に、Agent が不要にマイグレーションスキルをトリガーしないかを観察します。

ステップ2：AGENTS.md におけるドキュメントインデックスの書き換え

プロジェクトのルートディレクトリにある AGENTS.md を開きます。このファイルは Agent がリポジトリ内で作業する際の全体共通ガイドラインであり、記述されている各要件の必要性を1つずつ見直す必要があります。

全件強制通読からオンデマンド参照へ：過去の設定で最も一般的だったのは、作業前に一連の仕様書を通読するよう Agent に義務付ける運用でした。これは誤字の修正や定数の微調整といった作業においては著しいリソースの浪費です。Astra は、現在のタスクにどの背景情報が必要かを自ら判断する能力を十分に備えています。

Bad な書き方：

Before every edit, read architecture.md, database.md, and deployment.md.

Good な書き方：

Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.

解説：Bad な書き方は、編集作業のたびにアーキテクチャ、データベース、デプロイの3大ドキュメントを通読するよう要求しており、token を激しく消費するだけでなくレスポンス速度も著しく低下させます。Good な書き方ではドキュメントを場面別のインデックスへと変更し、サービス境界の確認、テーブル定義の変更、デプロイ準備の際にのみ対応するファイルを参照するよう案内しています。なお、インデックスが指すドキュメント自体が最新の状態に保たれていることも必ず確認してください。

過剰なテスト催促の削除：旧世代のモデルはコードを書いただけで作業を終えてしまうことが多かったため、従来の AGENTS.md では「変更後は必ずテストを実行して結果を確認すること」と強く要求していました。Astra はこの点において自律性が高く、自発的にセルフテストを実施するため、こうした催促をそのまま残しておくと不要な重複テストを誘発します。

修正後の確認方法：コメントの修正など軽微なタスクを依頼し、ログを確認します。Agent が必要なファイルへ直接アクセスし、無関係なアーキテクチャドキュメントの読み込みや全テストの過剰な再実行を行わないことを確認します。

ステップ3：権限境界の再設計とローカルテストの実行委譲

AGENTS.md およびグローバルルール内の「権限と承認」に関する記述を見直し、時代遅れとなった安全制限を解除します。

過度な防御的表現の修正：旧モデルの暴走を防ぐため、かつては「いかなる変更を加える前にも人間の許可を得ること」といった強い制限が頻繁に用いられました。判断力の高い Astra に対してこのような防御的指示を残しておくと、過度に慎重になり、本来そのまま進めてよい安全な工程でも作業を停止してしまいます。信頼不足から設けられていた無差別なブロック命令は整理すべきです。

安全な環境への明確な権限委譲：Astra は綿密に作業を進める一方で、自律的に進める歩幅については慎重な傾向があるため、適度な推進許可を与える必要があります。本番環境への影響がないローカルテストのような安全なシナリオでは、AGENTS.md 内で連続実行の権限を明示的に付与します。

権限委譲の記述例：

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

解説：この設定は2つの重要な前提を明確に伝えています。ローカルテストには本番リスクがないこと、そして「テスト実行 → エラー検出 → 自律修復 → 再テスト」という一連のサイクルを、ステップごとに確認を求めず自律的に完結させることです。

修正後の確認方法：あえて単体テストでエラーが出るようなコード変更を依頼し、Agent が「コード修正 -> テスト失敗を検知 -> 自律的に修正 -> 再テストでパス」という一連のループを、承認待ちで停止することなく自力で完結できるかを確認します。

ステップ4：タスク prompt の調整と完了定義の明確化

静的なルールファイルだけでなく、日常的にタスクを発行する際の prompt の記述スタイルも併せて見直す必要があります。

完了の定義（Definition of Done）の事前明記：GPT-5.6 Sol のように、指示を受けると長い工程を一気に自律走破するスタイルに慣れている開発者は、GPT-6 Astra に移行した際に「慎重すぎる」と感じることがあります。初版のコードを書いた段階で作業を止め、ユーザーのレビューを待とうとする傾向があるためです。

もしタスク自体に「コードを実際に動かす」「出力を確認する」「実行時エラーを修正する」までが含まれているなら、タスクを依頼する prompt の中でそれらを完了条件として明確に定義してください。「初稿ができたら確認を待つ」といったフローを無意識に前提にしてはいけません（人間による判断が不可欠な意思決定ポイントを除く）。不要な中間停止の要求は、モデルを早期の終了状態へと誘導してしまいます。

また、探索的な検証を依頼する際も、「いろいろな方法を試して」と曖昧に指示するのではなく、検証したい具体的な方向性と、どこまで確認できれば探索を打ち切ってよいかの境界を明確に伝えます。

修正後の確認方法：タスクを投入した後、Astra が未検証の初版コードを出力しただけで待機状態に入らず、テスト検証までエンドツーエンドで完了させ、整理された結果を提示できるかを確認します。

クイック導入：GPT-6 Astra によるリポジトリ自己監査

既存の設定ファイルをすべて手動で探して修正する必要はありません。最も手軽なアプローチは、GPT-6 Astra 自身にリポジトリのコンプライアンス監査を実行させることです。

GPT-6 Astra の設定リファクタリング原則に基づき、本リポジトリの skills、AGENTS.md、および主要タスクの prompt を監査してください。

特に以下の項目を重点的にチェックしてください：
1. 各 skill の説明文を精査：長すぎるものやトリガー条件が広すぎるものを指摘し、機能の羅列を避けて「いつ呼び出すべきか」のみを1〜2文で簡潔に書き直す。
2. フローが複雑な skill については、「ルートファイルには最小限の router のみを残し、サブドキュメントとスクリプトを分離してオンデマンドで読み込む」分割案を提示する。
3. レシピのようなステップ・バイ・ステップの過度な手順指示を洗い出し、Agent が自律的に推論できるものと、明示的に残すべき必須指示を判断・仕分ける。
4. AGENTS.md から無差別な強制通読要求を削除し、責務ごとに整理したドキュメントインデックス（どういう状況で何を参照するか）に改める。
5. 重複するテストの催促を整理し、無差別な割り込みを真の高リスク操作のみに絞り込む。また、隔離されたローカルテスト向けに「自動実行・エラー修正・再テストを都度の承認なしで進める」権限記述を追加する。
6. 主要タスクの prompt に完了の定義（実行、出力確認、パスするまでエラー修正）を追加し、不要な「作成後に一旦停止して確認」を削除する。
まずは問題箇所のリストを「ファイルパス」「現在の原文」「修正案」の3列対照で出力してください。こちらの確認が完了してから、実際の修正作業に着手してください。

この prompt は、あえて「修正作業に入る前に、まず変更予定リストを提示すること」を要求しています。監査の本質は、モデルが何をどのように変更しようとしているかを人間が事前に把握できる点にあります。リストを確認し、問題がないことを確かめてから反映させることで、設定アセット全体の刷新を安全に完了できます。