agent-ready-environments

エージェント向け環境

エージェントは、作業が 完了したように見える と停止します [A1]。その環境によって、「完了したように見える」ことと「完了している」ことが同じかどうかが決まります。このスキルの各柱は、次の3つの役割のいずれかを担います。

• 伝える：エージェントがリポジトリ内で確認できないことを伝えます。
• 確認する：成功か失敗かが返る方法で作業をチェックします。
• 制限する：エージェントが触れられる範囲と、承認者を定めます。

各柱のリファレンスファイルには、情報源、望ましい状態、監査チェック、アンチパターンが記載されており、柱の一覧表からそれぞれ参照できます。新しいモデルがリリースされたときや情報源が変わったときは、maintenance.md に従ってこのスキルを見直してください。

持続するガイダンスと劣化するガイダンス

ベンダーのガイダンスでは現在、モデルの弱点を補う助言と、モデルが自力では得られないものを与える助言が分けられています [A1, "What you can stop doing"]。持続するガイダンスに投資してください。

劣化するガイダンス：モデルを補うもの	持続するガイダンス：モデルが自力では得られないもの
強調、IMPORTANT、すべて大文字	リポジトリに含まれない事実
「もっとよく考えて」「続けて」「怠けないで」	合格か不合格が返るチェック
アーキテクチャの案内やファイル構成の説明	例外を一切認めないルールの決定論的な適用
積極的なコンテキスト管理	稼働中で、観測でき、初期データが用意された環境
「よりよい回答を得るために」サブエージェントへ委任すること	作成者の推論を見ていない独立したレビュアー

このスキルは、この区分に基づいて以下を論じていますが、ベンダーは各柱そのものに順位を付けていません。モデルがコードをよりよく読めるようになるにつれ、ドキュメント（柱4）の重要性は下がります。モデルがどれほど進歩しても、エージェントは起動できないアプリや、存在しないデータを観測できません。そのため、再現可能な環境（柱6）が最も持続する投資であり、次に作業を検証可能にする静的チェックとテストのゲート（柱2と3）が続きます。

配置：助言か、強制か

ガイダンスは2つの経路を通ります [A1]。

• 助言：プロンプト、AGENTS.md / CLAUDE.md、スキルです。モデルは内容を判断し、適用しないことを選ぶ場合があります。
• 強制：フック、拒否ルール、サンドボックス、型チェッカー、リンター、必須の CI チェックです。モデルがどう判断するかにかかわらず、それぞれのアクション境界（ツール呼び出し、コミット、マージ）で実行されます。

各ルールは、例外の有無に応じた経路に配置してください。

• 例外のないルールは強制します。OpenAIも2026年初頭に同じ対応を報告しました。ドキュメントだけでは不十分な場合、ルールをコードにします [O1]。
• 助言の一文が繰り返し見落とされる原因は2つのいずれかです [A1]。曲げられないルールであればフックまたは拒否ルールにします。あるいは、ファイルが長くなりすぎて埋もれているのであれば、ファイルを短くします。強調を増やしても、どちらの問題も解決しません。
• 選好は助言のままにします。強制するルールが多い場合、選好がそこに紛れ込んでいます。フックはときに誤作動し、保守する人が必要になります [A1]。
• 強制チェックはエージェントに伝わるものです。修正方法を示すエラーメッセージがあれば、エージェントは自分の作業を修正できます [O1, not yet confirmed by a current source]。

柱

スコア	意味
0	存在しない、または検証済みの証拠がありません
1	存在するものの、全体として実行可能ではありません。文書化されたポリシー、スクリプト、または一部のみ動作する仕組みがあり、レベル2の基準のいずれかが満たされていないか、未検証です
2	実行可能です。柱の「観測可能な監査チェック」が実行可能な証拠によって満たされています（「証拠」を参照）。新規チェックアウトが必要なのは柱6のみです
3	強制され、計測されています。保護対象のアクションを阻止し（必須チェックがマージを阻止する、フックがツール呼び出しを阻止するなど）、その結果が少なくとも20回の実行、または30日間にわたって追跡されています
N/A	このリポジトリには該当しません。理由を1行で示してください

採点ルール：

• 柱のスコアは、検証済みの証拠がすべての基準を満たす最高レベルです。未検証のチェックでは柱のレベルは上がりません。未検証の項目には「未検証」と記載してください。
• レベル2には、実行可能な証拠によって満たされた柱の「観測可能な監査チェック」が必要です。レベル3には、上記の定義に従い、そのチェックが対象のアクションを阻止し、経時的に追跡されていることも必要です。参照ファイルの「監査チェック」の箇条書きは「最大のギャップ」を診断するものであり、参照ファイルに明記されている場合にのみ、レベルの判定条件となります。
• 柱が複数の成果物（ファイル、スキル、レビューの観点）を対象とする場合、該当する成果物のうち最も弱いものを基準に採点してください。「観測可能な監査チェック」に必要な成果物が欠けている場合、柱のスコアはレベル2未満になります。ただし、それだけでスコアが0になるわけではありません。
• 失敗が明確に示されてもマージを阻止しない任意の CI は、レベル3ではなくレベル2です。
• 該当しない柱には N/A を付け、合計から除外してください。柱の一部のみが該当する場合は、該当する部分を採点し、除外したチェックを明記してください。
• レポートでは、Channel は現在の状態ではなく、提案する修正を示します。

#	柱	役割	観測可能な監査チェック
1	コード構造：再利用、所有権、データフロー、ジョブごとに1つのパターン	伝える	最近の3つの機能における各判断が1か所で行われており、境界と重複のツールがパスする
2	静的ゲート：型、リンティング、デッドコード、複雑度、重複	チェックする	1つのコマンドですべての静的ゲートをローカルで実行でき、CI も同じコマンドを実行する。クリーンな main が成功し、抑制の件数が集計されている
3	有効なシグナルを備えたテストゲート：レイヤー化され、重複やシグナルの弱いテストがない	チェックする	1つのテストファイルを1つのコマンドで実行でき、テストのサンプルのそれぞれが1つの契約と、信頼できる回帰ケースに対応している
4	ドキュメント：全体像、判断、ワークフロー、用語集	伝える	常時読み込まれる各行が2つの質問のテストまたは陳腐化のテストに合格し、文書化されたすべてのコマンドが実行できる
5	リスクに応じて選択されたレビューゲート	チェックする	各レビュー観点にトリガーがあり、新しいコンテキストで読み取り専用で実行され、修正前に検出内容が検証されている
6	再現可能な環境：1つのコマンド、シード済み、観測可能	チェックする	エージェント自身のサンドボックス内の新しいワークツリーが、1つのコマンドでシード済みの正常な実行中アプリに到達し、2つのワークツリーを衝突なく同時に実行できる
7	制限された自律性	制限する	すべての「決して〜しない」ルールが拒否ルール、フック、またはサンドボックスの制限になっており、無人実行にはターン数または費用の上限があり、結果を承認する担当者が明示されている
8	ガイダンスの評価	伝える	各指示ファイルまたはスキルについて、ガイダンスなしのベースラインと比較し、動作が変化する証拠がある

柱7と8は、元の6つの柱を拡張するものです。どちらも同じベンダーのガイダンスに由来します。無人実行のための事前確認事項 [A1] と、評価を優先する作成方法 [A4] です。

監査手順

該当するすべてのモードを選択してください。ガイダンスを提供するリポジトリでは、「既存のリポジトリ」と「エンジニアリングガイダンス」の両方が必要です。その後、報告してください。

エビデンス

権限の範囲内で最も強いエビデンスを使用し、その種類を「エビデンス」列に記載します。

1. エージェントのサンドボックス内で、新しくチェックアウトした状態からローカル実行した結果。
2. 監査対象と同一のコミットに対する CI の結果。
3. 現在の main に対する CI の結果。別のコミットであることを明記します。
4. ソースの確認：スクリプトが存在し、内容が正しいこと。実行可能なチェックについては、最大でもレベル 1 の根拠となります。

種類 1 では、実行時のサンドボックス構成（ホスト、サンドボックスモード、主な拒否ルール）を記録し、失敗の原因がリポジトリにあるのか、監査者のマシンにあるのかを追跡できるようにします。

新規セットアップの失敗は、ピラー 6 で一度だけ評価します。他のピラーは、種類 2 のエビデンス、または別の方法で依存関係を用意したローカル実行（その旨を明記）に基づいて、レベル 2 に到達できます。

読み取り専用の監査では、種類 2～4 を使用し、省略したローカル実行を列挙します。必須チェック、ブランチルール、レビュー履歴の確認にはフォージ API（たとえば gh api）への読み取りアクセスが必要です。アクセスできない場合は、未検証と記載します。

新規プロジェクト

ゲートは、コードが 0 行のうちに追加するのが最も低コストです。

1. ピラー 6：シードスクリプトとヘルスチェックを備えた、ワンコマンドでのセットアップ、実行、終了を用意します。エージェントのサンドボックス内で実証します。
2. ピラー 2 と 3：厳格な型チェック、リント、デッドコードと境界のチェックツール、および単一ファイルを指定して実行できるテストランナーを導入します。これらを CI でも実行し、必須とする単一の check コマンドにまとめます。
3. ピラー 7：「絶対にしない」ルールごとに拒否ルールとサンドボックス制限を設けます。
4. ピラー 4：ステップ 1 と 2 のコマンドを記載した簡潔な AGENTS.md を用意します。エージェントを 2 回修正する必要が生じてから、行を追加します [A1, O3]。
5. ピラー 1 と 5 はコードとともに育てます。各決定を行った時点で記録し、リスクが現れたらレビューの観点を追加します。

既存のリポジトリ

1. エージェントのサンドボックス内で、新しいワークツリーからシード済みの実行中アプリになるまでの時間を計測します。何もない状態からのコールドセットアップと、前提条件がすでにそろっている状態でのウォームセットアップを分けて記録し、手作業の各手順も記載します。
2. クリーンな main ですべてのゲートを実行します。所要時間と失敗を記録します。
3. 抑制の種類ごとに数を集計します（方法はピラー 2を参照してください）。
4. 20 件のテストと最近の機能 3 件を、ピラー 1 と 3 に照らしてサンプリングします。
5. ボットへの返信ではなく、最近の人間によるレビュー指摘を調べ、繰り返しを特定します。繰り返しが見つかった場合は、リントルール、テスト、または記録された決定の不足、あるいは誤ったレビューを仮説として扱います。不備と判断する前に検証します。
6. すべてのピラーを採点します。

エンジニアリングガイダンス（指示ファイル、スキル、レビューゲート）

1. 常時読み込まれる情報量は、ファイルサイズだけでなく、各ホストが実際に読み込む量として測定します。対象は指示ファイル、スキルの説明、フックの出力です。Claude Code では /context で読み込まれた内容を確認できます [A1]。ホスト側で確認できない場合はファイルサイズを報告し、読み込みサイズは未検証と記載します。
2. 各指示（文または箇条書き）を、永続的か陳腐化しやすいか、また助言か強制かに分類します。1 つの指示に両方の性質がある場合は、それぞれの部分を明記します。
3. 助言にすぎない「必ず」または「絶対にしない」ルールをすべて列挙します。それぞれ配置の欠陥か、強すぎる表現の好みです。
4. キャッシュを探します。ディレクトリ構成、package.json のスクリプト、または設定を繰り返し記載している行が該当します。検証コマンド [A1] と、参照に手間がかかる情報を含む行は残します。
5. ファイル間で意味が重複している箇所を探します。
6. レビューゲートに、トリアージの手順と、過剰な修正を抑える対策があるか確認します（ピラー 5）。
7. 評価のエビデンスを求めます（ピラー 8）。評価結果はピラー 8 のレベルに従って採点します。結果がなければ、文書化された評価方針は 1 点、方針がなければ 0 点です。maintenance.md の陳腐化テストは、このスキルに限らず、あらゆるガイダンスに有効です。

レポート

Evidence セクションを記述し、その後にこの表、続いて Skill gaps（このスキルを適用するのが難しかった点）と Unverified（省略したチェックと、それらの実行に必要なもの）を記述してください。

柱	スコア	エビデンス	主なギャップ	修正	チャネル

修正は影響範囲の大きい順に並べてください。適用されていない柱 7 のルール（シークレット、保護対象パス、取り消し不能な操作）を最初にし、サイズ制限による指示の途切れなど、エージェントがそのようなルールを見落とす原因となる不具合も同時に挙げてください。次に、耐久性（6、3、2、5、1、8、4）、その次にコストの順で並べてください。

ソース

現在のモデル世代は Claude 5.5 ファミリー（Fable 5.1 を含む）と GPT-6.x（6.1 Sol、6 Luna、6 Astra）です。特に明記されていない限り、ベンダーの情報源を一次資料として扱います。柱の参考資料では、Why の段落で出典を引用しています。Good looks like と Audit check は、出典キーが記載されていない限り、実務者による統合です。0～3 の評価基準、修正の順序、耐久性の順位はこのスキルによる統合であり、ベンダーのガイダンスではありません。現在のモデル世代より前と記された出典は裏付けにのみ使用します。その出典だけが根拠となる主張には、最新の出典または maintenance.md に記載された陳腐化テストが必要です。

• [A1] Anthropic、『Claude Code のベストプラクティス』。https://code.claude.com/docs/en/best-practices 確認日 2026-11-01。
• [A2] Anthropic Engineering、『AI エージェントのための効果的なコンテキストエンジニアリング』、2025-09-29。現在のモデル世代より前の資料です。https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents 確認日 2026-11-01。
• [A3] Anthropic Engineering、『長時間稼働するエージェントのための効果的なハーネス』、2025-11-26。現在のモデル世代より前の資料です。https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents 確認日 2026-11-01。
• [A4] Anthropic、『スキル作成のベストプラクティス』。https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices 確認日 2026-11-01。
• [A5] Anthropic、『Claude Code スキル：アプリの実行と検証』。https://code.claude.com/docs/en/skills 確認日 2026-11-01。
• [O1] OpenAI（Ryan Lopopolo）、『ハーネスエンジニアリング：エージェントファーストの世界で Codex を活用する』、2026 年 2 月。https://openai.com/index/harness-engineering/。現在のモデル世代より前の資料です。確認日 2026-11-03。
• [O3] OpenAI、『Codex のベストプラクティス』（GPT-6.1 Sol、GPT-6 Luna、GPT-6 Astra を対象）。https://learn.chatgpt.com/guides/best-practices 確認日 2026-11-01。
• [O2] OpenAI、『Codex：AGENTS.md』。https://learn.chatgpt.com/docs/agent-configuration/agents-md 確認日 2026-11-01。
• [S1] Agentic AI Foundation（Linux Foundation）、『AGENTS.md』。https://agents.md/ 確認日 2026-11-01。
• [G1] GitHub、『エージェント環境のカスタマイズ』（Copilot）。https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment 確認日 2026-11-01。