sdd-design

SDD 設計

このスキルの最初の応答では、次の行を一度だけ最初に記載してください。 sdd-design v1.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

クイックスタート

Brainstorm と DEFINE を、実装可能な技術 DESIGN に変換します。

1. Brainstorm と DEFINE をすべて読みます。
2. ユーザーから UX Review も提供された場合は、それも読みます。
3. 権威ある要件、元の意図、過去の決定、技術的な根拠を分けて整理します。
4. コードやプロジェクトのコンテキストが利用できる場合は、調査します。
5. アーキテクチャや具体的な File Manifest の作成を妨げる技術的な不足点を特定します。
6. 必要なことだけを尋ね、できる限り、やり取りごとに主な質問を一つにします。
7. アーキテクチャを作成し、重要な決定をインライン ADR として記録します。
8. 完全な File Manifest、コーディング規約、データフロー、連携、テスト戦略を作成します。
9. references/llm-prompts.md の LLM Prompts に関する条件付きルールを適用します。
10. 必ず assets/DESIGN_TEMPLATE.md を記入します。
11. ファイルシステムと Python を利用できる場合は、python scripts/validate_design.py <DESIGN.md> を実行します。
12. DESIGN_{FEATURE_NAME}.md を保存または提出します。
13. ドキュメントの最後は Execute o **SDD Build by RDD**. のみとします。

ワークフロー全体を通して references/design-protocol.md を参照してください。Build の前に正式な外部技術レビューがある場合に限り、references/advisor-review.md を参照してください。

必要な情報

必須

• Brainstorm の Markdown ファイル。BRAINSTORM_{FEATURE_NAME}.md が望ましいです。
• Define の Markdown ファイル。DEFINE_{FEATURE_NAME}.md が望ましいです。

質問する前に、両方を読んでください。

任意

• UX_REVIEW_{FEATURE_NAME}.md（存在する場合）
• プロジェクトのディレクトリツリーまたは関連ファイル
• リポジトリの技術的な規約
• API、スキーマ、キュー、データベース、インフラストラクチャのドキュメント
• テスト、lint、typecheck、build、smoke の実際のコマンド
• 利用可能なエージェント／専門家の一覧
• ユーザーからの確認回答

インターネットを必須としないでください。リポジトリ、エージェント、インフラストラクチャ、コードを実際に確認できる資料がない場合、それらを確認したと主張しないでください。

情報源の優先順位

要件と動作について：

1. ユーザーの最新の明示的な回答
2. UX Review（提供されており、中心的な要件と矛盾しない場合）
3. DEFINE
4. Brainstorm

Brainstorm は、意図、検討した代替案、YAGNI、決定の背景を把握するために使用します。ただし、正当な理由がない限り、DEFINE で確定した要件を再検討しないでください。

現在の技術的事実について：

1. 実際にアクセス可能なプロジェクトのファイル／コード
2. ユーザーが提供した技術ドキュメント
3. ユーザーの明示的な回答
4. 明確に推論と示した内容

関連する情報源同士が矛盾する場合は、決定を確定する前に質問してください。

生徒への話し方

最初の応答の前に references/como-falar.md を読んでください。このスキルの用語集と、最初から最後までの例が記載されています。 このスキルを使う人は、たいてい git もターミナルも使ったことがありません。

段階	生徒向けの名前	このスキルの手順
1	読む	1～3
2	決定事項	4（1 回の応答につき主要な決定を 1 つ）
3	コンポーネントとファイル	5～9
4	フロー、テスト、エラー	10～15
5	確認	16～18
6	保存	19、20

すべての応答は、次の順序にします（内容がない部分は省略します）。ステータス（Design: ✅ 1 … · ▶️ 2 … · ⬜ 3 …; ✅ は完了（訪問しただけではありません）、⏸️ は停止、➖ はスキップです。段階に戻る場合は、その理由を「現在」に記載します） · 実施内容（短い文で、コマンド出力は含めません。生徒の選択を記録します） · 現在：段階 N — 名前（2～4 文。時間がかかる作業の前には、何を実行するか、応答する必要がないことを伝えます） · 決定事項（許可を求める場合：質問と、それぞれの効果を示す選択肢を記載します。自由回答の場合：質問と回答方法を示し、「わかりません」という選択肢も用意します。グループ化して番号を付けます） · 次のステップ（1 行）。

• 1 回の応答につき 1 段階とし、決定事項を示したところで終了します。
• 技術用語は初出時に必ず説明を添えます。ステータス内の用語も含みます（用語集は参照資料にあります）。
• コマンド出力をそのまま提示してはいけません。件数、内容、懸念点を伝えます。名前は最大 10 個まで示し、残りがあれば「ほか N 件」とします。コマンドを示すのは生徒が実行する必要がある場合のみです。手順番号ごとに 1 つずつ記載し、画面に何が表示されるかも伝えます。
• このスキルの指示を引用したり要約したりしてはいけません（「手順 N に従って」など）。生徒にとっての理由を伝えます。
• 回答が選択肢に当てはまらない場合は、質問に答えてから選択肢をもう一度示します。
• 停止する場合：⏸️ をステータスに付け、理由を 1 文で説明し、作業を行う場所を示して、期待する結果を番号付きの手順で説明します。実施していないことも示します。生徒が何かする必要がある場合は、「完了したら、もう一度依頼してください。ここから続けます。」と伝えます。（lint の不合格は生徒が対処する作業ではありません。調整する内容を伝え、そのまま続けます。）

手順

1. 入力資料を読む

Brainstorm から抽出する内容：

• 問題と本来の意図；
• 選択したアプローチ；
• 却下した代替案；
• 重要な決定事項；
• YAGNI により削除または延期した項目；
• 依存関係とサンプル；
• 仮説と制限事項。

DEFINE から抽出する内容：

• Problem Statement；
• Target Users；
• Goals と優先順位；
• Success Criteria；
• Acceptance Tests；
• Out of Scope；
• Constraints；
• Technical Context；
• Assumptions；
• Verify Gate；
• LLM Prompts フラグ。

UX Review がある場合は、次の内容を抽出します：

• UX/CX の MUST；
• フロー；
• 状態；
• インタラクションの制約；
• アーキテクチャまたは実装に影響する推奨事項。

資料の文章を DESIGN にそのまま重複して記載してはいけません。技術的な決定に影響する内容だけを変換します。

2. 入力内容の準備状況を確認する

設計を始める前に、次の点を確認します：

• DEFINE が実装の指針として十分にまとまっている；
• 重要な要件に矛盾がない；
• LLM Prompts が文字どおり true または false である；
• Verify Gate が存在するか、客観的な完了の目印がある；
• Out of Scope が明示されている。

いずれかがアーキテクチャを妨げる場合は、ユーザーに質問します。DEFINE を黙って「修正」してはいけません。

3. 利用可能な技術コンテキストを調査する

プロジェクトやコードにアクセスできる場合：

• 言語とフレームワークを特定する；
• ディレクトリ構成を確認する；
• 類似モジュールを探す；
• 設定に関する規約を確認する；
• 既存のテストを探す；
• 再利用できるインテグレーションと抽象化を特定する；
• ロギングと可観測性のパターンを特定する；
• エージェントのカタログがあれば特定する。

アクセスできない場合：

• パス、ライブラリ、エージェントを推測しない；
• 具体的な File Manifest を作成するために必要な最小限の技術スタックと構成について質問する；
• ユーザーが技術スタックと技術基盤を確認してから、グリーンフィールドプロジェクトを開始する。

4. 構造を阻害する技術的判断を特定する

次の事項について、必要な判断を内部的に一覧化します。

• コンポーネントの境界；
• 永続化とデータモデル；
• 統合の契約；
• 同期／非同期の実行；
• 冪等性とリトライ；
• 認証／認可；
• 設定；
• オブザーバビリティ；
• テスト戦略；
• 作成／変更するファイル；
• 該当する場合は LLM ランタイム。

情報源やプロジェクト内の既存パターンですでに解決している選択肢については、質問しません。

メッセージごとに、主な質問は1つにすることを優先します。選択肢が明確な場合は、2～4個の選択肢を提示し、根拠とともに1つを推奨したうえで、自由回答も可能にします。

5. Architecture Overview を作成する

次の内容を表す、読みやすい ASCII 図を作成します。

• 入力；
• コンポーネント；
• ストレージ；
• 外部統合；
• 出力；
• 主なフローの方向。

図は Components および Data Flow と整合している必要があります。

明確な役割のないコンポーネントは追加しません。

6. Components を定義する

各コンポーネントについて、次の項目を記録します。

• 名前；
• 責務；
• 技術／パターン；
• 入力；
• 出力；
• 依存関係。

責務のまとまりを優先し、シンプルな境界を設定します。

既存の構造で要件を満たせる場合は、新たな抽象化を避けます。

7. Key Decisions をインライン ADR として記録する

重要な判断ごとに、次の項目を記録します。

• Status；
• Date；
• Context；
• Choice；
• Rationale；
• Alternatives Rejected；
• Consequences。

アーキテクチャ、保守コスト、契約、データ、デプロイ、セキュリティ、テスト容易性を変える判断を記録します。

些細な詳細について ADR は作成しません。

選択が DEFINE の内容から直接決まる場合は、その判断を維持し、技術的な影響のみを説明します。この段階で代替案を再評価したかのように記述してはいけません。

8. File Manifest を作成する

Build で作成、変更、または削除するすべてのファイルを一覧化します。

各行には次の項目を含めます。

• 番号；
• パス；
• アクション；
• 目的；
• owner/agent；
• 依存関係。

ルール：

• 利用可能な場合は、プロジェクト内の実際のパスを使います；
• 実際に確認したかのようにパスを捏造しません；
• greenfield の場合は、確認済みのスタックに適合するパスを使います；
• テストファイルを含めます；
• 実装に含まれる設定、migration、schema、prompt を含めます；
• 循環依存を避けます；
• 依存関係には manifest のインデックスを使います。

専門エージェントが不明な場合は (general) を使い、Agent Discovery: Not available を記録します。

9. Code Patterns を定義する

Build における曖昧さを減らす重要なパターンに限り、短く、そのままコピーして使えるスニペットを提示します。

次を優先します。

• 中核となるシグネチャ／インターフェース；
• 関連する schema／model；
• エラーパターン；
• 設定；
• 統合の契約。

確認済みのスタックで実際に使われている言語を使用します。

DESIGN で実装全体を書いてはいけません。

10. LLM Prompts のルールを適用する

references/llm-prompts.md を参照します。

LLM Prompts: false の場合：

• Brainstorm + DEFINE + UX Review + Design のスコープを対象に、防御的な再確認を行います；
• 該当する兆候がなければ、## LLM Prompts セクションを作成しません；
• 矛盾する兆候がある場合は、続行する前に質問します。

LLM Prompts: true の場合：

• Code Patterns と Data Flow の間に ## LLM Prompts を作成します；
• 計画されているすべての prompt／LLM ランタイムを一覧化します；
• 各項目を one-shot または loop に分類します；
• 各 prompt の契約を定義します；
• 一覧を File Manifest および LLM を呼び出すサービスと照合します；
• この段階では最終的な prompt を生成しません。

11. Data Flow を記述する

エンドツーエンドの運用手順を表します。

各重要なステップについて、次を明確にします。

• 入力；
• 変換；
• 永続化；
• 外部呼び出し；
• 状態／失敗；
• 出力。

アーキテクチャに影響する場合は、主要なエラーパスも説明します。

12. 統合ポイントを定義する

外部連携ごとに、以下を記録します。

• システム
• 種類
• 認証
• 方向
• 関連するタイムアウト／再試行
• 障害時の動作

認証情報、エンドポイント、上限を推測して記載しないでください。

連携がない場合は、None を使用します。

13. テスト戦略を計画する

要件とリスクを、以下のテストに対応付けます。

• unit
• integration
• E2E
• DEFINE から導かれる場合は smoke／eval／typecheck

プロジェクトで使用していないツールや、ユーザーが確認していないツールを勝手に追加しないでください。

DEFINE の Acceptance Tests および Verify Gate との整合性を保ってください。

14. エラー処理を定義する

少なくとも以下を網羅します。

• 無効な入力
• 外部依存先が利用できない場合
• タイムアウト
• 該当する場合は永続化の失敗
• 該当する場合は競合／冪等性
• 該当する場合は LLM のエラー

安全で、冪等性と互換性がある場合に限り、再試行を記録してください。

15. Configuration、Security、Observability を定義する

Configuration：

• 調整可能な値を外部化する
• コード内にシークレットを含めない
• 機密値の出所を明記する

Security：

• 認証／認可
• 入力の検証
• シークレット
• PII／機密データ
• 最小権限
• 機能固有のリスク

Observability：

• ログ
• メトリクス
• 該当する場合はトレーシング
• 可能な場合は Success Criteria および Verify Gate に関連するシグナル

16. 横断的な整合性を検証する

以下を確認します。

• すべてのコンポーネントが図に記載されているか、または記載しない理由がある
• File Manifest が関連するすべてのコンポーネントを実装している
• manifest の依存関係に循環がない
• テストがリスクと Acceptance Tests を網羅している
• 統合にエラー処理がある
• ファイルが必要な設定が manifest に記載されている
• セキュリティと可観測性が制約に反していない
• true の場合、LLM Prompt Inventory が完全である
• Out of Scope が誤って計画に含まれていない

17. 正式なアセットを記入する

最終ドキュメントの唯一の構造的な情報源として、assets/DESIGN_TEMPLATE.md を使用します。

必須セクションの見出しと順序を維持してください。

定義された条件に該当する場合にのみ、## LLM Prompts を追加します。

プレースホルダーを削除します。Ready for Build とマークされた DESIGN に、TBD、{placeholder}、[NEEDS CLARIFICATION] を残さないでください。

18. 決定的な lint を実行する

ファイルシステムと Python が利用できる場合は、以下を実行します。

python scripts/validate_design.py <caminho-do-DESIGN.md>

最終版を提出する前に、構造上の問題をすべて修正してください。

このスクリプトは構造と基本的な整合性を検証するものであり、アーキテクチャのレビューに代わるものではありません。

19. 保存して提出する

標準のファイル名： DESIGN_{FEATURE_NAME}.md

保存先。 プロジェクトのルートにある sdd/ に保存します。すべてのエージェントで同じ、見つけやすいフォルダーです。プロジェクトに .claude/sdd/ がすでにある場合は、そのフォルダーを引き続き使用します。5 フェーズのドキュメントはサブフォルダーを作らず、同じ場所に保存します。

プロジェクトのファイルシステムが利用できる場合：

• sdd/DESIGN_{FEATURE_NAME}.md に保存します（そのフォルダーがすでにある場合は .claude/sdd/DESIGN_{FEATURE_NAME}.md に保存します）。
• 既存のファイルを黙って上書きしないでください。

利用できない場合：

• プラットフォームで許可されていれば、.md ファイルをダウンロード用に提供します。

20. 標準の handoff で終了する

最後のセクションは、次のとおりにしてください。

## Next Step

Execute o **SDD Build by RDD**.

このテキストの後に、slash command、パス、アップロード、GPT／Skill、その他の並行アクションを追加しないでください。

品質ゲート

Ready for Build にする前に：

• Brainstorm をすべて読んでいます。
• DEFINE をすべて読んでいます。
• 提供された場合、UX Review を反映しています。
• 権威ある要件を維持しています。
• 技術的なコンテキストを確認するか、明示的に確認済みです。
• Architecture Overview が明確です。
• Components が図と整合しています。
• 重要な決定を根拠とともに記録しています。
• 関連する決定に Alternatives Rejected と Consequences を記録しています。
• File Manifest が、該当する場合はテスト／設定を含めて完全です。
• 観察していない Paths を、観察済みとして誤って提示していません。
• File Manifest の依存関係に循環がありません。
• Code Patterns はコピー＆ペーストで使用でき、スタックと互換性があります。
• LLM Prompts が条件付きルールに従っています。
• Data Flow がアーキテクチャと整合しています。
• Integration Points に障害時の動作が定義されています。
• Testing Strategy が要件とリスクを網羅しています。
• Error Handling が関連する障害を網羅しています。
• Configuration にハードコードされたシークレットが含まれていません。
• Security Considerations が具体的です。
• Observability で有用なシグナルを定義しています。
• 実装を予定している Out of Scope 項目はありません。
• placeholder、TBD、または進行を妨げる未解決事項はありません。
• 実行可能な場合、scripts/validate_design.py が成功します。
• 最終ドキュメントの名前が DESIGN_{FEATURE_NAME}.md です。
• Next Step に Execute o **SDD Build by RDD**. のみが含まれています。

例外の処理

• Brainstorm がない場合：ファイルを依頼してください。黙って再構築しないでください。
• DEFINE がない場合：ファイルを依頼してください。Brainstorm だけを基に最終 Design を作成しないでください。
• DEFINE が Brainstorm と矛盾する場合：要件には DEFINE を適用し、技術的な決定に影響する場合にのみ相違を記録してください。
• UX Review が DEFINE と矛盾する場合：その矛盾が重要であれば、どちらの方針を優先するか確認してください。
• LLM Prompts がない、または曖昧な場合：確認してください。独断で選択しないでください。
• コードのコンテキストがない場合：必要なスタック／構成を依頼してください。調査したふりをしないでください。
• File Manifest を具体化できない場合：ドラフトの状態を維持し、明確化を求めてください。
• ライブラリ／サービスが確認されていない場合：選択が進行を妨げるなら、代替案を提示して確認してください。
• ユーザーが進行を妨げる未解決事項を残したまま終了しようとする場合：Draft／Needs Clarification として提出し、Ready for Build と断定しないでください。
• 外部による正式なレビューの場合：references/advisor-review.md を適用し、各指摘を APPLIED または REBUTTED として記録してください。

---

SDD Open by RDD の一部 — https://github.com/robertodiasduarte/sdd-open