build-run-debug

ビルド／実行／デバッグ

クイックスタート

このスキルを使って、プロジェクト内に script/build_and_run.sh というエントリーポイントを1つ用意し、 .codex/environments/environment.toml を設定してCodexアプリに「実行」ボタンを表示し、 その後はこのスクリプトをデフォルトのビルド／実行方法として使用します。

シェルを中心としたワークフローを優先します。

• 用意できたら、./script/build_and_run.sh を終了・ビルド・実行をまとめて行う単一のエントリーポイントとして使います
• Xcodeのワークスペースまたはプロジェクトでは xcodebuild を使います
• SwiftPMの純粋なコマンドラインツールでは、スクリプト内で swift build を実行し、生成された実行ファイルを直接起動します
• SwiftPMのAppKit／SwiftUI GUIアプリでは、swift build の後、プロジェクト内に .app バンドルを用意し、/usr/bin/open -n で起動します
• lldb、log stream、テレメトリーの検証、起動後のプロセス確認には、必要に応じてスクリプトのフラグを追加します

シミュレーター、タッチ操作、モバイル固有のツールが使えるとは想定しないでください。

Xcode対応のMCPサーフェスがすでに利用可能で、ユーザーが明示的に希望する場合は、 適切な範囲でのみ使用してください。用途を限定し、Xcode関連の調査、ログ取得、デバッグ支援には活用できますが、 macOSのみのタスクにシミュレーター固有のワークフローを無理に適用しないでください。

ワークフロー

1. プロジェクトの構成を確認します。

   • git rev-parse --is-inside-work-tree を実行し、ワークスペースがすでにgitリポジトリ内にあるか確認します。
   • gitリポジトリがない場合は、ビルドの前にプロジェクト／ワークスペースのルートで git init を実行し、Codexアプリのgit連携機能を利用できるようにします。現在のワークスペースが親リポジトリに属している場合、ネストされたサブディレクトリ内で git init を実行してはいけません。
   • .xcworkspace、.xcodeproj、Package.swift を探します。
   • 候補が複数ある場合は、デフォルトでどれを選ぶかと、どのような曖昧さがあるかを説明します。

2. 実行可能なターゲットとプロセス名を特定します。

   • Xcodeの場合は、スキームを一覧表示し、ユーザーが別のスキームを指定していなければ、アプリを生成するスキームを優先します。
   • SwiftPMの場合は、可能であれば実行可能なプロダクトを特定します。
   • SwiftPMの起動処理は、プロダクトの種類に応じて分けます。
     • 純粋なコマンドラインツールには、実行ファイルを直接起動する方法を使います。
     • AppKit／SwiftUI GUIアプリには、プロジェクト内に生成した .app バンドルを使います。
   • 再起動前に終了させるアプリ／プロセスの名前を特定します。

3. script/build_and_run.sh を作成または更新します。

   • プロジェクトに合わせたスクリプトにし、実行可能にします。
   • スクリプトでは、必ず次の処理を行います。
     1. 既存のアプリ／プロセスが実行中であれば停止します。
     2. macOSターゲットをビルドします。
     3. ビルドしたばかりのアプリまたは実行ファイルを起動します。
   • デバッグ／ログ確認用に、任意のフラグを追加します。
     • --debug は lldb で起動するか、デバッガーをアタッチします
     • --logs は起動後にプロセスのログをストリーミングします
     • --telemetry はアプリのサブシステム／カテゴリで絞り込んだ統合ログをストリーミングします
     • --verify はアプリを起動し、pgrep -x <AppName> でプロセスの存在を確認します
   • フラグを指定しないデフォルトの処理は、終了・ビルド・実行だけにします。
   • エージェントに swift build、生成物の場所の特定、その後の場当たり的な実行コマンドを何度も手動で実行させるのではなく、このワークフローを一括して担うスクリプトを1つ作成することを優先します。
   • SwiftPMのGUIアプリでは、スクリプトでプロダクトをビルドし、dist/<AppName>.app を作成し、バイナリを Contents/MacOS/<AppName> にコピーします。また、CFBundlePackageType=APPL、CFBundleExecutable、CFBundleIdentifier、CFBundleName、LSMinimumSystemVersion、NSPrincipalClass=NSApplication を含む最小限の Contents/Info.plist を生成し、その後 /usr/bin/open -n <bundle> で起動します。
   • SwiftPMのGUIアプリで --logs と --telemetry を使う場合は、まず /usr/bin/open -n でバンドルを起動し、その後 /usr/bin/log stream --info ... で統合ログをストリーミングします。
   • AppKit／SwiftUI GUIアプリに対して、SwiftPMの実行ファイルを直接起動する方法を推奨してはいけません。
   • スクリプトの形式と環境ファイルの正確なフォーマットについては、正式な参照元として references/run-button-bootstrap.md を使用します。別のスキルやコマンドに、同じ内容を権威ある別のスニペットとして複製しないでください。
   • 実行スクリプトはアプリのソースコード外に置きます。App/、Views/、Models/、Stores/、Services/、Support/ ではなく、script/build_and_run.sh に置いてください。

4. スクリプトが存在したら、プロジェクトルートに .codex/environments/environment.toml を作成します。

   • この正確な配置を使用します: .codex/environments/environment.toml。
   • references/run-button-bootstrap.md にある正確なアクションの形を使用します。
   • このファイルが、スクリプトに接続された Codex アプリの実行ボタンをユーザーに提供するものです。
   • プロジェクトにすでにこのファイルがある場合は、重複するアクションを作成するのではなく、Run アクションのコマンドを ./script/build_and_run.sh を指すように更新します。
   • この Codex 環境設定は、Swift アプリのソースファイルとは別に保ちます。

5. スクリプトを通じてビルドと実行を行います。

   • 既定では ./script/build_and_run.sh を使用します。
   • ユーザーがデバッガー/ログ/テレメトリ/プロセス検証のサポートを求めた場合は、./script/build_and_run.sh --debug、--logs、--telemetry、または --verify を使用します。

6. 失敗を正確に要約します。

   • ブロッカーを、コンパイラ、リンカー、署名、ビルド設定、SDK/ツールチェーンの欠如、スクリプトのバグ、実行時の起動のいずれかに分類します。
   • 最小限の有用なエラースニペットを引用し、それが何を意味するのかを説明します。

7. 正しい方法でデバッグします。

   • 設定、エンタイトルメント、サンドボックス、アクションイベントの検証には、スクリプトの --logs または --telemetry モードを使用します。
   • SwiftPM の GUI アプリでは、アプリバンドルは起動するもののウィンドウが前面に出てこない場合、エントリポイントに NSApp.setActivationPolicy(.regular) と NSApp.activate(ignoringOtherApps: true) が必要かどうかを確認します。
   • シンボル化されたクラッシュのデバッグが必要な場合は、スクリプトの --debug モードまたは直接 lldb を使用します。
   • ユーザーが特定のウィンドウ、サイドバー、メニュー、またはメニューバーのアクションを計測および検証する必要がある場合は、telemetry に切り替えます。
   • エビデンスは簡潔にまとめ、ユーザー向けに示します。

8. Xcode を認識する MCP ツールは、役立つ場合にのみ使用します。

   • ユーザーが明示的に XcodeBuildMCP を求め、それがすでに利用可能な場合は、その場しのぎのセットアップよりも優先します。
   • 利用可能なツールの範囲がタスクに明確に合致する場合は、Xcode を認識する検出やデバッグ/ログのワークフローに MCP を使用します。
   • MCP がクリーンな macOS の手段を提供しない場合は、すぐにシェルコマンドにフォールバックします。

推奨コマンド

• プロジェクトの検出:
  • find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
• スキームの検出:
  • xcodebuild -list -workspace <workspace>
  • xcodebuild -list -project <project>
• ビルド/実行:
  • ./script/build_and_run.sh
  • ./script/build_and_run.sh --debug
  • ./script/build_and_run.sh --logs
  • ./script/build_and_run.sh --telemetry
  • ./script/build_and_run.sh --verify

参照

• references/run-button-bootstrap.md: 正規の build_and_run.sh と .codex/environments/environment.toml の契約。

ガードレール

• 現在の仮説を証明または反証する、最も狭いコマンドを優先します。
• 安定した build_and_run.sh スクリプトがワークフローを担えるようになったら、ユーザーを一度きりの手動コマンドチェーンに置き去りにしないでください。
• 実行スクリプトが存在する前に .codex/environments/environment.toml を書かないでください。また、Run アクションを古いスクリプトパスに向けないでください。
• ユーザーが明示的にその失敗モードを診断したい場合を除き、SwiftUI/AppKit の SwiftPM GUI アプリを生の実行ファイルとして起動しないでください。Dock アイコンが表示されない、フォアグラウンドアクティベーションが行われない、バンドル識別子の警告が欠落する、といった問題が発生する可能性があります。生の実行ファイルの起動は、真のコマンドラインツールにのみ用いてください。
• 直接検査できない UI の状態を主張しないでください。
• モバイルやシミュレータのワークフローを、macOS に当てはまるかのように説明しないでください。
• ビルド出力が膨大な場合は、最初の本当のブロッカーを要約し、後続のコマンドを示してください。

出力の期待事項

以下を提供します:

• 検出されたプロジェクト種別
• 設定した場合は、スクリプトパスと Codex 環境アクション
• 実行したコマンド
• ビルドと起動が成功したかどうか
• 失敗した場合の最上位のブロッカー
• 最小限の妥当な次のアクション