> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 手順書を生成する

> AI に Web アプリを探索させ、手順書を自動構築します。

## 概要

`generate` コマンドはブラウザを開き、指定したゴールに基づいて AI が Web アプリを探索し、構造化された手順書を出力します。生成された手順書は AI コストゼロで無制限に[実行](/ja/guides/execute-runbook)できます。

## 前提条件

* **Node.js** 18 以降
* **AI プロバイダーの API キー**（[AI プロバイダーを設定する](/ja/guides/ai-setup)を参照）
* **コンテキストファイル**（推奨）— 操作対象アプリの情報

## ステップバイステップ

<Steps>
  <Step title="コンテキストとシークレットを準備">
    操作対象アプリの補足情報を記載した `context.md` を作成します。ログイン URL、画面遷移のヒント、特殊な UI パターン、業務ルールなどを含めます：

    ```markdown theme={null}
    # アプリ情報

    - ログインページ: https://app.example.com/login
    - ログイン後、ダッシュボードは /dashboard にある
    - 「CSV エクスポート」ボタンは右上のツールバーにある
    - ステージング環境を使用（本番環境ではない）
    ```

    ワークフローに認証情報が必要な場合は `secrets.json` を作成します。全値が sensitive として扱われ、ログでマスクされます：

    ```json theme={null}
    {
      "email": "user@example.com",
      "password": "s3cret!"
    }
    ```
  </Step>

  <Step title="generate コマンドを実行">
    ```bash theme={null}
    npx @refrainai/cli generate -- \
      --url "https://app.example.com/login" \
      --goal "ログインしてダッシュボードに移動する" \
      --output ./login-flow.yaml \
      --context ./context.md \
      --secrets ./secrets.json \
      --headless false
    ```

    主要フラグ：

    | フラグ                | 説明                       |
    | ------------------ | ------------------------ |
    | `--url`            | 開始 URL（必須）               |
    | `--goal`           | AI が達成すべきゴール（必須）         |
    | `--output`         | 手順書の保存先パス（必須）            |
    | `--context`        | コンテキストマークダウンファイルのパス      |
    | `--secrets`        | シークレット JSON ファイルのパス      |
    | `--headless false` | ブラウザウィンドウを表示して AI の動きを確認 |

    全フラグは [CLI リファレンス: generate](/ja/cli/generate) を参照してください。
  </Step>

  <Step title="AI の探索を確認（任意）">
    `--headless false` を指定すると、AI がアプリをナビゲートする様子をリアルタイムで確認できます。

    AI が行き詰まったり誤った方向に進んだ場合は、**Enter** キーまたは **p** キーで一時停止し、ガイダンスを入力するか中止できます。

    AI はループにはまった場合にも自動検出し、ガイダンスを求めます。
  </Step>

  <Step title="生成されたステップをレビュー">
    探索後、AI がすべての記録ステップをレビューします：

    * 不要なステップ（冗長なクリック、誤ったナビゲーション）を除去
    * 各ステップにリスクレベル（`low`、`medium`、`high`）を付与
    * リスクの高いステップに承認フラグ（`requiresConfirmation: true`）を設定

    レビューフェーズでこれらのフラグを対話的に変更できます。
  </Step>

  <Step title="手順書を取得">
    最終的な手順書が `--output` で指定したパスに保存されます。実行に必要なすべてのステップ、セレクタ、変数、設定が含まれています。
  </Step>
</Steps>

## より良い結果を得るコツ

* **ゴールは具体的に** — 「管理画面でなんかやる」よりも「メールとパスワードでログインし、ユーザー一覧を CSV エクスポートする」の方が良い結果が得られます
* **コンテキストを充実させる** — `context.md` の情報が多いほど、AI の誤探索が減ります。認証情報、画面構成、期待される動作を記載しましょう
* **`--headless false` を使う** — 探索の様子を見ることで、問題を早期に発見しガイダンスを提供できます
* **シンプルなゴールから始める** — 複雑なワークフローは小さなゴールに分割し、別々の手順書を生成してからチェーンしましょう

## トラブルシューティング

<AccordionGroup>
  <Accordion title="AI が行き詰まる・同じ操作を繰り返す">
    **Enter** キーで一時停止し、「まず設定メニューをクリックして」「ボタンはページ下部にある」などのガイダンスを入力してください。ゴールに多くのステップが必要な場合は `--max-iterations` を増やすことも検討してください。
  </Accordion>

  <Accordion title="AI がゴールを達成しない">
    `context.md` に操作対象アプリの十分な情報があるか確認してください。ゴールをより具体的にしてみてください。アプリが bot 検出を使用している場合は `--stealth` モードを試してください。
  </Accordion>

  <Accordion title="AI のステップ数が多すぎる">
    レビューフェーズで不要なステップは除去されます。それでも多い場合は、よりフォーカスしたゴールにするか、最適なパスを `context.md` に記載してください。
  </Accordion>
</AccordionGroup>

## 次のステップ

<CardGroup cols={2}>
  <Card title="手順書を実行する" icon="play" href="/ja/guides/execute-runbook">
    生成した手順書を実行。
  </Card>

  <Card title="仕組み" icon="lightbulb" href="/ja/concepts/how-it-works">
    パイプライン全体を理解する。
  </Card>

  <Card title="generate CLI リファレンス" icon="terminal" href="/ja/cli/generate">
    generate コマンドの全オプション。
  </Card>
</CardGroup>