ADR 0008: プロンプト — ragspine/prompts/<locale>/ 配下のパッケージ化された PromptRegistry

ステータス: accepted · 日付: 2026-06-17

不変の記録。ドリフト追跡の対象外（covers なし）。編集せず、上書き（supersede）で対応すること。

0002 のプロダクト方針の一部。

背景

プロンプトはインラインコードの外に出すべきである。プロンプトは三次元的な存在である。すなわち、テンプレート（プレースホルダー付き）×ロケール（0007）×DomainProfile の値（0004）であり、「会社名やドメインをハードコードしない」という不変条件により、テンプレートは実行時に埋め込まれなければならず、リテラルとして書いてはならない。当初提案された配置場所——リポジトリルートの prompts/ フォルダ——は wheel に同梱されない（packages=['ragspine']）ため、pip install するユーザー（0003 が想定する対象読者）には届かないことになる。

決定

プロンプトを パッケージ化された テンプレートファイルとして ragspine/prompts/<locale>/<category>/*.jinja に外部化し、PromptRegistry Protocol の背後に置く（デフォルトはファイルベースで、ユーザーによるオーバーライドが可能）。プレースホルダーは実行時に DomainProfile から埋め込まれる。プロンプトはドメインモジュールごとに分散配置（co-locate）するのではなく、一元管理（ロケール別のキーを持つ単一ツリー）を維持する。

検討した代替案（不採用）

• リポジトリルートの prompts/ フォルダ（当初の提案）: 外部化するという点は正しいが、配置場所が誤っている——import ragspine するユーザーには届かない。
• 分散配置の ragspine/<domain>/prompts/<locale>/: ドキュメントの「フォルダで探す」という分散配置の方針には合致するが、ローカライズ可能な資産を 8 つのドメインに散らばらせてしまう。ここでの読者は翻訳者やロケールパックの貢献者であり、彼らが求めるのはロケールごとに 1 つのディレクトリであって、ドメイン横断の探索ではない（コードドキュメントとは異なるアクセスパターン）ため、不採用とした。

帰結

• プロンプトは wheel に同梱され、他のバックエンドと同様にオーバーライド可能になる。
• ロケールパック（0007）の一部は、「新しい <locale>/ プロンプトツリーを置くだけ」で実現できる。
• 翻訳者はコードに触れることなくフラットなテンプレートを編集でき、diff はレビューしやすい状態に保たれる。