railway-new

新規プロジェクト / サービス / データベース

Railway のプロジェクト、サービス、データベースを適切な設定で作成します。

使用するタイミング

• ユーザーが「deploy to railway」と言ったとき（リンク済みならサービスを追加、未リンクなら init）
• ユーザーが「create a railway project」「init」「new project」と言ったとき（明示的な新規プロジェクト）
• ユーザーが「link to railway」「connect to railway」と言ったとき
• ユーザーが「create a service」「add a backend」「new api service」と言ったとき
• ユーザーが「create a vite app」「create a react website」「make a python api」と言ったとき
• ユーザーが「deploy from github.com/user/repo」「create service from this repo」と言ったとき
• ユーザーが「add postgres」「add a database」「add redis」「add mysql」「add mongo」と言ったとき
• ユーザーが「connect to postgres」「wire up the database」「connect my api to redis」と言ったとき
• ユーザーが「add postgres and connect to the server」と言ったとき
• コードと Railway サービスをまとめてセットアップするとき

前提条件

CLI がインストールされているか確認します:

command -v railway

インストールされていない場合:

Install Railway CLI:

npm install -g @railway/cli

or

brew install railway

認証済みか確認します:

railway whoami --json

認証されていない場合:

railway login を実行して認証してください。

判断フロー

railway status --json (in current dir)
     │
┌────┴────┐
Linked    Not Linked
  │            │
  │       Check parent: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Parent      Not linked
  │    Linked      anywhere
  │       │            │
  │   Add service   railway list
  │   Set rootDir      │
  │   Deploy       ┌───┴───┐
  │       │      Match?  No match
  │       │        │        │
  │       │      Link    Init new
  └───────┴────────┴────────┘
           │
    User wants service?
           │
     ┌─────┴─────┐
    Yes         No
     │           │
Scaffold code   Done
     │
railway add --service
     │
Configure if needed
     │
Ready to deploy

現在の状態を確認する

railway status --json

• リンク済みの場合: 既存のプロジェクトにサービスを追加します（下記を参照）
• 未リンクの場合: 親ディレクトリがリンクされているか確認します（下記を参照）

すでにリンクされている場合

デフォルトの動作: 「deploy to railway」＝リンク済みプロジェクトにサービスを追加する、です。

ユーザーが次のように明示的に指示しない限り、新しいプロジェクトは作成しないでください:

• 「new project」「create a project」「init a project」
• 「separate project」「different project」

「flappy-bird」や「my-api」のようなアプリ名はプロジェクト名ではなく、サービス名です。

User: "create a vite app called foo and deploy to railway"
Project: Already linked to "my-project"

WRONG: railway init -n foo
RIGHT: railway add --service foo

親ディレクトリのリンク

Railway CLI はディレクトリツリーを上にたどって、リンクされたプロジェクトを探します。サブディレクトリにいる場合:

cd .. && railway status --json

親がリンクされている場合、サブディレクトリを init/link する必要はありません。代わりに次を行います:

1. サービスを作成: railway add --service <name>
2. 環境スキルを使って rootDirectory をサブディレクトリのパスに設定
3. ルートからデプロイ: railway up

親がリンクされていない場合は、init または link のフローに進みます。

Init と Link の判断

すでにリンクされている場合はこのセクションをスキップし、代わりにサービスを追加してください。

プロジェクトがリンクされていない（直接も親経由も）場合にのみ、このセクションを使用します。

ユーザーのプロジェクトを確認する

出力が大きくなることがあるため、サブエージェントで実行し、次の情報だけを抽出してください:

• プロジェクトの id と name
• ワークスペースの id と name

railway list --json

判断ロジック

1. ユーザーが「new project」と明示的に言った → railway init を使用
2. ユーザーが既存のプロジェクト名を指定した → railway link を使用
3. ディレクトリ名が既存のプロジェクトと一致する → 既存にリンクするか、新規作成するかを確認
4. 一致するプロジェクトがない → railway init を使用
5. 曖昧な場合 → ユーザーに確認

新規プロジェクトを作成する

railway init -n <name>

オプション:

• -n, --name - プロジェクト名（非対話モードで省略した場合は自動生成）
• -w, --workspace - ワークスペース名または ID（ワークスペースが複数ある場合は必須）

複数のワークスペース

ユーザーが複数のワークスペースを持っている場合、railway init には --workspace フラグが必要です。

ワークスペース ID は次のコマンドで取得できます:

railway whoami --json

workspaces 配列には、各ワークスペースの { id, name } が含まれます。

ユーザーの入力からワークスペースを推定する: ユーザーが「deploy into xxx workspace」や「create project in my-team」と言った場合は、名前を workspaces 配列と照合し、対応する ID を使用してください:

# User says: "create a project in my personal workspace"
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# Use the matched ID: railway init -n myapp --workspace <matched-id>

既存のプロジェクトをリンクする

railway link -p <project>

オプション:

• -p, --project - プロジェクト名または ID
• -e, --environment - 環境（デフォルト: production）
• -s, --service - リンクするサービス
• -t, --team - チーム / ワークスペース

Create Service

プロジェクトをリンクした後、サービスを作成します:

railway add --service <name>

GitHub リポジトリソースの場合: 空のサービスを作成してから、railway-environment スキルを呼び出し、ステージング変更 API を使ってソースを設定します。railway add --repo は使用しないでください。GitHub アプリ連携が必要で、多くの場合失敗します。

フロー:

1. railway add --service my-api
2. railway-environment スキルを呼び出し、source.repo と source.branch を設定する
3. 変更を適用してデプロイをトリガーする

プロジェクトタイプ別の設定

ビルド設定については railpack.md を参照してください。 モノレポのパターンについては monorepo.md を参照してください。

静的サイト (Vite、CRA、Astro static):

• Railpack は一般的な出力ディレクトリ (dist、build) を自動検出します
• 標準以外の出力ディレクトリを使用する場合: railway-environment スキルを呼び出し、RAILPACK_STATIC_FILE_ROOT を設定する
• railway variables CLI は使用しないでください。必ず environment スキルを使用してください

Node.js SSR (Next.js、Nuxt、Express):

• package.json に start スクリプトが存在することを確認する
• カスタムの起動設定が必要な場合: railway-environment スキルを呼び出し、startCommand を設定する

Python (FastAPI、Django、Flask):

• requirements.txt または pyproject.toml が存在することを確認する
• Railpack が自動検出するため、通常は設定不要です

Go:

• go.mod が存在することを確認する
• 自動検出されるため、設定は不要です

モノレポの設定

重要な判断: ルートディレクトリを指定するか、カスタムコマンドを使うか。

分離型モノレポ (アプリ同士がコードを共有しない):

• Root Directory にアプリのサブディレクトリを設定する (例: /frontend)
• ビルド時には、そのディレクトリのコードのみが利用可能になります

共有型モノレポ (TypeScript ワークスペース、共有パッケージ):

• Root Directory は設定しないでください
• カスタムのビルド/起動コマンドを設定し、パッケージをフィルタリングする:
  • pnpm: pnpm --filter <package> build
  • npm: npm run build --workspace=packages/<package>
  • yarn: yarn workspace <package> build
  • Turborepo: turbo run build --filter=<package>
• 不要な再ビルドを防ぐため、ウォッチパスを設定する

詳細なパターンについては monorepo.md を参照してください。

プロジェクトセットアップのガイダンス

Railway との互換性を確保するため、コードベースを分析します。

コードベースの分析

既存のプロジェクトファイルを確認します:

• package.json → Node.js プロジェクト
• requirements.txt、pyproject.toml → Python プロジェクト
• go.mod → Go プロジェクト
• Cargo.toml → Rust プロジェクト
• index.html → 静的サイト
• なし → スキャフォールディングのガイドを提示する

モノレポの検出:

• pnpm-workspace.yaml → pnpm ワークスペース (共有型モノレポ)
• workspaces フィールドを持つ package.json → npm/yarn ワークスペース (共有型モノレポ)
• turbo.json → Turborepo (共有型モノレポ)
• 複数のサブディレクトリにそれぞれ package.json があり、ワークスペース設定がない → 分離型モノレポ

スキャフォールディングのヒント

コードが存在しない場合は、railpack.md の最小限のパターンを提案してください:

静的サイト:

ルートディレクトリに index.html ファイルを作成してください。

Vite React:

npm create vite@latest . -- --template react

Astro:

npm create astro@latest

Python FastAPI:

FastAPI アプリを含む main.py と、依存関係を記載した requirements.txt を作成してください。

Go:

PORT 環境変数で待ち受ける HTTP サーバーを含む main.go を作成してください。

データベース

Postgres、Redis、MySQL、MongoDB などのデータベースを追加する場合は、railway-railway-database スキルを使用してください。

railway-railway-database スキルは以下を扱います:

• データベースサービスの作成
• 接続変数の参照
• サービスとデータベースの接続

組み合わせ

• サービス作成後: railway-deploy スキルを使用してコードをプッシュする
• 詳細な設定: railway-environment スキルを使用する (buildCommand、startCommand)
• ドメイン: railway-domain スキルを使用する
• ステータス確認: railway-status スキルを使用する
• サービス操作 (名前変更、削除、ステータス): railway-service スキルを使用する

エラー処理

CLI がインストールされていない

Railway CLI not installed. Install with:
  npm install -g @railway/cli
or
  brew install railway

認証されていない

Not logged in to Railway. Run: railway login

ワークスペースがない

No workspaces found. Create one at railway.com or verify authentication.

プロジェクト名が使用済み

Project name already exists. Either:
- Link to existing: railway link -p <name>
- Use different name: railway init -n <other-name>

サービス名が使用済み

Service name already exists in this project. Use a different name:
  railway add --service <other-name>

例

HTML 静的サイトの作成

User: "create a simple html site and deploy to railway"

1. Check status → not linked
2. railway init -n my-site
3. Guide: create index.html
4. railway add --service my-site
5. No config needed (index.html in root auto-detected)
6. Use deploy skill: railway up
7. Use domain skill for public URL

Vite React サービスの作成

User: "create a vite react service"

1. Check status → linked (or init/link first)
2. Scaffold: npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. No config needed (Vite dist output auto-detected)
5. Use deploy skill: railway up

Python API をプロジェクトに追加

User: "add a python api to my project"

1. Check status → linked
2. Guide: create main.py with FastAPI, requirements.txt
3. railway add --service api
4. No config needed (FastAPI auto-detected)
5. Use deploy skill

サービスをリンクして追加

User: "connect to my backend project and add a worker service"

1. railway list --json → find "backend"
2. railway link -p backend
3. railway add --service worker
4. Guide setup based on worker type

Railway にデプロイ（あいまいなケース）

User: "deploy to railway"

1. railway status → not linked
2. railway list → has projects
3. Directory is "my-app", found project "my-app"
4. Ask: "Found existing project 'my-app'. Link to it or create new?"
5. User: "link"
6. railway link -p my-app
7. Ask: "Create a service for this code?"

分離されたモノレポにサービスを追加

User: "create a static site in the frontend directory"

1. Check: /frontend has its own package.json, no workspace config
2. This is isolated monorepo → use root directory
3. railway add --service frontend
4. Invoke environment skill to set rootDirectory: /frontend
5. Set watch paths: /frontend/**

TypeScript モノレポにサービスを追加

User: "add a new api package to this turborepo"

1. Check: turbo.json exists, pnpm-workspace.yaml exists
2. This is shared monorepo → use custom commands, NOT root directory
3. Guide: create packages/api with package.json
4. railway add --service api
5. Invoke environment skill to set buildCommand and startCommand (do NOT set rootDirectory)
6. Set watch paths: /packages/api/**, /packages/shared/**

既存の pnpm ワークスペースパッケージをデプロイ

User: "deploy the backend package to railway"

1. Check: pnpm-workspace.yaml exists → shared monorepo
2. railway add --service backend
3. Invoke environment skill to set buildCommand and startCommand
4. Set watch paths for backend + any shared deps

リンクされたプロジェクトのサブディレクトリをデプロイ

User: "create a vite app in my-app directory and deploy to railway"
CWD: ~/projects/my-project/my-app (parent already linked to "my-project")

1. Check status in my-app → not linked
2. Check parent: cd .. && railway status → IS linked to "my-project"
3. DON'T init/link the subdirectory
4. Scaffold: bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. Invoke environment skill to set rootDirectory: /my-app
8. Deploy from root: railway up