spec-tech

Spec Tech

技術仕様書を作成します。プロダクト仕様書（/spec-product）の下流に位置する「どのように実現するか」を記述し、スライスごとの設計（/design）の上流に位置します。エンティティエンジン（TOML+MD の階層、リレーション、show コマンド）については、[[mem.concept.doctrine.entity-engine]] に記載されています。

構造について。 Doctrine では、仕様書を第一級のエンティティとして管理します。技術仕様書もプロダクト仕様書と同じ3つの連携した書き込みで作成します。spec new でひな型を作成し（サブタイプ／タイトル／スラッグのみ）、本文の骨格とフラットフィールドを手動編集して spec-NNN.toml に記述し、その後 spec req add で要件を追加します。再構成された全体を読むには show、外部キーの整合性を確認するには validate、コーパスを一覧するには list を使います（フラグは --help、動詞のモデルは lib:reference/using-doctrine.md を参照）。アイデンティティ、リレーショナルな骨格、フラットフィールド（c4_level、[[source]] アンカーを含む）は spec-NNN.toml に、説明文は spec-NNN.md に記述します。要件は members.toml を介してメンバーとして登録される対等なエンティティ（REQ-NNN）です。技術仕様書専用の仕様書間エッジは、手動で記述するのではなく、doctrine spec interactions add／remove で追加・削除します。骨格用の CLI フラグはありません。骨格は TOML で記述し、整合性のゲートとなるのは spec validate です。

長期的に維持されるアーキテクチャとメカニズムを記録します。

• ソリューションの構成（コンポーネント、境界、データフロー、不変条件）
• 主要な技術的決定とその根拠（関連する ADR をリンク）
• 単一の変更を超えて有効なインターフェースと契約
• 実装が遵守しなければならない制約

リレーショナルな骨格では、コーパスツリー内の各仕様書を位置づけます（すべて手動編集する TOML で記述し、spec validate を通過させます）。

• descends_from — 技術仕様書から PRD への単一値の参照です。この機能が実現するプロダクトの意図を指す、検証済みの外部キーです。
• parent — 親は1つで、循環のない包含関係（C4 の分解）を表します。
• 包含関係を対等なエッジとして表すことはありません。 parent を interactions エッジとして表すことはなく、原則として interactions エッジが包含関係を表すこともありません。分解と、対等な uses／calls は異なる軸です。

C4 の詳細度。 手動作成する仕様書は通常、コンテナー／コンポーネントレベルまでとします。コードレベル（C4 レベル4）の仕様書は例外であり、メカニズムの単位に実際にその詳細度が必要な場合に限り作成します。

記述の姿勢は二通りです。 技術仕様書は、出荷済みの「実現方法」を記述する回顧的なものでも、未構築のエンジンを記述する将来意図のものでもかまいません。ただし、計画済みと検証済みを区別できるようにしてください。要件はステータス pending の REQ-NNN エンティティです。カバレッジ表やステータスの導出はありません。観測されたカバレッジは仕様書から推測するのではなく、照合して整理します。

標準的な形は3種類です。 context／container／component の各種別には、それぞれ固定された形があります。作成前に spec show で同じ種別の仕様書を確認してください。

• context — システム全体を統合して説明します。アンカーや parent、descends_from はなく、コンテナーとその構成を示します。個々のコンテナーのメカニズムを繰り返し記述することはありません。
• container — parent のみを持ち、上位への参照はありません。メカニズムを収めるコンテナーであり、機能ごとの上位参照は子が担います。
• component — parent と descends_from を持ちます。薄くても内容の乏しくない機能の形とし、種別固有の契約のみを記述します。共有するメカニズムは親を参照し、繰り返し記述しません。

内容をいつでも有効な状態に保ちます。単一の変更に関する具体的な設計（現在と目標の動作、コードへの影響、検証）は、この仕様書ではなく、そのスライスの /design に記述します。プロジェクト全体に関わり、重要な決定であれば、仕様書の本文ではなく ADR（doctrine adr new）に記録してもかまいません。