• 日本語

      • AI Agent と協働して構築

      前提条件

      このページを読む前に、AI Portal 構築クイックスタートに従って最初の Portal を動かせていることを確認してください。

      AI Portal の日常的な開発は、AI Agent との会話そのものです。欲しいページを伝えると AI がコードを書き、あなたはブラウザで結果を確認します。

      Portal ディレクトリの中で作業する

      始める前に、まず Portal のソースコードディレクトリに移動し、そこで AI Agent を開くことをおすすめします。そうすれば Agent は最初から正しいコンテキストに置かれ、AGENTS.md と既存のコードを読めるようになります。

      まずディレクトリの場所を調べます：

      nb portal info main

      出力に含まれる開発パスが、Portal のソースコードがある場所です。そこに cd してから、AI Agent を開きます：

      cd <開発ワークスペースのディレクトリ>

      あとは要件を伝えるだけです：

      nocobase の main portal に注文リストページを追加してください

      AI にまず読ませてから書かせる

      テンプレートのルートディレクトリには AGENTS.md があり、このプロジェクトの開発規約が書かれています。src/extensions にある既存の実装を優先して再利用すること、UI コンポーネントのカスタマイズは基礎コンポーネントを直接変更するのではなく合成で行うこと、Ant Design を導入しないこと、などです。このファイルを読める AI Agent は、これらの規約に自動的に従います。

      AGENTS.md には自分のプロジェクトの規約を追記することもできます。命名の習慣、業務用語、触ってほしくないディレクトリなどです。書いておけば毎回の会話で有効になるため、繰り返し説明する必要がなくなります。

      src/extensions の下にはいくつかの組み込み拡張があります。その中の nocobase-users-example は、リスト、作成、編集、詳細がすべて揃った完全な CRUD ページです。ゼロから説明するより、これを参考にして新しいページを書かせるほうがはるかに手間がかかりません：

      nocobase-users-example の書き方を参考にして、商品管理ページを作ってください

      プロンプト例

      シナリオ A：新しい業務ページを作成する

      次の 3 点を明確に伝えれば十分です——ページに何があるか、データはどこから来るか、どう操作するか：

      顧客管理ページを追加してください：
テーブルには名前、電話番号、メール、作成日時を表示し、名前で検索できるようにしてください。
行をクリックすると詳細ドロワーが開き、ドロワー内でそのまま編集して保存できるようにしてください

      シナリオ B：既存ページを改修する

      変更系の要件では、変えたい箇所を具体的に伝えます。ページ全体を説明し直す必要はありません：

      顧客リストにステータスフィルターを追加してください。
選択肢は「フォロー中」「成約済み」「失注」で、デフォルトでは絞り込まないようにしてください

      シナリオ C：新しいデータテーブルをつなぎ込む

      データテーブルを作成したら、それに対応するページを AI に生成させます。AI はフィールド定義を読み取り、それに基づいてフォームコントロールとリストの列を決めます：

      contracts テーブルを作ったので、対応する一式の CRUD ページを作ってください

      テーブルがまだない場合は、先にデータモデリングで AI にデータ構造を設計させてから、ページ作成に戻ります。

      シナリオ D：プロトタイプから画面を再現する

      デザイン案や既存の HTML プロトタイプがある場合は、そのまま AI に渡します：

      このプロトタイプ画像のとおりにトップページを作ってください。
配色とレイアウトはそのままにして、データは orders テーブルにつないでください

      シナリオ E：認証方式を追加する

      サーバー側で認証方式を有効化したら、ログインページにも対応するフロントエンドの実装が必要です：

      NocoBase で DingTalk ログインを有効化したので、ログインページに DingTalk ログインボタンを追加してください

      協働のコツ

      小さく刻んで進める。 1 回につき 1 ページ、または 1 か所の変更を AI にやらせて、結果を確認してから次に進みます。一度に 5 ページ分を説明すると、問題が起きたときにどのステップでずれたのか判断しにくくなります。

      開発サーバーは起動したままにする。 nb portal dev main を起動しておけばホットリロードが効くので、AI が変更するたびにすぐ結果を確認できます。フィードバックループが最短になります。

      エラーは正確に伝える。 ページが真っ白、ビルド失敗、API が 403——完全なエラーメッセージやスクリーンショットを AI に貼り付けてください。AI に推測させないことです。通常は数回のやり取りで解決します。どの層の問題かを自分で先に切り分ける必要はありません。

      error

      よくある質問

      AI が間違えたときはどう戻せばよいですか？

      Portal のソースコードを Git で管理している場合は、git checkout で戻すだけです。デフォルトの nocobase source storage を使っている場合は、source storage から取得し直してローカルを上書きできます：

      nb portal pull main --force

      --force は開発ワークスペースを削除してから取得し直すため、実行前に残しておきたい変更がないことを確認してください。このトレードオフを避けるには、早めにソースコードを Git 管理に切り替えることをおすすめします。具体的な方法はデプロイとソース管理を参照してください。

      ビルドが失敗したときはどう調べればよいですか？

      まずローカルで一度ビルドを実行し、完全なエラーを確認します：

      nb portal deploy main

      TypeScript の型エラーと依存関係の不足が最もよくある 2 つの原因です。エラーを AI に貼り付けて修正させれば済みます。

      手動でのコード変更と AI の変更は競合しますか？

      競合しません。Portal のソースコードは普通のフロントエンドプロジェクトなので、いつでも自分で変更できますし、その続きを AI にやらせることもできます。同じタイミングで同じファイルを変更しない限り、問題はありません。

      関連リンク