nocobase-ai-builder

目標

ユーザーのビジネス上の要望を、まとまりのある本番運用を想定した AI Portal アプリケーションに仕上げます。プロダクト設計とソース実装の両方を担います。ユーザーから情報アーキテクチャ、ページ構成、文言、ビジュアルの方向性について詳細な情報が提供されていない場合でも、機械的な CRUD の例を作るだけで終わらせてはいけません。

エントリー条件

• portalType === "ai" の Portal レコードが解決された後は、すべての開発リクエストでこのスキルを使用してください。
• 利用可能な場合は、nocobase-portal-manage から解決済みの Portal 名、環境、ローカルソースパスを引き継いでください。このスキル内で別の Portal を解決してはいけません。
• 実際のローカルソースディレクトリがない状態で、ソースの編集を開始してはいけません。nb portal list -j または nb portal info <portal> -j で、選択した AI Portal の developmentPath／localPath／ローカルソースパスが空の場合は、Portal のワークフローを通じて最初に nb portal pull <portal> を実行します。その後、Portal の情報／一覧を再度読み込み、取得した開発ディレクトリに移動してからこのスキルを適用してください。
• ソースストレージの設定を作業ディレクトリとして扱ってはいけません。sourceStorage、git_repo、git_branch、git_path、--git-path、リポジトリのサブディレクトリ、デプロイ／ストレージのパスは、Portal のソースを pull／push／deploy する場所を示すものであり、ソース編集用のローカル開発ディレクトリではありません。ただし、nb portal pull の読み戻しで、同じパスが developmentPath／localPath として明示的に返された場合は除きます。
• すでに認識可能な AI Portal のソースプロジェクトで作業している場合、別の Portal がリクエストで指定されていない限り、そのプロジェクトを直接使用してください。
• @nocobase/portal-template-default は、ベーステンプレートの正規パッケージとして扱ってください。ユーザーが明示的に依頼範囲を限定していない限り、Portal のアップグレードとは、必要な @nocobase/portal-sdk とインストール済みの Registry のマイグレーションを含め、最新のベーステンプレートのソース変更をユーザーのプロジェクトに安全に適用することです。パッケージまたは互換性のバージョンだけを変更することではありません。
• 元のビルドリクエストを、その Portal のソースを編集し、検証する許可として扱ってください。コード編集について、改めて確認を求めてはいけません。
• ファイルを変更する前に、プロジェクトの AGENTS.md と適用されるローカルの指示を読んでください。
• 関係のない作業ツリーの変更は保持してください。ユーザーから依頼されない限り、push や deploy を行ってはいけません。

必須ワークフロー

1. 現在のアプリケーションを調査する

設計やコードの作成に着手する前に、質問を起点として段階的に調査してください。通常の前提条件として、リポジトリ全体の完全な一覧を作成してはいけません。

調査範囲は、現在のタスクまたはマイルストーンに限定してください。具体的な疑問への回答や、現在の変更の裏付けに必要な場合にのみアプリケーションのソースを調べ、関係のないレイヤーは必要になるまで保留してください。

1. プロジェクトの指示、パッケージスクリプト、依頼に直接関係するルートまたは機能のエントリーポイントを読みます。
2. ファイルを開く前に、ファイル名、シンボル、ルート、エクスポート、インポートで検索します。最も近い実装と、その公開契約を理解するために必要な直接の依存関係のみを調べます。
3. 該当ファイルから、ブランディング、ナビゲーション、テーマ、認証、ACL、i18n、API、アセットに関する規約を特定します。安全な実装を妨げる未解決の疑問がある場合にのみ、検索範囲を広げます。
4. 実際の NocoBase メタデータ、Swagger ドキュメント、レスポンス、または既存コードから、コレクション、フィールド、関連付け、アクションを確認します。API 連携が対象の場合は、nb api swagger list/get を使用して、関連するドキュメントの名前空間を必要最小限の範囲で読みます。バックエンドの契約を決して推測してはいけません。
5. 新規システムまたは大幅に再設計するシステムでは、無関係な Registry 項目やアプリケーション機能を監査せずに、置き換える必要があるテンプレートデモの範囲を特定します。

対象箇所、最も近い適用可能な実装契約、タスクに必要な API 契約、および適切な検証方法が分かった時点で、調査を終了してください。全体像を把握することだけを目的に、src、registry、src/extensions を再帰的に読み込んではいけません。リポジトリ全体の調査は、明示的な監査、アップグレード、移行、または横断的なリファクタリングの場合に限ります。

依頼されたサーバー側機能について、信頼できる既存の実装例がない場合は、実装可能だと主張する前に Swagger を読む必要があります。該当するコレクションまたはプラグインの名前空間を特定して取得し、エンドポイント、メソッド、パラメーター、リクエスト本文、レスポンス、文書に記載された権限要件を確認してください。利用可能なドキュメントに必要な機能の記載がない場合、API を推測したり、その機能がサポートされていると示したりしてはいけません。不足している契約を報告し、バックエンドまたはプラグインの変更が必要かどうかを判断してください。

現在のマイルストーンでアプリケーションの構造や UI の基盤を編集する場合は、プロジェクト規約を読んでください。データ、認証、i18n、ランタイム設定、またはアセットを実装する場合は、NocoBase ランタイムを読んでください。

2. コーディング前にシステムを設計する

システム設計の開始時に、国際化が必要かどうかを明示的にユーザーに確認してください。必要な場合は、主要ロケールと追加で必要なロケールを確認してください。依頼ですでに指定されている場合は、再度確認しないでください。

ユーザーの依頼をもとに、簡潔な内部向けプロダクト概要を作成してください。

• システムの目的と仮のタイトル。
• 主なユーザーの役割と、頻繁に行うタスク。
• 情報アーキテクチャとメニュー階層。
• ページ一覧と各ページの役割。
• 主要ページのコンテンツ、アクション、状態。
• ルート、ダイアログ、ドロワー、サブページのモデル。
• フロントエンドのアクセス制御モデル。
• ビジュアルの方向性、情報密度、テーマ、レスポンシブ動作。

実装計画は、段階的に更新し、マイルストーン単位で管理してください。システム全体を構築する場合は、後続のマイルストーンを簡潔に示し、現在の取り消し可能なマイルストーンを詳しく計画してください。次のマイルストーンを調整する前に、現在のマイルストーンを実装して検証し、専門的なスキルはその作業が必要になった時点で読み込んでください。

詳細が不足している場合は、妥当なプロダクト上の判断をしてください。不足している選択肢によってビジネス上の動作、データ、セキュリティ、または取り消せない操作が大きく変わる場合に限り、質問してください。

Users や CRUD の例からプロダクト全体を導き出さないでください。ビジネスに合わせてページ構成を調整してください。ワークスペースでは作業を、概要ページでは対応可能なシグナルを、詳細ページでは関連するコンテキストを整理して表示し、フォームでは実際のワークフローに沿ってください。

スターターのサイドバーは、固定されたアプリケーションシェルではなく、プリセットの参考として扱ってください。プロダクト設計を最適化するため、トップナビゲーション、サイドバーナビゲーション、セカンダリメニュー、コンテキストタブ、またはそれらを控えめに組み合わせるなど、システムに最も適したナビゲーション構成を検討してください。これは指針であり、サイドバーの置き換えを必須とするものではありません。どのパターンを選ぶ場合でも、ナビゲーションを分かりやすく保ち、サポート対象のデバイスサイズ全体で、ルートへの移動、直接アクセス、レスポンシブレイアウト、操作性を確保してください。

3. ロールと権限を設計・設定する

システム全体を構築する場合は、Todo リストまたは実装計画に、ロールと権限に関する専用タスクを含めてください。プロジェクトの調査、ルーティング、ページ実装の中に埋もれさせないでください。

• 実際のユーザーロール、メンバーシップ、ロールごとの責任を定義してください。システムに実質的に区別のない単一ロールしかない場合は、権限設計を黙って省略するのではなく、その判断を明記してください。
• Portal に入れるロールを決定し、設定してください。
• 解決済みの Portal に対してロールを作成する際は、その Portal の uid または正確な識別情報を nocobase-acl-manage に渡し、Portal への明示的なアクセス許可をロール作成の一部として扱ってください。続行する前に、ロールと Portal の関連付けを検証してください。
• フロントエンドの表示に依存する前に、各ロールのサーバー側のリソース、アクション、スコープ、フィールドのポリシーを設定し、検証してください。
• 許可されたユーザーと拒否されたユーザーの両方について、フロントエンドのメニュー、ルート、ページ、領域、フィールド、アクション、レコードの動作を設計してください。
• インストール済みの ACL の境界を、適切な最小スコープで使用してください。ページ全体には AclPage、独立した保護パネルには AclRegion、フィールドまたはフィールドグループには AclField、コントロールやレコード操作には CanAccess または ACL 対応の組み込みアクションコンポーネントを使用してください。ローカルのブール値やハードコードされたロール比較で、これらのチェックを重複させないでください。
• コントロールを非表示にするだけでは、セキュリティ対策として不十分です。NocoBase のサーバー ACL を最終的な権限の基準としてください。

ロール、メンバーシップ、Portal へのアクセス、サーバー ACL の変更には nocobase-acl-manage を使用してください。フロントエンドの権限を実装する前に、ルーティングとアクセス制御を最後まで読み、少なくとも 1 つの許可された状態と 1 つの拒否された状態について、ロールまたは権限を検証してください。

4. ナビゲーションと URL を確立する

ページ内部を実装する前に、ナビゲーションと URL の構成を設計してください。

• 表示されるすべての末端メニューは、実際にアクセス可能なルートへ遷移する必要があります。
• サイドバーに表示するページには、ルートと Refine の resource の両方を宣言する必要があります。ルート要素だけではメニュー項目は作成されません。
• プレースホルダーのメニュー項目や空のグループは作成しないでください。
• ダイアログ、ドロワー、詳細画面、エディター、意味のあるサブページには、直接開く操作、再読み込み、共有、ブラウザー履歴に対応した独立した URL が必要です。
• 各作成、編集、表示の操作を実装する前に、それぞれをドロワー、ダイアログ、全画面ページのどれにするか決めてください。resourceAction は Refine のパスに関するメタデータであり、表示形式の選択肢ではありません。
• 各リソースの作成、編集、表示の操作には、正規の resourceAction パスを 1 つだけ登録してください。同じ画面を別のリスト、詳細画面、ワークフローのホストから開く場合は、ビジネスコンテンツを再利用し、そのホストが所有する通常の相対子ルートを使ってください。正規の絶対 URL に移動して、現在のワークフローを置き換えてはいけません。
• コンテキストに応じた子画面を開く際は、検索文字列とハッシュを含む、遷移元の URL 全体を保持してください。閉じるときは、元の URL が分かる場合はそこへ戻し、直接開かれた場合は解決済みの親ルートに戻してください。

ナビゲーション、ルート、ダイアログ、ドロワー、サブページ、ロール、権限を追加または変更する場合は、Routing and Access を最後まで読んでください。

5. アプリケーションが所有するコードを実装する

• ルート、ページ、コンポーネント、フック、ユーティリティ、翻訳を含む、アプリケーションが所有するビジネス機能はすべて、プロジェクトの現在の構成に従って、アプリケーションが所有する src ディレクトリに配置してください。そのために src/extensions/<business-feature> を作成してはいけません。
• src/extensions はインストール済みの Registry 拡張機能のソース用に確保し、src/components/ui は shadcn の基盤として扱ってください。どちらも、原則として変更しないでください。
• 拡張機能や基盤コンポーネントを再利用する場合は、アプリケーションが所有するコードからインポート、再エクスポート、ラップ、または合成してください。その拡張機能や基盤の変更がタスクで明示的に求められており、合成では要件を満たせない場合に限り、ソースを変更してください。変更差分は最小限に抑えてください。
• プロジェクトにすでに存在する React、TypeScript、Refine、React Router、Tailwind、shadcn Base UI のパターンを使用してください。
• Ant Design や、Ant Design ベースの NocoBase クライアントコンポーネントを導入してはいけません。
• Base UI のレンダリング契約を守ってください。制御された Select が列挙型のキーやレコード ID を保持する場合、SelectValue でユーザー向けラベルを解決して表示し、生の値をそのまま見せないでください。
• Portal の API クライアント、データプロバイダー、認証セッション、ACL ランタイム、i18n ランタイム、システム設定、ベースネーム、アセット URL ヘルパーを再利用してください。
• チャート、KPI、グループ化された集計には NocoBase の query アクションを使用してください。すべてのリストレコードを取得して、サーバー規模の分析をブラウザー上で導出してはいけません。
• 必要に応じて、読み込み中、空、エラー、未認証、成功、破壊的操作の確認、レスポンシブ表示の各状態に対応してください。
• セマンティックトークンと共通の合成パターンを使用してください。場当たり的な色、任意の寸法、過剰な className、shadcn のデフォルトに対する不要な書き換えは避けてください。
• テンプレートのルートおよびページのエラーバウンダリーを維持してください。チャート、AI の出力、サードパーティーウィジェットなど、個別に復旧可能なレンダラーには、region スコープでインストール済みの NocoBaseErrorBoundary を使用してください。ビジネスコードでエラーバウンダリーの仕組みを再実装してはいけません。

実際のシステムを構築する場合は、アプリケーションの表示部分からテンプレートの見た目を取り除いてください。アプリケーション層でデモのナビゲーションとルートを非表示にするか登録解除し、スターターのブランディングと文言を置き換え、対象ユーザーにとって役立つページを最初にアクセスできるページにしてください。デモ項目を隠すためだけに、インストール済みの拡張機能ソースを削除してはいけません。

6. 代表的なデモデータを登録する

新しいシステム、または大幅に再構築したシステムでは、データモデルと主要なワークフローが機能するようになった後、一貫性のあるデモレコードを登録します。これはビルドの成果物の一部であり、任意の追加作業ではありません。

• 実際の NocoBase API または CLI コマンドを使ってレコードを作成します。フロントエンドのコンポーネントに、業務用のモックレコードをハードコードしないでください。
• ランディングページ、リスト、詳細画面、フィルター、ダッシュボード、AI コンテキストを有意義なものにするために必要な主要コレクション、関連付け、選択肢、担当者、ステータス、日付を網羅します。
• 識別しやすいデモ用の識別子を使用し、再実行時に制御不能な重複が生じないよう、まず既存のレコードを確認します。デモ用の領域を確保するために、既存のユーザーデータを上書きまたは削除しないでください。
• 無関係なプレースホルダーですべてのフィールドを埋めるのではなく、データ上で少なくとも1つの現実的なエンドツーエンドのワークフローを実行します。
• 対象に実際の業務データが含まれている場合、レコード作成の許可がない場合、または API に操作を拒否された場合、この手順を黙って省略しないでください。その理由と、残っているデータ設定作業の詳細を報告します。

7. テーマを選択して適用する

ユーザーがテーマを指定していない場合は、システムに適した、落ち着きのある一貫したデザイン方針を選び、作業を止めずに進めます。アプリケーションレベルのセマンティックトークンと共通のレイアウトルールを使って、テーマの動作を定義します。

ユーザーがテーマを選びたい場合は、https://www.shadcn.io/theme を案内し、選択したテーマ名、Registry URL、または生成されたインストールコマンドを受け取ります。作業ツリーとインストーラーの差分を確認し、アプリケーションのブランディングにテーマを統合します。カスタマイズ済みの src/components/ui ファイルを、確認せずに上書きしないでください。テーマはビジュアル面の基盤を提供するものであり、業務固有の情報設計、コンテンツ、状態、インタラクションに取って代わるものではありません。

8. 意味のある AI インタラクションを実装する

システムの主要なワークフローが AI なしで動作するようになったら、完成したページを確認し、AI によって作業を大幅に削減したり、意思決定を改善したりできるインタラクションを特定します。有力な候補には、自然言語による検索、要約、抽出、分類、草案作成、説明、分析のガイド、現在のページやレコードのコンテキストに基づく複数ステップの支援があります。

AI Portal システムを完全に構築するには、信頼できる、コンテキストに応じた AI インタラクションを少なくとも 1 つ実装してください。評価やアイデアの一覧だけでは、この要件を満たしません。ビジネス上の動作やセキュリティに重大な影響がない場合は、追加の確認を求めず、最も適切なインタラクションを選んでください。

• 選択したインタラクションに最も近い、インストール済みの AI サンプルを対象を絞って探します。そのサンプルと公開コントラクト、および再利用に直接必要な依存関係だけを確認してください。インストール済みの AI 拡張機能、フック、デモ、ツールレンダラーをすべて列挙しないでください。
• Portal AI インタラクションに、開発者カテゴリの従業員を追加、バインド、公開、または選択してはいけません。nathan、dara、lina、orin など、開発者だと分かっているユーザー名は、検出 API から返された場合でも除外し、適切なビジネス従業員を使用するか、専用の従業員を作成してください。
• ページレベルの AI インタラクションを実装する前に、要件に最も近い、インストール済みの Page Context シナリオを探します。既存のパターン（ページ要素の手動選択、Shortcut タスクコンテキスト、会話プリセットコンテキスト、継承した AIPageContextScope、Form filler、または権限を考慮したカスタムフロントエンドツール）を優先し、そのコンテキストとタスクのコントラクトを再利用してください。
• 関連するページ、レコード、選択内容、またはアクションの近くに、コンテキストに応じたエントリーポイントを設けることを優先します。共有されるコンテキストと生成される結果がユーザーに明確に伝わるようにしてください。
• 完全な非 AI ワークフローを維持してください。AI の出力によって、検証、ACL、確認、またはサーバー側のビジネスルールを暗黙に回避してはいけません。
• 既存の AI ランタイムと従業員／ツールのコントラクトを再利用してください。従業員、モデル、ツール、またはプロンプトの設定が必要な場合は、nocobase-ai-employee を使用してください。
• 装飾的なチャットボタンや、裏付けのない機能で要件を満たそうとしてはいけません。信頼できるインタラクションを支える従業員、モデル、ツールのコントラクト、またはランタイムがない場合は、不足している前提条件を特定し、AI 部分が未完了であると報告してください。黙って省略してはいけません。

9. テストで結果を検証する

実装と並行して検証を設計します。変更した動作とシステムの主要なワークフローを保護する、価値のある最小限の自動テストを追加または更新してください。カバレッジやテスト数を増やすだけのテストは作成しないでください。

バックエンドデータ、認証、ACL、データプロバイダーのモックなしで実行できる、純粋なロジックやローカルなコンポーネント操作にはフロントエンドテストを使用します。認証、データ、ロールと権限、ルーティング統合、ファイル、AI、ユーザーの一連の操作には、実際の NocoBase 環境に対する E2E テストを使用します。主要な成功ワークフローに加えて、代表的な高リスクの拒否、エラー、または復旧のパスもカバーしてください。

型チェック、関連するフロントエンドテスト、関連する E2E テスト、および本番ビルドを実行します。自動アサーションでは妥当に表現できない探索的なビジュアル確認やレスポンシブ確認に限り、対象を絞ったブラウザー検査を使用してください。再現可能な受け入れテストの代わりにしてはいけません。

大規模なページまたはシステムの構築を完了する前に、検証を読んでください。

10. 既存の Portal を安全にアップグレードする

Portal のアップグレードは、パッケージのみの更新ではなく、ソースの移行として扱ってください。アプリケーション独自のバージョンは、継承したベースリリースの正確なバージョンとは独立させ、nocobase.defaultTemplateVersion で管理してください。

既存の Portal のテンプレート、Portal SDK のメジャーバージョン、またはインストール済み Registry ソースを変更する前に、Portal Project Upgrades を最後まで読んでください。ユーザーコードは置き換えられないものとして扱い、まず復旧ポイントを確立して検証してください。プロジェクトが Git リポジトリでない場合は、別途バックアップも作成してください。対象バージョン、ソースへの影響、競合への対処方法、検証方法、ロールバック計画を提示し、編集を始める前にユーザーから明示的な確認を得てください。その後、アプリケーション所有のコードを上書きせずに、必要なベーステンプレートのソースをマージし、インストール済み Registry アイテムは個別に更新してください。互換性メタデータを変更するのは、対応するソースが実際に取り込まれ、検証された後に限ります。

連携の境界

• 要求された UI でバックエンドのコレクションやフィールドの作成・変更が必要な場合は、nocobase-data-modeling を使用してから、ソース実装のためにこちらに戻ってください。
• ロール、ユーザーとロールの所属関係、Portal へのアクセス、またはサーバー側のリソースポリシーの変更が必要な場合は、nocobase-acl-manage を使用してください。フロントエンドのアクセス制御の実装は、このスキルで行ってください。
• AI 従業員の検索、ライフサイクル、モデル、ツール、プロンプト設定には、nocobase-ai-employee を使用してください。
• Portal の作成、ソース同期、開発ライフサイクル、プッシュ、デプロイ、破棄の操作には、nocobase-portal-manage を使用してください。
• 実行時に必要な機能が不足している場合は、そのことを診断して報告し、NocoBase のインフラを並行するローカル実装で置き換えないでください。

参照資料の読み込みマップ

このマップは必要なタイミングで参照するためのガイドであり、事前にすべて読むためのチェックリストではありません。現在のマイルストーンに必要な参照資料のみを読み込み、今後のマイルストーン向けの参照資料は読まないでください。

参照資料	読むタイミング
プロジェクトの規約	構成、ブランディング、テーマ、共通 UI、拡張機能の使用、またはスターターコンテンツを変更するとき
NocoBase Runtime	データ、API アクション、認証、i18n、システム設定、ベース名、またはアセットを使用するとき
ルーティングとアクセス制御	ナビゲーション、URL サーフェス、ロール、ACL、または保護されたコントロールを追加するとき
検証	ページ、機能、テーマ、またはシステム全体を検証するとき
Portal Project Upgrades	既存の Portal テンプレート、Portal SDK のメジャーバージョン、またはインストール済み Registry ソースをアップグレードするとき

完了時の報告

次の内容を報告してください。

• 設計したシステムまたは機能
• 重要な製品上および技術上の判断
• 変更したファイルと統合ポイント
• 実際の証拠に基づいて確認したデータ、ルート、アクセス制御に関する前提
• 作成した代表的なデモデータ、または作成できなかった明確な理由
• 提供したコンテキストに応じた AI インタラクション、またはそれを妨げている実行時の前提条件の不足箇所
• 実施した自動チェックと受け入れシナリオ
• 未完了の項目、またはサーバー設定が必要な項目
• プッシュやデプロイを自動で行わず、任意の次のステップを提示すること