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 - チーム / ワークスペース

サービスの作成

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

railway add --service <name>

GitHub リポジトリをソースにする場合：空のサービスを作成してから、environment スキルを呼び出して staged changes API 経由でソースを設定します。railway add --repo は使用しないでください。GitHub アプリとの連携が必要で、失敗することがよくあります。

手順：

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

プロジェクトの種類に応じた設定

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

静的サイト（Vite、CRA、Astro static）：

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

Node.js SSR（Next.js、Nuxt、Express）：

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

Python（FastAPI、Django、Flask）：

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

Go：

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

モノレポの設定

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

分離型モノレポ（アプリ間でコードを共有しない）：

• ルートディレクトリをアプリのサブディレクトリ（例：/frontend）に設定します
• ビルド時に利用できるのは、そのディレクトリ内のコードのみです

共有型モノレポ（TypeScript ワークスペース、共有パッケージ）：

• ルートディレクトリを設定しないでください
• パッケージを絞り込むカスタムビルド／起動コマンドを設定します：
  • 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）を追加するには、database スキルを使用します。

database スキルでは、次の操作を行います：

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

組み合わせて使う

• サービス作成後：コードをプッシュするには deploy スキルを使用します
• 高度な設定の場合：environment スキル（buildCommand、startCommand）を使用します
• ドメインの場合：domain スキルを使用します
• ステータス確認の場合：status スキルを使用します
• サービスの操作（名前変更、削除、ステータス確認）の場合：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