design-an-interface

インターフェースを設計する

「A Philosophy of Software Design」の「Design It Twice」に基づいています。最初のアイデアが最善とは限りません。根本的に異なる複数の設計を生成し、比較してください。

ワークフロー

1. 要件を集める

設計の前に、次の点を理解します。

• このモジュールは何の問題を解決しますか？
• 呼び出し元は誰ですか？（他のモジュール、外部ユーザー、テスト）
• 主要な操作は何ですか？
• 制約は何ですか？（パフォーマンス、互換性、既存のパターン）
• 内部に隠すべきものと、公開すべきものは何ですか？

「このモジュールには何が必要ですか？誰が使いますか？」と尋ねます。

2. 設計を生成する（並列サブエージェント）

Task ツールを使って、3 つ以上のサブエージェントを同時に起動します。それぞれ、根本的に異なるアプローチを提示する必要があります。

Prompt template for each sub-agent:

Design an interface for: [module description]

Requirements: [gathered requirements]

Constraints for this design: [assign a different constraint to each agent]
- Agent 1: "Minimize method count - aim for 1-3 methods max"
- Agent 2: "Maximize flexibility - support many use cases"
- Agent 3: "Optimize for the most common case"
- Agent 4: "Take inspiration from [specific paradigm/library]"

Output format:
1. Interface signature (types/methods)
2. Usage example (how caller uses it)
3. What this design hides internally
4. Trade-offs of this approach

3. 設計を提示する

それぞれの設計について、次の内容を提示します。

1. インターフェースのシグネチャ — 型、メソッド、パラメーター
2. 使用例 — 呼び出し元が実際にどのように使うか
3. 隠すもの — 内部に留める複雑さ

比較する前にユーザーが各アプローチを理解できるよう、設計を1つずつ順番に提示します。

4. 設計を比較する

すべての設計を提示したら、次の観点で比較します。

• インターフェースのシンプルさ：メソッドが少なく、パラメーターがシンプル
• 汎用性と特化：柔軟性と焦点
• 実装効率：この形状によって効率的な内部実装が可能か？
• 深さ：小さなインターフェースで複雑さを多く隠す（良い）か、大きなインターフェースに薄い実装を組み合わせる（悪い）か
• 正しく使いやすいかと誤用しやすさ

トレードオフは表ではなく、文章で説明します。設計間の違いが最も大きい点を強調します。

5. 統合する

最善の設計は、多くの場合、複数の選択肢の知見を組み合わせたものです。次のように尋ねます。

• 「主なユースケースには、どの設計が最も適していますか？」
• 「他の設計から取り入れる価値のある要素はありますか？」

評価基準

「A Philosophy of Software Design」に基づいています。

インターフェースのシンプルさ：メソッドが少なく、パラメーターがシンプルであるほど、習得しやすく、正しく使いやすくなります。

汎用性：変更せずに将来のユースケースにも対応できます。ただし、過度な汎用化には注意してください。

実装効率：インターフェースの形状によって効率的な実装が可能ですか？それとも、内部実装を不自然なものにせざるを得ませんか？

深さ：小さなインターフェースで複雑さを多く隠すのは、深いモジュールです（良い）。大きなインターフェースに薄い実装を組み合わせるのは、浅いモジュールです（避けてください）。

アンチパターン

• サブエージェントに似た設計を提示させないでください。根本的に異なる案を求めます。
• 比較を省略しないでください。価値は対比にあります。
• 実装しないでください。ここではインターフェースの形状だけを議論します。
• 実装にかかる労力を基準に評価しないでください。