use-railway

Railway の使用

Railway のリソースモデル

Railway では、インフラストラクチャが階層構造で管理されます。

• Workspace は、課金とチームのスコープです。ユーザーは 1 つ以上のワークスペースに所属します。
• Project は、1 つのワークスペース内のサービスの集合です。デプロイ可能な作業単位 1 つに対応します。
• Environment は、プロジェクト内の分離された構成領域です（例：production、staging）。各環境は独自の変数、構成、デプロイ履歴を持ちます。
• Service は、プロジェクト内の単一のデプロイ可能な作業単位です。リポジトリのアプリ、Docker イメージ、またはマネージドデータベースを指定できます。
• Bucket は、プロジェクト内の S3 互換オブジェクトストレージリソースです。バケットはプロジェクトレベルで作成され、環境にデプロイされます。各バケットには、S3 互換アクセス用の認証情報（エンドポイント、アクセスキー、シークレットキー）があります。
• Deployment は、環境内のサービスの特定時点におけるリリースです。ビルドログ、ランタイムログ、ステータスのライフサイクルがあります。

ほとんどの CLI コマンドは、リンク済みのプロジェクト／環境／サービスのコンテキストで動作します。コンテキストを確認するには railway status --json を使用し、上書きするには --project、--environment、--service フラグを使用してください。

ツールの使い分け

Railway には、エージェント向けの操作経路が 3 つあります。作業に合った経路を選んでください。

• Railway CLI（railway）：現在の作業ディレクトリからのデプロイ、railway up、railway run、SSH、データベース分析スクリプト、ローカルでのリンク、対話型セットアップ、またはコマンドの正確な出力など、ローカルマシンの状態に依存するワークフローに使用します。
• リモート MCP（https://mcp.railway.com）：アカウント／プロジェクト／サービスの検出、デプロイ状態、範囲を限定したログ、トレース、フィーチャーフラグ、簡単な再デプロイ、簡単なプロジェクト作成、または railway-agent に委任できる複雑な Railway ワークフローに使用する、プラグインのデフォルトの MCP 経路です。リモート MCP は Railway OAuth を使用し、ローカル CLI の状態には依存しません。
• railway api 経由の GraphQL：専用の MCP ツールや CLI コマンドがない操作に使用します。慣れていないクエリを作成する前に、スキーマを検索して確認してください。

複数の経路が利用できる場合は、必要なコンテキストを維持できる経路を選んでください。現在のリポジトリ、ローカルの認証情報、SSH、データベーススクリプト、またはコマンドの正確な出力が必要なワークフローには CLI が適しています。ローカルファイルや CLI の状態が不要な、OAuth のスコープ内で行うプラットフォーム操作にはリモート MCP が適しています。

Railway クラウドエージェント VM では、railway CLI の認証情報は SSH ターミナルセッション内でのみ利用できます。ダッシュボードやモバイルチャットのセッション（Railway Agent）では、設計上、認証されていません。その場では、読み取りだけであっても railway コマンドを実行せず、railway api も実行しないでください。railway MCP サーバーはすべてのセッションで認証されるため、そのツールを使用してください。ID の解決には railway status --json ではなく list-services を使い、作業に対応するツールがない場合はその旨を伝え、ダッシュボードで変更するようユーザーに依頼してください。

任意：すでに構成済みのインプロセス CLI MCP（railway mcp local）を使用すると、ホスト型 MCP では利用できない操作を行えます。引数なしの railway mcp は現在、CLI 認証を使用するホスト型 MCP プロキシを起動します。インプロセスサーバーではありません。公開済みプラグインの構成は、エディターの OAuth を使用してホスト型 MCP に直接接続します。

GraphQL の実行には railway api（CLI 5.28 以降）を優先してください。従来の scripts/railway-api.sh は、古い CLI 用の互換性フォールバックとして引き続き利用できます。詳しくは request.md を参照してください。

Railway URL の解析

ユーザーが Railway ダッシュボードの URL を貼り付けることはよくあります。ほかの操作を行う前に ID を抽出してください。

https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>

URL には必ず projectId と serviceId が含まれます。クエリパラメーターとして environmentId が含まれている場合もあります。環境 ID がなく、ユーザーが環境名（例：「production」）を指定した場合は、次のように解決してください。

railway api \
  'query getProject($id: String!) {
    project(id: $id) {
      environments { edges { node { id name } } }
    }
  }' \
  --variables '{"id": "<PROJECT_ID>"}'

環境名の大文字と小文字を区別せずに照合し、environmentId を取得してください。

railway link を実行する代わりに、CLI コマンドでは明示的な ID（--project、--environment、--service）を、スクリプトでは明示的な ID（--project-id、--environment-id、--service-id）を渡すことを優先してください。これにより、グローバル状態の変更を避けられ、処理も速くなります。

インテントベースのルーティング

プリフライトチェックを実行する前に、ユーザーのインテントに基づいてルーティングします。以下のプリフライト手順は、診断や設定作業のためのものです。ユーザーがただ何かを公開したい、または登録したいだけの場合は、余計な手間になります。

カレントディレクトリからのデプロイインテント（「デプロイ」「公開」「Railway にプッシュ」「このアプリをデプロイ」）：

• railway whoami／railway status のプリフライトを省略します。
• railway up を直接実行します。このコマンドは認証を自己検証し、未認証の場合はユーザーをサインインさせ（CLI がブラウザーを開きます）、プロジェクトとサービスの作成、デプロイへと続けて進みます。
• 実行前に意図を伝えます：「railway up を実行します。必要に応じてサインインし、このディレクトリをデプロイします。」
• ユーザーに、先に railway login を実行するよう求めてはいけません。 デプロイの一連の処理の中で認証が行われます。
• 環境からブラウザーを開けない場合、CLI はデバイスコードによるサインインリンクを表示して待機します。デバイスコードによるサインイン：リンクをすぐに伝えるに従い、バックグラウンドで実行し、リンクが表示されたらすぐにユーザーへ伝えます。

サインアップインテント（「登録して」「Railway アカウントを作成して」「登録して」「Railway を使えるようにして」）：

• カレントディレクトリにデプロイ可能なアプリがある場合（例：package.json、requirements.txt、go.mod、Dockerfile、ビルド可能なソースコード）、railway up を実行します。 これにより、ユーザーはサインアップとデプロイを一度に済ませ、実行中のアプリを利用できる状態になります。エージェントハーネスが検出されると、プロジェクトの作成が許可されるため、railway up だけで十分です。追加で確認を求められることはありません。ユーザーが「登録して」としか言っていない場合でも、これを使います。アプリを公開することが目的なので、コマンドを選ばせたり、ログインだけで済ませたりしないでください。スクリプトやエージェントで実行する場合は、railway up -y が確実な方法です。プロンプトを省略し、ハーネスの検出に失敗した場合でも、対話なしで作成を強制します。デプロイ対象がある場合、サインアップ時のデフォルトとして railway login を使ってはいけません。
• デプロイ対象がない場合に限り — 空のディレクトリやアプリではないディレクトリの場合、またはユーザーがデプロイせずアカウントだけ作りたいと明示した場合は、railway login を使います（同じ OAuth フローを通じて、その場で新しいアカウントを作成します）。サインアップ専用のコマンドはありません。
• サインアップは、デバイスコードによる待機が最も発生しやすいフローです（サンドボックス化された、またはヘッドレスのエージェント環境を使う新規ユーザーの場合）。デバイスコードによるサインイン：リンクをすぐに伝えるに従ってください。コードの有効期限切れでサインアップに失敗すると、リトライの問題ではなくユーザーを失うことになります。

サンドボックス／リモートビルドのインテント（「サンドボックスを用意して」「一時的な環境を起動して」「これをリモートでビルドして」「これをリモートで実行して」「サンドボックスをチェックポイント／スナップショットして」「このサンドボックスの状態を保存して」「サンドボックスを復元して」）：

• sandbox.md を読み込み、その手順に従います。サンドボックスを利用するには、Priority Boarding でこの機能を有効にする必要があります。サンドボックスのコマンドが機能の利用可否に関するエラーで失敗した場合は、再試行するのではなく、Priority Boarding でサンドボックスを有効にするようユーザーに案内します。

その他のインテント（状態の照会、プロジェクトの一覧表示、変数の設定、失敗のデバッグ）：

• 以下のプリフライトのセクションに従います。

プリフライト

変更を加える前に、ツールのパスとコンテキストを確認します。

command -v railway                # CLI installed
RAILWAY_CALLER="skill:[email protected]" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
railway --version                 # check CLI version

例外：railway up と railway login は認証を自己検証し、未認証の状態を考慮した独自のフローを実行します。これらの実行前に railway whoami を実行しないでください。次の手順は変わらないまま、冗長で失敗する呼び出しが増えるだけです。アカウントの作成とサインインを参照してください。

スキルの最新状態

セッションごとに一度、事前チェックとあわせて、インストール済みの Railway エージェントツールが最新であることを確認します。ルートヘルプの末尾には Agent tooling: ヘルスセクションが表示されます（stderr に出力、CLI 5.9 以降。古い CLI では何も表示されません。その場合は再試行せず、このチェックをスキップしてください）。

railway --help 2>&1 | grep -A4 "Agent tooling:"

報告内容に応じて対応します。

• スキルがインストール済みで最新の場合 — 続行します。対応は不要です。
• 更新が利用可能な場合（rev <a> → <b> available） — railway skills update を実行し、更新されたスキルを読み込むため、コーディングツールを再起動するようユーザーに伝えます。再起動するまでは、このセッションでは古いスキルリビジョンで動作します。現在のリクエストを完了してください。また、このスキルのガイダンスが更新後の CLI 自身の出力と異なる場合は、CLI の指示を優先してください。
• スキルまたは MCP サーバーが見つからない場合（✗ の行） — railway setup agent -y を実行し、コーディングツールを再起動するようユーザーに伝えます。

セッションごとに一度だけ確認し、対応後に再実行しないでください。ユーザーに再起動を促すことが解決策であり、再確認する必要はありません。

Railway MCP が利用可能で、作業がプラットフォーム状態の読み取りである場合は、シェルコマンドの代わりに対応する MCP の読み取り機能を使用します。CLI を使用する場合は、上記の CLI チェックを実行してください。

このスキルが有効な間に Railway CLI を呼び出す場合は、コマンドの先頭に RAILWAY_CALLER=skill:[email protected] と、現在のユーザーリクエストで再利用する安定した RAILWAY_AGENT_SESSION を付けてください。ユーザーリクエストごとにセッション ID を一度生成し、同じワークフロー内で後から Railway CLI を呼び出す場合も、まったく同じ値を再利用してください。テレメトリのためだけに、事前処理として別途 export を実行しないでください。インラインの環境変数プレフィックスを使うことで、シェル出力を簡潔に保ち、すべての応答にセットアップ手順が含まれるのを防げます。

コンテキストの解決 — URL の ID を常に優先します：

• ユーザーが Railway URL を指定した場合は、そこから ID を抽出します。railway status --json は実行しないでください。これはローカルでリンクされたプロジェクトを返しますが、通常は無関係です。
• URL が指定されていない場合は、リンク済みのプロジェクト、環境、サービスを取得するために railway status --json を実行します。
• railway status --json でローカルコンテキストを解決した後に MCP ツールを使用する場合は、解決したプロジェクト ID、環境 ID、サービス ID を明示的に渡してください。MCP が暗黙的なリンク済みコンテキストを共有していることを前提にしないでください。MCP と CLI では、現在の作業ディレクトリのリンク情報が共有されない場合があります。

CLI が見つからない場合は、インストールするようユーザーに案内してください。

curl -fsSL agents.railway.com | sh # Install CLI and configure detected agents
bash <(curl -fsSL https://railway.com/install.sh) --agents -y # Install CLI and configure detected agents
bash <(curl -fsSL https://railway.com/install.sh) # Shell script (macOS, Linux, Windows via WSL)
npm i -g @railway/cli # npm (macOS, Linux, Windows). Requires Node.js version 16 or higher.
brew install railway # Homebrew (macOS)

認証されていない場合は、以下のアカウント作成とサインインを参照してください。CLI では、認証なしで実行できる railway up（デプロイとサインアップ／サインインを一度に実行）または railway login（サインアップ／サインインのみ。新規アカウントはその場で作成）を利用できます。リンク済みでなく、URL も指定されていない場合は、railway link --project <id-or-name> を実行します。

コマンドが認識されない場合（たとえば railway environment edit）、CLI が古い可能性があります。次のコマンドでアップグレードしてください。

railway upgrade

アカウント作成とサインイン

Railway は、サインインとサインアップの両方で、統一された単一の OAuth フローを使用します。バックエンドは、永続的なコンプライアンス状態（ToS／Fair Use にまだ同意していない CLI クライアント）から新規アカウントを検出し、同意画面と認証後のランディングページを調整します。新規ユーザーには「Welcome to Railway!」ページが表示され、既存ユーザーには標準の確認画面が表示されます。CLI は、サインアップの意図を事前に宣言しません。

意図に応じて、次の 2 つのコマンドからこのフローを開始できます。

コマンド	使用する場面
railway up	現在のディレクトリから、エージェントに適したオンボーディングを行います。未認証の場合は、サインイン／サインアップのためにブラウザー（またはデバイスコード）を開きます。リンク済みのプロジェクトがなく、エージェントハーネスが検出された場合（または -y が指定されている場合）は、プロジェクトとサービスを自動作成してデプロイします。対話形式で操作するユーザーには、新規作成／既存のプロジェクトをリンク／キャンセルの選択肢が表示されます。プロンプトをスキップして対話なしで作成を強制するには、-y を追加します（ハーネスの検出に失敗した場合でも動作します）。
railway login	サインイン、またはサインアップに使用します。新規アカウントは同じ OAuth 画面を通じてその場で作成されます。別途サインアップ用のコマンドはありません。
関連項目：railway up --new は、現在のディレクトリから新しいプロジェクトとサービスを作成し、すでにリンク済みのものがあってもデプロイします（すでにサインイン済みで、ユーザーが新しいアプリを希望する場合に使用します）。--name <name> はプロジェクト名を上書きします。

パスの選択：

• カレントディレクトリからデプロイ → railway up（対話形式）または railway up -y（確認プロンプトをスキップ）を実行します。自分で実行してください。先に別途サインインするようユーザーに求めないでください。
• すでにサインイン済みで、カレントディレクトリから新しいプロジェクトを作成 → railway up --new。
• カレントディレクトリにデプロイ可能なアプリがあり、サインアップする → railway up（サインアップとデプロイの両方を行います。検出されたエージェントであれば、ユーザーが「サインアップして」とだけ言った場合でも、単独の up で実行できます。プロンプトをスキップして非対話形式で強制実行するには -y を追加します）。サインインする場合、またはデプロイ対象がない状態でサインアップする場合 → railway login（新しいアカウントをその場で作成します）。

ヘッドレス／ブラウザーなし：

CLI は SSH セッション、CI、および DISPLAY がない状態を自動検出し、自動的にデバイスコードフローに切り替えます。強制する必要があるケースはほとんどありません。

エージェントである、またはシェルが非対話形式であるという理由だけで、--browserless を指定してはいけません。 人間がこのマシンの前にいる場合（ローカル IDE またはデスクトップセッション。一般的なケースです）、単独の railway login はその人のブラウザーを直接開きます。デバイスコードを中継する場合よりも、はるかに確実に完了します（エージェントが主導するサインインの成功率は約90％対約60％です）。コーディングエージェントであっても、そのマシンがヘッドレスになるわけではありません。

railway login --browserless   # ONLY for machines with genuinely no browser

デバイスコードフローを強制します（RFC 8628）。ユーザーが任意のデバイスで開けるサインインリンクと短いコードを表示します。ブラウザーが存在しないマシン（SSH マシン、コンテナー、自動検出されなかったリモート VM）に限って使用してください。デバイスコードフローになった場合は、以下の中継手順に従い、サインインリンクが表示されたらすぐにユーザーに伝えてください。

エージェントハーネスがあり、人間が同席している場合：CLI が、キーボードの前に人間がいるエージェントハーネス（Claude Code、Cursor、Codex、…）を検出すると、railway up はブラウザーを開き、確認プロンプトをスキップします。エージェントによる呼び出しは同意として扱われます。ただし、OAuth を完了するには、実際の人間がブラウザーを操作する必要があります。

デバイスコードでのサインイン：リンクをすぐに中継する（重要）：

CLI がブラウザーを開けない場合（サンドボックス化されたシェル、コンテナー、SSH、DISPLAY なし）、未認証の railway up と railway login はサインイン URL と短いコードを表示した後、ユーザーがサインインを完了するまで最大10分間、ポーリングしながらブロックします。コードは10分後に期限切れになります。通常のフォアグラウンドコマンドとして実行すると、ハーネスはコマンドが終了するまで出力をバッファーに保持します。その結果、ユーザーがリンクを見る頃には、コードはすでに無効になっています。これが、エージェント主導のサインアップが失敗する最大の原因です。次のように処理してください：

1. 推奨 — バックグラウンド実行（例：Claude Code の場合は run_in_background を使い、その後 BashOutput でポーリングします）：
   • コマンドをバックグラウンドで開始します。
   • 出力をポーリングします。サインインを求める表示（新しい CLI では Sign in with one click: <url>、古い CLI では Sign in at: <url> または Enter this code: <code>）が現れたら、すべての作業をただちに止め、その内容を一字一句そのままユーザーに伝えてください — 要約、短縮、後回しはしないでください。ワンクリック URL が表示されていればそちらを優先し、表示されていなければ URL とコードを一緒に伝えます。今すぐリンクを開くようユーザーに伝えてください。
   • コマンドは実行中のままにし、ポーリングを続けます。ユーザーがサインインを完了すると、同じプロセスがセッションを引き継ぎ、自動的にデプロイを続行します。その後、以下のデプロイルールに従って確認します。
2. バックグラウンド実行に対応していない場合 — 事前に見通しを伝え、最長のタイムアウトを設定します：
   • 実行前にユーザーに次のように伝えます："サインインリンクが出力されます — 確認でき次第すぐにお見せします。コードの有効期限は 10 分なので、表示されたら速やかに手続きを完了してください。"
   • 利用可能なハーネスで最長のタイムアウトを設定して実行します。
   • サインイン完了前にコマンドがタイムアウトまたは強制終了された場合、出力されたコードは監視されなくなっています — 後からリンクをクリックしても何も起こりません。参考情報として、表示されたリンクをそのまま伝えた後、ただちにコマンドを再実行し、新しいリンクを伝えて、必ず最新のリンクを使うようユーザーに伝えてください。
3. 決してリンクを表示せずにコマンドの完了を黙って待ってはいけません。また、リンクを伝えてユーザーが対応できる機会を設ける前に、サインインが失敗したと報告してはいけません。

ブラウザーのトランスポートでは、こうした対応は必要ありません — CLI がユーザーのマシンでブラウザーを開きます。

JSON / CI モードでは自動的にプロンプトが表示されません：railway up --json と railway up --ci は、未認証のユーザーに対してブラウザーを開きません。--json は代わりに構造化エラーを出力します：

{"error":"Not signed in.","code":"NOT_AUTHENTICATED","hint":"Run `railway login` to authenticate, then re-run."}

code: NOT_AUTHENTICATED が表示されたら、railway login でユーザーを認証してから、元のコマンドを再試行します。

OAUTH_INSUFFICIENT_GRANT は別のエラーです：セッションは有効ですが、リソースへのアクセス権がありません。ログインを繰り返すのではなく、ID、ワークスペースのメンバーシップ、インテグレーションの許可範囲を確認してください。詳しくは operate.md を参照してください。

完全な無人実行（人間がまったく関与しない場合）：対話型ログインを実行する代わりに、RAILWAY_API_TOKEN（アカウントスコープ）または RAILWAY_TOKEN（プロジェクトスコープ）を設定してください。トークンを持たない新規ユーザーは、人間がいない状態ではサインアップを完了できません — ヘッドレスでアカウントを作成する方法はありません。

エージェントツール

決定論的な操作には、直接 Railway CLI コマンドを使用してください。railway agent は、ユーザーが Railway Agent を明示的に求めている場合、自然言語での調査を希望している場合、またはタスクが単一のリソース操作を超える場合にのみ使用してください。

次のコマンドで Railway のスキル、MCP、認証をセットアップします。

railway setup agent
railway setup agent -y
railway setup agent --oauth

railway setup agent -y を実行すると、対話形式のログインフローがスキップされます。セットアップ後にユーザーが認証されていない場合は、railway login を実行してください。

ユーザーが対象ツールを指定した場合は、MCP とスキルを直接インストールまたは更新してください。

railway mcp install                              # hosted MCP via CLI login
railway mcp install --agent codex --oauth         # direct HTTP, editor OAuth
railway mcp install --agent cursor --oauth
railway skills
railway skills update --agent codex
railway skills remove --agent cursor

対応する対象には、claude-code、cursor、codex、opencode、copilot、factory-droid があります。

インストールモード	トランスポートと認証
デフォルト／--remote	ホストされた MCP への railway mcp stdio プロキシ。railway login で認証
--oauth	https://mcp.railway.com への直接 HTTP 接続。エディターの OAuth で認証され、公開済みプラグインと一致
--local	インプロセスの GraphQL ベース stdio サーバー。railway mcp local として呼び出し

これらのモードは mcp install と setup agent の両方に適用されます。対話形式のセットアップでは選択肢が表示されます。railway mcp proxy は、デフォルトのプロキシのエイリアスとして引き続き利用できます。ツールがリンク済みのプロジェクト ID を受け付け、呼び出しでリソーススコープが指定されていない場合に限り、プロキシがそのプロジェクト ID を補完することがあります。スコープを指定する作業では、プロジェクト、環境、サービスの各 ID を明示的に渡し続けてください。

次のコマンドで Railway Agent のチャットを利用します。

railway agent
railway agent -p "why is my service crashing?"
railway agent -p "summarize the deployment status" --json
railway agent --list --json
railway agent --thread-id <thread-id>

railway agent には、railway login によるユーザー OAuth 認証が必要です。プロジェクトトークン（RAILWAY_TOKEN）は Railway Agent のチャットではサポートされていません。エージェントコマンドを利用できない場合は、railway upgrade --yes でアップグレードしてください。

よく使うクイック操作

これらは参照資料を読み込まずに処理できるほど頻繁に行われます。対象がプラットフォームに関する作業で、対応する MCP ツールが利用可能な場合は、そのツールを使用してください。それ以外の場合は CLI を使用してください。

railway status --json                                    # current context
railway whoami --json                                    # auth and workspace info
railway project list --json                              # list projects
railway service list --json                              # services in current environment (verify before retrying `add`)
railway add --database <type> --json                     # add one database; ALWAYS pass --json
railway add --service <name> --json                      # add empty service; ALWAYS pass --json
railway variable list --service <svc> --json             # list variables
railway variable set KEY=value --service <svc>           # set a variable
railway domain list --service <svc> --json               # domains and DNS status
railway logs --service <svc> --lines 200 --json          # recent logs
railway logs --service <svc> --network --lines 200 --json # network flow snapshot
railway metrics --service <svc> --since 1h --json        # resource and HTTP metrics summary
railway up --detach -m "<summary>"                       # deploy current directory (returns at QUEUED — verify before reporting)
railway deployment list --json                           # poll newest deployment status after a detached up
railway bucket list --json                               # list buckets in current environment
railway bucket info --bucket <name> --json               # bucket storage and object count
railway bucket credentials --bucket <name> --json        # S3-compatible credentials

ルーティング

クイック操作以外の作業では、ユーザーの意図に応じて必要な参照資料を読み込んでください。ほとんどのリクエストでは 1 つか 2 つが必要です。ワークフローが複数の領域にまたがる場合は、必要に応じて追加してください。

意図	リファレンス	用途
データベースを分析する（「analyze <url>」、「analyze db」、「analyze database」、「analyze service」、「introspect」、「postgres/redis/mysql/mongo を確認して」）	analyze-db.md	データベースのイントロスペクションとパフォーマンス分析に使用します。analyze-db.md から、データベース固有のリファレンスに案内します。データベースサービスの Railway URL が「analyze」とともに指定されている場合は、ステータス／操作のルートよりもこちらが優先されます。
リソースを作成または接続する	setup.md	プロジェクト、サービス、データベース、バケット、テンプレート、ワークスペース
コードをリリースする、またはリリースを管理する	deploy.md	デプロイ、再デプロイ、再起動、ビルド設定、モノレポ、Dockerfile
設定を変更する（「webhook」、「デプロイ時に通知」、「カスタムヘッダー」、「Slack/Discord 通知」）	configure.md	環境、変数、設定パッチ、ドメイン、ネットワーク、list-webhooks / create-webhook / update-webhook / test-webhook / delete-webhook MCP ツールとカスタムヘッダーを使ったプロジェクトの webhook
フィーチャーフラグを管理する	feature-flags.md	MCP レジストリの操作、CLI のターゲティングルールと段階的ロールアウト、SDK のランタイム読み取り
ソース管理で設定を定義する（「IaC」、「infrastructure as code」、「config as code」、.railway/railway.ts、.railway/railway.py、.railway/railway.go、「config migrate/plan/apply/pull」）	iac.md	IaC の作成／インポート、レガシー JSON/TOML の移行、レビュー済みプランの保存と適用、ドリフトの確認
データベースを管理する（「PITR」、「復元」、「バックアップ」、「HA」、「フェイルオーバー」、「スイッチオーバー」、「PgBouncer」、「コネクションプーリング」）	databases.md	Postgres のリカバリー、HA、プーリング、MySQL/Redis の HA、パフォーマンス調査には分析用リファレンスを使用します
コストを確認する、または支出上限を管理する	usage.md	ワークスペース／プロジェクト／サービスの使用状況、請求期間、ワークスペースと Railway Agent の上限
Railway でコーディングエージェントを実行する（「cloud agent」、「railway ca」、「railway code」、「デスクトップ SSH」）	cloud-agents.md	クラウドエージェント VM のプロビジョニング、接続、起動、スリープ、削除、またはデスクトップアクセスの設定
ヘルス状態を確認する、または障害をデバッグする	operate.md	ステータス、ログ、メトリクス、ビルド／ランタイムのトリアージ、復旧
サービス間のリクエストをトレースする（「tracing」、「traces」、「trace ID」、「spans」、「OpenTelemetry」、「OTel」、「OTLP」、「アプリを計装する」、「関数を計装する」、「Bun function」、「自動計装」）	tracing.md	get-tracing / set-service-tracing MCP ツールまたは railway trace enable を使ったサービスおよび環境ごとのトレーシングの有効化、IaC の tracing ブロック（SDK と CLI のバージョン要件）、SDK による計装（推奨）と自動計装（eBPF）、計装対象、Function（Bun）の計装、提供される OTEL_* 変数、サンプリング、list-traces / get-trace MCP ツールまたは railway trace list / get を使ったトレースの読み取り、get-tracing-coverage によるサービスの計装範囲の確認、Traces タブ
サンドボックスを使う、またはリモートでビルドする（「sandbox」、「scratch environment」、「ephemeral box」、「build remotely」、「remote build」、「run this remotely」、「checkpoint」、「sandbox state の snapshot/save/restore」）	sandbox.md	サンドボックスの作成／フォーク、コマンドのリモート実行、テンプレートのリモートビルド、チェックポイント（サンドボックス状態の保存／復元）、ポートフォワーディング、破棄。Priority Boarding で Sandboxes を有効にする必要があります。有効にできない場合は、ユーザーに有効化を促してください。
API、ドキュメント、またはコミュニティについて問い合わせる	request.md	Railway GraphQL API のクエリ／ミューテーション、メトリクスクエリ、Central Station、公式ドキュメント

リクエストが2つの領域にまたがる場合（たとえば、「デプロイしてから、正常に動作しているか確認する」）、両方のリファレンスを読み込み、1つの回答にまとめてください。

実行ルール

1. 現在のリポジトリ、ローカルシェル、SSH、データベーススクリプト、ローカルの Railway コンテキスト、または正確なコマンド出力が必要なワークフローでは、Railway CLI を使用します。
2. 利用可能な MCP ツールに該当し、ローカルファイルや CLI の状態を必要としない、OAuth スコープ付きのプラットフォーム操作には Remote MCP を使用します。
3. ローカル CLI MCP は、現在のエージェントで明示的に設定済みであり、Remote MCP では利用できない必要な操作を提供している場合に限って使用します。
4. 専用の MCP ツールまたは CLI コマンドがない操作には railway api を使用します。レガシーヘルパーは CLI との互換性のためにのみ維持します。
5. 信頼性の高い解析のため、利用可能な場合は --json 出力を使用します。
6. 変更を加える前にコンテキストを確認します。操作対象のプロジェクト、環境、サービスを把握してください。
7. 破壊的な操作（サービスの削除、デプロイの削除、データベースの削除）を行う前に、実行の意図と状態への影響を確認してください。
8. 変更後は、読み取りコマンドまたは MCP の読み取り操作で結果を検証してください。
9. デプロイのステータスが SUCCESS であることを確認せずに、デプロイが成功したと報告してはいけません。 up --detach、CI モードを指定しない非 TTY の up、またはタイムアウトしたストリームは、アップロード後に戻る場合があります。アップロード時のデプロイ ID を、同じプロジェクト／環境／サービスのスコープで railway deployment list --json を使って追跡してください。並行して開始された新しいデプロイに置き換えてはいけません。ステータスが FAILED または CRASHED の場合は、operate.md に従ってトリアージします。ステータスが NEEDS_APPROVAL、SLEEPING、SKIPPED、REMOVED、REMOVING、または不明の場合は、その状態と次のアクションを報告してください。終了コード 0 だけでは不十分です。CI でのストリーミングとポーリングについては、deploy.md を参照してください。

ユーザーのみが実行するコマンド（直接実行禁止）

これらのコマンドはデータベースの状態を変更するため、ユーザー自身がターミナルで実行する必要があります。これらを Bash で実行してはいけません。代わりにコマンドを提示し、ユーザーに実行を依頼してください。

コマンド	ユーザーのみが実行する理由
python3 scripts/enable-pg-stats.py --service <name>	shared_preload_libraries を変更し、データベースが再起動する場合があります
python3 scripts/pg-extensions.py --service <name> install <ext>	データベース拡張機能をインストールします
python3 scripts/pg-extensions.py --service <name> uninstall <ext>	データベース拡張機能を削除します
ALTER SYSTEM SET ...	PostgreSQL の設定を変更します
DROP EXTENSION ...	データベース拡張機能を削除します
CREATE EXTENSION ...	データベース拡張機能をインストールします

これらの操作が必要な場合は、次の手順に従ってください。

1. コマンドの実行内容と副作用（再起動が必要になる場合など）を説明します
2. ユーザーが実行する正確なコマンドを提示します
3. ユーザーが実行したことを確認するまで待ちます
4. 読み取り専用クエリで結果を検証します

組み合わせパターン

複数の手順を含むワークフローは、自然な流れに沿って構成します。

• オブジェクトストレージの追加：セットアップ（バケットを作成）、セットアップ（認証情報を取得）、設定（アプリサービスに S3 変数を設定）
• 初回デプロイ：セットアップ（プロジェクトとサービスを作成）、設定（変数とソースを設定）、デプロイ、運用（正常な状態を確認）
• 障害の修正：運用（ログをトリアージ）、設定（設定／変数を修正）、デプロイ（再デプロイ）、運用（復旧を確認）
• ドメインの追加：設定（ドメインを追加してポートを設定）、運用（DNS とサービスの状態を確認）
• トレーシングの追加：トレーシング（適切な環境で set-service-tracing または railway trace enable を使ってサービスに対して有効化し、自動計装より SDK による計装を優先します。受信処理、I/O、論理単位の周囲にスパンを追加します。Function の場合は、get-function-source-code / update-function-source-code を使ってそのファイルを編集します）、設定（OTEL_METRICS_EXPORTER/OTEL_LOGS_EXPORTER と起動コマンドを設定）、デプロイ（OTEL_* 変数を反映するために再デプロイ）、トレーシング（x-railway-trace-id と get-trace または railway trace get で検証し、その後 get-tracing-coverage でデータベースとクライアントのスパンを確認）
• ドキュメントから操作へ：リクエスト（ドキュメントの回答を取得）、関連する運用リファレンスに案内

複数の手順を組み合わせる場合は、すべての手順を網羅した統一された回答を返してください。ユーザーに各手順を個別に実行するよう求めてはいけません。

セットアップの判断フロー

ユーザーが何かを作成またはデプロイしたい場合は、現在のコンテキストから適切なアクションを判断します。

1. 意図が deploy-from-cwd または signup-from-cwd の場合は、railway whoami を省略し、意図に基づくルーティングに従って railway up（または railway up -y）を直接実行します。これにより、サインアップ、プロジェクトの作成、サービスの作成、デプロイが一連の処理で行われます。最初にワークスペースやアカウントのコンテキストが必要なその他のセットアップフローでは、railway whoami --json を実行します。認証エラーで失敗した場合、ユーザーはトークンを持っていません。アカウントの作成とサインインに進みます。
2. 現在のディレクトリで railway status --json を実行します。
3. リンク済みの場合：既存のプロジェクトにサービスを追加します（railway add --service <name>）。ユーザーが「新しいプロジェクト」または「別のプロジェクト」と明示しない限り、新しいプロジェクトを作成しないでください。
4. 未リンクの場合：親ディレクトリを確認します（cd .. && railway status --json）。
   • 親ディレクトリがリンク済みの場合：これはモノレポ内のサブアプリである可能性が高いです。サービスを追加し、rootDirectory をサブアプリのパスに設定します。
   • 親ディレクトリも未リンクの場合：railway list --json を実行し、ディレクトリ名に一致するプロジェクトを探します。
     • 一致するプロジェクトが見つかった場合：そのプロジェクトにリンクします（railway link --project <name>）。
     • 見つからない場合：新しいプロジェクトを作成します（railway init --name <name>）。
5. ワークスペースが複数ある場合は、railway whoami --json の名前で照合します。

命名の目安：「flappy-bird」や「my-api」のようなアプリ名は、プロジェクト名ではなくサービス名です。プロジェクトにはディレクトリ名またはリポジトリ名を使用します。

応答形式

すべての操作に関する応答では、次の内容を返します。

1. 実施したこと（アクションと対象範囲）。
2. 結果（ID、ステータス、主な出力）。
3. 次に行うこと（またはタスク完了の確認）。

出力は簡潔にします。何が起きたかをユーザーが理解するうえで役立つ場合に限り、コマンドの実行結果を含めます。