carto-develop-app

carto-develop-app

プロンプトから、動作する CARTO + deck.gl アプリを生成します。アプリの種類、フレームワーク、認証モデル、データの形状の4つを決めたら、レイヤー、ウィジェット、フィルター、入力、凡例、そして（任意で）埋め込み型マップエージェントを組み立てます。

アプリはCartoDB/deck.gl-examplesの設計を基にしています。レイヤーには@deck.gl/cartoを使用し、データソース、ウィジェット、フィルター、fetchMap、query()には@carto/api-clientを使用します（ソースはv0.4.0で@deck.gl/cartoから移動しました。そちらからインポートしないでください）。

アクセス経路。 これはCLI経路のスキルです。アプリのスキャフォールディングと実行には、実際のシェルと開発環境（npm、Vite）が必要です。また、アプリを生成するMCPツールはないため、サンドボックス化されたチャットホスト（Claude.ai、ChatGPT）では実行できません。MCPに相当する手段があるのは、認証情報の取得と検出の手順のみです。OAuth MCPセッションを通じて、manage_api_access_tokensでトークンを作成し、manage_oauth_clientsでOAuth/M2Mクライアントを作成し、read_maps / read_workflowsでマップIDやワークフローIDを検出できます。それ以外はすべてシェルが必要です。経路の検出方法については、carto-basics/references/access-paths.mdを参照してください。

使用するタイミング

• 「deck.gl アプリ」「CARTO アプリ」「マップアプリ」「空間ダッシュボード」には、このスキルを使用します。
• BuilderのマップIDが指定されている場合 → fetchmap.md。
• ストーリーマップ／スクロールテリング／ナラティブマップ／ガイド付きツアーの場合 → storymap.md（以下のReactスキャフォールドをベースに構成します）。
• マップとのチャット／埋め込み型AIエージェントの場合 → agentic-variant.md。
• Builderでマップを作成する場合 → carto-create-builder-maps。Builderのマップを組織／プロファイル間で移行する場合 → cross-profile-copy.md。

動作モード — デフォルトでは自律的に実行

CARTO CLIで環境変数を生成します。ユーザーに質問しないでください。 --jsonを渡して解析します。

実行後、.envを書き込みます。

carto auth status --json                  # → tenant_id (region) → apiBaseUrl
carto connections list --json             # → connectionName (default: carto_dw)

# One token, ONE grant per source — repeat --connection alongside every --source.
carto credentials create token --json \
  --connection <connectionName> --source <fully.qualified.table.A> \
  --connection <connectionName> --source <fully.qualified.table.B> \
  --apis sql,maps \
  --referers 'http://localhost:5173*,<production-origin>*'

1つのトークンに複数の権限を付与します。テーブルごとにトークンを作成する必要はありません。--connectionと--sourceは位置順に対応するため、--sourceごとに--connectionを繰り返してください。--referers（複数形のCSV）を使用してください。--referer（単数形）は、繰り返すと上書きされます。リファラーはブラウザーの完全なページURLに対してワイルドカード照合されるため、各パターンの末尾には*を付けてください（http://localhost:5173だけでは、ブラウザーが実際に送信するhttp://localhost:5173/には一致しません）。--apisと権限付与は独立しています。mapsはソース／レイヤーを、sqlはquery()をカバーします。また、*QuerySourceには、権限付与にそのクエリを含める必要があります。auth-public-token.mdを参照してください。

プライベートアプリでは、トークンコマンドの代わりにcarto credentials create spa --json（OAuth）またはcarto credentials create m2m --json（M2M）を使用します。ホスト型アプリでは認証情報は不要です。トークンの手順を省略し、auth-hosted.mdに従ってください。

cartoがPATHにない場合、またはauth statusが失敗した場合は、その旨を一度だけ伝えて停止し、不足しているコマンドを表示してください。質問に切り替えないでください。動作するCLIを前提としています（carto-basics）。

CLIでは答えられないことだけを尋ねてください。明確でない場合のテーブル名と、以下の曖昧なアプリ形状の選択肢です。

判断フロー — 本当に曖昧な場合にのみ質問する

1. Builder map ID が指定されていますか？ はい → fetchmap.md。完了です。 1b. Storymap の形式ですか？ 手がかり：「story map」、「scrollytelling」、「guided tour」、「scenes/chapters/slides」、「fly through」。→ storymap.md。引き続き、以下から React のスキャフォールドとデータソース／レイヤーを選びます。storymap はその上に重ねる状態パターンであり、別個のスキャフォールドではありません。
2. デモですか、本番環境ですか？ プロンプトに「production」、「auth」、「deploy」、「team」、「multi-screen」とある場合を除き、デフォルトでは vanilla TS + Vite + MapLibre（scaffold-vanilla.md）を選びます。その場合は React（scaffold-react.md）を選びます。Vue／Angular は、明示的に指定されている場合のみ選びます（scaffold-vue-angular.md）。
3. 認証モデルは？ プロンプトの手がかりに基づいて選びます。手がかりが矛盾する場合のみ質問します。
   • 「public」／「share」／「embed」／ログインなし → API アクセストークン（auth-public-token.md）
   • 「private」／「users log in」／「CARTO login」 → OAuth SPA（auth-private-oauth.md）
   • 「SSO」／「Okta」／「Azure AD」／「corporate IdP」 → OAuth + SSO（auth-private-sso.md）
   • 「backend」／「ETL」／「CI」／「scheduled」 → M2M（auth-m2m.md）
   • 「hosted on CARTO」／「internal tool」／「for my team」／「no infrastructure」／carto app deploy → CARTO ホスト型、実行時にビューワートークンを使用（auth-hosted.md）。Hosted Apps フラグが必要です。匿名アクセスには使用できません。
4. データの形状は？ data-sources.md + layers.md からソース／レイヤーの組み合わせを選びます。points/lines/polygons → vector、H3 → H3、quadbin → quadbin、surfaces → raster。ベースマップとビュー状態の同期は basemap-and-view.md を使って設定します。

その後、依頼されたものだけを追加します：widgets、filters、inputs、legend、SQL/workflows、agentic chat。レシピは recipes/ にあります。

5. ビジュアルスタイルは？ スタイルの手がかりがなければ、Meridian を参考にしたデフォルト（すっきりとしてプロフェッショナルな、CARTO ネイティブのスタイル）を使用します。スタイルの手がかり（「futuristic」、「corporate」、名前の挙がったデザインシステムなど）があれば、ユーザーの説明に合わせたカスタムテーマを使用します。いずれの場合も、UX レイアウトの原則を適用します。design-and-theming.md を参照してください。

常時適用されるガイダンス

• apiBaseUrl は https://<tenant_id>.api.carto.com です。tenant_id（リージョン。例：gcp-us-east1）は carto auth status --json で確認します。tenant_domain は組織独自のドメイン（例：clausa.app.carto.com）で、リージョン情報は含みません。https://<tenant_domain>/config.yaml の apis.baseUrl を正とします（セルフホスト環境も含みます）。ハードコードしないでください。
• connectionName のデフォルト値は carto_dw です。carto connections list --json で確認してください。
• 公開トークンでは、必ず --source を渡し、--apis は sql,maps に限定してください。公開バンドルに imports や lds を含めないでください。
• 複雑な分析はワークフローであり、アプリの SQL ではありません。 収益予測、複合スコア／適合性スコア、セグメンテーション、複数段階の結合は、carto-create-workflow を使って構築してください。その後、アプリは Workflows API 経由で出力テーブルを読み込むか、プロシージャを CALL します（または、埋め込みエージェントが操作する場合は、公開済みの MCP ツールとして呼び出します）。複雑なロジックはサーバー側に置き、アプリからはパラメーターを渡します。詳しくは workflows-and-sql.md を参照してください。
• 1つの filters オブジェクトを、ソースヘルパーとウィジェットメソッドの両方で共有します。これを変更すると、両方で再取得が発生します。
• レイヤーの Z 順は layers 配列で決まり、最後のレイヤーが最前面です。CSS の z-index ではありません。 順序を変えるには配列内の位置を変更し、新しい配列を渡してください（その場で変更しないでください）。z-index は DOM パネルの順序を制御しますが、共有キャンバス上のレイヤーには影響しません。詳しくは layers.md を参照してください。（不透明な塗りつぶしがベースマップのラベルを隠す問題は、別途ベースマップ側で対処します。詳しくは basemap-and-view.md を参照してください。）
• onViewStateChange のビューポート空間フィルターには、約 300 ms のデバウンスを設定してください。
• デザイン — ユーザーが異なる美的スタイルを指定しない限り、Meridian を参考にしたデフォルトテーマを適用してください。マップを主役にすること、パネルの整理、段階的な情報開示といった UX レイアウトの原則は、常に適用してください。詳しくは design-and-theming.md を参照してください。
• ロゴを創作しないでください。 ロゴ（CARTO、顧客、パートナー、サードパーティブランド）を表示できるのは、ユーザーから検証済みの PNG／JPG／SVG アセットが提供された場合、または公式ソースが指定された場合に限ります。検証済みアセットがない場合は、ユーザーに確認するか、テキストのワードマークを使用するか、ロゴを省略してください。SVG のマークを生成したり、未検証の URL から取得したり、似たブランドのロゴで代用したりしないでください。有名ブランドにも同じルールが適用されます。
• 最後にアプリを実行してください。 npm install && npm run dev を実行し、URL を報告してください。