manage-railcode-org

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 に照らして確認されています。

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

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

Railcode を使った重要な作業の後、具体的な製品フィードバック（バグ、不便な点、提案、特にうまくいったこと）がある場合は、 隠しコマンド railcode agent-feedback を使用してください。明確に異なる所見ごとに一度だけ送信してください。作業内容、 期待した動作と実際の動作、および回避策を記載します。簡潔にまとめ、認証情報、顧客の非公開データ、ソースファイル、 会話の記録は含めないでください。

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 が返される場合があります。その場合は 利用できないものとして扱ってください。

管理ワークフロー

1. 認証して対象範囲を確定する

必要に応じて railcode login を実行してください。管理コマンドはログイン時に保存された組織を対象とし、 どのディレクトリからでも実行できます。アプリや railcode.json は必要ありません。

状態を変更する前に、対象の組織を確認し、現在のリソースを調べてください。ほとんどの参照では、適切な名前、 スラッグ、メールアドレス、または UUID を指定できます。人が読める参照先が曖昧な場合は、UUID を優先してください。 機械可読な結果が必要な場合は --json を使用してください。

2. 変更前に確認する

まず該当する読み取りコマンドを使用してください。例：apps show/access、members list、 roles list/grants/effective/catalog、connections list、connector list --admin／native、 query list、analytics、または logs。

オーナー／管理者の権限はサーバー側で適用されます。403 は権限の境界であり、ユーザーの許可なく CLI を回避したり、別の認証情報を使ったりする理由にはなりません。

3. 必要最小限の変更を行う

指定されたリソースのみを変更してください。最小権限の原則を守ります。

• 広範なアクセスが明示的に意図されている場合を除き、* ではなく特定のリソースを許可します。
• アドホック SQL の権限より、保存済みクエリを優先します。
• サービスコネクターで使用できる HTTP メソッドを制限します。
• シェルの履歴に認証情報を埋め込まないでください。サポートされているファイルオプションを優先します。
• ユーザーから状態変更を依頼されていない限り、削除、メンバーの削除、所有権の移譲、アクセス権の取り消し、 認証情報のローテーションを行わないでください。

4. 実効状態を確認する

変更後に、該当する読み取りコマンドを再実行してください。アクセス権を変更した場合は、直接のポリシーと計算済みの権限付与（apps access、roles effective）の両方を確認してください。コネクターを設定した場合は、依頼されていない後続処理を引き起こさずに設定を証明できる、最も影響の少ない一覧表示／ドキュメント参照／クエリ操作で検証してください。

機能の境界

• members list はすべてのメンバーが読み取れます。メンバーの変更には管理者権限が必要です。
• アプリの一覧表示／詳細表示／アクセス権はアプリごとの可視性に従います。アクセス権の設定／移管／アーカイブ／アーカイブ解除／削除には管理権限（オーナーまたは組織管理者）が必要です。
• ロール、権限付与、接続、コネクター管理、分析、ログは、サーバー側で機能ごとにアクセスが制限されています。
• CLI ではメンバーを作成できません。新しいユーザーは Web アプリの招待フローから参加し、その後 CLI で一覧表示、ロール変更、削除ができます。
• apps delete はデプロイとアプリのデータを削除する操作で、取り消せません。可逆的な代替手段は apps archive です。アプリは引き続きサービスを提供し、データを保持し、エージェントを実行します。ランチャーから非表示になるだけです。ユーザーの目的がアプリの破棄ではなく終了である場合は、アーカイブを提案してください。
• app kv／app files（単数形の app）は、デプロイ済みアプリのレコードとファイルを読み書きします。オーナー権限または app:manage_any が必要です。また、set／delete／drop／upload は、各メンバーのプライベートスコープを含む、テナントの稼働中データを変更します。まず調査し、依頼された内容のみを変更してください。
• roles materialize はワイルドカードを明示的な行に展開します。対象とリソースを事前に調査してください。今後の権限付与のメンテナンス方法が変わるためです。

スキルの境界

静的アプリのひな形作成、開発、テスト、マニフェスト作成、デプロイには $create-railcode-app を使用してください。管理対象エージェントの JSON マニフェスト、テスト、呼び出し、スケジュールには $create-railcode-agent を使用してください。このスキルは、それらのビルダーが必要とする場合のある組織レベルの管理を担当します。

リファレンス

正確なコマンド、フラグ、リソースタイプ、アクセスモード、接続形式（SSH 踏み台経由の Postgres を含む）、ログフィルター、保存済みクエリの管理については、CLI 管理リファレンスを参照してください。