このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。 英語版

ゴール保証

ステータス: 現行 対象範囲: ゴールの受け入れ検査とソースの鮮度 最終確認: 2026-09-14 所有者: AX Code runtime のメンテナー

ゴールプランナーが作るコード変更計画は、実行可能な受け入れ検査を宣言します。各検査は、対象とする結果、正確なコマンド、目的、意図した環境を名指しします。エージェントが verify_project を、その検査の goalCheck ID 付きで実行すると、AX Code は実行証拠を記録します。

{ "goalCheck": "invoice-parity" }

コマンドは凍結されたゴール計画から来ます。エージェントはこの呼び出しで、別のコマンドに置き換えることはできません。既存の bash 権限は引き続き適用されます。ゴールを完了するには、宣言された各検査の最新試行が、一致するゴール、セッション、ワークスペース、契約、ソース内容とともに合格する必要があります。受け入れの文章は結果を説明しますが、実行された検査の代わりにはなりません。通常のシェル実行や、完全にスキップされた検査は、この証拠を供給できません。

保証のない古いゴール計画は、以前の完了規則を保ちます。新しい契約が必要なときは、古いゴールを消去して作り直してください。凍結された要件をその場で編集すると、契約の不一致が起きます。フォークは契約を保持しますが、新しいセッションで検査を新たに実行する必要があります。

移行プロジェクトを準備する

改訂識別子付きの権威あるレガシーソースまたはエクスポート、範囲を限定したカバレッジ台帳、そしてアサーションを検証できないときに失敗する検査スクリプトを用意します。コメントや以前の移行実装は、調べる手がかりとして扱います。承認された挙動変更は、レガシーとの同等性要件とは別に記録します。

要求された変更が実際に影響する層の検査を選んでください。

スクリプトは検査を行う前に、対象の同一性を主張しなければなりません。認証情報は、プロジェクトの既存の認証情報の仕組みに置き、計画の本文、コマンド、対象の説明には決して置かないでください。検査は、アサーションの失敗、環境の欠落、必須アサーションのスキップに対して、ゼロ以外の終了コードを返すべきです。失敗を隠すラッパーは避けてください。AX Code は、プロセスの成功終了からアサーションを推測できません。

大規模な移行では、作業を範囲の限られた業務フローのバッチにまとめ、フォーム、依存関係、レガシー参照、受け入れ検査を結ぶ台帳を維持します。受け入れたバッチと残りのカバレッジの両方を報告してください。1 つのバッチに合格しても、移行全体の完了にはなりません。

計画が記録するもの

プランナーは assurance オブジェクトを供給します。次の例示的な断片は、プロジェクトが参照されるソースエクスポートと検査スクリプトを持っていることを前提にします。

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

すべての受け入れ ID がカバーされなければなりません。コマンドはワークスペースのルートから実行されます。保証オブジェクトは受け入れ契約とともに凍結されます。エージェントは、継続するゴールの文脈の中で、検証済みの範囲、ソース参照、検査 ID、宣言された対象を受け取ります。契約が欠ける、または変わると、復元の通知が出ます。生成された会話要約は誤り得ます。宣言された参照と対象ラベルは要件であり、独立に観測された事実ではありません。

このゴールが何を変えたかを測る Git の範囲は、変更前の状態として {BASELINE} を使わなければなりません。プランナーはそのプレースホルダーを、計画提出時に捕捉した HEAD の SHA へ書き換えます。そのため、origin/main より前にある既存のコミットや、汚れた作業ツリーが、ゴールを完了不能にすることはありません。リモート追跡参照（origin/main、@{u}、refs/remotes/…）は、ゴールの目的がそのリモートを名指ししない限り、その変更前状態としては拒否されます。すでに分岐したパスや汚れたパスはリスクの下に記録してください。その失敗を直すことが目的でない限り、すでに失敗している関門検査を凍結しないでください。

鮮度と限界

Git のソース指紋には、宣言された sourcePaths の範囲で、追跡対象ファイルと、無視されていない未追跡ファイルの実際のバイトが含まれます。明示的なファイルパスには、無視された設定ファイルも含まれます。ディレクトリパスは Git の無視規則を保ちます。可変のゴール計画チェックリストは除外されます。その凍結された要件は、契約ダイジェストを通じて検査されます。Git 以外のプロジェクトは、欠落パスを含めて、宣言された sourcePaths を再帰的に指紋化します。関係するソース、設定ファイル、検査スクリプトをすべてその範囲に含めてください。

指紋化は 20,000 項目と、ファイル内容 128 MiB までに限られます。リンクされたソース、入れ子の Git リポジトリ、特殊ファイル、範囲外へ逃げるパス、変化するファイル、読み取り不能は、新鮮な証拠を作れません。そのような失敗は、保証付きの完了を阻みます。検査の出力成果物は無視される場所へ置き、報告書を作ることが検証対象のソースを変えないようにしてください。

明示的に名指しされていない無視ファイル、ソース範囲の外にある依存関係、データベース、デプロイは、プロジェクトのコマンド内のアサーションが必要です。受領は、その実行時点の観測を記録します。外部状態がその後も変わっていないことは証明しません。設定、データベース、デプロイを変えたあとは、影響を受けた検査を再実行してください。AX Code は、レガシーの挙動をすべて自動発見せず、移行の同等性を認証もしません。

計画がいつ走るか

計画は両方の面でオプトインです。/goal <objective> と create_goal を assure なしで使うと、ゴールは直ちに開始します。凍結された受け入れ基準は持たず、完了は作業計画（未完了の todo）と、最後の変更後の合格した検証によって判断されます。/goal --assure <objective> と create_goal を assure: true 付きで使うと、先に計画ライターが走ります。これにより、下記の実行済み検査の受領が完了要件になります。

契約のないゴールは、表示される場所（/goal view、ゴールダイアログ、制御メッセージ）でその旨を示すため、完了の関門を推測する必要はありません。/goal replace は、置き換えられるゴールが有効な契約を持つとき、保証を保ちます。

計画の文脈とモデル選択

ゴール計画は、選択されたセッションモデルを、/goal と create_goal ツールの両方を通じて継承します。互換性のある呼び出し側の変種は保持されます。読み取り専用のライターは、最近の元のユーザー要件と添付の参照を、16 KiB の記録予算で受け取ります。過大な記録は、通知付きで、より古い記録の取り込みを止めます。これにより、省略された訂正を、より古い要件が黙って置き換えることはありません。インラインのメディア内容は、検査済みの証拠としては扱われません。メディアにしかない要件には、検査できるソースファイルを用意してください。

進捗と阻害要因

get_goal には、現在の検査状態（合格、失敗、陳腐、実行中、欠落）と、最近のツール証拠 ID が含まれます。完了の関門は、引き続き現在の成功した受領を要求します。阻害された更新には、阻害の種類、理由、必要な外部変更、元の証拠 ID、そして独立した作業が残っていないことの確認が必要です。阻害の理由は、検査できる記録に支えられたモデルの宣言であり、外部サービスが利用不能のままであることの認証ではありません。

新しい成功したツール証拠を繰り返し生まない完了ターンは、回復の案内を受けたあと、未完了の作業を開示してゴールを一時停止します。新しい調査結果は、ソース編集なしでも数えられます。todo の書き換えや、同一結果の繰り返しは数えられません。これは範囲の限られたヒューリスティックであり、意味的な進捗の証明ではありません。/goal resume は別の試行を開始します。より前のゴール向けに生成されたツール呼び出しは、その置き換えを終了できません。ツールが作ったゴールは、モデルが次のステップで作成結果を受け取ったあと、ステータス更新に使えます。

既存の計画を改訂する

アクティブ、一時停止、または阻害された凍結ゴールを明示的に改訂するには /goal revise <correction> を使います。完了した作業と使い切った予算には、新しいゴールが必要です。以前の計画とダイジェストはそのまま残ります。改訂された計画は新しい同一性と、両方のダイジェストと訂正を結ぶローカルの準備済み改訂記録を得ます。現在のゴール同一性が、実際にインストールされた候補を決めます。失敗した同時候補は、検査のためディスクに残ることがあります。古い受領は履歴に残り、新しい改訂を満たすことはできません。トークン予算と累積使用量は引き継がれます。改訂は新しい支出予算を与えません。

改訂は現在の実行を取り消し、新しい計画を準備しているあいだゴールを一時停止します。計画が失敗した場合、以前の契約は再開可能なままです。以前に阻害されていたゴールは、その状態を保ちます。計画中のユーザーによる一時停止または取り消しは、有効化を防ぎます。同時の置き換えは、候補が引き継ぐことを防ぎます。モデルのツールは、凍結された要件を黙って改訂できません。結果の計画とその受け入れ基準を確認してください。実行可能なコマンドだけでは、そのアサーションが訂正された要求を覆うことは確立しません。

レビュー結果とその後のソース変更

空でないレビューログは、レビューの成功を確立しません。必須の外部レビュアーには、実際の終了コード、終端の完了、ソースまたは差分の同一性、そして最終所見または所見なしの明示的な判定を検証する、プロジェクト所有の検査を使います。警告だけのログ、部分的な推論、タイムアウトは失敗しなければなりません。失敗した試行は、診断のために別に保持してください。

新しいコード変更の提出は、認識された単純なファイル存在検査と検査閲覧のチェックを拒否します。これは狭い受け入れガードであり、任意のシェルコマンドに対する意味的な証明ではありません。既存の凍結契約はスキーマとダイジェストを保ちます。チェックポイントは、より古い検査にこの弱点があるとき警告します。

ゴール検査の鮮度は、現在のゴールのあいだに成功したファイル編集ツールが報告した解決済みファイルパスも指紋化します。これにはすべての multiedit 結果と、元のソース一覧から省かれたパスが含まれます。それらのファイルへの後の編集は、より前の受領を無効にします。凍結された契約とダイジェストは変わりません。この追跡はファイルツールの結果メタデータを使います。任意のシェル副作用やテストカバレッジは推測しません。既存のファイルシステム封じ込め、リンク、サイズ、ファイル数の上限は引き続き適用されます。

検査の出力とゴールのチェックポイントは、追加のパスを開示します。凍結されたテストコマンドが必要な回帰を省いている場合は、/goal revise <correction> を要求し、改訂された検査を実行してください。指紋にファイルが含まれることは鮮度を証明しますが、テストがそのファイルを実行したことは証明しません。範囲の限られたソースディレクトリと、新しい回帰を含むテストコマンドを、開かれたバグ掃引を計画するときに優先してください。

ワークスペースの別名は、観測されたファイルパスについて正規化されます。外部のスクラッチファイルはワークスペースのソース入力にはなりません。チェックポイントは、外部内容が指紋化されないことを開示します。必要な外部状態には、引き続きプロジェクト所有の検証が必要です。

コミット範囲の証拠

空でない git log <baseline>..HEAD -- <paths> は、コミットがフィルタに一致することだけを証明します。そのコミット内の無関係なファイルや、他のコミットを除外することはしません。新しいコード変更計画は、認識された、単独で空でないパスフィルタ付き Git ログのアサーションを拒否します。より古い凍結検査は、ダイジェストや読み取り時の検証を変えずに、改訂の案内を受けます。

ベースラインの祖先を確認し、空でない範囲を要求し、パスフィルタなしで各コミットの変更パスをすべて検査する、プロジェクト所有の検証器を使います。削除されたファイルと名前変更の両側を含め、マージコミットを明示的に扱い、必要なブランチやメッセージの性質は別に検証してください。既存の契約を強めるには /goal revise を使います。凍結された要件を編集しないでください。

計画の大きさと完全な再提出

描画された計画は、Markdown と保証 JSON を含めて、8,192 UTF-8 バイト以内に収まらなければなりません。7,168 バイト未満を目指してください。提出が上限を超える場合は、繰り返される文章を短くし、kind と必須フィールドをすべて含む完全なオブジェクトを再提出します。受け入れ ID と検査は保持してください。ランタイムは要件を切り詰めず、過大な計画を受け入れるために読み手の上限を上げることもありません。

ローカル CLI アニメーションのレビュー受領

リポジトリ所有の packages/ax-code/script/verify-cli-review-receipts.ts は round-* の成果物を検査します。受領ルートは --root で選びます。各ラウンドには revision.txt が必要で、grok、claude、codex のそれぞれには exit.txt が必要です。それには 0 と、stdout.jsonl（Grok のテキストイベント）または stdout.txt（Claude / Codex）にある最終判定が 1 つ含まれます。失敗した試行は、完了したラウンドのディレクトリの外に保持してください。失敗を終了コード 0 の受領に変えないでください。

dispositions.json は findings 配列を含みます。各項目は round、cli、id、status（fixed または rejected）、および空白でない evidence を名指しします。固定された項目はさらに regression オブジェクトを要求します。そこにはリテラルなリポジトリパス file があり、場所は packages/ax-code/test/cli/tui/ の下で、正確な Vitest の fullName を伴います。重複した処遇や、曖昧な複数の判定は失敗します。

検証器は、グローバルな再試行既定をゼロに設定した、インストール済みの Vitest でそれらのファイルを実行します（個々のテストオプションはその既定を上書きできます）。その後、参照された各アサーションがちょうど 1 回合格したことを確認します。欠落、スキップ、失敗、または曖昧なアサーションは検証を失敗させます。これは、参照されたテストが合格したことを証明しますが、そのアサーションが所見を意味的に覆うことは証明しません。拒否された処遇は、記録された判断として残ります。最終ラウンドは現在の HEAD と一致しなければなりません。修正済みと印が付いた所見には、より新しい改訂とレビューラウンドが必要です。未コミットのコアパッケージのソース、テスト、設定の変更は検証を妨げます。無関係なローカルの ax-code.json 設定はコミットに含めないでください。

このリポジトリでは、vitest run --dir test/cli/tui は通常レーンの除外を保ちながら TUI ディレクトリを走査します。グループランナーは、AX_TEST_FILES で正確なファイルを選ぶことができます。ディレクトリ選択は除外を無効にしません。