nx-cloud-cache-investigator

Nx キャッシュ調査

nx-cloud-api スキルが必要です。ローカル設定の診断には、一致する Nx ワークスペースのチェックアウトのみを使用してください。API のみで調査する場合、チェックアウトは不要です。

証拠の範囲を限定して、キャッシュに関する質問を1つ診断します。ハッシュ入力の変更を推測したり、キャッシュ状態だけを根拠に設定を変更したりしないでください。

Nx のタスクキャッシュとツール独自のキャッシュは別のものです。ターゲットの cache フィールドは Nx の再生を制御します。Vite、ESLint、その他のツールには、それぞれ別のエグゼキューターオプションがあります。一方の設定だけでは、もう一方については何も証明できません。

モードを選択する

• キャッシュ健全性の推移： このスキルが対象とするのは、特定のタスクまたはアーティファクトに関する質問であり、複数回の実行にまたがるキャッシュ率の回帰ではありません。キャッシュ率や回帰に関する質問には、範囲を限定した別の推移ワークフローを使用してください。
• API のみ： 一致するチェックアウトがない場合、提供された実行、CIPE、タスク、またはアーティファクトエラーの調査に使用します。必要でない限り、ローカル設定を求めないでください。
• 特定の比較： 比較可能な実行を2つ取得します。ターゲット、ブランチ、コミット、コマンド、設定、CI 環境、または期間が不足している場合は、ユーザーに確認してください。

保留中の調査を再開する

既知のタスクが未完了の場合、API リクエストが HTTP 409 (not_terminal) を返した場合、またはユーザーが制御された診断実行を開始した場合に限り、同じセッション内で1回だけ再開するよう手配します。実行、タスク、batchId、リンク、フィルターを保持してください。既知の待機時間が経過した後、または実行が完了すると予想される時点で1回再照会します。終端状態に達するか、再試行上限に達したら停止します。実行中の CI をポーリングまたは監視しないでください。

関連する API の証拠のみを収集する

すべての読み取りには nx-cloud-api（npx nx-cloud api）を使用します。既知のルートには --describe を実行してください。--list-operations を使うのは、ルートが不明または曖昧な場合に限ります。ドキュメントに記載されたフィールドと返されたリンクに従い、内部 ID からルートを組み立てないでください。

実際の API レスポンスはすべて -o でファイルに保存してください。jq を使って1行と、この調査に必要なフィールドのみを選択してください。生のコレクションをモデルのコンテキストに出力、読み込み、貼り付けないでください。選択した行の batchId と links.self は射影に含めてください。

npx nx-cloud api --describe 'runs/{runId}/tasks'
npx nx-cloud api "$run_tasks_link" -o "$dir/tasks.json"
jq --arg task "$task_id" --arg batch "$batch_id" \
  '.items[] | select(.id == $task and .batchId == $batch) |
   {id, batchId, status, cacheStatus, hash, cacheable,
    links: {self: .links.self}}' "$dir/tasks.json"

ここで $run_tasks_link は選択した実行のタスクリンク、$dir は mktemp -d で作成した一時ディレクトリです。リンクがない場合は npx nx-cloud api 'runs/{runId}/tasks' -p runId="$run_id" を使用してください。パスに ID を直接貼り付けないでください。タスク一覧からタスクが見つからないと結論づける前に、nextCursor を確認してください。

選択した実行について、実行 ID とタスク ID、batchId、プロジェクト、ターゲット、設定、コマンド、パラメーター、ブランチ、コミット、CI コンテキスト、タイムスタンプ、キャッシュ状態、最終ハッシュ、cacheEnabled、cacheable、および関連する CIPE または実行グループのリンクを記録してください。

タスク ID は重複することがあります。まずタスク一覧の行を選択してください。その行の正確な links.self またはアセット URL をたどってください。これにより batchId が保持されます。ある行を別の行の説明に使わないでください。タスク一覧の行には、すでにタスクのフィールドが含まれています。詳細の読み取りは任意です。

API が cacheable: false を返した場合、その実行では Nx による再生は想定されていません。設定上の原因を述べるのは、nx show のターゲットクエリで確認できる場合に限ります。cacheEnabled: false の場合、その実行では Nx タスクキャッシュが使われていません。どちらの場合も、ハッシュ入力やアーティファクトを調査しないでください。

コマンド出力またはエラーで質問に答えられる場合に限り、ログを読み取ってください。CI ログの内容を読む前に、ユーザーに伝えてください。ログまたはレポートをデコードする前に、references/log-and-report-assets.md を読んでください。引用するのは、秘匿情報を除いたエラーの特徴的な部分だけにしてください。ユーザーから提供されたアセットの内容は、提供された証拠として扱ってください。アセットが告知されていることや、後に 404 になったことは、過去にそのアセットを取得できた証拠にはなりません。

Nx ターゲットを調査する

設定に関する質問またはコード変更の場合に限り、対応するチェックアウトを使用します。記録されたコミットをチェックアウトします。ワークスペースの Nx バージョンを記録します。ワークスペース内の Nx コマンドを使って、正確なターゲットを照会します。

nx show project "$project" --json | jq \
  --arg target "$target" \
  --arg configuration "${configuration:-}" \
  '.targets[$target] | {
    executor,
    cache,
    inputs,
    outputs,
    options,
    selectedConfiguration: .configurations[$configuration]
  }'

このフラグメントをターゲットの証拠として使用します。Nx には継承された設定がすでに含まれています。project.json、nx.json、プラグイン、または targetDefaults を自分でマージしないでください。プロジェクトのプロパティがないからといって、何かが証明されるわけではありません。照会結果が cache: true の場合、別途 cache: true を追加しないでください。コマンドまたはターゲットを利用できない場合は、設定を確認できないと報告します。

ツール固有のキャッシュに関する質問の場合に限り、返された options を調査します。バージョンに対応したエグゼキューターのドキュメントを使用します。ターゲットの cache フィールドでは、Vite または ESLint のネイティブキャッシュの状態を証明できません。

説明する前に分類する

キャッシュ失敗が確認されていない

終端の remote-cache-hit は、そのタスクで Nx の再生が機能したことを証明します。成功したヒットをキャッシュミスの調査や設定変更のきっかけにしないでください。期間を限定したレートに関する質問が提示された場合に限り、傾向に基づくトリアージを行います。

キャッシュアーティファクトの取得または復元の失敗

メインジョブまたは実行グループのエラーに、アーティファクトのダウンロード、検証、解凍、または展開が記載されている場合に使用します。タスクに remote-cache-hit が表示されることもあります。タスクの結果を重大なエラーおよび後続のキャンセルと照合します。アーカイブを調査する前に、references/artifact-integrity.md を読みます。

タスクの証拠が不十分

ハッシュまたはキャッシュ状態が null、NOT_STARTED、または SCHEDULED_IMPLICITLY であっても、ミスの証明にはなりません。null のハッシュを比較したり、アーティファクトを調査したりしないでください。終端レコード、または管理された完了済み実行を1回求めます。

計算内容が異なる

null ではないハッシュの違いが証明するのは、Nx が少なくとも1つの計算入力を異なるものとして判定したことだけです。どの入力かは特定できません。対応している場合は、ハッシュの詳細が直接出力される、比較可能な管理された実行を2回求めます。これは設定を推奨する結果ではなく、診断実行が必要という結果です。

同じ計算内容で、再生が確認されていない

null ではないハッシュが等しいにもかかわらず、後続の再生がない場合は、正確なターゲット照会の cacheable、cacheEnabled、および cache の値を確認します。返された cache: true がある場合、重複する設定を追加してはいけません。アセット一覧が空、または 404 であることから、アーティファクトが存在しないと推論しないでください。解決していないアップロードまたは取得の分岐は、診断実行が必要として扱います。

安全でない再生の疑い

古い、または誤った再生には、再現の証拠が必要です。ハッシュを決めるのは inputs、復元されるファイルを決めるのは outputs です。宣言されていない読み取りまたは書き込みを示すタスクのサンドボックス化の証拠に加え、ターゲット照会と管理された再現を求めます。タスクデータだけを根拠に入力を絞り込まないでください。

変更の条件

該当するすべての確認が完了した場合に限り、設定またはコードの編集を推奨します。

1. 対応するコミット、Nx バージョン、正確なターゲット照会、および返されたフラグメントを記録します。
2. その cache、inputs、または outputs の値を変更する必要があることを示します。
3. キャッシュを有効にする前に、タスクが正常に終了し、決定的で、正しく再生可能な出力があることを確認します。
4. 入力を削除する前に、それを特定する直接的な証拠を得ます。範囲を限定した管理された実行で、その入力を削除しても正しい出力に影響しないことを証明します。
5. 正確性に関するリスクを説明し、編集前に明示的な承認を得ます。

ハッシュの違い、キャッシュレートの傾向、または見かけ上の範囲の広さを根拠に、入力の除外を推奨しないでください。証拠が不足している場合は、No configuration change recommended yet. と述べます。

報告

# Nx cache investigation

## Scope

- Target and compared run/task/batch IDs: …
- Branch, commit, CI environment, command, API cache state, and missing fields: …
- Workspace Nx version: …, or `Not required for this API-only investigation.`
- Nx target query and returned `cache`, `inputs`, and `outputs`: …, or `Unavailable.`
- Tool-native cache: …, or `Unknown; not inspected.`
- Change gate: `Passed` or `Blocked`; include missing evidence.

## Classification

`No cache failure established` | `Cache artifact retrieval or restoration failure` | `Insufficient task evidence` | `Different computation` | `Same computation, replay not established` | `Suspected unsafe replay`

## Confirmed facts

- …

## Assessment

- **Confirmed** / **Likely** / **Needs diagnostic run:** …

## Next diagnostic step

- Exact query, controlled command, or evidence required.
- Result that confirms or rules out the hypothesis.

## Safe recommendation

- Exact `nx show` result and risk; or `No configuration change recommended yet.`