cmux-artifact

cmux アーティファクト

ユーザーから HTML アーティファクト、ウォークスルー、エビデンスページ、デモページ、アーティファクトのプレビュー、または変更内容を実際に試したり、検証したり、理解したりするためのワークスペースレイアウトを求められた場合は、このスキルを使用します。目的は、長期的に利用でき、内容を確認できるアーティファクトと、重要なエビデンスを表示するための、作業を妨げない cmux ワークスペースのタブを用意することです。

前提条件

• 呼び出し元の cmux ワークスペースはデフォルトの配置先ですが、必須ではありません。ペイン、タブ、ブラウザー、ログ、スクリーンショット、動画、生成ドキュメントを開く場合は、cmux-workspace スキルを参照してください。
  • タスクに関連するエビデンス（実際に試した証拠、失敗ログ、検証ページなど）をユーザーが実行した作業の隣に表示する場合は、呼び出し元ワークスペースの右側のヘルパーペインをデフォルトにします。
  • アーティファクトが単独で長期的に利用されるもの（設計ドキュメント、レポート、または後で参照するページ）の場合、呼び出し元ワークスペースを分割すると作業中のターミナルが手狭になる場合、またはユーザーが別の場所を指定した場合は、専用のワークスペースまたは新しいワークスペースを優先します。cmux new-workspace で追加作成し、ユーザーが今すぐアーティファクトを表示するよう求めた場合（「開いて」という明示的な依頼を含む）にのみ切り替えます。推測で select-workspace／focus-pane を呼び出してはいけません。
  • どちらが適切か判断できない場合は、ユーザーに尋ねるか、影響の少ない方を選び、ユーザーが変更できるよう配置先を伝えます。
• 実際のコマンド出力、ログ、スクリーンショット、トレース、所要時間を優先します。エビデンスを捏造してはいけません。
• 最終的なユーザー向けアーティファクトを /tmp に置いてはいけません。

アーティファクトの配置先

最終的なアーティファクトは、ブランチごとの永続的なツリーに置きます。

BRANCH="$(git -C <worktree-or-repo> branch --show-current 2>/dev/null || echo task)"
ASSET_ROOT="/cmux-assets/${BRANCH:-task}/<artifact-slug>"
mkdir -p "$ASSET_ROOT"

/cmux-assets を作成または書き込みできない場合は、現在のリポジトリのチェックアウト内にある cmux-assets/<branch>/<artifact-slug> を使用し、その代替先を使ったことを伝えます。/tmp は一時作業専用です。採用したログ、スクリーンショット、フレーム、動画、トランスクリプトは、開いたり報告したりする前に永続的なツリーへコピーします。

ワークフロー

ステップ 1：エビデンスの収集

タスクを説明するのに必要な、実際のアーティファクトを最小限のセットで収集します。

• コマンドのトランスクリプトまたはターミナル出力
• 関連するログ
• スクリーンショット、フレーム、動画、またはブラウザーのスナップショット
• 正確な所要時間を記載したタイミング表
• 必要に応じてコード参照や PR リンク
• クリーンアップの状況と残っている阻害要因

run-transcript.md、server.log、failure.log、screenshot.png、index.html のように、簡潔な名前を付けます。

ステップ 2：index.html の作成

ファイルシステムから動作する、単独で完結した HTML ドキュメントを作成します。次の内容を含めてください。

• テストまたは変更の概要を平易な言葉で説明したもの
• 簡潔なタイムラインまたは手順表
• 重要な所要時間
• 相対パスを使った、ローカルにコピーしたログ／メディアへのリンク
• 実際に確認された失敗と、次に直接実行するアクション
• 外部リソースを作成した場合は、そのクリーンアップ状況

エンジニアリングレビューに適した、シンプルで情報密度の高い UI を使用します。マーケティング用セクション、大きなヒーローレイアウト、装飾的なグラデーション、隠されたエビデンスは避けてください。

インタラクティブなアーティファクトの場合は、単一の静的ドキュメントではなく、小規模な React ウェブサイトを作成してもかまいません。たとえば package.json、server.ts、src/main.jsx、src/styles.css、public/ などを含め、同じ ASSET_ROOT の下に配置します。既存のリポジトリ依存関係またはブラウザーの ESM インポートを使用した、インストール不要のセットアップを優先します。bun がインストールされていて、ホスティングによってユーザーが UI を試せる場合は、表示可能な cmux ヘルパーターミナルで Bun サーバーをフォアグラウンド実行し、ブラウザー画面で正確なローカル URL を開きます。ホスティングしたアーティファクトに、隠れた tmux、nohup、デタッチされたバックグラウンドサーバー、汎用 localhost ページを使用してはいけません。Bun を利用できない場合や、ホスティングに利点がない場合は、ファイルシステム上の index.html を使用します。

ステップ 3：役立つタブを開く

最終的な index.html を、フォーカスを変更せずに、その file:// URL を開いたブラウザーサーフェスとして表示します。デフォルトでは呼び出し元ワークスペースの右側のヘルパーペインが対象ですが、前提条件に応じて、専用ワークスペースまたは新しいワークスペースを使う場合もあります（独立した永続的な成果物の場合や、呼び出し元ワークスペースを分割すると実行中のターミナルが窮屈になる場合など）。別のワークスペースを使う場合は、以下のサーフェス／ペインのコマンドで ${CMUX_WORKSPACE_ID} の代わりに --workspace <that-workspace> を指定します。HTML の成果物を cmux open で開かないでください。ブラウザーで成果物を表示する代わりに、ファイルプレビューが作成されます。ログ、Markdown のトランスクリプト、スクリーンショット、動画などの生のエビデンスは、ブラウザーで成果物を表示した後に cmux open で開きます。

まず、同じ index.html の成果物が対象のワークスペースまたはヘルパーペインですでに開かれているか確認します。ブラウザーサーフェスとしてすでに開かれている場合は、そのサーフェスをそのまま使い、必要に応じて成果物の URL に移動してから、引き継ぎ前に必ず更新後の index.html を再読み込みします。

FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"
cmux browser --surface surface:<existing-artifact-browser> goto "$FILE_URL" --snapshot-after
cmux browser --surface surface:<existing-artifact-browser> reload --snapshot-after

同じファイルを書き換えた後に、goto だけで十分だと判断しないでください。ブラウザーサーフェスには古いファイルの内容が表示されたままになることがあります。reload --snapshot-after によって、現在表示されている成果物が更新されたことを確認できます。

既存の成果物がファイルプレビュー、または再読み込みできない別のサーフェスとして開かれている場合は、その古い成果物のサーフェスを閉じてから、同じヘルパーペインにブラウザーサーフェスを 1 つ開きます。同じ成果物のサーフェスが重複している場合は、ブラウザーサーフェスがあれば 1 つだけ残し、古い重複分を閉じてから、残したブラウザーで移動または再読み込みします。同じ成果物の index.html タブを複数残さないでください。どれが最新バージョンなのか分からなくなります。

成果物は作業と並べて、独立したペインに配置します。 エビデンスをターミナルの背後に隠さず、隣に表示することが目的です。呼び出し元ワークスペースに適切な右側のヘルパーペインがすでにある場合は、それを再利用します。ワークスペースが 1 つのペイン（アクティブなターミナルのみ）の場合は、成果物を同じペインの別のサーフェスとして追加しないでください。new-surface --pane <active-pane> は、ターミナルの背後に積み重ねられたバックグラウンドタブを作成するため、ユーザーには何も変わっていないように見えます。代わりに右側に分割します。new-pane --direction right を使って新しい右側のペインにブラウザーを直接開くか、アクティブなペインですでに作成したサーフェスを split-off します。

FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"

# Single-pane workspace (no right helper yet): open the artifact in a NEW right split.
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" \
  --direction right \
  --type browser \
  --url "$FILE_URL" \
  --focus false

# Already have a dedicated right helper pane: add the browser surface there.
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "$FILE_URL" \
  --focus false

# Recovery: artifact landed as a background tab in the active terminal's pane?
# Split that exact surface out to the right instead of leaving it buried.
cmux split-off --surface surface:<artifact-browser> right --focus false

cmux open "$ASSET_ROOT/failure.log" \
  --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --no-focus

ホストされた React の成果物の場合は、同じ対象ワークスペース／ペインにヘルパーターミナルを作成または再利用し、そこでサーバーを実行して、稼働中であることを画面上で確認してから、提供された URL を開きます。

cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type terminal \
  --focus false
cmux send --surface surface:<helper-terminal> \
  "cd '$ASSET_ROOT' && PORT=<port> bun run server.ts\n"
curl -fsS "http://127.0.0.1:<port>/healthz"
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "http://127.0.0.1:<port>/" \
  --focus false

cmux-workspace スキルで説明されているとおりに、ヘルパーペインを正確に特定します。明らかな場合は既存の右側のヘルパーペインを再利用します。該当するペインがない場合は、成果物をアクティブなターミナルの背後に積み重ねるのではなく、右側に分割して作成します（new-pane --direction right または split-off）。呼び出し元の環境が古いために cmux open が失敗した場合は、cmux identify --json の出力を使って 1 回だけ再試行し、それでも失敗する場合は正確なパスを報告します。

ステップ 4：検証

完了を報告する前に、次を確認してください。

test -f "$ASSET_ROOT/index.html"
ls -la "$ASSET_ROOT"

ホストされた成果物の場合は、引き渡しの前にサーバーも確認してください。

curl -fsS "http://127.0.0.1:<port>/healthz"
cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:<helper-terminal> --lines 20

cmux で開いた場合は、cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json または最も近い同等のコマンドを実行して、タブが作成されたことを確認してください。

また、対象のヘルパーペインに、成果物 index.html の表示可能なサーフェスが 1 つだけあることを確認してください。コマンド出力に同じ成果物のパスまたはタイトルの重複が表示される場合は、完了を報告する前に古い重複を閉じてください。

成果物が作業領域と横並びの専用ペインにあり、アクティブなターミナルのペイン内のバックグラウンドタブになっていないことを確認してください。list-panes --json で、ワークスペースに成果物のブラウザーサーフェスを保持する独立したペインがあることを確認してください（アクティブなターミナルのペインを共有する非選択サーフェスは、ターミナルの背後に隠れていることを意味します）。埋もれている場合は、完了を報告する前にそのサーフェスを右側に split-off してください。

このタスクを開始する前から成果物が開いていた場合は、最後の書き込み後に、保持するブラウザーサーフェスが再読み込みされたことを確認してください。最後のブラウザーコマンドの後に最後の書き込みが行われた場合は、再読み込みをやり直してください。

ルール

• 最終成果物を /tmp にだけ残さないでください。
• リンクされたトランスクリプトで確認できない限り、実行が成功したと主張しないでください。
• 成果物にシークレットを貼り付けないでください。ログをコピーする前に、API キー、トークン、Cookie、Authorization ヘッダーを伏せてください。
• フォーカスを奪わないでください。明示的なワークスペース参照とペイン参照に加え、--no-focus または --focus false を使用してください。
• 呼び出し元のワークスペースが既定ですが、必須ではありません。独立した永続的な成果物は、専用または新しいワークスペースで開いてもかまいません。追加で作成し、ユーザーが今すぐ表示するよう求めた場合にのみ切り替えてください。
• 特定の成果物パスまたはディープリンクがある場合、リポジトリのトップレベルや一般的な localhost ページを開かないでください。
• 最終チャットの回答は簡潔にし、永続的な成果物のパスと具体的な次のアクションを含めてください。