api-shape-explorer

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

「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. 隠すもの - 内部に保持する複雑さ

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

4. 設計を比較する

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

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

トレードオフは表ではなく文章で説明します。設計が最も大きく異なる点を強調してください。

5. 統合する

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

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

評価基準

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

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

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

実装効率：インターフェースの形状によって、効率的に実装できますか？それとも、内部に無理のある構造を強いることになりますか？

深さ：小さなインターフェースで大きな複雑さを隠す設計は、深いモジュールです（良い設計）。大きなインターフェースに薄い実装が対応する設計は、浅いモジュールです（避けてください）。

アンチパターン

• サブエージェントに似た設計を作らせないでください。大きな違いが出るようにしてください。
• 比較を省略しないでください。価値は対比にあります。
• 実装しないでください。ここで扱うのはインターフェースの形状だけです。
• 実装の労力を基準に評価しないでください。