promptpack

promptpack

プロンプトテンプレートのパックは、気付かないうちに少しずつずれていきがちです。 誰かがテンプレート内の変数名を変更して宣言を更新し忘れたり、テンプレートで宣言した変数が使われなくなったり、バージョン文字列に 1.2.0 ではなく 1.2 と入力されたりしても、本番環境でレンダリングが失敗するまで誰も気付きません。promptpack は、そうなる前にパック全体を一度にチェックします。 各テンプレートの名前、バージョン、本文、宣言する変数と、実行したいテストレンダリングを指定してください。promptpack は、本文で実際に使われているプレースホルダーと宣言内容を比較し、すべてのバージョン文字列をチェックし、指定された値でレンダリングを決定論的に実行して、1 つのレポートを返します。公開、書き込み、取得は行いません。入力は、指定したパックのみです。

プレースホルダーは {{name}} の形式で記述します。内側のテキストをトリミングした結果が、英字、数字、アンダースコアのみで構成される単純な名前である場合に限り、その範囲をプレースホルダーとして扱います。つまり、{{ name }} は name のプレースホルダーですが、{{}}、{{first name}}、{{user-name}}、閉じられていない {{ は通常のテキストとして扱われ、レンダリング時にもそのまま残り、レポートにも記載されません。各テンプレートのプレースホルダーは、本文内で最初に出現した順に並ぶ、重複のない名前の一覧です。

レポートでは、各テンプレートについて宣言された変数をそのまま示し、2 種類の問題を一覧表示します。宣言されていないプレースホルダー（missing_declarations、プレースホルダーの順）と、どのプレースホルダーからも使われていない宣言（unused_declarations、宣言の順）です。どちらの問題もないテンプレートは ok となり、問題がある場合は issues となります。バージョンの不備は単なる問題より重大です。バージョンがドットで区切られた 3 つの非負整数と完全に一致しない場合、テンプレート名が重複している場合、または宣言された変数が重複している場合は、問題のあるパスを示すエラーとなり、入力全体が拒否されます。不正な入力に対して部分的な結果は返されません。

テストレンダリングは、指定した順に実行されます。それぞれでテンプレート名と、そのテンプレートの変数に対する値を指定します。テンプレート内の各プレースホルダーは、指定された値に置き換えられます。置換後のテキストは再走査されないため、値に {{other}} が含まれていても、指定したままの状態で保持されます。余分な値は無視されます。プレースホルダーに対応する値が指定されていない場合、そのレンダリングによってチェックが失敗することはありません。該当するエントリーは ok: false となり、値がない重複しない名前がプレースホルダーの順に示されます。残りのテンプレートとレンダリングについても、引き続きレポートされます。パックに含まれていないテンプレートを指定した場合、または文字列以外の値を指定した場合は、不正な入力として、他の検証エラーと同様にエラーになります。

CLI

npx @reneturcios/promptpack check --input args.json
npx @reneturcios/promptpack --version

args.json には、引数オブジェクト全体が含まれます。

{
  "templates": [
    {
      "name": "welcome",
      "version": "1.2.0",
      "body": "Hi {{name}}, welcome to {{ product }}!",
      "variables": ["name", "product"]
    },
    {
      "name": "reminder",
      "version": "0.3.1",
      "body": "Hi {{name}}, your {{plan}} renews soon.",
      "variables": ["name"]
    }
  ],
  "renders": [
    {
      "template": "welcome",
      "values": { "name": "Ada", "product": "Promptpacks" }
    },
    {
      "template": "reminder",
      "values": { "name": "Ada" }
    }
  ]
}

レポートは JSON として出力されます。

{
  "templates": [
    {
      "name": "welcome",
      "version": "1.2.0",
      "placeholders": ["name", "product"],
      "declared": ["name", "product"],
      "missing_declarations": [],
      "unused_declarations": [],
      "status": "ok"
    },
    {
      "name": "reminder",
      "version": "0.3.1",
      "placeholders": ["name", "plan"],
      "declared": ["name"],
      "missing_declarations": ["plan"],
      "unused_declarations": [],
      "status": "issues"
    }
  ],
  "renders": [
    {
      "template": "welcome",
      "ok": true,
      "rendered": "Hi Ada, welcome to Promptpacks!"
    },
    {
      "template": "reminder",
      "ok": false,
      "missing_values": ["plan"]
    }
  ],
  "counts": {
    "templates": 2,
    "with_issues": 1,
    "renders": 2,
    "renders_ok": 1,
    "renders_failed": 1
  }
}

終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/promptpack mcp

MCP クライアント設定：

{
  "mcpServers": {
    "promptpack": {
      "command": "npx",
      "args": ["-y", "@reneturcios/promptpack", "mcp"]
    }
  }
}

ツール

• check_prompt_pack — 呼び出し元から提供されたプロンプトテンプレートのパックをチェックします。使用されているプレースホルダーと宣言された変数、バージョン形式、指定された値を使った決定的なテストレンダリングを確認します。

  • templates（配列、必須、1 項目以上） — チェックするプロンプトテンプレート。パック内の順序で指定します。各項目は次のとおりです。
    • name（文字列、必須、空でない） — テンプレート名。パック内で一意である必要があります。
    • version（文字列、必須） — テンプレートのバージョン。ドット区切りの 0 以上の整数がちょうど 3 つ必要です（例："1.2.0"）。
    • body（文字列、必須、空でも可） — テンプレートのテキスト。プレースホルダーは {{name}} の形式で記述します。
    • variables（文字列の配列、任意） — テンプレートで宣言する変数名。省略した場合は [] です。
  • renders（配列、任意） — パックに対して実行するテストレンダリング。省略した場合は [] です。各項目は次のとおりです。
    • template（文字列、必須、空でない） — レンダリングするテンプレートの名前。
    • values（オブジェクト、必須） — レンダリングに使用する値。変数名を置換文字列に対応付けるマップです。

  {templates, renders, counts} を返します。templates には、入力された各テンプレートについて、パック内の順序で {name, version, placeholders, declared, missing_declarations, unused_declarations, status} が 1 つずつ格納されます。renders には、入力された各レンダリングについて、入力順に {template, ok, rendered} または {template, ok, missing_values} が 1 つずつ格納されます。counts は {templates, with_issues, renders, renders_ok, renders_failed} です。

Docker

docker run -i ghcr.io/cloudcorprecords/promptpack
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/promptpack check --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios