software-design

ソフトウェア設計

このスキルは、PRD と公開済みのバックログを、明確な設計にまとめます。名前を付けたモジュール、配置を定めた境界、明示的なテスト戦略、そして /tdd や /implement が一度に 1 つの振る舞いを実装できる、TDD に対応したイシュー本文を作成します。

これはオーケストレーション用のラッパーです。ディープモジュール／境界の用語とテスト容易性の原則は /codebase-design に、ユビキタス言語の基盤は /domain-modeling にあります。このスキルは両方を呼び出し、それらに欠けている接着剤、つまり前提条件のゲート、フロントエンドの振り分けスタンプ、確認ループ、バッチ形式のトラッカー更新を加えます。

バックエンドサービスや、実際の I/O 境界を持つコードが最も効果を発揮する対象です。UI コンポーネントツリーは /frontend-design に振り分けます。このスキルは振り分けブロックを追加して引き継ぐだけで、コンポーネントの設計は行いません。

---

実行するタイミング

次の条件を満たした後に実行します。

• PRD またはエピックが存在する（会話内、ファイル内、または親イシューとして）。
• /to-issues が、そのエピックのバックログとしてイシューを公開済みである。
• イシューで使われるドメイン用語を記載した CONTEXT.md が存在する。

バックログが2 つ以上のモジュールにまたがる可能性があり、モジュールや境界の選択がまだ明示されていない場合に、最も効果を発揮します。これらの条件を満たさない場合は、以下の早期終了ルールを適用するか、不足している前提スキルを実行するようユーザーに提案してください。

---

スキップするタイミング

次のいずれかに該当する場合、このスキルは早期終了します。

• 変更が単一モジュール内の調整、コピーの編集、1 行のバグ修正、または境界を越えずに既存の 1 つのモジュール内で完結する作業である。
• バックログのイシューが 2 件以下で、同じドメイン概念に関わる。
• 作業が探索的または使い捨てで、境界を意図的に破棄可能にしている。

早期終了時の動作には、次の 2 つの経路があります。

• バックエンドの単一モジュール — 影響を受ける各イシューに design-skipped: single-module change を投稿し、ユーザーに /tdd または /implement を直接実行するよう伝えます。
• UI のみ — 影響を受ける各イシューに routed-to: /frontend-design を投稿し、次に /frontend-design を実行し、その後 /tdd または /implement を実行するようユーザーに伝えます。

早期終了する場合でも、すべてのフロントエンド関連イシューに対してスタンプ処理（ステップ 2）を実行します。

---

呼び出し時のセルフチェック

何かを始める前に、前提条件を確認します。

1. PRD またはエピックのコンテキスト — 機能を明記した PRD ファイル、親イシュー、または会話のコンテキストがありますか？ない場合は中止し、まず PRD を作成するようユーザーに伝えます（例：/to-prd を使います）。
2. CONTEXT.md の存在 — 存在しない場合は中止し、ドメイン用語を整備するため、まず /grill-with-docs を実行するようユーザーに伝えます。
3. 設計対象のイシュー — トラッカーから、エピックの未完了イシューを取得します（docs/agents/issue-tracker.md に従います）。イシューがない場合は中止し、まず /to-issues を実行するようユーザーに伝えます。
4. 複数モジュールにまたがる可能性 — イシュー一式を読みます。2 つ以上のモジュールにまたがる可能性があれば続行し、そうでなければ上記の早期終了ルールを適用します。

---

ワークフロー

1. コンテキストを収集する

次の順に読みます。

• イシューで使われるドメイン用語について CONTEXT.md
• 対象領域における過去のアーキテクチャ判断について docs/adr/
• PRD（イシュー本文、ファイル、または会話のコンテキスト）
• エピックのすべての未完了イシューと、そのコメントおよびラベル

用語集を読むまでは設計を始めないでください。すべてのモジュール名、インターフェース、書き換えたイシューで、用語集の用語を使います。

引き継いだ選択を見直してください。 CONTEXT.md、ADR、現在の技術スタックは、このスキルより前に決められていることがよくあります。以前の判断がバックログに合わない場合（永続化モデルが不適切、同期／非同期の境界が不適切、これから設ける境界にそぐわない技術スタックなど）は、その不一致を明示してください。トレードオフを平易な言葉で説明し、提案を 1 つ提示します。ユーザーが承認した場合は（ADR のための改訂を /grill-with-docs に委ねます）、その提案を採用します。あるいは、ユーザーが上書きできます。すでに記録されているというだけで、不適切な判断を黙って引き継がないでください。

2. フロントエンド関連の課題にルーティングブロックを付与する

モジュール／シームの作業に入る前に、未解決の課題をすべて確認します。次の3つのシグナルのうち2つに該当する課題を、フロントエンド関連とします。

1. 出力面が可視である — ページ、画面、コンポーネント、モーダル、フォーム、グラフ、テーマ、レイアウト。キーワードの目安：renders, displays, shows, page, screen, component, modal, form, button, layout, theme, responsive。
2. モジュールの責務がプレゼンテーションである — クラスターが、変更する理由がプレゼンテーションに限られるモジュールに属する。下流に UI の利用側があるだけの純粋なデータモジュールは該当しません。
3. 受け入れ基準に視覚的な動作やインタラクションの動作が記載されている — 色、余白、フォーカス状態、ホバー、アニメーション、アクセシビリティ、レスポンシブのブレークポイント。

フロントエンド関連の課題ごとに、本文へ **Frontend design** ルーティングブロックを付与します。バックログが小さく、このスキルの残りの処理が早期終了する場合でも同様です。一貫性は最適化より優先されます。

ブロックには、Stack（プロジェクトのパッケージマニフェストから取得）、Intent（Behavior 行の言い換え）、Aesthetic direction（docs/design/direction.md へのパス）、Token authority（そのファイルから読み取ったパス）、Review（AC にアクセシビリティ／コントラスト／デザイン監査が明示されている場合のみ必須）が含まれます。フィールドの完全な仕様は skills/engineering/frontend-design/direction-doc-format.md にあります。

フィールド値は、プロジェクトのマニフェストと方向性ドキュメントから機械的に記述してください。タイポグラフィ、色、動きについてユーザーに質問しないでください。バックエンドのみの課題にはスタンプを付けません。

3. ドメイン概念ごとに課題をクラスター化する

課題を、関連する概念ごとにグループ化します。クラスターとは、同じ理由で変更される、一貫した責務のまとまりです。各クラスターには CONTEXT.md のドメイン名詞をラベルとして付けます。

境界を見極める手がかりの1つは、どの課題が通信境界（同期／非同期、外部システム）をまたぐかです。これはシームであり、モジュールを分割する境界ではありません。アダプターを置く場所を示します。

4. /codebase-design を呼び出して、モジュール／シームの用語と設計を確認する

クラスター化した課題セットにディープモジュール／シームのフレームワークを適用するため、/codebase-design を呼び出します。モジュール／シームの用語、削除テスト、分解のヒューリスティック、アダプター戦略、テスト容易性の原則は、ここではなくすべてそこにあります。

各モジュールについて、次の項目を明確にします。

• 名前 — ドメインの用語から選ぶ
• 責務 — 変更する理由を1つに絞る
• インターフェース — コマンド、クエリ、イベント（実装ではない）
• 不変条件 — このモジュールが所有するルール
• 依存先 — 他のモジュールまたはシーム
• 依存してはならないもの — 例：トランスポート層、永続化層

5. /domain-modeling を呼び出して、ユビキタス言語に照らして確認する

/domain-modeling に次の項目を渡します。

• ステップ4で候補に挙がったモジュール名
• 設計セッションで明らかになった、すべてのインターフェース操作名とイベント名
• 参照用の現在の CONTEXT.md 用語集

次の結果を期待します。

• 各用語がプロジェクトのユビキタス言語に適合しているかの確認または修正（例：「OrderCreated ではなく OrderPlaced — CONTEXT.md §Events を参照」）
• 明らかになったものの、まだ CONTEXT.md にない用語のリスト。各用語について、このセッションの前または後に /grill-with-docs で抽出する必要があります。

ユーザーにモジュールマップを提示する前に、正規の用語を反映します。新たに見つかった用語は、ステップ7で提示します。

6. ユーザーに確認する

ステップ5で確認された正規の用語のみを使い、モジュールマップを短くまとめて表示します。次の点を質問します。

• 責務の分け方は適切ですか？
• 不足しているモジュールや、まとめられてしまった責務はありますか？
• シームの位置は、変更が予想される箇所と一致していますか？

必要に応じて反復します。承認を得るまでステップ7に進まないでください。

7. 抽出対象となる永続的な項目を明らかにする

設計セッションで新しいドメイン用語や、容易には覆せない難しいトレードオフが明らかになったら、自分で書き起こさないでください。内容を示し、担当スキルに委ねます。

• 新しいドメイン用語 → 「この用語は CONTEXT.md にありません。今ここで /grill-with-docs の手順に沿って記録しますか、それとも後回しにしますか？」
• 実際に代替案がある、容易には覆せないトレードオフ → 「これは ADR に値する内容のようです。今ここで /grill-with-docs を使って ADR を作成しますか、それとも後回しにしますか？」

CONTEXT.md と docs/adr/ は /grill-with-docs の管理対象です。

8. 敵対的な設計レビューのために /council を呼び出す（助言のみ）

ステップ 6 で確定したモジュールマップと、ここまでに明らかになった最も強い未解決の異論――容易には覆せない境界の決定、未解決のトレードオフ、またはチームがすでに確信している結論――を /council に渡します。これらは、クラスターを切り分け、モジュールに名前を付け、永続的な項目に印を付けるステップ 3〜7 の過程で自然に明らかになります。

/council は標準の 4 ブロック形式の出力（Synthesis、Rationale、Panel Dissent、Confidence）を返します。Panel Dissent ブロックと、設計セッションで明らかにならなかったリスクを指摘する Synthesis の内容があれば、それらを助言としての「パネルの異論」セクションにまとめます。確定した設計とともにユーザーに提示し、ステップ 9 に進むか、モジュールの決定を見直すかを尋ねます。承認するのはユーザーであり、このスキルではありません。

助言のみです。 council の出力によってイシューの切り分けが妨げられることはありません。拒否権ではなく、追加の判断材料です。

正常な縮退。 Workflow ツールが利用できない場合、/council が明示的にスキップされた場合、または何らかの理由で呼び出しに失敗した場合は、会話内でスキップしたことを伝え、直接ステップ 9 に進みます。このサブステップは助言の付加であり、構造上の必須要件ではありません。

9. イシュー本文を TDD 対応形式に書き直す

各イシューの本文を書き直します。書き直した各イシューは、1 つの観測可能な振る舞いを扱います。必須項目と順序は次のとおりです。Module（ステップ 5 の正規名）、Behavior（アクター／振る舞い／価値）、Acceptance criteria（独立して検証可能な Given／When／Then）、Frontend design（ステップ 2 で記録した内容。バックエンドのみのイシューでは省略）、TDD notes（パスではなく名前で示すエントリーポイント、テストファーストの対象、エッジケース、フェイクの方針、テストしてはならない項目の一覧）。

ファイルパスや行番号ではなく、振る舞い、インターフェース、型に名前を付けます。システムをどのように接続するかではなく、観測可能な Given／When／Then の形式で、システムが何をすべきかを記述します。

複数のモジュールが混在するイシューは分割します。分割と書き直しの後、全体を次の順に並べます。まずトレーサーバレット（エンドツーエンドで経路が機能することを証明するイシュー）、次にコアの振る舞い、次にエッジケース、最後に統合です。

10. すべての変更を単一のバッチとして提案する

トラッカーやディスクに何かを書き込む前に、変更一式を会話内に提示します。

• 書き直したすべてのイシュー本文
• docs/design/<feature>.md の Design Plan の内容

Design Plan には、モジュール、境界、テスト戦略、不変条件、および書き直した各イシューへのリンクを含む 1 行のイシュー一覧を記録します。イシュー本文を重複して記載しません。イシュー本文の正本はイシュートラッカーです。

Design Plan ファイル（docs/design/<feature>.md）には、次の項目をこの順序で記載します。タイトル、ステータス／日付／エピックのヘッダー、Context（ドメイン用語のみを使った 1 段落）、Domain Vocabulary Used（この計画が依拠する CONTEXT.md の用語）、Module Map（モジュール → 責務 → インターフェース操作 → 境界）、Seams（各境界を越えるもの、テストと本番で使うアダプター）、Invariants and Contracts（実装にかかわらず守るべきルール）、Testing Strategy（モジュール → テストのエントリーポイント → テストレベル → フェイクの方針）、Issue Index（イシュー → モジュール → 1 行の説明）、Open Questions（実装前または実装中の未解決事項）。

明示的な承認を待ちます。ユーザーが求めたインライン編集を反映します。その後、トラッカー（gh issue edit）とファイルシステムに、一度にすべてを書き込みます。

このスキルは、1 回のバッチ承認なしに外部の状態を変更することはありません。

古くなった設計計画

設計計画は、実装のための短期間の足場です。現状との乖離に気づいたら、ユーザーはその場で対応します。該当するセクションに注記を追加し、その後、長期的に役立つ知見を /grill-with-docs で抽出します。

最後の課題がリリースされたら、設計計画の status: shipped を設定します。

---

各設計セッションのチェックリスト

[ ] Self-check passed (PRD, CONTEXT.md, issues, multi-module signal)
[ ] Domain vocabulary read from CONTEXT.md before naming anything
[ ] Frontend-flavored issues stamped (step 2) regardless of backlog size
[ ] /codebase-design invoked for module/seam framework (step 4)
[ ] /domain-modeling invoked before user confirmation; canonical terms incorporated (step 5)
[ ] Each module has exactly one reason to change
[ ] No issue mixes responsibilities from two modules
[ ] Issues ordered: tracer bullet → core behavior → edge cases → integration
[ ] New terms or trade-offs surfaced for /grill-with-docs extraction
[ ] /council invoked on confirmed design; Panel Dissent block appended and reviewed (or skip noted)
[ ] Full batch of rewrites previewed and approved before writing
[ ] Design Plan written and linked from affected issues