個別システム設計（SYSD）作成ルール

System Design Topic Documentation Rulebook

sysd-<term>.md を、システム設計の個別トピックまたは複数の子設計を束ねる hub として記述するためのルールです。sysd-index が設計 SSOT 全体への入口であるのに対し、本 rulebook は一つの設計関心事に絞った構造、責務、制約、検証観点を定義します。

1. 全体方針

• 一つの sysd-<term> は、一つの設計関心事、または同じ関心事に属する子設計群への導線だけを扱います。
• 設計判断、責務境界、構成、主要フロー、制約、検証観点を記述し、実装コードや設定ファイルの全文は一次情報への参照に留めます。
• 複数 provider や実装方式を同じ共通設計の下で管理する場合は、親を薄い hub、方式別の詳細を子 sysd-<term> として分冊できます。
• 複数トピックへ適用する必須・禁止ルールは sysd-cross-cutting-policy、事故予防に必要な難所フローは sysd-critical-flows を SSOT とします。
• 運用判断は opd-*、再現可能な操作手順は opr-* に委ね、個別システム設計へ混在させません。

2. 位置づけと用語定義

ドキュメント	役割	記載しないもの
sysd-index	システム設計 SSOT の全体入口	個別設計の本文
sysd-cross-cutting-policy	複数トピックへ適用する横断ルール	個別 provider の詳細
sysd-critical-flows	最大5件の事故予防フロー	通常系の網羅的な手順
sysd-<term>（hub）	共通の目的・境界と子設計への導線	子設計の設定全文
sysd-<term>（子設計）	一つの方式・provider・機能の詳細設計	親と同じ共通方針の再掲

hub は内容の薄さを目的とするのではなく、共通事項の SSOT と子設計の選択条件を一箇所に保つための構成です。

3. ファイル命名・ID規則

• ファイル名は sysd-<term>.md、ID は sysd-<term> とします。
• <term> は英小文字・数字・ハイフンで、設計関心事を一意に表します。
• hub と子設計は同じディレクトリへ配置し、子設計の part_of から hub の ID を参照します。
• provider 別に分冊する場合は、sysd-<provider>-<topic>.md のように選択軸を名前へ含めます。
• sysd-index、sysd-critical-flows、sysd-cross-cutting-policy は専用 rulebook の対象であり、本 rulebook の対象外です。

4. 推奨 Frontmatter 項目

項目	説明	必須
id	sysd-<term>	○
type	architecture	○
status	draft / ready / deprecated	○
rulebook	specdojo:sysd-rulebook	○
part_of	hub または sysd-index の ID	子設計では○
based_on	設計判断へ直接利用した成果物 ID	任意
supersedes	置き換える旧設計 ID	任意

hub の子設計一覧と part_of の参照は一致させます。作成途中は status: draft とし、実装・検証との整合を確認してから昇格します。

5. 本文構成（標準テンプレ）

章構成はトピックに応じて柔軟に決められます。ただし、次の観点を本文から追跡できるようにします。

観点	hub	子設計・単独設計	内容
目的・適用範囲	○	○	対象、対象外、利用者
設計方針・採用理由	○	○	選択理由、前提、代替との境界
責務分担・境界	○	○	コンポーネント、人、外部システムの責務
全体構成・主要フロー	推奨	○	構成要素、データ・制御の流れ、永続化点
設定・インターフェース	導線のみ	必要時○	SSOT の所在、解決規則、互換性
失敗時・再実行・セキュリティ	導線のみ	必要時○	失敗境界、復旧条件、権限制約

| 子設計一覧 | ○ | - | 選択条件、責務、参照先 |

| 検証観点・関連文書 | ○ | ○ | テスト、運用、横断ルールへの導線 |

6. 記述ガイド

6.1. 目的・適用範囲

• 何を設計し、誰が実装・検証・運用判断に利用するかを1〜3段落で示します。
• 対象外を明示し、横断ルール、運用方針、運用手順へ委譲する事項を区別します。
• 現在の実装境界と将来構想を混在させず、未確定事項には共通ラベルを付けます。

6.2. 設計方針・責務境界

• 採用理由、守るべき制約、責務外を判定可能な表現で記載します。
• 責務表を置く場合は、構成要素、責務、責務外、参照する SSOT を列に含めます。
• 複数トピック共通の MUST / MUST NOT は本文へ複製せず、Rule ID を付けて sysd-cross-cutting-policy を参照します。

6.3. hub と子設計

• hub は共通の目的、責務境界、選択軸、子設計一覧、横断ルールへの導線を保持します。
• 子設計一覧には、子設計 ID、対象、固有責務、選択条件を記載します。
• provider 固有の認証、モデル、設定、制限シグナルは子設計へ置き、hub に詳細を再掲しません。

6.4. 構成・フロー・設定

• 図は主要コンポーネントと境界が変わる場合に使い、クラスや関数単位へ展開しません。
• 設定は項目の意味、解決順序、検証条件を記述し、設定全文や秘密情報を掲載しません。
• 事故時に再実行性、順序、補償、監査が問題になるフローは sysd-critical-flows へ切り出します。

6.5. 検証観点・関連文書

• 設計制約ごとに、コード、設定検証、単体・統合テスト、レビューのどれで確認するかを示します。
• sysd-index、sysd-cross-cutting-policy、必要な sysd-critical-flows、テスト設計、OPD / OPR への導線を置きます。
• 参照先が存在しない場合は空欄にせず、（なし） または未確定ラベルを明記します。

7. 禁止事項

禁止事項	理由
hub に子設計の設定全文を再掲する	SSOT が分散するため
横断ルールを複数の sysd-<term> に複製する	変更時に不整合となるため
運用コマンドを長い手順として記載する	OPR の責務を侵食するため
コード、設定、schema の全文を貼り付ける	Code as Spec の一次情報と二重管理になるため
失敗・再実行・権限・検証観点を省略する	実装とテストの判断材料が欠落するため
親子関係のない設計を便宜的に同じ hub へ束ねる	選択軸と責務境界が不明になるため