> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

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

コーディングエージェントにタスクを渡す：エージェントが読むファイル、貼り付け可能なプロンプトライブラリ、無人セットアップ、そしてあなたが主導権を保つためのレビュー。

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

前提条件：下の 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. 公開、デプロイ、有料プロバイダーの呼び出しは、タスクプロンプトの一部にしません。明示的に承認する別のステップとして保持してください。

[始める前に](https://supastack.dev/ja/docs/web/before-you-start.md)

[ターミナルの基本](https://supastack.dev/ja/docs/web/terminal-basics.md)

[Web ローカルセットアップ](https://supastack.dev/ja/docs/web/ship-in-5-minutes.md)


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

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

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

| ファイル | エージェントにもたらすもの |
|---|---|
| `llms.txt` | リポジトリの入口マップ — 読む価値のあるすべてのドキュメントとセキュリティプロトコルが読む順序で |
| `AGENTS.md` | 譲れない境界：さらに承認するまではローカル作業のみ、workspaceId のスコープ、サーバー専用シークレット |
| `.ai/PROJECT_CONTEXT.md` | セッションをまたぐメモリ — 最近何が、なぜ変わったか。コード変更前に読む |
| .ai/ ミラードキュメント | 重要なファイルの隣にある対応する .ai/<path>.md メモ。ファイルごとの決定と未解決スレッドを記録 |
| `docs/agent-setup.md` | 無人ランブック — インストール、マイグレーション、デプロイの各フェーズに検証チェックポイント付き |
| `prompts/` | オーナーが最もよく頼む作業のための貼り付け可能なタスクプロンプト |
| `docs/agent-security.md` | 受け入れチェックリスト — 認証、ワークスペースと RLS のチェック、マスク済みログ、デプロイの証拠 |
| `.env.example` | 環境設定の完全な目録 — エージェントはこのファイルにない変数名を決して作りません |


## プロンプトライブラリ

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

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

[エージェントにセットアップを実行させる](https://supastack.dev/ja/docs/web/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 リポジトリにあるからです。

[エージェント主導のセットアップを進める](https://supastack.dev/ja/docs/web/agent-setup.md)


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

エージェントにはセッション間のメモリがありません — `.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` がデプロイをチェックするのと同じ方法で確認してください：

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

[検証ゲートとテストスイート](https://supastack.dev/ja/docs/web/testing.md)

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


設定を続けるには、[外部アカウントを作成する](https://supastack.dev/ja/docs/web/external-accounts.md)をご覧ください。


## 次へ

[外部アカウントを作成する](https://supastack.dev/ja/docs/web/external-accounts.md)