design-solution

docs/specs/<YYYY-MM-DD>-<feature>/design.md を作成します。承認済みの要件をどのように満たすかを記述します。スキルセットの templates/design.md を起点にします。最初に見つかったパスを使います。templates/ がこの SKILL.md と同じ場所にある場合はそこを使い、なければ ${CLAUDE_PLUGIN_ROOT}/templates、それもなければ ../../../templates を使います。テンプレート内のすべての見出しは 必須項目です。要件ファイルは入力契約です。まず最後まで読んでください。

開始前に各ステップ（1、2、2b、3、4）の ToDo を作成し、順番に完了させてください。このスキルが管理するリストは、specify-behavior の上流リストや plan-tasks の下流リストとは別です。各項目は、その 完了条件： を満たした場合にのみチェックを付けてください。

ステップ 1：コンテキストと決定事項

現在あるもの、アプローチを決定づける制約、その制約によって却下される代替案を、2～4 段落で説明します。変更対象の範囲（シグネチャ、データ形状、保存／読み込み経路）を調査する scan サブエージェントを起動し、生のソースではなく、要約ファイル（.skills/<CODE>/scan.md、または CODE が決まる前なら .skills/_pending-<slug>/scan.md）にまとめます。特定の決定がファイルの正確な内容に左右される場合に限り、そのファイルをコンテキストに取り込みます。（サブエージェントが利用できない場合は、決定に必要な部分だけを直接読みます。）

ユーザーが変更対象のサブシステムを読んだことがないと述べている場合、scan の要約を追跡済みモデルとして扱う前に、ユーザー自身が実行する /understand を案内してください。実行してはいけません。その案内行を記載する場所は、オンランプの表だけです。

scan の要約の作成後、再利用の段階を始める前に： 新たに検索を実行します。 必須サブスキル： 機能の CODE、要件の用語、scan で得た候補パスをシードとして load-subgraph を使います（状況に応じて neighbors または subgraph を使用。スキーマ 1.1）。古い親パッケージを使ってはいけません。新たな検索とは、現在の SSOT を使うことです。根拠のある主張を記載する場所は 1 か所だけです。skills/execution/load-subgraph/references/grounded-claims.md に従ってください。エンベロープだけを根拠に Reuse: をでっち上げてはいけません。実際に再利用できるものを確認するため、段階を追って調査してください。

ディスカバリー中に確定した決定事項を番号付きリストに記録します。変更が難しく、コンテキストなしでは意外であり、実質的なトレードオフを伴う決定については、ADR も作成します（必須サブスキル： ADR の要否は define-domain が判定します）。

docs/architecture/ にアーキテクチャの背骨がある場合、そこに記載された **ARCH-N** の不変条件は、この設計の入力です。内容を読み、この機能が依拠する不変条件をステップ 2 に記載します。決定が不変条件に反する場合は、ADR の作成または背骨での不変条件の取り消し線による置き換えが必要です。黙って違反してはいけません。背骨がない場合は、この手順を省略します（任意）。

任意のシステムドキュメント（手順を参照）

設計が信頼性／コンプライアンス、信頼性、標準化領域、アーキテクチャの構造、またはモジュール横断の構造に関わる場合、このファイルと同じ場所にある system-docs.md を読み、記載された手順に正確に従います。

完了条件： コンテキストと決定事項のセクションで、拘束力のある制約、制約を理由に却下した代替案、新たな検索の実施を明記します。また、背骨が存在する場合は、この機能が依拠する **ARCH-N** の不変条件も記載します。

ステップ 2：アーキテクチャ — 満たす要件、深さ、局所性

モジュールまたは領域ごとに ### セクションを 1 つ作成します。テンプレートの項目を順番どおりに使います。Architecture 配下の見出しはすべて必須の構成要素であり、自由記述ではありません。

セクションごとの契約（テンプレートで指定されたすべての項目を記入）：

項目	内容
Satisfies:	このモジュールが満たす要件 ID。この行がない場合は、インフラストラクチャ（その旨を明記）であるか、このセクションは不要です
Reuse:	成立したラダーの最上位と具体的な対象、または none — new code (rung 7) ＋理由
Respects:	設計が基幹の不変条件に依存する場合は ARCH-N（基幹がない場合、または依存しない場合は省略）
Surface:	このセクションが、すでに参照元があるものの動作、値、形状、またはシグネチャを変更する場合は必須です。まだ何からも読み取られていない新規コードの場合に限り省略できます。参照検索で確認してください。シンボル、カラム、ルート、イベント名を grep します。記憶に頼ってはいけません。影響を受ける参照元（リポジトリ内の呼び出し箇所、テスト、永続化された行、発行イベント、外部サブスクライバー、ドキュメント、設定）をすべて列挙し、それぞれに次の処置を1つだけ指定します。replace — この変更で移行し、旧経路を削除します。compat — 両方の経路を存続させます。この変更では到達できない参照元に限り許可され、削除する後続作業を明記します。frozen — この変更が 一方的に 変更してはならない契約です。外部サブスクライバー、永続化された行、公開済みイベントが該当します。解消方法は2つあり、そのどちらを選ぶかを行に記します。設計が契約に沿って構築し、契約に手を加えない方法、または要件上どうしても変更が必要な場合は、当該オーナーの合意をリリース条件とし、その合意をゲートとして明記する方法です。frozen は誰が同意できるかを定めるもので、値が将来変更される可能性を否定するものではありません。回避策もゲートも記載されていない frozen の行は未完了です
Security:	任意です。設計が既定のセキュリティドキュメントに依存する場合は、Approved の docs/security/threat-model.md（TB/THR）または docs/security/compliance.md（CMP）でのみ定義される、grep 可能な TB-N、THR-N、および／または CMP-N ID を列挙します。該当しない場合は省略してください。これらの ID を Respects: に記載してはいけません（Respects: は ARCH のみです）。
Reliability:	任意です。設計が既定の信頼性目標に依存する場合は、Approved の docs/ops/reliability.md でのみ定義される、grep 可能な SLO-N ID を列挙します。該当しない場合は省略してください。
Interface:	呼び出し元が把握する内容。実装より小さいもの
Depth:	ラダー 7（新規モジュール）： 1文の 削除テスト — このモジュールがなくなった場合、動作を再構築するために呼び出し元が引き続き把握しておくべきことは何ですか？答えが実装全体ではなく 小さな インターフェースになるまで再設計します。既存のものを再利用する場合（ラダー 2～5）： n/a — extends <target>
Locality:	これらの Satisfies ID に対する変更を適用する場所と、Step-1 のスキャンですでに確認した隣接モジュールへの影響：leave | extend | extract のいずれかと、短い説明を1つ

構造の品質は設計の一部であり、後から負債を調査するものではありません。トレースの網羅性（Satisfies:）と構造の品質（Interface:／Depth:／Locality:）の両方が満たされた時点で、このセクションは完了です。

Locality: は 編集箇所を記録し、Surface: は影響を受ける参照元を記録します。編集が不要な参照元にも処置の指定が必要です。呼び出し元が受け取る内容は変わるのに、コードは変更されないケースこそ、この項目が存在する理由です。

プロジェクトがまだ利用していない新しいサードパーティ依存関係の導入は、ユーザーが決定します。ラダーの結果、プロジェクトがまだ採用していないライブラリに行き着いた場合は、そこで止めてユーザーに確認してください。そのライブラリの概要、適合する理由、コスト（保守、フットプリント、サプライチェーン）を伝えます。バージョンや API を提示する前に、Context7 MCP（または research）で最新の事実を確認し、設計に盛り込む前に合意を待ってください。断られた場合は、ラダーを下って別の選択肢を検討します。すでにインストール済みの依存関係（ラダー 5）について確認は不要です。ユーザーの判断が必要なのは新しい依存関係の 採用 のみです。Reuse: の行には、引き続き成立したラダーを記録します。

真に難しいインターフェース（新しい永続化、並行処理、プラグインの接続点など。CRUD やフィールド追加ではない）の場合は、design-principles.md を読み、ベースとなる考え方を選んでください。そこに ≤2 個のアイデアを組み込み、平均化してはいけません。形が一目瞭然の作業では、この手順を省略します。 どのモジュールを作るか決める前に、再利用の段階を上り、条件を満たす最も高い段階で止めます。すでに機能する最も低コストな方法を、新しいコードより優先します。

1. そもそも必要ですか？ 要件で求められていないなら、削除します（YAGNI）。
2. このコードベースにすでにありますか？ ステップ1の調査で見つかったヘルパー、ユーティリティ、型、パターンがあれば、再利用または拡張します。
3. 標準ライブラリや言語の組み込み機能で実現できますか？ それを使います。
4. プラットフォーム／フレームワーク／ランタイムの機能で対応できますか？ 独自実装より優先します。
5. すでにインストール済みの依存関係で解決できますか？ それを使います。
6. 1行で書けますか？ 1行で書きます。
7. その場合に限り — 動作する最小限の新規コードを書きます（続けて Depth: を記入します）。

問題を理解したら、ステップ1の調査結果をもとに段階を上ります。この段階を使って、重要な手順を省略することはできません。信頼境界での入力検証、データ損失を防ぐエラー処理、セキュリティ、アクセシビリティ、そして要件で求められているすべてが対象です。

考え	実態
「シグネチャは変わっていないから、呼び出し側の修正は不要」	修正が不要でも、影響がないわけではありません。各読み手に Surface: の処置を記載します。
「上の説明文で呼び出し側を挙げた」	説明文は一覧ではありません。読み手ごとに1行ずつ、処置を記載します。

完了条件： すべてのアーキテクチャセクションで、表に従って Satisfies:、Reuse:、Interface:、Depth:、Locality: を記入します（背骨となる不変条件が適用される場合は Respects: も、すでに読み手がいるものをセクションで変更する場合は Surface: も記入します）。

ステップ2b：UI 設計 — 観測可能な条件

Satisfies: ID のいずれかが、ブラウザーで描画されるサーフェス（ユーザーが見るページ、画面、コンポーネント、スタイル）を通じて提供される場合 → テンプレートの ## UI design セクションを記入します。該当するものがない場合 → セクションを削除します。

記入する際は、ロック済みの ui-brief.md を引き継ぐ場合も、リポジトリの実際のビジュアルシステムに合わせて新規に構築する場合も、このファイルの隣にある ui-design-recipe.md を読み、記載どおりに正確に進めます。

完了条件： 条件が成立する場合に限りセクションが存在し、各サーフェスの5つのスロットがすべて埋まっていて、到達可能な表示状態ごとに1行が記載されています。

ステップ3：テスト対象の境界に合意する

「テスト用の境界」テーブルに、テストを記述する公開境界、各境界が対象とする要件 ID、テストの種類（unit/integration/e2e）を記入します。既存の境界を優先します。理想的な新規境界の数は0または1です。test-first スキルは、ここで合意されていない境界に対するテストの記述を拒否します。このテーブルが契約となります。 完了条件： すべての要件 ID が、少なくとも1つの境界の行に対応しています。

ステップ 4：網羅性の自己チェックと承認ゲート

requirements.md を先頭から順に確認します。すべての ID が、ちょうど 1 つの Satisfies 行に記載されているか（または、理由を添えて意図的にマッピングしていないものとして記載されているか）を確認します。次に、プレースホルダーと内部矛盾（同じ名前が異なる意味で使われている、データフローがコンポーネントを飛ばしているなど）がないかを確認します。

• 再利用の網羅性： アーキテクチャの各セクションに、そのセクションが主張する段階に合った Reuse: 行があることを prove-claim で確認します。
• 構造の網羅性： ステップ 2 に従い、各セクションに Interface:、Depth:、Locality: があることを prove-claim で確認します。段階 7 の各 Depth: 文では、呼び出し元が把握し続ける必要がある内容を明記します。Depth の回答が実装全体を言い換えているセクションは、再設計します。
• サーフェスの網羅性： Surface: を含む各セクションについて、参照検索を自分で再実行し、一覧が完全で、各行に処置が記載されていることを確認します。削除のフォローアップがない compat 行、または frozen とマークされていない変更対象の外部リーダー／永続化されたデータのリーダーがあれば、このチェックは不合格です。
• UI の網羅性： requirements.md に対してステップ 2b の条件を再評価します。ブラウザーでレンダリングされるサーフェスを通じて提供される Satisfies: ID があるのに ## UI design セクションがない場合、このチェックは不合格です。そのセクションがある場合は、サーフェスごとにすべてのスロットが埋まっており、色は生の 16 進数値ではなくトークン名を使用し、到達可能な可視状態（空、エラー、読み込み）には States: 行があることを確認します。

独立した設計レビュー — 自分でレビューせず、委任します。 新鮮なコンテキストであれば、古い要件を見つけるのではなく、都合よく解釈し直してしまうという、あなたの見解に対する偏りがありません。設計、requirements.md、存在する場合はステップ 1 のスキャン要約、およびリポジトリをレビューサブエージェントに渡し、次の点を prove-claim で確認させます。

1. コードに関する主張 — 名前を挙げた接合点とパスが存在する（file:line）。exactly-once、atomic、idempotent といった動作上の特性は、前例やコメントではなく、その特性が耐えるべき障害の発生時に記述された処理がどう動くかから導かれている。3 回中 2 回の実行では、exactly-once を SKIP LOCKED に対応づけていましたが、ロックは守るはずだったディスパッチより前に解放されていました。
2. 構造に関する主張 — Interface: が実装より小さいこと、段階 7 の Depth: が空疎でないこと、Locality: がスキャン要約と一致すること。

指摘事項は .skills/<CODE>/design-review.md に記載させます。ここではコードを読み込まずに修正します。 （サブエージェントがいない場合は、新たにコードと要約を読み直して、自分でこの確認を行います。）

上流への同期 — 省略しないでください。 設計を進めると、承認済みの要件に矛盾する事実が判明することがよくあります。たとえば、誤りと判明した前提、要件に誤って記されたメカニズム、成立しない制約（例：要件では保存された本文が ProseMirror-JSON とされているが、実際には Markdown だと判明した場合）です。その場合、要件自体の文章を必ず修正し、再度承認を求めてください。誤りだと分かった文言を黙って解釈し直して要件を満たしてはいけません。誤った文言の要件を指す Satisfies: 行があると、トレースの根幹が虚偽を根拠として示し、その誤りがコードに至るまで残ります。既存の ADR と矛盾する ADR を作成する場合も同様です。番号を明記して、既存の ADR を明示的に置き換えてください。要件を変更した場合は、承認を求める際に、変更した要件と理由を正確に伝えてください。

大規模な設計の場合はセクションごとに FILE をユーザーに提示し、承認を求めて停止します。承認されたら Status: Approved に設定します。

完了条件

必須のサブスキル：plan-tasks を使用します。