create-railcode-agent

Railcode エージェントの作成

最初に更新

Railcode エージェントや CLI に関する質問に回答する前、または railcode コマンドを実行する前に、インストール済みの Railcode スキルと CLI を更新し、npm の公開バージョンを確認してください。

npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version

スキルが変更された場合は、このファイルを先頭から読み直してください。npm に接続できない場合は、最新バージョンを確認できなかったと伝え、このガイダンスが最新であると主張しないでください。このバージョンは、公開済みの Railcode CLI 0.1.28 を基準に確認されています。エージェントへの入力は自由形式であり、その契約は system プロンプトで定義されます。バックエンドではマニフェストのツールと制限が検証されるため、保存時の検証がこのスナップショットより優先されます。

0.1.28 以降、CLI はメジャーバージョンの範囲内で自動更新されます。ただし、対話型ターミナルでのみ実行されます。エージェントによるセッションは非対話型のため、最新の状態だと想定せず、上記の npm install -g railcode@latest を引き続き明示的に実行してください。

Railcode へのフィードバックを報告する

Railcode で意義のある作業を終えた後、具体的な製品フィードバック（バグ、使いづらさ、提案、または特にうまく機能した点）がある場合は、非公開の railcode agent-feedback コマンドを使用してください。具体的な指摘ごとに 1 回送信してください。タスク、期待した動作、実際の動作、および回避策を簡潔に記述し、認証情報、顧客の非公開データ、ソースファイル、会話の記録は含めないでください。

railcode agent-feedback --message "Deploy failed with an unclear error; expected the missing field to be named." \
  --category friction --command "deploy" --context "Static app deploy; corrected the manifest to unblock."

準備済みのレポートには --file <path> を使用するか、--message の代わりに標準入力からテキストを渡してください。メッセージは 10,000 文字まで、--context は任意で 5,000 文字までです。カテゴリは bug、friction、suggestion、praise、other（デフォルト）です。任意で --agent を使ってアシスタント／ツール名（例：Codex や Claude Code）を、--model を使ってモデル名を、わかる場合に自己申告できます。これらは自己申告であり、不正確な場合があります。不明な値は推測せず、省略してください。これらのフィールドと --command は、それぞれ 200 文字までです。

CLI はそのバージョン、OS プラットフォーム、CPU アーキテクチャ、Node のバージョンを添付します。バックエンドはレポートを PostHog 内のログイン済みユーザーおよび組織に紐付けます。既存のログインが必要ですが、アプリのディレクトリ外でも使用できます。Feedback accepted. はベストエフォートで受理されたことを意味し、保存が確認されたことを意味するものではありません。報告に失敗した場合は、再試行を繰り返したり、フィードバック送信だけを目的にログインしたりせず、元のタスクを続行してください。

このコマンドは意図的に CLI のヘルプには記載されておらず、CLI 0.3.3 以降が必要です。このフィードバックに関するガイダンスは、CLI 0.3.3 のソースを基に検証されています。古い CLI では Unknown command が返される場合があります。その場合は使用できないものとして扱ってください。

リクエストを Railcode に対応付ける

マニフェストを作成する前に、この表を参照してください。リクエストで外部の製品またはデータソースが指定されている場合、利用可能なものを判断する前に、必ずデータ接続／保存済みクエリとコネクター（共有されているもの、または誰かがリンクして所有しているアカウントのもの）を確認してください。詳しい確認コマンドはスコープ設定の手順に記載されています。

ファイルに関する厳格な境界： AI がファイルを読み取り、理解、抽出、要約、変換、または生成する必要がある場合は、tools.app_files とそのサンドボックスを備えた管理対象エージェントを使用してください。付属アプリではファイルのアップロード、保存、一覧表示、ダウンロード、表示ができますが、ページ内の llm.generate()／llm.stream() でファイルの内容、ファイル URL、ファイル由来のペイロードを処理したり、代替手段としてファイル成果物を生成したりしてはいけません。永続化する結果は、tools.app_data_write を通じて公開してください。

ユーザーの依頼	使用する Railcode の機能
「データベースから会社の指標／注文／顧客を分析する」	tools.saved_queries（デフォルト）。直接 SQL の実行が明示的に依頼された場合に限り、tools.adhoc_sql を使用します
「チームで共有している Stripe、CRM、その他の SaaS アカウントを使う」	tools.connectors と tools.docs。組織管理のコネクターに認証情報が保持されています
「自分で接続した Gmail、Slack、その他のアカウントを使う」	同じ tools.connectors を使い、その人がリンクして所有する行を指定します（railcode connector link gmail → gmail-jp）。エージェントの作成者がそのコネクターを所有しているか、共有されている必要があります。認証情報はその行に属するため、組織エージェントや cron でも機能します
「Railcode に標準搭載されていない製品に自分のアカウントを接続する」	railcode connector add-mcp <name> <https-url> を実行して、個人が所有するコネクターとしてリモート MCP サーバーを追加し、他の行と同じように tools.connectors で指定します
「各自が自分自身として操作する（自分の会議、自分の受信トレイ）」	エージェントではありません。 ユーザーごとのコネクターは呼び出し元のアカウントで動作しますが、エージェントには呼び出し元がいないため、マニフェストは拒否されます。Railcode アプリ（$create-railcode-app）を作成するか、1 人が所有するコネクターを指定して、エージェントがその人として動作することを受け入れてください
「Railcode アプリ内でユーザーが管理するレコードを読み取る」	tools.app_data。通常はコンパニオンアプリと併用します
「AI でファイルを読み取る、抽出する、要約する、変換する、または生成する」	tools.app_files とサンドボックスを備えたマネージドエージェント。コンパニオンアプリの llm は決して使用しないでください
「この Word 文書／DOCX を編集し、ファイルとして保持する」	マネージドエージェント＋コンパニオンアプリ：アプリでソースファイルと出力ファイルを保存・管理します。tools.app_files を宣言して DOCX を読み込み、tools.app_data_write を宣言して編集した文書を公開します
「PowerPoint／PPTX のスライドデッキを作成または修正する」	マネージドエージェント＋コンパニオンアプリ：アプリでテンプレート、入力、生成したスライドデッキを管理します。サンドボックスで PPTX を作成／編集し、publish_artifact_to_app で返します
「PDF のレポート、フォーム、または文書を作成する」	マネージドエージェント＋コンパニオンアプリ：アプリで入力とダウンロード可能な出力を管理します。サンドボックスで PDF を生成・検証してから、tools.app_data_write を通じて公開します
「この Excel／XLSX ブックを分析する」	マネージドエージェント＋コンパニオンアプリ：アプリでブックと分析結果を保存します。tools.app_files を通じて読み込み、サンドボックスで解析／分析し、tools.app_data_write を通じて永続的な結果を公開します
「結果を書き込む、または成果物をアプリに公開する」	tools.app_data_write（app_kv_*／publish_artifact_to_app）
「実行間で状態を保持する」	tools.agent_kv。人が状態を閲覧または編集する必要がある場合は、代わりにアプリのストレージを使用します
「ファイルを解析する、文書を作成する、またはコードを実行する」	マネージドエージェントのサンドボックスと tools.app_files を使用します。永続的な出力は tools.app_data_write でアプリに公開します
「システムからレポートをメール送信する」	tools.email。所有者自身のメールボックスから送信する必要がある場合は、所有者がリンクした Gmail コネクターを tools.connectors で指定します
「毎朝実行する、Slack から実行する、またはブラウザーを閉じた後に実行する」	マネージドエージェントと cron スケジュール、または組み込みの Slack 呼び出し経路を使用します
「入力をアップロードしたり、実行を開始したり、結果を確認したりする UI をユーザーに提供する」	ワーカーから agents.start() を呼び出すコンパニオン Railcode アプリ（コンパニオンアプリを参照）
「任意の Web サイト／API を呼び出す」	まず既存のコネクターを探します（railcode connector list）。なければ、コネクターの追加（connector catalog／link／add-mcp／管理者の connector create）またはインポート経路を提案します。マネージドエージェントはオープンウェブからデータを取得できません

サンドボックス機能

デプロイでサンドボックスを設定している場合、管理対象エージェントは実行ごとにコードサンドボックスで実行されます。サンドボックスを要求するためのマニフェストキーやエージェントごとの切り替え設定はありません。サンドボックスはシェルツールとファイルツールを提供するため、エージェントはコードの記述と実行、ファイルの調査と変換、Excel／CSV データの解析、PDF の抽出や作成、ドキュメントの編集、アーカイブの展開、生成した成果物の作成などのタスクに適したライブラリを使用できます。

サンドボックスは一時的なもので、認証情報や永続的な組織アクセス権は保持しません。テナントのファイルは tools.app_files で取り込み、他のシステムには明示的にマニフェストで許可された権限を通じてのみアクセスし、永続化するファイルやレコードは tools.app_data_write を通じて書き戻してください。サンドボックス内にのみ残されたものは、実行の終了時に消失します。

管理対象エージェントとページ内 LLM の使い分け

管理対象エージェント（このスキル）は、独自の承認済みマニフェストの下、コードサンドボックスを備え、永続的で監査可能な実行環境でサーバー側にて動作します。アプリ独自の LLM（$create-railcode-app 経由の llm.generate／llm.stream）はアプリのワーカー内で動作し、1 回の呼び出しに制限されます。リクエストの終了後も動作を続けること、コードを実行すること、ファイルにアクセスすることはできません。最初に該当する行を選んでください。

AI 機能…	使用するもの
アプリがすでに読み取っているデータを要約／分類／分析する（ユーザーが見守る中、数秒で完了）	アプリのワーカーの llm
ファイルを読み取り、理解、抽出、要約、変換、または生成する	管理対象エージェント（app_files ＋サンドボックス）。アプリの llm は使用しないでください
コードを記述して実行する	管理対象エージェント（サンドボックス）
アプリの外部（Slack、cron、API）から呼び出される	管理対象エージェント
リクエスト終了後も動作を続ける必要がある、無人で実行する必要がある、または再試行が必要である	管理対象エージェント
表示しているユーザーに左右されてはならない効果（共有書き込み、システムとしての送信）がある	管理対象エージェント
誰かが監査またはデバッグできる実行履歴が必要である	管理対象エージェント

2 つの実行環境は連携できます。アプリはページ内にチャットのシェルを維持し、LLM ツールの run から agents.start を呼び出して負荷の高い処理を委譲します（アプリのマニフェストでは agents: [name] を宣言し、このエージェントではアップロードされたファイルにアクセスするため app_files: [app] を宣言します）。

例から始める

Railcode には、すぐにデプロイできる動作例が https://github.com/Railcode-HQ/railcode-examples に用意されています。パターンを学ぶにはこれらを読み、ユーザーの要望の多くを満たす例があれば、それをコピーしてください。各 agents/ の例は、コンパニオンアプリとそのエージェントマニフェストで構成されています。これはエージェント関連の作業でよく見られる形です。

例	内容	紹介する機能
agents/pitch-deck	会社資料をアップロードするアプリと、それらの資料から完成度の高いピッチデッキの PDF を作成するエージェントを組み合わせた例です。	アプリと連携するマネージドエージェント：app_data／app_files へのアクセス、コード実行、そしてワーカーは単一の実行を維持できないため、アプリのワーカーから agents.start() で開始する実行。
agents/proposals	cron で Granola のミーティングを監視し、編集可能な .docx の提案書を作成するエージェントと、それらを表示するアプリを組み合わせた例です。	オーナーがリンクしたコネクター（Granola）を tools.connectors に指定する方法、エージェントが所有する cron スケジュール、そしてスケジュールをアプリに設定できない理由。cron の呼び出しには呼び出し元がないため、cron からの agents.start() は 409 になります。

エージェントはファイルやストレージを直接所有できず、データにアクセスできるアプリを介して動作するため、アプリとマネージドエージェントを組み合わせています。どちらのコンパニオンアプリも apps v2（静的な frontend/ と server/index.ts のワーカー）であるため、エージェントはページではなく、アプリのワーカーから開始します。リポジトリの apps/ ディレクトリには、通常のアプリの例（かんばん、データチャット、CRM）があります。これらを利用するには $create-railcode-app を使ってください。

決めつけずに尋ねてください。 リクエストが例と大きく重なる場合は、ステップ 1 の要件確認の質問に、その例をユーザー自身の言葉で挙げて選択肢を含めてください。

「Railcode には、ミーティングのメモからクライアント向け提案書を作成する例があります。これを出発点として使いますか、それとも一から作成しますか？」

ほかの要件確認の質問とあわせて、一度だけ尋ねてください。促されていないのに例をコピーしてはいけません。一致する例がない場合は、この質問をしないでください。

例をコピーする

ディレクトリを1つだけプレーンファイルとしてコピーしてください。ユーザーのプロジェクトにリポジトリを git clone したり、サブモジュールとして追加したり、.git を残したりしてはいけません。

mkdir -p my-proposals
curl -fsSL https://github.com/Railcode-HQ/railcode-examples/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=3 -C my-proposals railcode-examples-main/agents/proposals

--strip-components=3 により railcode-examples-main/agents/<example>/ が取り除かれ、例のファイルが my-proposals/ に直接配置されます。他の行の例を使う場合は、末尾のパスを入れ替えてください。コピーせずにマニフェストを1つだけ確認するには、https://raw.githubusercontent.com/Railcode-HQ/railcode-examples/main/agents/proposals/agents/proposal-writer/agent.yaml から raw ファイルを取得してください。

エージェントのマニフェストは agents/<agent-name>/agent.yaml にあります。その周囲にあるアプリは通常の Railcode アプリ（railcode.json + manifest.yaml）です。動作を作成する前に、コピーをユーザー自身のものにしてください。

• agents/<name>/ ディレクトリとマニフェストの name をそれぞれ変更し、組織内に既に存在するエージェントとコピーが衝突しないようにします。
• tools.app_data / app_files / app_data_write が、名前を変更した連携アプリのスラッグを指すようにします。また、tools.connectors にある名前をすべて railcode connector list と照合してください。例にある granola-… の行は、別の組織に属しています。
• 新しいエージェントに不要なツールはすべて削除してください。コピーしたマニフェストには、この作業に必要な最小限の権限ではなく、例の権限が含まれています。また、新しいワークロードに合わせて limits を調整してください。
• 新しい仕様に合わせて system プロンプトと input_schema を書き換えてください。例のプロンプトには、例独自の手順と入力形式が記述されています。
• アプリでは、railcode.json の app を設定し、package.json の name を変更して、npm install を実行します。manifest.yaml の agents: リストと、すべての agents.start / agents.get 呼び出しを更新し、例に README.md が含まれている場合は差し替えてください。

その後、以下のビルドワークフローとまったく同じように、何かを作成する前にドラフトをテストしてください（railcode agent test --file …）。ダウンロードに失敗した場合は、その旨を伝えて最初から作成してください。記憶を頼りに例を再構成してはいけません。

ビルドワークフロー

1. エージェントの範囲を決める

スコーピングの質問はまず、すべてまとめて一度に尋ねてください。ユーザーがまだその場にいるのはこのタイミングです。ビルド中に質問を小出しにすると、ユーザーが席を外した後になってしまうおそれがあります。Railcode の内部仕様を知らない技術者以外のユーザーにもわかる表現にし、意図について尋ね、回答から使うプリミティブを決めてください。たとえば、「チーム全員がこれを実行できるようにしますか、それともあなただけですか？」と尋ねます。「組織単位と個人単位のどちらの可視性にしますか？」ではありません。「毎朝、自動で実行するようにもしますか？」と尋ねます。「cron スケジュールを設定しますか？」ではありません。以下の箇条書きは、回答からあなたが把握する必要がある内容であり、質問にそのまま使う言葉ではありません。

依頼された内容がエージェントではできないこと（公開ウェブのスクレイピング、データ変更への反応、継続的な実行など。ハードリミットを参照）を必要とする場合は、最初にその旨を伝え、最も近い対応可能な方法を提案してください。定義に大きく影響する選択肢だけを確認してください。

外部ソースの探索は必須です。 ユーザーが名前の挙がった製品やシステム（「X」）のデータの読み取り、書き込み、同期、検索、操作を行うエージェントを求めている場合は、マニフェストの作成に進んだり、X はサポートされていないと結論づけたりしてはいけません。ツールを選ぶ前に、サインイン中のユーザーが利用できる Railcode のすべての連携プレーンを調べてください。

railcode db list                       # database/data-source connections
railcode query list                    # admin-published saved queries over those sources
railcode connector list                # connectors you can reach: org-managed, yours, shared with you
railcode connector catalog             # providers that could be linked, if no row exists yet

作成前に、候補となるものをすべて確認してください（http 行は railcode connector docs <name>、mcp 行とリンク済みアカウントは railcode connector tools <name>）。コネクター名、エンドポイント、ツールのスラッグ、スキーマは推測せず、正確な値を使ってください。adhoc_sql よりも保存済みクエリを優先してください。mode 列を確認してください。per-user の行はエージェントから指定できません（保存が拒否されます。呼び出し元のアカウントで実行されますが、エージェントはアカウントを持たないためです）。所有者がいる shared の行は、エージェントの作成者が所有しているか、作成者または組織に共有されている場合に限り指定できます。インスタンスに認証できない、またはアクセスできない場合は、何が設定されているかを尋ね、確認に失敗したことを連携が存在しない証拠と見なすのではなく、探索用のコマンドをユーザーに案内してください。 適切なソースが見つからない場合は、その不足を説明し、具体的な方法を提示してください。管理者にデータベースを接続して保存済みクエリを公開してもらう、管理者に共有認証情報／API 用の組織管理コネクターを作成してもらう、本人に自分のアカウントをリンクしてもらう（railcode connector link <provider>）、または X のリモート MCP サーバーを URL で追加してもらう（railcode connector add-mcp <name> <url>）方法があります。どちらもエージェントが tools.connectors で指定する行になります。または、エージェントが読み取れる接続済みデータベース／アプリストアに必要なデータをインポートしてください。X がこれらの接続方法をどれも提供していない場合は、Railcode から直接接続できないことを伝え、どの代替ソースを使うかユーザーに確認してください。

• 担当するタスクと期待する出力；
• 受け付ける入力（自由形式の JSON またはテキスト）。system プロンプトが入力の契約です；
• 必要なモデルとツール；
• オンデマンド、アプリから、スケジュール実行、Slack でのメンションのいずれで実行するか；
• コンパニオンアプリが必要か（コンパニオンアプリを参照）；
• 例から始めるか。例から始めるに依頼の大部分をカバーする例がある場合は、次のように尋ねてください。「Railcode には、会議メモからクライアント向け提案書をすでに生成できる例があります。これを出発点として使いますか、それとも最初から作成しますか？」；
• テストでアクセスする可能性のある実際のシステム、データ、費用、または副作用；
• 公開範囲 — org（デフォルト：共有され、実行権限がある人なら誰でも呼び出せます。作成者または管理者が管理します）または personal（作成者のみが所有し、呼び出せます。管理者も含まれます。権限を付与しても共有されず、後から org に変更することもできません）。エージェントを一人だけが使えるようにする場合は personal を選びます。通常は、作成者しか保持していないコネクター（本人の Gmail、Slack、Granola など）を介して動作し、ほかの人が実行できないようにする場合です。

役に立つ範囲で最小限のツールセットを使い、指示を明確にしてください。ただし、limits はその逆に、タスクに必要なトークン予算を設定し、余裕を残してください。ドキュメント編集やファイル分析の実行では、デフォルトよりはるかに多くのトークンを使います。上限に達すると実行は limit_exceeded で失敗しますが、未使用の上限にコストはかかりません（マニフェストツールのリファレンスの「limits の設定」を参照）。 ツール識別子、プロバイダー名、マニフェストフィールドを勝手に作らないでください。管理対象エージェントのマニフェストフィールドはサーバーで定義されます（JSON または YAML でファイルを作成してください。手順 2 を参照）。現在の tools.* の語彙と limits については、マニフェストツールのリファレンスを参照してください。これはサーバースキーマのスナップショットであり、仕様を保証するものではありません。保存時のエラーが常にこのファイルより優先されます。

2. 認証して確認する

CLI に使用可能な保存済みトークンがない場合は、railcode login を実行します。エージェントコマンドは選択中の組織コンテキストを使用し、どのディレクトリからでも実行できます。エージェントの公開範囲は org または personal に設定でき、railcode.json は使用しません。

マニフェストファイルの形式。 create／update／test の --file は、マニフェストを JSON または YAML として読み込みます。CLI は拡張子に基づいてパーサーを選択します（.yaml／.yml → YAML、それ以外 → JSON）。どちらも同じオブジェクトに解析され、API に保存されます。ローカルのマニフェストスキーマバリデーターはありません。サーバーによる検証と承認時の警告を正式なものとして扱ってください。

既存のエージェントを編集する前に、保存されているマニフェストの正確な内容を取得します。

railcode agent show <agent>
railcode agent pull <agent> --output agent.json

pull と show --manifest は JSON のみを出力します。YAML 出力フラグはありません。ユーザーがエージェントの定義を YAML で表示または保存したい場合は、取得した JSON を自分で YAML に変換し、agent.yaml に書き込みます。--file 経由で再度読み込んでも、内容は変わりません。

新しいエージェントの場合は、現在サーバーがサポートしている形式でマニフェストを作成します。または、ユーザーが手順 1 で例を選んでいる場合は、その例の agent.yaml をコピーして調整します（例から開始するを参照）。システムプロンプトの作成の説明に従って system プロンプトを記述します。定義を現在の作業ディレクトリに保存するか、ユーザーに確認してください。 保存する場合は、そこに YAML（agent.yaml）として書き込み、そのファイルを test／create に渡します。保存しない場合は、ユーザーのプロジェクト外の一時的な場所に置いてください。

3. ドラフトをテストする

エージェントを作成または置き換える前に、未保存のマニフェストをテストします。

railcode agent test --file agent.json --input '{"key":"value"}' --trace

テスト用のペイロードが大きい場合や機密情報を含む場合は、--input-file を使用します。テストでは設定済みのモデルとツールを実際に呼び出すため、費用が発生したり、実データを読み取ったり、ツールの副作用が発生したりすることがあります。副作用を伴うテストを実行する前に、必要な承認を得てください。

app_data／app_files を介してコンパニオンアプリを読み取るエージェントは、データが空のアプリでは検証になりません。まず、アプリ自体が書き込む形式を使って railcode app kv set <collection> <key> '<json>' と railcode app files upload <path>（CLI 0.1.28 以降、アプリ所有者または組織管理者）でデータを投入し、その後、使い捨てデータを削除してください。

プロセスの終了コードだけを信用しないでください。実行環境に到達したリクエストは、実行結果に表示されるステータスが失敗でも、終了コードが 0 になる場合があります。Status: を確認するか、--json を調べてください。

ドラフトテストでは書き込みは永続化されません。app_data_write ツールは実行ごとのメモリ内オーバーレイに対して実行されます。一方、保存済みエージェントがまだ存在しないため、agent_kv ツールは省略されます。test 後にストアが変更されていないのは想定どおりです。永続化を検証するには、create と run を使用してください。マニフェストツールのリファレンスを参照してください。

4. 公開または更新する

railcode agent create --file agent.yaml            # or agent.json — format is picked by extension
railcode agent create --file agent.yaml --visibility personal
railcode agent update <agent> --file agent.yaml

update は保存済みのマニフェストを置き換えます。意図したフィールドを保持するには、railcode agent pull から始め、変更を完了と見なす前に、承認に関する警告をすべて確認してください。取得したマニフェストで作業する間に、以前のテスト実行で残った不要な内容が system プロンプトにないか監査してください。システムプロンプトの作成を参照してください。

create／update／test の --visibility <org|personal> は、エージェントの所属先を設定または変更します。create／test で省略すると、デフォルトの org になります。update で省略すると、既存の公開範囲が維持されます（明示するだけの目的でフラグを渡さないでください。サーバー側では、フラグの省略と org の明示は異なるリクエストとして扱われます）。personal の作成または変更には agent:create 機能が、org には agent:create_org が必要です。一方の機能を持っていても、もう一方を持っているとは限りません。personal から org への変更は一切拒否されます。org から personal への変更は許可されますが、過去に共有された実行結果や書き込みの公開範囲は遡って変更されません。

5. 保存したエージェントを検証する

railcode agent run <agent> --input '{"key":"value"}' --trace
railcode agent show <agent> --manifest

保存されたマニフェスト、実行ステータス、出力、関連するトレースの手順を確認します。組織のオブザーバビリティログには、$manage-railcode-org を使用します。railcode logs agent ... ワークフローは管理者向けの機能であり、エージェントの作成には含まれません。

エージェントが tools.app_data_write を通じてデータを書き戻す場合、実行ステータスが正常でも、データが保存された証拠にはなりません。コンパニオンアプリのストアを直接確認してください（CLI 0.1.28 以降、アプリの所有者または組織の管理者が対象です）。

railcode app kv collections --app <app>              # collections + record counts
railcode app kv list <collection> --app <app>        # what app_kv_set actually wrote
railcode app files list --app <app>                  # what publish_artifact_to_app produced
railcode app files download <name> --app <app>       # open the generated .docx/.pdf yourself

共有されていない名前空間を調べるには、--scope user --user <member-uuid> または --scope role --role <role-uuid> を追加します。--scope all は、すべてのスコープを所有者情報付きで一覧表示します。チームが共有レコードを期待していたのに、パーソナルエージェントが所有者のプライベートスコープに書き込んでいるケースを見つけるのにも、これが最も手早い方法です。

6. 要望があった場合にのみスケジュールを設定する

各管理対象エージェントに設定できる cron スケジュールは、現在最大 1 つです。まず既存のスケジュールを確認し、schedule set を使ってアップサートします。作成と更新を区別する必要がある場合は、より厳密なエイリアスを使用してください。

railcode agent schedule show <agent>
railcode agent schedule set <agent> --cron "0 9 * * *" --timezone UTC

IANA タイムゾーンと、5 フィールドの cron 式を使用します。変更を行うたびに、保存されたスケジュールを確認してください。run-now は実際のサービスに対して同期実行します。

スケジュールされた実行には、null の入力が渡されます。スケジュールごとのペイロードはありません。入力がなくても実行内容を正確に把握できるよう、system プロンプトを作成してください。エージェントの例（daily-metrics-report）を参照してください。

システムプロンプトの作成

system プロンプトは、エージェントが担うタスク、入力の読み取り方、返す内容を定める、エージェントの契約全体です。進化に合わせて機能させ続けるには、2 つの習慣が役立ちます。

肯定的な指示を優先します。 エージェントにしてほしくないことではなく、すべきことを伝えます。「数値はアップロードされた資料からのみ引用し、見つからない場合は角括弧付きのプレースホルダーを記載してください」と指示すれば、モデルが目指すべきことがわかります。一方、「数値を捏造しないでください」では、1 つの方法を禁止するだけで、それ以外は推測に委ねられます。これは推奨であって、ルールではありません。実際の境界（「出席者リストにない人には、決してメールを送らないでください」）は明示する価値があり、厳格な制限は厳格なままにしてください。ただし、「してはいけない」が「すべきこと」の代わりになっている場合は、「すべきこと」を書きましょう。

更新のたびにプロンプト全体を見直します。 実行のたびに、エージェントはプロンプトを初めて読む状態です。以前のバージョンや過去の実行、先週追っていたバグについての記憶はありません。そのため、私たちには自然に読めても、エージェントを誤解させる不要な記述がプロンプトに蓄積していきます。

• 過去の経緯として書かれた修正 — 「以前は X をしていましたが、今後は Y をしてください。」 このエージェントが X をしていたことはありません。この文は X を持ち出し、両方を実行するよう求めてしまいます。Y だけを記述してください。
• デバッグ時の残骸 — 一時的な 「今のところ、最初の 3 行だけを処理してください」 という指示や、すでに修正されたバグに対する回避策。
• 孤立した手順 — マニフェストにもう宣言されていないツール、アプリ、コネクター、フィールドを指定する指示。
• 少しずつ言い回しを変えながら、同じルールが 3 回書かれている状態。それぞれ別のテストの際に追加されたものです。言い換えた指示同士が競合するため、最も明確なものだけを残してください。

そのため、railcode agent update の前に、最後に書いた内容の記憶に頼らず、railcode agent pull で保存済みの system を最初から最後まで読み、初めて読む人が実行する手順として書き直してください。システムプロンプトは変更履歴ではなく、仕様として読めるものであるべきです。

Slack（デフォルトで有効）

組織の管理者が組織の Slack ワークスペースに接続すると、すべてのアクティブなエージェントを、エージェントごとの設定なしで Slack から呼び出せます。メンバーは、ボットが招待されているチャンネルでボットにメンションして実行します。

@Railcode $<agent-name> summarize this thread

エージェント名の先頭には $ を付け、メンションの後の最初のトークンにする必要があります（名前だけの場合は、何も実行せずに使い方のヒントを表示します）。エージェント設計上の意味は次のとおりです。

• 権限は変わりません。 Slack の呼び出し元は、検証済みのメールアドレスによって有効な組織メンバーとして特定され、通常の呼び出し権限を持っている必要があります。一致するメンバーがいなければ、実行されません。そのため、personal エージェントを Slack から呼び出せるのは、その所有者だけです。
• 入力は { text: <message> } として渡されます。 エージェントの入力は自由形式のため、どのエージェントにもメンションできます。入力の解釈方法は、エージェントの system プロンプトで説明する必要があります。
• 最終応答は、成功時も失敗時もプラットフォームがメンションされたスレッドに投稿します。 エージェントが返す内容がそのまま Slack の返信になります（Slack 経由で実行される場合はその旨が system プロンプトで伝えられ、Slack mrkdwn で書くよう指示されます）。返信に slack コネクターは必要ありません。コネクターが付与されている場合は、実行中の進捗更新にのみ使用します。

そのため、チームが会話形式で使うエージェントは、自由形式のテキスト入力を処理し、Slack メッセージとして読みやすい最終回答を生成できるようにしてください。

コンパニオンアプリ

エージェントには、多くの場合、コンパニオンアプリ（エージェントと併せてデプロイする小規模なアプリ、$create-railcode-app）が必要です。現在構築するアプリはすべて apps v2 です。静的フロントエンドとバックエンドワーカーで構成されるため、コンパニオンアプリからエージェントを呼び出す際は、ページからではなく、ワーカーから @railcode/sdk を使用します。エージェントが誰かの管理するファイルやレコードに依存する場合や、エージェントを実行して出力を確認する場所が必要な場合は、このパターンを使用してください。

• エージェントが依存するストレージ — アプリは、エージェントが読み取るファイルやレコードをアップロード・管理するための UI です。アプリでは files.upload()／db、エージェントのマニフェストでは app_files: [<app-slug>]／app_data: [<app-slug>] を使用します。
• 結果を表示する場所 — エージェントは app_data_write（app_kv_set、publish_artifact_to_app）を介して結果を書き戻し、アプリが実行結果を表示します。
• 簡単にテストして実行する方法 — agents.start(name, input) に接続したワーカールートを使うと、エージェントをエンドツーエンドではるかに簡単に試せます（アプリのマニフェスト：agents: [<agent-name>]）。手作業で CLI の実行を作成する手間が省けるだけでなく、対話型の本番実行トリガーとしても使えます。

v2 コンパニオンアプリからエージェントを実行する際に、知っておくべきことは次の 4 つです。

• agents.start() は、実行を キューに追加 するとすぐに返ります。request_id をフロントエンドに渡し、agents.get() を呼び出すルートをポーリングさせます。ワーカー側で実行の終了を待つ呼び出しはありません。また、get() のループも代わりにはなりません。ポーリングのたびにサブリクエストを消費し、長時間の実行が終わる前にトークンの有効期限が切れるためです。
• アプリでは エージェントを宣言する必要があります（agents: [<name>]）。宣言がない場合は、ダッシュボードからエージェントを実行できる呼び出し元であっても、処理がそのまま通るのではなく拒否されます（403）。
• 実行は (app, caller) に紐づきます。 アプリが読み取れるのは、そのアプリが開始した、開始者本人の実行だけです。ダッシュボードから開始した実行はアプリから見えません。
• アプリの cron から実行を開始することはできません（409 — 呼び出し元がいないため、実行の所有者を設定できません）。スケジュール実行には、エージェント自身にスケジュールを設定してください。

v2 コンパニオンアプリには ORG エージェントを推奨します。 ORG エージェントの app_data_write は、アプリの共有スコープに書き込みます。これは v2 アプリのフラットな db ストアにあたるため、結果はワーカーがすでに読み取っているコレクションに表示され、ブリッジは不要です。個人用エージェントは、所有者のユーザースコープに書き込みます。移行済みのアプリでは、このスコープは凍結されており、ワーカーからは読み取り専用です。

エージェントにちなんだ名前をアプリにつけ（例：エージェントが report-extractor、アプリが report-extractor-console）、両側で必要最小限のスラッグを宣言し、$create-railcode-app を使ってアプリを構築してください。例から始めるの agents/ の項目には、エージェントのマニフェストとワーカーの両方を含む、この組み合わせの動作する apps-v2 版があります。ユーザーの要望に合うものがあれば、それをコピーしてください。

厳格な制限

マニフェストの内容にかかわらず、管理対象エージェントができないこと（プラットフォーム全体の完全な一覧は $create-railcode-app →「制限事項」を参照してください）：

• オープンウェブにアクセスすること。 サンドボックスの外向き通信は許可リスト方式です（PyPI、npm、app_files を含む署名付きダウンロードホスト）。connector ツールがアクセスできるのは、承認済みのエンドポイントのみです。スクレイピングや任意の API 呼び出しはできません。
• 長時間または継続的に実行すること。 実行には上限があり、最大 300 ステップ／1200 秒／limits で定められたトークン上限です。デーモンやモニターは動かせません。定期実行には cron スケジュールを使用します。
• イベントに応答すること。 トリガーとして使用できるのは、アプリ／API の呼び出し、cron、Slack のメンションのみです。データ変更や受信 Webhook をトリガーにはできません。
• ほかのエージェントを呼び出すこと。 エージェント間をつなぐツールはありません。パイプラインはアプリまたは外部の呼び出し元を通じて構成してください。
• ユーザーごとのコネクターを使うこと。 ユーザーごとのコネクター（名前は 1 つで、各メンバーがそれぞれのアカウントを使用）は呼び出し元のアカウントで実行されますが、エージェントには呼び出し元がありません。そのため、これを指定したマニフェストは保存時に拒否され、ランナーも実行時に拒否します。代わりに、作成者が所有するコネクター（または組織管理のコネクター）を指定してください。URL を指定する MCP 行（railcode connector add-mcp）は使用できます。
• サンドボックスの状態を保持すること。 サンドボックスのファイルシステムは実行ごとに作成されます。保持する必要のあるものは、実行終了前に公開（publish_artifact_to_app）するか、KV に書き込む必要があります。

権限と境界

• list、show、pull が返すのは、組織のエージェントと、呼び出し元自身の個人用エージェントのみです。他者の個人用エージェントは、存在を確認されないよう、管理者であっても不可視（403 ではなく 404）です。
• 組織エージェントの場合：run にはそのエージェントへの実行許可が必要です。update／delete／test／スケジュールの変更が許可されるのは、そのエージェントの作成者本人、または組織のオーナー／管理者のみであり、すべてのメンバーではありません。エージェントを新規作成する場合、または既存のエージェントを org に変更する場合は、agent:create_org 機能も必要です。
• 個人用エージェントの場合：実行と管理はどちらも所有者のみに許可され、管理者による例外はありません。緊急アクセス手段もないため、組織のオーナー／管理者であっても他者のエージェントにはアクセスできません。作成には、広く付与可能な agent:create 機能が必要です。オーナー／管理者である必要はありません。
• delete は実行履歴を保持したままエージェントをアーカイブします。TTY の外では --yes が必要です。
• ワーカーから agents.start(name, input) を使ってエージェントを開始するアプリを構築する場合は、$create-railcode-app を使用してください。権限のあるアプリのマニフェストでは、agents: [name] を宣言します。
• アプリは、llm.generate({ tools })／llm.stream({ tools }) を使ってページ内で独自のエージェント型ループを実行することもできます。管理対象エージェントは必要ありません。使い分けについては、このスキルの冒頭にある管理対象エージェントとページ内 LLM の使い分けを参照してください。
• メンバー、ロール／許可、アプリ／アクセス、接続、サービスコネクター、分析、組織ログについては、$manage-railcode-org を使用してください。

リファレンス

エージェントの正確なコマンド、エイリアス、スケジュールの動作、入力、出力、失敗時の動作については、CLI リファレンスを参照してください。tools.* の用語、それぞれが付与する権限、権限ゲート、limits については、マニフェストツールのリファレンスを参照してください。最小構成のエージェントと、スケジュールに従ってクエリ結果をメールで送信するワークフローを実行可能なマニフェストで解説したエージェントの例を参照してください。エージェントと対応するアプリを組み合わせた完全なプロジェクト（ピッチデッキ、クライアント向け提案書）については、railcode-examples を参照するか、そこからコピーしてください。詳しくは例から始めるを参照してください。