dataapp-development

Keboola アプリ開発

このスキルでは、Keboola アプリ（旧称「Data Apps」）のライフサイクル全体を扱います。適切なアプリタイプの選択、ローカルでの構築、デプロイ、デバッグに対応しています。Streamlit アプリと Python/JS アプリの両方に対応し、3 つのクライアント経路（MCP のみ、ファイルシステムにアクセスできる Claude Code、kbagent CLI）を利用できます。

このスキルはルーターとして機能し、すべてのガイダンスを自ら含んでいるわけではありません。タスクに応じて、references/ 内のファイルを必要に応じて読み込みます。以下の判断フローを確認し、必要なリファレンスだけを読み込んでください。

判断フロー

次の質問に順番に答えてください。それぞれの回答に応じて、参照すべきリファレンスが決まります。

1. タスクは何ですか？

タスク	最初に参照する場所
アプリを新規に構築する	references/choosing-app-type.md → タイプ固有のリファレンス → references/deployment-paths.md。Python/JS の場合は、まず references/python-js-prod-and-drafts.md を読んでください — 通常、すでに本番アプリが存在します
modify_python_js_data_app を呼び出すすべての作業	呼び出す前に references/python-js-prod-and-drafts.md
既存のアプリを変更する（機能追加、バグ修正）	変更の反復プロセスについては references/dev-workflow.md。Python/JS の場合：アプリのドラフトを引き継いでください — references/python-js-prod-and-drafts.md
開発モードで実行中のアプリに実際に表示される内容を確認する	references/dev-workflow.md の「開発モードで実行中のアプリを検証する」— 自分のブラウザーでプレビューリンクを開きます
自分で作成したばかりではないクローンから読み取る、説明する、またはプッシュする	references/existing-clone.md
デプロイまたは再デプロイする	references/deployment-paths.md
デプロイまたはランタイムの問題をデバッグする	references/troubleshooting.md
既存のアプリを別のタイプに移行する	references/choosing-app-type.md + references/streamlit-apps.md + references/python-js-apps.md

2. アプリのタイプはどれですか？

不明な場合 → references/choosing-app-type.md。簡単に言うと：

• Streamlit — チームが Python のみを使用し、UI がほぼサイドバーとメインペインで構成される場合に最速です。references/streamlit-apps.md を読んでください。
• React + Vite + Express を 1 つの Node コンテナーで実行 — Python/JS の標準構成です。templates/react-vite-app/ から始めてください。ブラウザーで読み込まれるすべてのものがバンドルされます。references/python-js-apps.md を読んでください。
• Python + Node の組み合わせ — Python バックエンド（ML モデル、既存の Python コードベース）が本当に必要な場合に限ります。references/python-js-apps.md（マルチサーバーのセクション）を読んでください。

3. クライアント経路はどれですか？

references/deployment-paths.md ですべての経路を確認できます。

• 経路 A — Claude Desktop / web（MCP のみ、ファイルシステムなし）： Streamlit は modify_streamlit_data_app / deploy_data_app を使用します。Python/JS は modify_python_js_data_app + create_python_js_data_app_git_credential + git + deploy_data_app を使用します（references/python-js-prod-and-drafts.md を参照。git 対応のランナーが必要です）。
• 経路 B — Claude Code / ファイルシステム + MCP を備えたローカルエージェント： ファイルをローカルで編集し、アプリの git リポジトリ（Keboola 管理または顧客提供）にプッシュして、MCP または kbagent 経由でデプロイします。
• 経路 C — CLI エージェント（kbagent）： kbagent data-app コマンドグループでライフサイクル全体を実行します。

4. 横断的な考慮事項はありますか？

項目	リファレンス
Keboola Storage からの読み取り／書き込み（RO のデフォルトでは DuckDB キャッシュを使用）	references/storage-access.md + references/duckdb-caching.md
アプリのセキュリティ保護（ログイン、SSO、OAuth）	references/authentication.md
DWH コストの削減と読み取り専用ダッシュボードの高速化（RO アプリのデフォルト）	references/duckdb-caching.md
スタイリング — Keboola のデフォルトのカラーパレットとフッター	references/styling-guide.md
スタイリング — テンプレートに shadcn/ui、ダークモード、ECharts を追加	references/styling-react-bundled.md
ダッシュボード形式のアプリを構築する	references/dashboard-patterns.md
アプリに自然言語アシスタントを追加する	references/kai-integration.md
ソースリポジトリ／正式なドキュメント／UI ナビゲーション	references/glossary.md

テンプレート一覧

テンプレート	使用するタイミング
templates/streamlit/	新しい Streamlit アプリ、コード、または Git デプロイの場合。
templates/python-app/	Python のみを使用する新しい Python/JS アプリ（Flask など）の場合。
templates/react-vite-app/	新しい Python/JS アプリの場合 — デフォルトです（React + Vite + Tailwind + Express）。
templates/python-node-app/	デフォルトのテンプレートの Node サーバーに Python バックエンドを追加する場合。
templates/duckdb-cache/	既存の Python または Node アプリに DuckDB キャッシュパターンを追加する場合。

信頼できる Keboola のドキュメントが必要ですか？

Keboola MCP サーバーは、公式の Keboola Connection ドキュメントを検索する docs_query ツールを公開しています。このスキルのリファレンスで疑問が解決しない場合（UI のナビゲーションの詳細、エッジケース、最近のプラットフォーム変更など）は、推測したり古い記憶に頼ったりせず、docs_query を呼び出して正式な回答を取得してください。

厳守事項（すべてのタスクに適用）

1. .streamlit/secrets.toml や、実際の認証情報が含まれるファイルは絶対にコミットしないでください。 コミットする前に .gitignore に追加してください。
2. 入力マッピングの前に RO ワークスペースを使用してください。 新しいアプリでは、デフォルトで RO ワークスペースパターンを使用します。入力マッピングは推奨されません。references/storage-access.md を参照してください。
3. アプリはルートパスで POST / を処理する必要があります。 Keboola は起動時に / へ POST します。React + Vite テンプレートでは、nginx がこれに応答します。Streamlit は標準で処理しますが、Flask では methods=["GET", "POST"]、Express では app.all('/') が必要です。
4. Python アプリで pip install を実行しないでください。 ベースイメージでは PEP 668 がブロックされています。pyproject.toml に基づく uv sync を使用してください。Python のすべての supervisord コマンドでは uv run を使用してください。
5. keboola-config/supervisord/ で [program:nginx] を宣言しないでください。 Nginx はベースイメージによって管理されます。
6. まずデータを検証し、その後でコードを作成してください。 Keboola MCP を使用する場合は、SQL を書く前に get_table と query_data を呼び出してスキーマを確認してください。プロジェクトにセマンティックレイヤーがある場合は、まず search_semantic_context ／ get_semantic_context で確認し、計算方法を作り上げるのではなく、その定義に基づいてクエリを作成してください。references/dev-workflow.md を参照してください。
7. 1 回のセッションで使用する Keboola の経路は 1 つにしてください。 プロジェクトを変更する呼び出しを行う前に、両方の検出チェック（which kbagent と mcp__*[Kk]eboola* ツールのスキャン）を実行し、複数の経路が見つかった場合は、どれを使用するかユーザーに確認してください。黙って選ばないでください。references/deployment-paths.md §Pick one path per session を参照してください。
8. MCP のみを使用するフローでは、ソースを直接ツール呼び出しに渡してください。 選択した経路が modify_streamlit_data_app の場合、source_code 引数がデプロイ成果物そのものです。ローカルコピーを事前に書き出さないでください。references/deployment-paths.md Path A を参照してください。
9. ローカル開発用の認証情報は、分かる範囲で先に入力し、不足分をユーザーに尋ねてから、実行を申し出てください。 認証トークンを探すためにファイルシステムを grep したり、無関係な環境変数をスキャンしたりしないでください。ローカル開発用の環境変数の取得については、references/storage-access.md §Getting the env vars for local development を参照してください。
10. ID が空の場合は作成を意味します。 空の configuration_id によって更新から作成へ切り替わる Keboola ツール（modify_python_js_data_app、modify_streamlit_data_app）では、ID は単なる詳細ではなく、判断を左右する値です。新しいリソースを作成すること、また既存のリソースが適さない理由を返信で伝えずに、空の ID を送らないでください。Python／JS アプリの作成では、後から接続できない git リポジトリも作成されます。また、parent_configuration_id を指定すると、呼び出しはドラフトになります。references/python-js-prod-and-drafts.md を参照してください。
11. Storage アクセスを有効にする前に、何が許可されるかを説明してください。 ワークスペースのアクセス範囲は、アプリが使用するテーブルに限らず、プロジェクト全体です。つまり、アプリはプロジェクトの Storage にあるすべてのテーブルを読み取れます。storage_access を有効にする際は、そのことを自分の言葉でユーザーに伝えてください。また、アプリが no-auth の場合は、URL を知っている人なら誰でもアプリを通じてデータにアクセスできることを、もう一度伝えてください。有効にすること自体は問題なく、通常はユーザーの希望に沿っていますが、黙って有効にしてはいけません。references/storage-access.md を参照してください。
12. ドラフトと本番アプリの間で、どちらの方向にも設定は引き継がれません。 それぞれ別の Storage 設定です。git のマージで移行されるのはソースコードだけで、それ以外は何も移行されません。ドラフト作成時にも設定は引き継がれません。modify_python_js_data_app が親から読み取るのは、リポジトリと認証情報だけです。そのため、反復作業中に設定した内容（storage_access、書き込み可能なテーブルを指定する storage、authentication_type、auto_suspend_after_seconds）はドラフトにしか設定されません。デプロイ前に本番アプリにも再設定する必要があります。特に問題になりやすいのは次の 2 点です。storage_access がないと、本番環境ではリクエスト時に missing required env vars: WORKSPACE_ID が発生します。storage の出力マッピングがないと、読み取りは引き続き動作しますが、アプリによる書き込みは失敗します。どちらもコードのリグレッションのように見えますが、そうではありません。references/python-js-prod-and-drafts.md §6 を参照してください。
13. ログに記録するのはメタデータだけにし、データは記録しないでください。 アプリのログからエンドユーザーの個人情報が漏れるおそれがあります。行数、列名、マスキングした SQL、どのコード分岐が応答したかを記録してください。セルの値、行の内容、レスポンス本文、生のリクエスト値は記録しないでください。console.debug(`${rows.length} rows, columns: ${Object.keys(rows[0] ?? {})}`) は ✓、console.debug(rows) やログに記録した顧客のメールアドレスは ✗ です。
14. 実行時に CDN から読み込むものがあってはなりません。 ブラウザーが読み込むすべてのスクリプト、スタイルシート、フォントは、ビルド時にバンドルするか、アプリ自身から配信してください。<script src="https://cdn…"> は使用しないでください。CDN の停止、パッケージの侵害、ページのコンテンツポリシーによって、アプリが外部要因で動作しなくなるおそれがあります。新しい Python／JS アプリは、React、Tailwind、Recharts がすでにバンドルされている templates/react-vite-app/ を出発点にしてください。別のスタックを使用している既存のアプリは、そのまま維持してください。そのアプリの流儀に沿って編集し、新たな CDN 依存関係を追加せず、ユーザーが許可した場合にのみテンプレートへ移行してください。変更によってフロントエンドの大部分を書き換えることになる場合は、移行を提案してください。
15. すべての Vite アプリに kaiPreview() を組み込んでください。 これにより、Keboola のアプリプレビューはアプリの描画を認識でき、ユーザーはページ内の特定箇所を示せるようになります。vite.config にこれがない既存の Vite アプリを変更する場合は、その変更と同時に追加してください。失敗しない限り、ユーザーに知らせる必要はありません。以前のインライン kaiPreviewErrorHandler は代わりになりません。kaiPreview() がこれに置き換わります。references/python-js-apps.md §Keboola's app preview を参照してください。