> ## 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.

# 変数とシークレット

> 変数、シークレット、テンプレート構文で手順書をパラメータ化します。

## 概要

変数を使うと手順書を再利用可能にできます。一度定義すれば、ステップの値で `{{variableName}}` 構文で参照できます。値は対話プロンプト、環境変数、コンテキストファイル、シークレット、固定値から取得できます。

## 変数ソース

変数は手順書内で `source` とともに定義し、値の解決方法を決定します：

| ソース          | 説明                              | 用途例                    |
| ------------ | ------------------------------- | ---------------------- |
| `prompt`     | 実行時にユーザーに入力を求める（CLI のみ）         | ログイン認証情報、ワンタイム値        |
| `fixed`      | 静的にハードコードされた値                   | ベース URL、定数             |
| `context`    | `--context` マークダウンファイルから AI が抽出 | ドキュメントに記載された値          |
| `env`        | 環境変数から取得                        | `AWS_REGION`、`APP_URL` |
| `expression` | テンプレート式を評価                      | `{{Date.now()}}`、計算値   |
| `data`       | データファイルから取得                     | バッチワークフローでの行固有の値       |

### 例

```yaml theme={null}
variables:
  email:
    source: prompt
    description: "ログインメールアドレス"
    required: true
  baseUrl:
    source: fixed
    value: "https://staging.example.com"
  region:
    source: env
    envKey: "AWS_REGION"
  timestamp:
    source: expression
    expression: "{{Date.now()}}"
  appName:
    source: context
    description: "コンテキストからのアプリケーション名"
```

## 解決優先順位

実行時に変数は以下の順序で解決されます。最初にマッチしたものが使用されます：

| 優先度 | ソース            | 説明                                         |
| :-: | -------------- | ------------------------------------------ |
|  1  | **secrets**    | `--secrets` フラグまたは SDK の `secrets` オプションの値 |
|  2  | **data**       | データファイルの値                                  |
|  3  | **context**    | `--context` マークダウンからの AI 抽出                |
|  4  | **env**        | 環境変数                                       |
|  5  | **expression** | テンプレート式の評価                                 |
|  6  | **fixed**      | 定義内の静的値                                    |
|  7  | **prompt**     | 対話プロンプト（CLI のみ）                            |

つまり、secrets は常に最優先です。`--secrets` で値を渡すと、他のソースを上書きします。

## シークレットの扱い

シークレットはログやレポートに表示されるべきではない機密値です。指定方法は 2 つあります：

### `--secrets` フラグで指定

キー・バリューペアの JSON ファイルを作成します：

```json theme={null}
{
  "password": "s3cret!",
  "apiToken": "tok_abc123"
}
```

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --secrets ./secrets.json
```

シークレットファイルの全値は自動的に sensitive として扱われ、すべての出力でマスクされます。

### `sensitive: true` フラグで指定

手順書内で個別の変数を sensitive としてマークします：

```yaml theme={null}
variables:
  password:
    source: prompt
    description: "ログインパスワード"
    sensitive: true
```

## コンテキストベースの解決

変数が `source: context` の場合、AI が `--context` マークダウンファイルを読み取り、変数の説明に基づいて値を抽出します。値がドキュメント化されているがハードコードされていない場合に有用です：

```yaml theme={null}
variables:
  adminUrl:
    source: context
    description: "管理画面ダッシュボード URL"
```

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

管理画面ダッシュボードは https://admin.example.com/dashboard にあります
```

AI は `adminUrl` を `https://admin.example.com/dashboard` に解決します。

## テンプレート構文

二重中括弧で変数を任意の文字列フィールドに参照できます：

```yaml theme={null}
steps:
  - ordinal: 0
    description: "{{baseUrl}} に移動"
    action:
      type: navigate
      url: "{{baseUrl}}/login"
  - ordinal: 1
    description: "メールアドレスを入力"
    action:
      type: input
      value: "{{email}}"
      selector:
        role: textbox
        ariaLabel: "Email"
```

テンプレートは以下に対応しています：

* シンプルな参照：`{{variableName}}`
* キャプチャされたオブジェクトのドット記法：`{{captured.field}}`
* 最大 3 階層のネスト

## ベストプラクティス

* **認証情報には `prompt` を使用** — 手順書にパスワードをハードコードしない
* **環境固有の値には `env` を使用** — ベース URL、API エンドポイント、リージョン
* **ドキュメント化された値には `context` を使用** — `context.md` を信頼できるソースとして維持
* **機密値にはマークを付ける** — `sensitive: true` または `--secrets` でマスクを確保
* **シークレットはバージョン管理から除外** — `secrets.json` を `.gitignore` に追加

## 次のステップ

<CardGroup cols={2}>
  <Card title="YAML 変数リファレンス" icon="code" href="/ja/yaml/variables">
    変数スキーマとフィールドの全リファレンス。
  </Card>

  <Card title="手順書を実行する" icon="play" href="/ja/guides/execute-runbook">
    変数を使った手順書の実行。
  </Card>
</CardGroup>