メインコンテンツへスキップ

​
概要

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

​
変数ソース

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

​
例

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: "コンテキストからのアプリケーション名"

​
解決優先順位

実行時に変数は以下の順序で解決されます。最初にマッチしたものが使用されます：
優先度ソース説明
1secrets--secrets フラグまたは SDK の secrets オプションの値
2dataデータファイルの値
3context--context マークダウンからの AI 抽出
4env環境変数
5expressionテンプレート式の評価
6fixed定義内の静的値
7prompt対話プロンプト（CLI のみ）
つまり、secrets は常に最優先です。--secrets で値を渡すと、他のソースを上書きします。

​
シークレットの扱い

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

​
--secrets フラグで指定

キー・バリューペアの JSON ファイルを作成します： 
{
  "password": "s3cret!",
  "apiToken": "tok_abc123"
}

npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --secrets ./secrets.json
シークレットファイルの全値は自動的に sensitive として扱われ、すべての出力でマスクされます。

​
sensitive: true フラグで指定

手順書内で個別の変数を sensitive としてマークします： 
variables:
  password:
    source: prompt
    description: "ログインパスワード"
    sensitive: true

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

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

# アプリ情報

管理画面ダッシュボードは https://admin.example.com/dashboard にあります
AI は adminUrl を https://admin.example.com/dashboard に解決します。

​
テンプレート構文

二重中括弧で変数を任意の文字列フィールドに参照できます： 
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 に追加

​
次のステップ

YAML 変数リファレンス

変数スキーマとフィールドの全リファレンス。

手順書を実行する

変数を使った手順書の実行。