For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ja/docs/web/first-feature.md (or send Accept: text/markdown).

最初の機能を作る

スキーマから出荷済み画面までのエンドツーエンドの流れ。

このガイドについて質問

初心者向けのウォークスルー

前提条件: 以下の 2 つの初心者向けガイドを読み、Web ローカルのセットアップを完了し、エディターでルートにあるこのモノリポジトリを開きます。 Web 設定は apps/web/.env.local に属します。 Next.js はルート .env を読み取りません。デフォルトのフェイクモードの /dashboard はデータベースなしのデモです。 /auth には移行されたデータベースが必要です。

簡単に説明すると、ワークスペースは 1 つのチームの個別のユーザー、データ、設定です。サーバーは信頼できるバックエンドです。プロバイダーキーがブラウザーや電話コードに含まれないようにします。移行は、テーブルを作成または更新する、バージョン管理されたデータベースの変更です。 AI モデルは答えを返すエンジンです。モデルカタログは、使用可能なモデル ID と価格のサーバーのリストです。プロバイダーは、AI、電子メール、請求サービスなどの外部サービスです。資格は、ワークスペースで機能を使用できるようにする付与です。 Webhook は、あるサービスが別のサービスの URL に送信するメッセージです。

1. リポジトリルートで VS Code を開き、コーディングエージェントに apps/web/app/reports/page.tsx および apps/web/src/reports.ts を作成するように依頼します。レポートのフィールドと許可されるロールを指定します。サーバー側のメンバーシップチェックと、workspaceId でフィルターされたクエリが必要です。

2. サインインしたメンバーとして /reports を開き、ワークスペースのレコードのみが表示されることを確認します。

3. サインアウトした 2 番目のワークスペースアカウントを試します。どちらかがレコードを読み取ることができる場合は、サーバーチェックを停止して修正します。

カスタムコードの場合は、提供された prompts/README.md から始めて、最も近いプロンプト (アプリ画面の場合は prompts/new-app-screen.md、パブリックページの場合は prompts/new-landing-page.md) をコピーします。サーバー、データベース、またはプロバイダーの作業については、コーディングエージェントにこのガイドのタスクを与え、AGENTS.md、.ai/PROJECT_CONTEXT.md、および一致する .ai/ ミラーを読み取るように依頼します。ここで指定されている正確なソースファイルを調べてください。ファイルをリストし、編集前にチェックします。ワークスペースの所有権とサーバーのみの秘密を保持します。そして差分を見せてください。必要な動作、入力フィールドと出力フィールド、許可されるロール、予想される成功とエラー、テストアカウント、プロバイダー、またはデバイスを指定します。サンプル値を使用します。絶対に本当の秘密を貼り付けないでください。

始める前に

【端末の基本】(/docs/web/terminal-basics)

ルートを作成する

apps/web/app/ の下にページを追加します。ダッシュボードまたはコンテンツルートから開始して、そのセッションとアクティブワークスペースの解決を再利用します。フォルダーに page.tsx が含まれている場合、ルートは存在します。保護された読み取りにはサーバーコンポーネントを使用します。

apps/web/app/reports/page.tsx
apps/web/src/reports.ts
.ai/apps/web/app/reports/page.md
.ai/apps/web/src/reports.md

サーバー上の所有権を解決する

既存の認証/ワークスペースヘルパーを介して、サインインしている ID とアクティブなワークスペースを読み取ります。レコードをロードする前にメンバーシップを確認してください。解決された workspaceId によってすべてのクエリをフィルターします。フォームまたはモデルの出力から所有者識別子を決して取得しないでください。

管理アクションに対する所有者/管理者の権限を確認してください。機能が有料の場合は、保護されたデータを返す前に、読み取りまたはアクションの境界でその権利を確認します。非表示のボタンはアクセスを強制しません。

アクセスとリカバリを確認する

匿名アクセス、有効なメンバー、別のワークスペースのメンバー、取り消されたセッション、および必要なロールをテストします。回復アクションを使用して、空の状態とロード失敗状態を追加します。ルートをパブリックサイトマップから除外し、そのプレフィックスをロボット禁止に追加します。

レコードをモデル化する

すべてのプロダクトレコードはデータベーススキーマから始まります。packages/db に workspaceId カラムを持つテーブルを追加し、マイグレーションを生成し、読み書きの前にワークスペースを解決するリポジトリヘルパーを書きます。

// packages/db/src/schema.ts
export const ideas = pgTable("idea", {
  id: uuid().primaryKey(),
  workspaceId: uuid().notNull().references(() => workspaces.id),
  title: text().notNull(),
  createdAt: timestamp().defaultNow(),
});

corepack pnpm --filter @supastack/db db:generate

アクションを認可する

セッション、ワークスペース、エンタイトルメントの順に解決する server action を作ります。zod スキーマで入力を検証し、リポジトリ経由でミューテーションを実行し、インターフェースが描画できる型付き結果を返します。

順序が重要です：ワークスペースの所有権を確認する前に書き込むミューテーションは、すでに境界を越えています。所有権はサーバーで導出してください——ブラウザが送る workspace id を信用してはいけません。

サーフェスを組み立てる

共有コンポーネントとトークンでページを組み立てます——キットの blocks と ui-web プリミティブが一般的なパターンをカバーします。ローディング・エラー・空状態を処理してください。ハッピーパスしか描画しない機能は完成ではありません。