RAGSpine
意思決定（ADR）

意思決定（ADR）

RAGSpine を支えるアーキテクチャ決定記録 — 不変・追記専用であり、編集ではなく置き換え（supersede）によって更新されます。

アーキテクチャ決定記録（ADR） は、1 つの重要な決定を記録するものです。その決定を迫った 文脈、決定そのもの、却下された代替案、そしてその決定から導かれる帰結を含みます。 RAGSpine は ADR を不変の歴史的記録として保持します。

ここでの ADR の運用方法

  • 1 ファイルにつき 1 つの決定。 各レコードは単一の自己完結した選択です （リポジトリ内の docs/adr/NNNN-kebab-title.md）。
  • 追記専用かつ不変。 ADR は承認された後は決して編集されません。決定を覆すには、 古いものを置き換える（supersede）新しい ADR を追加します — 履歴はそのまま残り、 監査可能な状態が保たれます。
  • 編集ではなく置き換え。 このため、レコードが古い時点の内容（たとえば src/ レイアウト以前のファイル配置）を記述していても「誤り」にはなりません。それは当時の 時点における決定をそのまま文書化したものだからです。
  • ドリフト追跡の対象外。 歴史的な記録であるため、ADR には covers frontmatter がなく、scripts/check_doc_drift.py によるチェックも行われません。

一貫して流れる原則

これらの決定を貫いて繰り返される原則は、保証と柔軟性を分離することです。 不変条件（捏造防止、出典追跡、ソース分離、依存関係のライセンス、セキュリティ ゲート）はハードで決定的かつ差し替え不可であり、それ以外のすべて（ドメイン、言語、LLM、 埋め込み、リランカー、解析戦略）はソフトで、config または Protocol 駆動です。

記録一覧

ADR 0002 は製品方針を扱う包括的な記録であり、 同じ設計インタビューで確定した 8 件の個別決定 ADR（0003–0010）の索引になっています。

ADR 番号はリポジトリローカルです

ウェブサイトの ADR 0012–0015 は、以前のファミリー/ウェブサイト公開時の連番を保持しています。現在の RAGSpine エンジンリポジトリにも、一部同じ番号を持つ独自の ADR ファイルが存在します。たとえば、 ウェブサイトの ADR 0012 は corespine の LLM シームを記録していますが、エンジン側の docs/adr/0012-onboarding-complexity-budget.md は別の決定です。番号だけで同一の記録だと 推測しないでください。以下の新しいウェブサイト ADR 0016–0018 は、対応する番号を持つ エンジン側の記録を英語で転写したものです。

#タイトル概要ステータス
0001単一の LLM パスではなく決定的な二重チャネル2 つの決定的チャネル（構造化数値 + ナラティブ RAG）。LLM は合成に限定され、事実を作り出すことには決して使われません。accepted
0002製品方針：汎用・ライセンスクリーン・フレームワークに縛られない RAG ライブラリ包括的な北極星となる記録。ハードな不変条件と、config/Protocol 駆動のソフトな柔軟性を分離し、ADR 0003–0010 の索引となります。accepted
0003対象読者：他者がその上に構築するための汎用 OSS ライブラリ主な対象読者は、RAGSpine の上に独自の RAG を構築する開発者です。金融はアイデンティティではなく、一例のドメインになります。accepted
0004完全な汎用性：DomainProfile と任意次元のファクト完全に汎用化します — CompanyProfile は DomainProfile になり、構造化チャネルは、ユーザー定義の任意次元を持つ型付きファクトストアになります。accepted
0005リーンなコア。休眠中の機能は experimental/extras として隔離デフォルトのオフラインパスで動作するものだけを出荷します。OCR、実ベクトル、verifier は、明確にラベル付けされた experimental モジュール/extras へ移動します。accepted
0006品質基準：不変条件のプロパティテスト + 1 つの実データ検索ベンチマーク品質を、保証（プロパティテストで証明された不変条件）と、1 つの実際のラベル付き検索ベンチマークとして定義します。ドメイン精度についてはユーザーのデータに委ねます。accepted
0007多言語対応：5 言語を見据えて設計し、2 言語を出荷。残りはロケールパックとしてすべてのレイヤーに locale のシームを通します。中国語 + 英語はコアで出荷・テストし、日本語/イタリア語/ドイツ語はコミュニティのロケールパックとして提供します。accepted
0008プロンプト：ragspine/prompts/<locale>/ 配下のパッケージ化された PromptRegistryプロンプトを、PromptRegistry Protocol の背後にある、パッケージ化されたロケールキー付きテンプレートファイルへ外部化し、実行時に DomainProfile から充填します。accepted
0009「フレームワーク非依存」の再定義：フレームワークロックインなし + 許容的ライセンスのみフレームワーク非依存を、オーケストレーションのロックインがないこと、および許容的ライセンスのみ（≤ Apache-2.0）と再定義します。実バックエンドは、純粋性のためではなく軽量さのためのオプトイン extras です。accepted
0010インテント解析：決定的なセキュリティゲート + 差し替え可能な IntentParser常時有効で決して差し替え不可能な決定的セキュリティゲートを、差し替え可能な IntentParser Protocol から分離します。accepted
0011python-project-standard の採用。src/ レイアウトへ移行し、それ以外は維持ハウス標準を統治哲学として採用します。唯一の限定された構造的不変条件（src/ragspine/ レイアウト）を整合させ、文書化された 4 つの逸脱を受け入れます。accepted
0012corespine LLM シームの採用 — create_message ではなく chat / ChatCompletionLLMProvider Protocol をファミリー共有コア（corespine）へ移動し、OpenAI chat-completions の形を採用し、オプションのアクティブな TPM スロットルを追加します。0.3.0 で出荷。accepted
0013Dify ワークフロー YAML → 純 Python コンパイラ + 静的最適化アドバイザーDify の .yml を、Dify 色を取り除いた IR（parse → IR → codegen）を通じてフレームワーク非依存の命令型 Python にコンパイルし、加えて純粋に静的な 8 つの最適化ルールを提供します。PyYAML は [dify] extra の背後に置きます。0.4.0 で出荷。accepted
0014Dify ワークフローのサービス化（analyze / compile / run）と三層の安全実行信頼度が段階的に高まる 3 つのサービスエンドポイント。analyze / compile は常時有効。run はデフォルトで無効であり、L0 静的 import ゲート、L1 制限付きサンドボックス、（Linux では）L2 サブプロセス分離の背後にあります。プロバイダーは常にサーバー側で決定されます。0.5.0 で出荷。proposed
0015関係抽出 — model-derived / unverified の出典追跡マーカーを持つオプトインのスロットbuild_relation_graph の隣に RelationExtractor Protocol スロットを追加します。デフォルトはバイト単位で同一のまま保たれ、LLM が抽出したエッジには model-derived + unverified の印が付けられ、SecurityGate によるスクリーニングを経て、決して黙って信頼されることはありません。0.9.0 で出荷。accepted
0016検索の製品化設定絞り込み用のメタデータフィルター、出典追跡付きのマルチライブラリ RRF ルーティング、parent-child プリセット、そして埋め込み/ベクトルコンポーネントを一切構築しないエコノミーモードを追加します。accepted
0017会話履歴は生成専用のコンテキストファーストクラスの履歴を追加しつつ、インテント解析、セキュリティ、検索クエリ、エビデンスからは除外し続けます。accepted
0018親子のストアレベル展開階層/ウィンドウのフィールドを永続化し、チャンカーを ingestion 経由で接続し、分離の後にのみ展開を行います。引用は子ヒットのまま維持されます。accepted

Python API

コアオーケストレーション、ストア、検索、ワークフローのフォーマット/ひな形生成/プレビュー、および Dify/n8n 変換のエントリポイント。

ADR 0001: 単一の LLM パスではなく決定論的な二重チャネルを採用する

2 つの決定論的チャネル（構造化数値 + ナラティブ RAG）を用い、LLM は合成に限定し、事実の捏造には決して用いない。

このページ

ここでの ADR の運用方法記録一覧