prompts

LangWatch Prompts CLI でプロンプトをバージョン管理する

対象範囲を決める

ユーザーのリクエストが一般的な場合（「プロンプトのバージョン管理を設定する」「プロンプトをバージョン管理する」など）：

• コードベース全体を読み、ハードコードされたプロンプト文字列をすべて見つけます
• Git の履歴を調べて、何が、なぜ変更されたのかを把握します。エージェントの動作変更、プロンプトの調整、バグ修正に注目してください。背景を理解するため、コミットメッセージも読みます
• Prompts CLI を設定し、ハードコードされたプロンプトごとに管理対象プロンプトを作成します
• アプリケーションコードをすべて更新し、langwatch.prompts.get() を使用するようにします

ユーザーのリクエストが具体的な場合（「このプロンプトをバージョン管理する」「新しいプロンプトバージョンを作成する」など）：

• 対象のプロンプトに絞って作業します
• 管理対象プロンプトを作成または更新します
• 関連するコードを更新し、langwatch.prompts.get() を使用するようにします

Langy では、ユーザーが手作業で適用するためのコード変更を表示しないでください。code_access を呼び出し、code-changes スキルに従って、ユーザーのマシン上または GitHub 経由で変更します。

プランの上限

LangWatch の無料プランでは、プロンプト、シナリオ、評価器、実験、データセットに上限があります。上限に達すると、API はアップグレード用リンクとともに "Free plan limit of N reached..." を返します。

対応方法：

• 上限の範囲内で作業します。該当する種類のリソースが 3 つまで許可されている場合は、10 個ではなく、意味のあるものを 3 つ作成します
• 作成するものは一つひとつ価値が明確に伝わるようにします
• まず、動作するものを提示します。上限に達した場合は、達成した内容をまとめ、プランをアップグレードすると上限が引き上げられることを伝えます。プラットフォームのサブスクリプション設定、または CLI がセルフホストのエンドポイントを参照している場合はライセンス設定を案内してください。CLI が実際に使用しているエンドポイントを確認します。これは .env、プロセス環境、または保存済みの CLI 設定から取得できます
• 上限に空きを作るために既存のリソースを削除したり、上限を回避するために既存のリソースを転用したりしないでください

ステップ 1：Prompts CLI のドキュメントを読む

langwatch docs <path> を使って、ドキュメントを Markdown として読みます。以下は、参照に役立つページです。

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

langwatch --help と langwatch <subcommand> --help でコマンドを確認します。list コマンドと get コマンドは、機械可読な出力形式として --format json を受け付けます。すべての list コマンドは、行数を制限する --limit <n> と、回答の一部を取得する --jq <expr> を受け付けます。ページネーション付きの list コマンドはエンベロープを返します。行数を数えるには行配列（--jq '.traces | length'）を使い、全体の件数は .pagination.total で確認します。単独の --jq length では行数ではなく、エンベロープのフィールド数が数えられます。SDK API や CLI フラグを推測するのではなく、先にドキュメントを読んでください。

シェルを利用できない場合は、同じ Markdown をプレーン HTTP で取得します。ドキュメントのパス末尾に .md を付けてください（例：https://langwatch.ai/docs/integration/python/guide.md）。インデックス：https://langwatch.ai/docs/llms.txt。シナリオのインデックス：https://langwatch.ai/scenario/llms.txt

このスキルを実行中に問題が発生したり、内容が分かりにくかったりした場合（コマンドの不具合、実際の動作と異なるドキュメント、回避策が必要なエラーなど）は、ユーザーの許可を得て、--title と --summary（または --session <transcript.jsonl>）を付けて npx --yes langwatch report --user-approved を実行し、LangWatch チームに報告してください。報告内容は、修正すべき箇所に直接反映されます。ログインや API キーは不要です。--user-approved を指定しない限り、何も送信されません。また、--dry-run を指定すると、送信せずに正確なペイロードを表示できます。タイトル、概要、トランスクリプトは、パターンに基づいてローカルでスクラブされます。対象は、シークレットと API キーに加え、メールアドレス、電話番号、カード番号、パブリック IPv4 アドレスです。パターンに一致しない内容は、--email に指定した連絡先アドレスも含め、そのまま送信されます。--session を使う場合は、トランスクリプトにはユーザーが確認していない内容が含まれるため、必ず先に --dry-run を実行して、ユーザーにペイロードを確認してもらいます。オプションの説明は npx --yes langwatch report --help を参照してください。

プロジェクトと API キー：個人用ではなく、実際のプロジェクトを対象にしてください。

LangWatch には、次の 2 種類のプロジェクトがあります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、計装は、必ずこれらのいずれかを対象にする必要があります。
• 個人プロジェクト：1 人のユーザーに紐づく、非公開の「My Workspace」用の作業スペースです。ユーザーの評価、実験、本番環境のトレースをここに送らないでください。これは個人的な探索専用であり、実際のプロジェクトと取り違えるおそれがあります。

認証方法は次の 2 つです。

• .env 内のプロジェクト API キー（LANGWATCH_API_KEY）：これらのスキルで使用するすべての認証情報です。1 つの実際のプロジェクトにスコープが限定されます。これがデフォルトです。ユーザーが明示的に別の方法を求めない限り、こちらを優先してください。
• langwatch login --device（AI ツール／SSO）：コーディングアシスタント（langwatch claude、langwatch codex、…）をラップするための個人用デバイスセッションです。評価、プロンプト、データセット、シナリオ、SDK の計装には使用しません。また、個人用ワークスペースを参照します。これらのスキルでの作業を設定するために実行しないでください。

したがって、これらのスキルでプロジェクトを読み書きする場合は、実際の共有プロジェクトの LANGWATCH_API_KEY が CLI から利用できることを確認してください。ローカルではプロジェクトの .env に設定されています。CI ではランナーがプロセス環境に注入し、CLI はどちらからでも読み取ります。新しいキーを求める前に、変数がすでに設定されているか確認してください。また、値は CLI に読み取らせ、絶対に表示、コピー、送信しないでください。プロジェクトを選ぶために langwatch login を実行しないでください。個人プロジェクトをデフォルトにしないでください。同じ場所で LANGWATCH_ENDPOINT も確認してください。設定されている場合、プロジェクトはセルフホスト型のインスタンス上にあり、CLI は app.langwatch.ai ではなく、そのエンドポイントに対して動作します。

読み取る内容と伝える内容は別です。 これらのスキルは作業用メモであり、読者向けの文章ではありません。作業先を把握するには、プロジェクト独自の .env から LANGWATCH_API_KEY と LANGWATCH_ENDPOINT を読み取ってください。そのファイルからほかのものは何も読み取らないでください。データベース、クラウド、プロバイダーの認証情報が含まれており、あなたには関係ありません。また、読み取った値はすべて、あなたのコンテキストやコマンド出力に入り込む可能性があります。回答に含めてはいけないのは、あなたが実行されているマシンを説明する情報です。ワークスペース内のパス、コンテナのポート、このワーカーが接続するアドレスなどです。それらは作業の内容ではなく進め方を示すものであり、こちら側のホスト情報は読者にとって意味がありません。何を行い、LangWatch のどこで確認できるかを伝えてください。

次に、Prompts CLI ガイドを読んでください。

langwatch docs prompt-management/cli

重要：Prompts CLI の使い方を推測しないでください。まずドキュメントを読んでください。

ステップ 2：プロジェクトで Prompts を初期化する

langwatch prompt init

プロジェクトのルートに prompts.json 設定ファイルと prompts/ ディレクトリを作成します。

ステップ 3：ハードコードされたプロンプトごとに管理対象のプロンプトを作成する

コードベースからハードコードされたプロンプト文字列（システムメッセージ、指示）を検索します。それぞれについて、次の操作を行います。

langwatch prompt create <name>

生成された .prompt.yaml ファイルを編集し、元のプロンプトの内容に合わせます。

モデル： 生成された model は現行モデルのままにします。バージョン番号ではなく、エイリアス openai/latest を保存してください。LangWatch は実行時にこれを最新のフラッグシップモデルに解決するため、リリースのたびにプロンプトの世代が古くなることはありません。新しいプロンプトで gpt-4o-mini のようなレガシーモデルをデフォルトにしないでください。ユーザーが意図的に品質とコストまたはレイテンシのトレードオフを選ぶ場合に限り、使用してください。

Temperature： gpt-5 ファミリーではカスタムの temperature が拒否されるため、これらのモデルでは modelParameters.temperature を追加しないでください。create がこれを省略するのは意図的なものです。

構造化出力： プロンプトで厳密な JSON を返す必要がある場合は、文章で JSON を要求するのではなく、response_format ブロックを追加してください。

response_format:
  name: product_category
  schema:
    type: object
    properties:
      category: { type: string }
      reasoning: { type: string }
    required: [category, reasoning]
    additionalProperties: false

response_format は sync／pull でロスレスに往復できます。形式の詳細については、langwatch docs prompt-management/cli を参照してください。

ステップ 4：アプリケーションコードを更新する

ハードコードされたプロンプト文字列をすべて、langwatch.prompts.get() の呼び出しに置き換えます。

Python（BAD → GOOD）：

agent = Agent(instructions="You are a helpful assistant.")

import langwatch
prompt = langwatch.prompts.get("my-agent")
agent = Agent(instructions=prompt.compile().messages[0]["content"])

TypeScript（BAD → GOOD）：

const systemPrompt = "You are a helpful assistant.";

const langwatch = new LangWatch();
const prompt = await langwatch.prompts.get("my-agent");

重要：langwatch.prompts.get() を、ハードコードされたフォールバック文字列を含む try/catch で囲まないでください。プロンプトのバージョン管理の目的は、プロンプトを外部で管理することです。フォールバックを設定すると、古いハードコードのコピーに気付かないまま戻ってしまい、この目的が損なわれます。

ステップ 5：プラットフォームと同期する

langwatch prompt sync

ステップ 6：デプロイ用にバージョンへタグを付ける

組み込みのタグは 3 つあります：latest（自動割り当て）、production、staging です。タグを指定して取得するようにコードを更新します：

prompt = langwatch.prompts.get("my-agent", tag="production")

const prompt = await langwatch.prompts.get("my-agent", { tag: "production" });

CLI（または LangWatch UI の「Deploy」ダイアログ）からタグを割り当てます：

langwatch prompt tag assign my-agent production

カナリアデプロイやブルー／グリーンデプロイでは、langwatch prompt tag create を使ってカスタムタグを作成します。

ステップ 7：確認する

langwatch prompt list を実行してすべてが同期されたことを確認するか、LangWatch アプリの「Prompts」セクションを開きます。

よくある間違い

• プロンプトをハードコードしないでください。必ず langwatch.prompts.get() で取得します
• try/catch にハードコードされたフォールバック文字列を追加しないでください。バージョン管理の目的が気付かないまま損なわれます
• prompts.json を手動で編集しないでください。CLI を使用します
• プロンプトを作成した後に langwatch prompt sync を実行し忘れないでください
• 主要なエイリアス openai/latest（高速ティアでは openai/latest-mini）を優先します。プロンプトが特定のバージョン向けに調整されている場合に限りバージョンを固定し、コストやレイテンシーを意図的に最適化する場合に限り、gpt-4o-mini のような古いモデルを選びます
• gpt-5 ファミリーのモデルに modelParameters.temperature を設定しないでください。このファミリーでは受け付けられません
• 構造化出力が必要な場合、プロンプトのテキスト内で JSON を要求しないでください。response_format ブロックを使用します