design

ハイレベル設計

機能要件に基づいてモジュール式のハイレベルアーキテクチャを設計し、包括的な設計ドキュメントを作成します。すべてのアーキテクチャ上の判断に、Balanced Coupling モデル（balanced-coupling スキルから事前に読み込まれたもの）を適用します。

入力

$ARGUMENTS にファイルパスが含まれている場合は、そのファイルを機能要件の入力として読み込みます。 $ARGUMENTS が空の場合、または有効なファイルパスでない場合は、AskUserQuestion を使ってファイルパスを尋ねます。ヘッダー：「Requirements」。質問：「機能要件ファイルのパスを指定してください。」 有効なファイルパスを受け取り、ファイルを正常に読み込めるまで先に進まないでください。

TaskCreate を使って、次の 6 つのステップを追跡します：要件の把握、モジュール式アーキテクチャの設計、モジュール設計ドキュメントの作成、モジュールテスト仕様の作成、アーキテクチャドキュメントの作成、モジュール性のレビュー。

やり取りのルール

ユーザーからの入力には、必ず AskUserQuestion を使います。次の原則に従ってください。

• 質問は一度に 1 つ。 複数の質問を 1 つのメッセージにまとめないでください。
• 選択式を優先。 説明を添えた具体的な選択肢を 2～4 個提示します。自由回答よりも答えやすくなります。
• 「その他」は自動で追加されます。 ツールには自由記述の「その他」オプションが常に用意されるため、追加する必要はありません。
• ヘッダーを使用。 「Approval」「Subdomain」「Coupling」など、短いラベル（最大 12 文字）を使います。

プロセス

以下の手順に厳密に従ってください。次の手順に進む前に、各手順でユーザーの明示的な承認を得る必要があります。いずれかの手順で曖昧な点があれば、作業を止めて AskUserQuestion を使ってユーザーに確認してください。決して推測しないでください。

ステップ 1：要件を理解する

機能要件のファイルを読みます。その後、次の手順を実行します。

1. 機能要件を自分の言葉で言い換えます。 一貫性のある機能領域ごとに整理します。

2. 結合を考慮した設計に不足している情報を特定します。 適切なバランスの取れた結合を判断するために必要な情報、つまりドメインの分類（変化のしやすさを判断）、組織構造（距離を判断）、統合パターン（結合の強さを判断）を検討します。要件の不足を特定し、特に次の点を確認します。

   • コア、支援、汎用の分類が曖昧なビジネス領域 — 解釈を提示し、ユーザーに確認または修正を求めます
   • モジュール境界に影響する組織上の制約（チームの所有権、デプロイ単位、共有インフラストラクチャ）
   • 変化が最も大きい領域と設計に注力すべき領域に影響する戦略的な方向性
   • 適切な結合の強さが不明確な統合要件

   AskUserQuestion を使って、それぞれの不足情報について個別にユーザーに質問します。要件から明らかな点は省略します。回答によって設計が変わらない質問はしないでください。各質問で、結合の判断に影響する曖昧さを解消する必要があります。これらのカテゴリに限定されず、要件にアーキテクチャの判断に影響する曖昧な点があれば質問してください。質問は、読み取った具体的な要件に基づいて作成します。

3. DDD のサブドメインを使ってドメイン領域を分類します（コア／支援／汎用）。これは、変化のしやすさと設計に注力すべき領域を判断するために使います。要件を分析し、分類案を提示します。次の表形式で示します。

サブドメイン	分類	根拠
{領域 1}	コア	{理由}
{領域 2}	支援	{理由}
{領域 3}	汎用	{理由}

その後、AskUserQuestion を使ってユーザーに分類を確認します。

Header	Question	Options
Subdomains	これらのサブドメイン分類は適切ですか？	1. 承認 - すべて正しい 2. 一部誤り - 変更が必要な箇所を伝えます 3. サブドメインの不足 - 一覧にない領域があります

一部が誤っているとユーザーが回答した場合は、どの分類を何に変更すべきか質問します。

次の AskUserQuestion を使って、要件に対する理解全体を提示し、ユーザーに確認します。

Header	Question	Options
Approval	要件に対するこの理解は正しいですか？	1. 承認 - アーキテクチャ設計に進みます 2. 修正が必要 - 誤っている点を説明します 3. コンテキストの不足 - 追加で伝える情報があります

承認されるまで先に進まないでください。

ステップ 2：モジュール型アーキテクチャを設計する

Balanced Coupling モデルを使用して、次の手順を実施します。

1. 上位レベルのモジュールと、その責務およびモジュール間の統合を特定します。
2. DDD のサブドメインを使用して変動性を分類します（コア＝変動性が高い、サポート／汎用＝変動性が低い）。これにより、設計に注力する場所を決定します。
3. 各統合について、3 つの次元（統合の強度、距離、変動性）すべてにわたって結合を評価します。
4. バランスルールを適用します：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY
   • 変動性の高いコンポーネントでは、強度と距離のバランスが取れるように統合を設計します。
     • 高度な知識の共有が必要なコンポーネント（機能的結合／モデル結合）は、同じ場所に配置します（距離が短い）→ 凝集度が高い。
     • 距離が長いコンポーネント（別々のサービス、別々のチーム）は、コントラクトを介して統合します（強度が低い）→ 疎結合。
   • 変動性の低いコンポーネントでは、実用的な近道が許容されることを認識します。
5. バランスの取れていない結合に印を付けます：強度が高く距離も長い（分散モノリスのリスク）、または強度が低く距離も短い（凝集度が低い／ビッグボールオブマッドのリスク）。
6. 問題のある統合を再調整するための、具体的な対応策を推奨します。

結合評価表をユーザーに提示します。

統合	強度	距離	変動性	バランスが取れているか	対応
A -> B	モデル	高（別々のサービス）	高（コア）	いいえ — 密結合	強度を下げる：API 経由のコントラクトを導入

各ステップで AskUserQuestion を使用してユーザーと一緒に進めます。各ステップでユーザーの承認が必要です。ユーザーがモジュール型アーキテクチャを完全に検証するまで、設計ドキュメントの作成に進まないでください。

ヘッダー	質問	選択肢
承認	このモジュール型アーキテクチャは正しいと思いますか？	1. 承認 - 設計ドキュメントに進む 2. 変更が必要 - 調整内容を説明します 3. 再検討 - モジュールの境界を見直しましょう

ステップ 3：モジュール設計ドキュメントを作成する

ステップ 2 で検証されたアーキテクチャを使用して、各モジュールについて docs/design/!date +%Y-%m-%d/{module-name}/design.md を作成します。

# {Module Name}

## Functional Responsibilities

What this module does — the functionality it implements and the business capabilities it provides.

## Encapsulated Knowledge

What this module knows that no other module should — the domain concepts, business rules, and implementation details it owns.

## Subdomain Classification

Core / Supporting / Generic — and the rationale for the classification.

## Integration Contracts

For each module this one integrates with:

- **Direction**: Which module depends on which
- **Contract type**: The integration strength level (contract / model / functional)
- **What is shared**: The specific knowledge exchanged
- **Contract definition**: The interface, API, events, or data structures that define the boundary

## Change Vectors

Reasonable future changes that would require ONLY this module to change — the axes of evolution this module's boundary is designed to support.

個別の承認を求めずに、すべてのモジュール設計ドキュメントを作成します。モジュール型アーキテクチャはすでにステップ 2 で承認されているため、これらのドキュメントは承認済みの設計をそのまま反映したものです。

すべてのモジュールドキュメントを作成した後、AskUserQuestion を使用して一式をユーザーに提示し、レビューを依頼します。

ヘッダー	質問	選択肢
モジュール	すべてのモジュール設計ドキュメントを作成しました。内容はいかがですか？	1. 承認 - テスト仕様に進む 2. 変更が必要 - 修正が必要なモジュールを説明します 3. アーキテクチャを再検討 - ドキュメントから境界の問題が明らかになりました

承認されるまで繰り返します。

ステップ 4：モジュールのテスト仕様を作成する

各モジュールについて、次の内容を含む docs/design/!date +%Y-%m-%d/{module-name}/tests.md を作成します。

# {Module Name} — Test Specification

## Unit Tests

Tests for the module's internal logic in isolation. Covers business rules, calculations, state transitions, and edge cases.

## Integration Contract Tests

Tests that verify the module honors its integration contracts — that it produces the correct outputs given valid inputs according to its contract definitions.

## Boundary Tests

Tests that verify the module correctly rejects invalid inputs, handles edge cases at its boundaries, and maintains its encapsulation (nothing leaks).

## Behavior Tests

Tests that verify the module's functional responsibilities from an outside-in perspective — given a business scenario, the module behaves as expected.

各テストセクションには、具体的な名前を付けたテストケースを次の内容とともに記載します。

• テスト名：内容がわかる名前
• シナリオ：テスト対象
• 期待される動作：正しい結果

承認を求めずに、すべてのテスト仕様を作成してください。モジュール設計はすでに承認されているため、テスト仕様はその設計から直接導き出します。

ステップ 5：アーキテクチャドキュメントを作成する

次の内容を含む docs/design/!date +%Y-%m-%d/architecture.md を作成します。

# Architecture Overview

## Functional Requirements Summary

Brief summary of the requirements this architecture addresses.

## Module Map

List of all modules with one-line descriptions.

## How the Modules Work Together

For each key functional flow / use case:

- Which modules participate
- How data/control flows between them
- What contracts govern the interactions

## Coupling Assessment

The coupling assessment table from the modular architecture analysis, with commentary on the key design decisions and their rationale grounded in the Balanced Coupling model.

## Design Decisions and Trade-offs

Key architectural decisions, what was considered, what was chosen, and why — grounded in the coupling dimensions and balance rule.

## Unresolved Risks

Anything the design intentionally leaves open, along with the conditions under which it should be revisited.

承認を求めずにアーキテクチャドキュメントを作成してください。これは、すでに承認されているモジュール設計をまとめたものです。

ステップ 6：モジュール性をレビューする

すべてのドキュメントを作成したら、設計におけるモジュール性の不均衡を自らレビューします。モジュール間の各統合について、次の点を確認します。

1. 統合を整理する：共有される知識は何ですか？それは暗黙的ですか、明示的ですか？統合の強度レベルはどの程度ですか？
2. 3 つの側面すべてを評価する：強度、距離、変動性。
3. バランスのルールを適用する：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY
4. 不均衡を特定する：不均衡かつ変動性の高い統合に重点を置きます。

見つかった問題は、それぞれ次の重大度に分類します。

• 重大：強度が高く、距離が遠く、変動性も高い。
• 重要：中程度に変動性のある領域で結合が不均衡な場合、または統合ポイントを隠してしまう暗黙的な結合。
• 軽微：変動性の低い領域で結合が不均衡な場合、または連鎖的な変更は引き起こさないものの、認知負荷を高める凝集度の低さ。

重大または重要な問題がある場合は、次の手順を実行します。

1. ステップ 2 の結合評価表と同じ構成で問題をユーザーに提示し、それぞれについて知識漏洩の説明と推奨される改善策を加えます。
2. 結合のバランスを取り直すための具体的な設計変更を提案します。
3. ユーザーが変更を承認したら、影響を受ける設計ドキュメント（モジュール設計、テスト仕様、アーキテクチャドキュメント）を更新します。
4. このステップを繰り返します — 更新後の設計を再度レビューします。重大または重要な問題がなくなるまで続けてください。

軽微な問題はアーキテクチャドキュメントの「未解決のリスク」セクションに記載しますが、完了を妨げるものではありません。

重要な制約

• 決して推測しないでください。 不明な点があれば、作業を進める前にユーザーに確認してください。
• 実行可能なドキュメントを作成してください。 各設計ドキュメントには、開発者が実装を始めるのに十分な情報を記載してください。各テスト仕様には、開発者がテストを書き始めるのに十分な情報を記載してください。
• 「すべてを切り離せばよい」と決して勧めないでください。 それでは、強度と距離のバランスが無視されます。
• 1 つの側面だけで結合を評価しないでください。 強度、距離、変動性の 3 つすべてを常に考慮してください。
• 本質的な変動性と偶発的な変動性を区別してください。 コミット頻度が高い場合、ドメインの変動性が高いのではなく、設計が不適切である（偶発的な変動性）ことを示している可能性があります。
• 距離の組織的な側面を考慮してください。 コード構造が同じでも、チームが異なれば、実質的な距離は大きくなります。
• すべての推奨事項の根拠をモデルに求めてください。 各設計判断を正当化する具体的な側面と原則を示してください。