design

設計

何を構築するのか、なぜ重要なのか、ユーザーがどのような体験をするのか、どのように機能するのかを決めます。実装エージェントが判断を補う必要がないよう、重要な選択を確定します。

プロセス

1. 依頼、リポジトリの指示、関連コード、リンク先の資料を確認します。確定済みの要件とリポジトリの慣例を再利用します。
2. 動作、インターフェース、データ、セキュリティ、運用、または検証方法を変える未決定事項を特定します。草案の作成前に、推奨する回答とともに作業を妨げる質問をします。作業を妨げない質問には、推奨する既定値を添えて記録します。
3. 下記の簡潔な形式で docs/<feature-slug>/design.md を作成します。定型的な機能の場合は、500～800語を目安にします。重要な決定やリスクを説明するために必要であれば、分量を増やします。語数の目標よりも完全性を優先します。
4. レビューを1回行います。入手可能な根拠に基づいて不足を修正し、未解決の決定事項を「未解決の質問」に記録します。
5. レビューに回せる設計案ができたら終了します。計画や実装は行いません。

ドキュメントの形式

# <Title>

> **Status:** Proposed for review

## 1. Requirements: what and why
Explain the problem, who has it, and the outcome they need. State the required capabilities, constraints, and what is out of scope. Make the value clear before introducing implementation details.

## 2. User experience
Describe the system as a black box: what the user does or supplies, what they see or receive, and what happens next. Walk through the main flow and relevant empty, invalid, denied, and failed outcomes, including recovery. For a CLI, API, or library, the user can be an operator or caller. Keep internal components and algorithms in the technical design.

## 3. Technical design and choices
Explain how the proposed change fits the existing system. Name the changed responsibilities, interfaces, and data. Record consequential technology choices with a reason and their main tradeoff. Add the relevant detail described below.

## 4. Acceptance and proof
Pair each testable condition with how it will be checked. Include affected failure paths and rules that must always hold. Reference earlier decisions instead of repeating their full definitions.

| ID | Done when | How to check |
|---|---|---|
| AC-1 | Observable condition | Exact command, automated scenario, or manual check |

## 5. Open questions
List unresolved decisions, the recommended answer, and whether they block planning or implementation. Write None when the design is settled.

技術的な詳細

今回の変更で決定が必要なトピックだけを記載します。必要に応じて短い小見出しを使います。

• 技術選択： 言語、フレームワーク、主要な依存関係、ストレージ、デプロイ。新規プロジェクトでは、コアとなる技術スタックを選びます。既存プロジェクトでは、確立済みの選択を参照し、追加や変更について説明します。互換性に関わる場合はバージョンを固定します。
• 構成と契約： 変更するコンポーネントの責任と境界、API、コマンド、イベント、スキーマ、設定、マイグレーション。保存済みの名前やIDを変更する場合は、識別子の作成方法と互換性について説明します。
• 障害と復旧： 起こりうる障害、その結果の状態、再試行とその上限、復旧方法。結果に影響する場合は、起動中、処理中の変更、シャットダウンについても説明します。
• セキュリティと運用： 信頼境界、認可、機密データ、スケール、レイテンシ、接続数、ディスク、メモリ、コストに関する制限。該当する制限に達した場合の動作を明記します。

重要な選択ごとに、決定内容、要件に適している理由、主なコストまたは制約を記載します。却下した代替案は、比較が選択理由の説明になる場合に限り記載します。容易に元に戻せる局所的な実装上の詳細は、実装エージェントに委ねます。

執筆ルール

• 平易な言葉を使い、必要な用語は定義します。 em ダッシュは使いません。
• 各事実は1か所に記載します。要件では必要性を、ユーザー体験では観察できる動作を、技術設計では実装方法を説明します。受け入れ確認ではこれらを参照し、同じ内容を重ねて記載しません。
• 説明には文章を使い、並列する事実にはリストを使います。図は関係やフローを明確にする場合に限り使用します。
• 現在のアーキテクチャと提案する動作を明確に区別します。ARCHITECTURE.md がある場合はリンクし、共有されている慣例は繰り返さずに参照します。
• 計画、実装、レビューを通じて安定した参照が必要なルールには INV-n を使います。すべての不変条件を「受け入れ条件と検証」における検証方法に対応付けます。
• 引用した AC-n と INV-n の ID は、対応する同じルールに付けたままにします。番号を振り直したり、再利用したりしないでください。追加する場合は、未使用の次の番号を割り当てます。
• 既存の設計を更新するときは、リンクされたセクションのアンカーを維持します。このテンプレートに合わせるためだけに構成を変更しないでください。

レビューパス

設計を返す前に、次の4点を確認します。

1. 新しいチームメンバーは、技術設計を読まなくても、何が変わるのか、なぜ変わるのか、ユーザー体験を説明できますか？
2. 実装エージェントは、重大なプロダクト上または技術上の判断を独自に行わずに作業を進められますか？ 技術の選択には妥当な理由があり、リポジトリと互換性がありますか？
3. 関連する障害、データの変更、信頼境界、運用上の制限が明確で、安全で互換性のない実装を防ぐのに十分な詳細がありますか？
4. 各受け入れ基準と不変条件には、具体的な根拠がありますか？ 曖昧なタイミングや複数の結果を許す記述を、検証可能な単一のルールに置き換えてください。背景の重複をなくし、判断材料を増やさないセクションは削除してください。

返却内容

設計のパス、主な技術的判断とトレードオフ、ブロッキングとなる質問の有無、レビュー結果を報告してください。簡潔にまとめてください。詳細は設計に記載されています。