light-system-design

システム設計のライフサイクル

システム境界、ランタイムインターフェース、運用データストア、システム移行、アーキテクチャ上の意思決定を管理します。図、SQL ファイル、OpenAPI ドキュメントを、稼働可能で安全、またはスケーラブルなシステムと同一視しないでください。

既存システムに関する作業を始める前に、 references/system-design-resource-map.md を読んでください。ここでは、ライフサイクル、成果物の契約、意思決定の停止条件、証拠の状態、アクセス階層、スキル間の責任範囲を定義しています。選択したシステムに適用されるデータベース／API／信頼性の分岐についてのみ、 references.md を読んでください。

譲れない境界

1. リポジトリ、設定、スキーマ、API、依存関係、デプロイの情報収集は読み取り専用アクセスとして扱います。これらを書き換える許可ではありません。
2. 不明な事実は UNKNOWN のままにしてください。「システム設計」という言葉から、トラフィック、SLO、整合性、予算、コンプライアンス、移行期間、チームの能力を推測しないでください。
3. 少なくとも推奨案、実行可能な代替案、明示的な却下／終了条件を提示してください。ユーザーに代わってデータベース、トポロジー、互換性ポリシー、移行戦略を選択する前に停止してください。
4. 後続の変更は、ユーザーが選択した案と、正確に許可されたアクション ID に紐付けてください。変更前後のロケーター、SHA-256、検証、ロールバックを保持してください。
5. 本番データベースや設定は絶対に変更しないでください。明示的に対象範囲に含められた破棄可能な環境にのみ適用してください。それ以外の場合は、レビュー済みの計画とスクリプトを納品してください。
6. schema_lint.py は字句的なヒューリスティックとして説明してください。SQL パーサー、クエリプランナー、ロックシミュレーター、スキーマ差分エンジン、ゼロダウンタイムの証明ではありません。
7. 実際に実行したチェックにのみ VERIFIED を使用し、そのコマンド、終了コード、ロケーター、ハッシュを保持してください。それ以外には PLANNED、UNKNOWN、または UNAVAILABLE を使用してください。
8. このスキルをリサーチ DAG に含めないでください。light.findings.v1 を出力せず、STAGE_GATES、ROUTES、ステージ番号、逆向きエッジを追加せず、_shared を添付しないでください。

モードを選択する

状況	モード
実装のない新規システム	グリーンフィールドの要件整理と選択肢の設計
既存のリポジトリ／システム	読み取り専用で情報を収集し、現状のインベントリを作成
既存のモノリスまたは段階的に変更中のサービス	互換性とロールバックを考慮したモダナイゼーション
API のみの変更	契約と利用側の互換性に関する分岐
スキーマのみの変更	方言／バージョン／コンテキスト固有の移行に関する分岐
ユーザーから完成済みパッケージが提供された	レビューと証拠の検証

フェーズ 1 — 情報収集と保護

次の項目を収集するか、不明な場合は UNKNOWN のままにしてください。

• ユーザー、ビジネス目標、重要なユースケース、データ分類。
• 負荷の範囲、レイテンシ、可用性、耐久性、整合性の目標。
• チーム／運用能力、予算、デプロイ環境、コンプライアンス、移行期間。
• トポロジー：グリーンフィールド、モノリス、モジュラーモノリス、サービスのいずれか。
• コンポーネント、オーナー、インターフェース、ストア、依存関係、書き込み経路、信頼境界、障害モード、バージョン、ソースロケーター、鮮度。
• 既存のクライアント、スキーマ履歴、デプロイ／ランタイムの制約、互換性に関する保証。

既存システムの場合は、 templates/system-intake.template.json から情報収集マニフェストを作成して、次を実行してください。

python scripts/architecture_lifecycle.py intake <root> \
  --manifest <system-intake.json> --out <evidence-dir>

--out はソースルートの外に設定してください。出力されたすべての成果物を読み、source_unchanged=true を確認してください。

フェーズ 2 — 要件と現状

次を作成します。

• 測定可能な刺激、環境、応答、および目標または UNKNOWN を含む、コンテキストシナリオと品質属性シナリオ；
• リクエストレート、ストレージ増加量、ファンアウト、レイテンシ予算、および支配的なリソースの容量見積もり。不明な場合は数値を捏造せず、測定計画とともに UNKNOWN と記載します；
• 明示的なギャップを含む、現状 → 目標状態のマッピング。グリーンフィールドの場合、現状は none とできますが、ギャップの一覧には不足しているエビデンスを記録します；
• アーキテクチャ適合性関数：観測可能なシグナル、しきい値、検証コマンド／プローブ、エビデンスの状態。適合性関数のない品質属性は、依然として説明文にすぎません；
• オーナーと事実の来歴を含む、コンポーネント／インターフェース／ストアの一覧；
• 同期／非同期のデータフロー、トランザクション境界、配信セマンティクス、冪等性／重複排除、バックプレッシャー、タイムアウト／リトライ、障害処理；
• リスク、仮定、不明点、古くなった事実の各レジスター。

コード検索の結果を、暗黙のうちにアーキテクチャ上の事実として扱ってはいけません。各事実に、宣言済み、観測済み、推論、または不明のいずれかを明記します。

フェーズ 3 — 選択肢と決定の停止点

少なくとも次を提示します。

1. 理由を添えた推奨案；
2. 実行可能な代替案；
3. 各案を使用すべきでない条件；
4. コスト／複雑さ、移行リスク、互換性維持期間、ロールバック、運用、終了条件；
5. 推奨を覆す可能性がある未解決の事実。

その後、停止します。ユーザーに選択肢を選び、正確なアクション ID を承認するよう求めます。ユーザーが選択する前に、その選択を先取りして記述したり、承認済みであるかのように選択されたスキーマ／API／移行／ADR を生成したりしてはいけません。

決定を提示する前に、要件、容量見積もり、現状／目標状態、適合性関数、真に異なる選択肢を少なくとも 2 つ、ハード制約と適合性のエビデンス、トレードオフ、却下条件、決定を覆すコスト、移行／非推奨化の方針が揃っていることを検証します。

python scripts/design_readiness.py --input templates/design-readiness.example.json \
  --as-of 2026-07-05

proposal では、PASS が意味するのは ready_for_user_decision=true のみです。選択を記録することはなく、レポートは各選択肢について正規の option_packet_sha256 を出力します。authorized では、選択に light.system-design.v2.authorization を組み合わせる必要があります。その選択肢のダイジェストが一致し、承認済みアクション ID がその選択肢に含まれるアクションのサブセットであり、対象が明示的に破棄可能で、ロールバックが免除不可で、日付が --as-of より後でない必要があります。ウォーキングスケルトン（entry/core_path/state_boundary/observable_result/failure_probe/verification/action_ids）には、ready_for_implementation=true になる前に、承認済みアクションのみを含めることができます。

各選択肢について、移行／非推奨化が該当するかどうかを明記します。該当する場合、その選択肢は置き換えを先行させる必要があります。コンシューマー一覧には、安定したコンシューマー／インターフェース ID、オーナー、使用状況、エビデンスの状態、エビデンスの場所／日付、または明示的な測定計画を記載します。テレメトリーは、メトリクス／ソース／エビデンスを構造化した記録です。ロールアウトは、開始条件、終了条件、ロールバック条件を含むフェーズの順序です。ロールバックには、トリガー、アクション、検証が必要です。非推奨化における互換性維持期間には、開始、終了、削除条件が必要です。単なる文字列では、これらのフィールドを満たしません。移行が該当しない場合は、その理由を記録し、空欄のままにしないでください。

ユーザーの応答後に templates/decision-authorization.template.json を使用します。design_readiness.py が出力した選択済みダイジェストをコピーします。要件、状態モデル、適合性関数、または選択済みの選択肢を変更すると、そのダイジェストも変わり、改めて承認が必要になります。

フェーズ 4 — アーキテクチャパッケージを作成する

承認後、選択したスコープのみを作成します。

• コンテキストと品質特性；
• コンポーネント／境界ビューとデータフロービュー；
• API／イベントの契約とコンシューマー互換性ポリシー；
• スキーマと現状から目標への変更計画；
• ロールアウト、バックフィル、ロールバック、非推奨化の計画；
• 代替案とその影響を含む ADR；
• セキュリティ／プライバシー設計の制御と専門家によるレビュー項目；
• 検証計画とデリバリーの証拠。

templates/architecture-package.template.mdを使用してください。 同梱の SQL／OpenAPI ファイルは、方言／バージョンを明示した例として扱い、本番環境のデフォルトとして扱わないでください。

フェーズ 5 — 契約、スキーマ、移行のチェック

API 契約

バージョニング、認証／認可の境界、エラーモデル、ページネーション、冪等性、互換性期間、非推奨化を定義します。以下を使用して OpenAPI を検証してください。

python scripts/contract_validate.py --spec openapi.yaml \
  --examples examples.json --json

VALIDATED とするには、openapi-spec-validator に加え、サンプルスキーマのチェックが正常に完了している必要があります。STRUCTURE_ONLY または UNAVAILABLE は、契約の検証を意味しません。

スキーマと移行

次の 4 つのタスクを分けて扱います。

1. 設計時のスキーマレビュー；
2. 現状と目標の差分／ドリフト確認；
3. 移行 SQL のリスク静的解析；
4. ロールアウト／バックフィル／ロールバックの実行テスト。

明示的な方言と関連するコンテキストが指定されている場合に限り、ヒューリスティックリンターを実行してください。

python scripts/schema_lint.py --ddl migration.sql \
  --dialect postgresql --server-version 18 \
  --context migration-context.json --json

信頼できる差分／ドリフト確認には、プロジェクトに応じて選定した実際のエンジン／ツール（たとえば Atlas、Skeema、Alembic、Flyway、Liquibase、Prisma）を使用し、そのコマンド／出力を保持してください。このスキルがそれらのエンジンを実装していると主張しないでください。

スキーマ仕様から ER ビューを生成します。

python scripts/er_diagram.py --in schema.yaml --strict --out schema.mmd

Mermaid のレンダリングを利用できない場合は、構文／構造の検証のみを報告してください。

フェーズ 6 — 検証、リハーサル、納品

該当する項目を検証してください。

• 契約とリクエスト／レスポンスの例；
• 選定したデータベース／バージョンでのスキーマ作成と移行；
• データの保持、互換性期間、ロールバック、再適用；
• 架空の負荷結果ではなく、負荷に関する前提；
• タイムアウト／再試行／サーキットブレーカーと障害時の演習；
• ログ、メトリクス、トレース、SLO、デプロイ、ロールバックの可観測性；
• テナント分離と PII の制御（専門家によるレビューは引き続き保留）。

承認との紐付け、ソース受け入れとの紐付け、実装済みアクション ID、アーティファクトのハッシュ、検証項目をパッケージマニフェストに記録し、次を実行してください。

python scripts/architecture_lifecycle.py verify-package \
  --package package-manifest.json --json

パッケージで VERIFIED、PLANNED、UNKNOWN、UNAVAILABLE を区別していること、すべての VERIFIED 項目が証拠に裏付けられていること、マニフェストがコピーされた承認ファイル、オプションダイジェスト、承認済みアクション ID、実装済みアクション ID に紐付いていること、既存システム向けパッケージでは読み取り専用の intake-integrity.json のハッシュに紐付いていることを確認してから納品してください。マニフェスト内のアーティファクトおよび検証項目のロケーターは、マニフェストのディレクトリを基準とし、パッケージディレクトリ内に収まる必要があります。../、パッケージ外の証拠を指す絶対パス、または現在の作業ディレクトリに依存するロケーターは、移植可能なデリバリーパッケージになりません。

スキル間の担当範囲

• system-design：システム境界、ランタイムインターフェース、運用スキーマ、システム移行、信頼性に関する選択、ADR。
• project-structure：可視のファイルツリーと承認済みのファイル移動。保護に関する規律を取り入れますが、スキーマ移行をこのスキルに戻さないでください。
• data-engineering：研究データの品質、来歴、変換、分割、データリリース。サービスデータベースは研究データセットのパイプラインではありません。
• frontend-design：インタラクションとインターフェースの実装。このスキルが担当するのはバックエンド／API の境界であり、UI ではありません。
• research-ethics：最終的な倫理／プライバシーの判断。このスキルが提案するのは設計上の制御とレビュー項目のみです。
• orchestrator：納品された状態を利用できますが、創作したゲートを受け取ることはありません。

検証

すべてのスクリプトのセルフテストを実行してください。

python scripts/architecture_lifecycle.py --selftest
python scripts/schema_lint.py --selftest
python scripts/er_diagram.py --selftest
python scripts/contract_validate.py --selftest
python scripts/design_readiness.py --selftest

提出前に、次の項目を確認してください。

• 既存システムの調査は読み取り専用で実施されている。
• 不明な要件と古くなった事実は、明示されたままになっている。
• 容量・負荷・ストレージの見積もりが明示されている。不明な項目には、数値を捏造する代わりに測定計画が示されている。
• 現状から目標状態までのギャップが記録されている。グリーンフィールドの場合も同様（current_state=none）。
• 各品質属性に適合性関数があり、各選択肢について、根拠を伴う適合性評価、または正直な UNKNOWN／UNAVAILABLE の警告が記載されている。
• 選択肢、トレードオフ、却下条件が記載され、ユーザーが実際に判断を下している。
• 認可ダイジェストが選択されたオプションパケットと引き続き一致している。承認済みアクション ID が対象範囲内にあり、対象が明示的に破棄可能で、ロールバックが引き続き必須となっている。
• パッケージマニフェストに、認可ファイルのハッシュ、オプションダイジェスト、実装したアクション ID、読み取り専用の調査の完全性、または明示的なグリーンフィールド／該当なしの理由が紐付けられている。
• 少なくとも 2 つのインターフェース／選択肢が比較されている。最初の案が暗黙に採用されていない。
• 認可された設計には、エンドツーエンドで動作する最小限のウォーキングスケルトンと障害プローブが含まれている。
• 移行／非推奨化の方針が明示されている。該当する移行は、コンシューマーの一覧化、テレメトリ、段階的ロールアウト、ロールバック、互換性維持期間を含む置換優先となっている。
• 変更内容が、認可されたアクション ID と破棄可能な対象に合致している。
• API／スキーマ／移行に関する主張には、方言、バージョン、コンテキスト、制限が記載されている。
• すべての VERIFIED 項目に、コマンド、戻りコード、ロケーター、SHA-256 が記載されている。
• すべての検証エントリーに、実装済みかつ承認済みの範囲内にあるアクション ID が含まれている。
• パッケージの成果物／証拠のロケーターはマニフェスト相対であり、パッケージディレクトリの外に出ていない。
• ロールバックと互換性が実際に検証されているか、今後の計画として明示されている。
• スキル間および DAG 外の境界が維持されている。