LLM ガイド

このドキュメントは、Databricks AppKit でコードを生成する AI コーディングアシスタント向けの規範的なガイダンスです。一貫性があり本番環境で使えるコードを生成できるよう、あえて明確な方針を示しています。

note

このファイルに記載されているのは、LLM 向けガイダンスの一部のみです。完全なガイダンスは、AppKit ドキュメントに基づく llms.txt ファイルを参照してください。

全体的なミッション

以下を使って Databricks 上で フルスタックの TypeScript アプリ を構築します。

本ガイドは、AppKit のソースリポジトリにアクセスできない場合でも利用できるように設計されています。公開パッケージの API と移植性の高いプロジェクト構成のみを使うようにしてください。

APIを勝手に作り出さないこと。不明な場合はドキュメントに示されたパターンに従い、@databricks/appkit および @databricks/appkit-ui のドキュメント化されたエクスポートのみを使用してください。
createApp() は非同期です。トップレベルの await createApp(...) を推奨します。それができない場合は void createApp(...) を使用し、Promiseのリジェクトを無視しないでください。
UIでは必ずローディング／エラー／空の状態を処理してください (Skeleton、エラーテキスト、空状態の表示を使用) 。
クエリパラメータには必ず sql.* ヘルパーを使用してください (クエリがパラメータを必要としない場合を除き、生の文字列や数値をそのまま渡さないこと) 。
SQL文字列を動的に組み立てないでください。:paramName を用いたパラメータ化クエリを使用します。
require() は決して使用しないでください。ESMの import/export を使用します。

tsconfig.json で "verbatimModuleSyntax": true を設定している場合は、型のみのインポートには必ず import type を使用してください (設定が厳格な環境では、ビルドが失敗することがあります) :

import type { ReactNode } from "react";
import { useMemo } from "react";

API リファレンスを表示します (ドキュメント参照用のみ。スキャフォールディングには使用しません) :

# ドキュメントの閲覧専用 - init/スキャフォールディングには使用しないこと
npx @databricks/appkit docs <query>

重要: 必ず最初に npx @databricks/appkit docs (query なし) を実行して、ドキュメントのインデックスを確認してください。パスを推測せず、インデックスから正しいパスを探してください。

例:

package.json に "type": "module" が設定されている
開発サーバー用に tsx が devDependencies に含まれている
dev スクリプトが NODE_ENV=development tsx watch server/server.ts を実行している
client/index.html が存在し、<div id="root"></div> と client/src/main.tsx を指すスクリプトが記述されている

await createApp({ plugins: [...] }) を使用している (または意図的に void createApp を使用している)
server() が含まれている (常に必須)
SQL を使用する場合: analytics({}) が含まれ、config/queries/*.sql が存在する
クエリは :param プレースホルダーを使用し、パラメータは sql.* で UI から渡している
クエリをワークスペース単位に絞り込む必要がある場合: :workspaceId を使用している

useMemo でパラメータオブジェクトをラップしている
ローディング／エラー／空の状態を明示的に扱っている
"json"/"arrow" を強制する理由がない限り、チャートは format="auto" を使用している
チャートは children ではなく props (xKey、yKey、colors) を使用している (Recharts ではなく ECharts ベースのため)
ツールチップを使う場合：ルートを <TooltipProvider> でラップしている