コーディングエージェントで構築する

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

前提条件：下の 2 つの初心者向けガイドを読み、Web ローカルセットアップを完了し、エディターでこのリポジトリをそのルートで開いてください。コーディングエージェントとは、プロジェクトを読み、ファイルを編集し、コマンドを実行する AI ツール（Cursor、Claude Code、Devin などのアシスタント）です。このページのすべての内容は、どれを使っても当てはまります。

早わかり用語：プロンプトはエージェントに貼り付ける指示テキストです。差分（diff）はエージェントが提案するファイル変更の一覧です。リポジトリルートは package.json を含む最上位フォルダーです — エージェントは常にそこから始めるべきです。

1. リポジトリルートの prompts/ フォルダーを開き、タスクに最も近いプロンプトをコピーします。new-landing-page.md が最初の試行におすすめです。

2. エージェントに貼り付けて <placeholders> を埋めます：欲しいルート、ページや画面が行うこと、誰が使えるか、成功がどう見えるか。そして 1 行追加します：コードに触れる前に llms.txt、次に AGENTS.md、次に .ai/PROJECT_CONTEXT.md を読むこと。

3. 編集前に、エージェントに変更するファイルと実行するチェックを列挙させます。終了したら差分をレビューします — 製品への実際の変更を承認するのです。

4. 公開、デプロイ、有料プロバイダーの呼び出しは、タスクプロンプトの一部にしません。明示的に承認する別のステップとして保持してください。

• 始める前に
• ターミナルの基本
• Web ローカルセットアップ

エージェントが読むファイル

リポジトリには、人間だけでなくエージェントのために書かれた小さなファイル群が同梱されています。このコンテキストを手動で貼り付ける必要はありません — エージェントを llms.txt に向ければ、残りは自分で読みます。

読む順序が重要です：llms.txt はマップ、AGENTS.md は境界を定め、.ai/PROJECT_CONTEXT.md は以前のセッションが学んだことを保持しています。境界をスキップするエージェントは、公開できないコードを生み出します。

プロンプトライブラリ

prompts/README.md がインデックスです。各ファイルは完全なブリーフです：貼り付けて <placeholders> を埋めるだけで、キットのルール（ハードコードされた色よりデザイントークン、独自パターンよりキットブロック）が一緒に伝わります。

ゼロから実行までの経路には、代わりに prompts/agent-setup.md を貼り付けます — 次に説明する無人セットアップを駆動します。

• エージェントにセットアップを実行させる

• agent-setup.md — エージェントでキットを立ち上げてデプロイする
• pick-a-style.md — 製品全体にデザインスタイルを適用する
• new-landing-page.md — キットブロックからマーケティングページを組み立てる
• new-app-screen.md — ワークスペースのアプリシェル内に画面を追加する
• restyle-product.md — 既存ページをキットのトークンでテーマし直す
• ui-audit.md — ルートに視覚とアクセシビリティの監査を実行する

エージェントにインストールとデプロイを任せる

キットはほぼ自分自身をセットアップできます。prompts/agent-setup.md を貼り付けると、エージェントが docs/agent-setup.md（同梱のランブック）をフェーズごとに実行します：事前チェック、環境ファイル、インストール、データベース起動、マイグレーション、アプリ起動、そして必要に応じて VPS デプロイ。各フェーズの後、そのフェーズの検証チェックポイントを実行し、主張ではなく実際の出力を報告します。

2 つのヘルパーがそれを安全に保ちます。scripts/setup-env.mjs は .env.example から env ファイルをブートストラップします：存在しないファイルだけを作成し、欠けているかプレースホルダーのシークレットだけを生成し、--check モードは書き込まずに検証します。docker-compose.dev.yml は完全にコンテナ化された開発環境（Postgres と Node 22 開発コンテナ）なので、エージェントはコンピューターにインストールされた Node.js を必要としません。

ここでは受け取ったリポジトリが重要です。Web リポジトリと All Platforms モノレポには、ランブック、compose ファイル、scripts/setup-env.mjs、prompts/ が同梱されています。スタンドアロンのモバイル・デスクトップリポジトリには、スコープ付きの llms.txt、AGENTS.md、.ai/ ミラードキュメント、docs/agent-security.md を含む厳選されたドキュメントが同梱されますが、セットアップランブックや compose ファイルはありません — それらのアプリが通信するバックエンドは Web リポジトリにあるからです。

• エージェント主導のセットアップを進める

エージェントがセッション間で記憶する仕組み

エージェントにはセッション間のメモリがありません — .ai/ フォルダーがそのメモリです。.ai/PROJECT_CONTEXT.md は最近何が、なぜ変わったかを記録します。その隣に、.ai/apps/web/src/reports.md のようなミラードキュメントが apps/web/src/reports.ts の背後にある、コードだけでは見えない決定を説明します。

契約は単純です：ファイルを編集する前にそのミラーを読み、変更が入ったらミラーを更新します。Open Threads のエントリは未完の作業を記録し、次のセッションが最初からではなく再開できるようにします。古いミラーはないより悪いものです — エージェントの差分をレビューするとき、変更されたファイルのミラーがコードと一緒に動いたか確認してください。

実行中アプリ自身のエージェント向け窓口

デプロイした製品もエージェントに応答します — これらのエンドポイントはリポジトリだけでなく実行中のアプリに存在します。

• GET /llms.txt — アプリが独自の llmstxt.org インデックスを配信します：ガイド、公開ページ、公開エンドポイントを絶対 URL で。
• POST /api/mcp — アプリのツールを公開するステートレスな MCP エンドポイント。sk_ API キーをベアラートークンとしてのみ受け付けます — ブラウザの Cookie セッションは適用されません。キーは Settings → Developers で作成します。
• GET /api/v1/openapi — 公開 REST API の OpenAPI 仕様。クライアントジェネレーターやエージェントツール向け。
• GET /api/health — ロードバランサーや稼働監視が呼び出す生存・依存プローブ。プロバイダー設定の種別を報告し、シークレットは決して返しません。
• /status — 各サブシステムの健全性を報告する人間が読めるページ。

エージェントの作業を正直にレビューする

完了したタスクは要約ではなく証拠です。エージェントの作業を採用する前に、docs/agent-security.md がデプロイをチェックするのと同じ方法で確認してください：

何かが間違っているときは差分を送り返します — 失敗したチェックを指名すると、エージェントは自分の作業を最も速く修正します。単独で試みるべきではなかったことについては、一度明示的に伝えてください。その境界はセッションの残りで保たれます。

• 検証ゲートとテストスイート

• 主張するテストを実行した — 結論ではなくコマンドとその出力を求めてください。
• シークレットがサーバー専用のまま — 新しいものに NEXT_PUBLIC_ や EXPO_PUBLIC_ プレフィックスがなく、レポートやコミットにキーが出力されていません。
• すべてのユーザー所有の読み書きが workspaceId でスコープされたまま — どのクエリもブラウザから送られた id を信用しません。
• 変更された各ファイルの .ai/ ミラーがコードと一緒に動きました。
• 公開、デプロイ、有料プロバイダーの呼び出しがあなたが承認した別のステップのまま — エージェントは自分でマージ、プッシュ、デプロイをしていません。
• ステップが 2 回失敗した場合、即興で回避せずに停止して失敗したコマンドを報告しました。