# アーキテクチャ（コンセプト）

本書では、Forge のアーキテクチャを [README](../README.md) より一段詳しく説明します。ただし、扱う範囲は公開可能なコンセプトレベルに限定します。本番向けの詳細実装と内部評価手法は、この公開ショーケースの対象外です。本リポジトリに含まれるのは、人手で整理したサンプル成果物であり、完全に実行可能な Forge の実装ではありません。

## 二種類のコンテキスト

Forge は、コンテキストを寿命の異なる二つの層として扱います。

**安定したプロジェクトコンテキスト** — 要件ごとには変化しないプロジェクトの事実です。モジュールの境界、利用しているフレームワークと規約、主要な層（UI、API、Service、Persistence）の配置、その他の構造情報が含まれます。構築コストは高い一方、低いコストで再利用できます。

**要件固有の実装コンテキスト** — 特定の要件が実際に触れるプロジェクトの一部と、その調査から得られた情報です。関係する実装範囲、各調査結果を支える根拠、未解決事項が含まれます。要件ごとに新規、またはほぼ新規に構築し、意図的に疎に保ちます。プロジェクト全体を記述するものではありません。

両者を分離することが重要です。特定の変更に対して古くなっている可能性のある既成のプロジェクト要約をすべて取り込むのではなく、要件に必要な部分だけを抽出し、新しい根拠と照らして評価できるためです。

## 処理パイプライン

```
要件
   │
   ▼
対象範囲を限定した調査 ──────► 安定したプロジェクトコンテキストを参照し、
   │                           コードベースに対して対象を絞った、
   │                           根拠を提示できる検索を行う
   ▼
関連するプロジェクトコンテキスト（要件に限定、疎）
   │
   ▼
根拠 / 不明点 / 矛盾への分類
   │            │           │
   │            │           └─ 二つの情報源が矛盾する
   │            └─ 情報源がなく、判断が必要
   │
   ▼
人間による合意 ──────► プロジェクト上の権限を持つ人が、Forge の判断範囲を
   │                    超える不明点と矛盾を解決する
   ▼
実装可能なコンテキスト（根拠 + 決定済み事項）
   │
   ▼
Coding Agent
```

### 対象範囲を限定した調査

Forge は要件を受け取ると、関連する可能性のある実装範囲を特定します。一般的な Web アプリケーションであれば、入口（UI または API）、Handler / Controller、存在する場合は中間の Service 層、Persistence 層などが該当します。同じ考え方は他のアーキテクチャにも適用できますが、すべてのプロジェクトにすべての層があるとは限りません。たとえば、[リファレンスケース](../examples/petclinic)には独立した Service 層がありません。

コンセプト設計では、自由生成ではなく、構造的なコード検索による決定論的・字句的な調査を重視します。得られた各記述から、コードベース内の具体的な位置を追跡できる必要があるためです。本公開ショーケースには、実行可能な調査パイプラインは含まれていません。

### 根拠 / 不明点 / 矛盾

調査結果を一つの説明文へまとめず、項目ごとに分類します。

- **根拠** — 情報源（ファイル、シンボル、設定値）を直接示せる記述
- **不明点** — 利用可能な資料だけでは回答できず、追加調査ではなく判断を必要とする問い
- **矛盾** — 二つの根拠が異なる内容を示している状態

これらを分けることで、「確かな情報が見つからなかった」が暗黙のうちに「一般的な答えを採用した」へ変わることを防ぎます。実際の不明点は [examples/petclinic/gaps.json](../examples/petclinic/gaps.json) を参照してください。

### 人間による合意

プロジェクト上の権限に関係する不明点や矛盾は、人間の判断へ戻します。ここで扱うのは、調査を深めれば判明する事実ではなく、誰かが決める必要のある事項です。この段階の出力は文書ではなく、実装パッケージに組み込まれる具体的な回答です。

### 実装可能なコンテキスト

Coding Agent への引き継ぎ情報は、調査で集めた根拠と、人間による合意で決定した事項を組み合わせたものです。エージェントに意図の推測を求める未確定の問題ではなく、対象範囲と判断結果が明確な問題を渡すことを目的とします。

## 検索を適用する位置（将来の方向性）

一つ、または複数のプロジェクトの対象範囲が広がると、網羅的な字句検索だけでは適切なコンテキストへ効率よく到達できなくなる可能性があります。構造検索・字句検索と、埋め込みベースまたはエージェントによる検索を組み合わせたハイブリッド検索は、パイプラインの「関連するプロジェクトコンテキストへ到達する」段階における将来の候補です。これは本公開ショーケースの対象ではありません。

将来どのような検索層を導入しても、網羅性と引き換えにせず、根拠に基づき情報源を追跡できるという性質を維持する必要があります。人手で整理したリファレンスケースは意図する動作を示すものであり、このリポジトリに当該パイプラインが実装されていることを示すものではありません。

## 本書で扱わない内容

本書では、パイプラインの構成と、公開上の保証（根拠、不明点、矛盾、人間による合意）だけを扱います。本番向けの詳細実装と内部評価手法は、この公開ショーケースの対象外です。