discovery

ディスカバリー

概要

計画やコーディングを始める前に、問題を理解します。有用な質問をし、エッジケースを探り、不明確な要件を早い段階で明らかにします。

ディスカバリーの前に、principles スキルを読みます。ドメインの用語、境界、状態、契約、運用上のリスク、トレードオフの確認に活用します。

まず、対話の深さを選びます。

• ライトウェイトなディスカバリー：非公式な探索、質問だけの依頼、またはファイルを作成すると手間がかかりすぎる場合に使います。最も重要な質問を1〜3個尋ねるか、すでにわかっていることを要約します。簡潔なチャットのまとめと未解決の質問で締めくくります。
• フルディスカバリー：複雑なテーマ、回答が後の計画や実装に使われる場合、またはユーザーが設計成果物を求めている場合に使います。焦点を絞った質問を3〜7個まとめて尋ね、必要に応じてやり取りを重ね、最後に独立した設計成果物を作成します。

回答によって設計の理解が変わる場合にのみ質問します。 各質問群は回答可能な範囲にとどめ、一度に尋ねる質問は7個までにします。重要度の高いものを優先します。まず全体像を尋ね、必要に応じて掘り下げます。

考えられるテーマ：

• 目標／成果（成功とはどのような状態か）
• 対象者／ユーザーと利用状況
• 制約（時間、予算、技術、トーン、スコープ）
• 現状（現在あるもの、避けるべきこと）
• 既知の問題点と障害のパターン
• 主な前提と不明点

エッジケース、悪用ケース、不明確なシナリオを指摘します。要件が不十分な箇所を明確に示します。

ディスカバリーの最後に、設計成果物を保存するかどうかを判断します。

• ユーザーが設計成果物を求めた場合、ディスカバリーで失われてはならない決定事項や制約が明らかになった場合、または今後の計画／実装がその結果に依存する可能性が高い場合は、独立した設計成果物を作成します。
• それ以外の場合は、有用な結論をチャットで要約し、ファイルは作成しません。

開始時に宣言します： "I'm using the discovery skill to understand the design space."

原則の活用

• トップレベルの原則を使って、質問を選び、回答を要約します。
• 必要に応じて、principles スキルの詳細を読みます：shape code by domain、keep boundaries sharp、states are values、 evolve contracts deliberately、performance is not optional、および design for operation。
• 設計上の事実、トレードオフ、リスクには原則名を使います。
• 成果物には、ドメイン用語、状態モデル、信頼境界、長期にわたる契約、運用上の制約、リスクを記録します。

設計成果物

成果物は設計ドキュメントであり、計画やレビューではありません。

• 設計には、問題の理解、目標、制約、決定事項、選択肢、トレードオフ、除外したアプローチ、リスク、エッジケース、未解決の質問を記録します。
• 計画には、設計の一部を実装するための具体的な手順を記載します。
• レビューには、実装、計画、設計などの成果物に関する指摘を記載します。

設計の保存先： <repository-root>/designs/YYYY-MM-DD_HH:MM_<design-name>.md

存在しない場合は designs/ を作成します。

以下の構成を標準として使いますが、テーマに応じてセクション名を変更したり、セクションを追加または削除したりします。

# Design: <Name>

## Summary
<1-3 sentences describing the problem, intended outcome, and current design understanding.>

## Context
<Relevant background, users/audience, existing state, constraints, and why this matters.>

## Goals
<Bulleted outcomes this design should support.>

## Non-Goals
<Bulleted boundaries for what this design is not trying to solve. Skip if not useful.>

## What We Learned
<Important discoveries, domain facts, user needs, constraints, assumptions, and edge cases.>

## Design Shape
<Current conceptual model, requirements, principles, interfaces, UX shape, system behavior, or other design-relevant structure. Keep this at design level, not implementation-task level.>

## Options Considered
<Candidate approaches, including approaches ruled out. Capture why they matter and why they were accepted, rejected, or deferred.>

## Risks and Edge Cases
<Known failure modes, abuse cases, unclear scenarios, and places where the design may break down.>

## Open Questions
<Unresolved decisions or unknowns that future discovery, planning, or review should address. Skip only if none remain.>

アーティファクトのルール

• 設計アーティファクトを作成するのは、検討が完了し、その結果を保存すべき場合に限ります。ただし、ユーザーが検討の続行を明示的に求めた場合は除きます。
• ユーザーがファイルを作成しないよう求めている場合や、簡潔な話し合いだけを希望している場合は、設計アーティファクトを作成しないでください。
• アーティファクトを作成しない場合は、現在の理解、重要なトレードオフ、未解決の質問を簡潔にまとめてチャットを締めくくってください。
• 設計は単独で理解できるものにしてください。それ以前のチャットに依存してはいけません。
• 後で重要になる可能性の高い知見、特に制約、却下したアプローチ、未解決の質問を残してください。
• 順序付きの実装タスク、ファイル単位の変更一覧、検証コマンド、ロードマップは含めないでください。
• 不要な情報が増える場合は、すべてのセクションを無理に設けず、アーティファクトを有用なものにしてください。
• ユーザーが検討から計画または実装へ移ることを求めた場合、重要なコンテキストが失われるおそれがあるときに限り、まず設計アーティファクトを保存することを提案してください。

対話に関する注意事項

• 深く掘り下げてください。
• 計画、ロードマップ、実装手順、コードは作成しないでください。
• ユーザーが計画やコードを求めた場合、十分なコンテキストが得られた時点で検討モードを終了してください。設計のコンテキストが重要で、まだ記録されていない場合は、切り替える前に保存するかどうかを尋ねてください。