charted-design

共同設計ドキュメント

目標

セクションごとにユーザーに質問しながら、設計ドキュメントを作成します。利用可能な場合は、AskUserQuestion ツールを使用してください。 重要：各セクションの後に、現在の状態を解決済みの設計ドキュメントフォルダーに書き込んでください（下記の設計ドキュメントの保存場所を参照）。 ディスク上の設計ドキュメントファイルが主な成果物です。 機能の複雑さに合わせて、インタビューの進め方を調整してください。

文体

以下のルールは、（このスキルファイルではなく）設計ドキュメントの出力にのみ適用してください。

• 段落よりも、短い箇条書きの文を優先します。
• 1つの箇条書きに1つのアイデアを記載し、行の長さはおおよそ画面幅（約150文字）に収めます。
• インタビュー中に草案を提示するときも、最終的にまとめたドキュメントでも、この文体を使用します。

設計ドキュメントの保存場所

何かを書き込む前に、このワークスペース内で設計ドキュメントを保存する場所を特定します。

• ルート：ワークスペースのルートにある design-docs/
• サブフォルダー：例：contributing/design-docs/、docs/design/、またはプロジェクト固有のその他のパス
• モノレポ：複数のプロジェクトにそれぞれ専用のフォルダーがある場合があります（例：apps/web/design-docs/、packages/core/design-docs/）

特定方法：

1. 既存の設計ドキュメントフォルダー（design-docs という名前のディレクトリ、または 001-*.md のような番号付きファイル）を検索します
2. ユーザーがプロジェクトまたはパスを指定した場合は、それを使用します
3. 明確な場所が1つだけある場合は、それを使用します
4. 候補が複数ある場合、または見つからない場合は、書き込む前にどのフォルダーを使用するかユーザーに確認します

場所を特定したら、セッションの残りの間はそのフォルダーを使用します。

出力ファイル

• パス：解決済みの設計ドキュメントフォルダー（上記を参照）
• 名前：NNN-short-kebab-title.md — NNN はゼロ埋めの番号です（例：001、002）
• 連番：そのフォルダーとサブフォルダー（例：archived/）内のファイルを一覧表示し、最大の番号に1を加えます。空のフォルダーの場合は 001 から始めます
• タイトル：機能の説明から短いケバブケースのタイトルを作成します（先にユーザーに確認します）

インタビュープロセス

各セクションについて、次の手順に従います。

1. セクションの内容と、必要な情報を説明します
2. 必要な情報を集めるため、的を絞った質問をします
3. 設計ドキュメントファイルに、セクションの草案をすぐに書き込みます — チャットだけでなく、ディスク上のファイルを更新します
4. ファイルのパスと更新したセクションをユーザーに伝え、次に進む前にファイルを確認・編集してもらい、承認または修正内容を確認します

ユーザーの回答に後のセクションで扱う内容が含まれている場合は、その旨を伝え、該当するセクションに進んだときに追加すると説明します。

セクションの順序と質問

1. 目標

この作業がなぜ重要なのかを記述します。ユーザーの課題、ビジネス上の成果、または機会に焦点を当てます。解決策ではなく、目的を重視します。

質問：この問題を抱えているのは誰ですか？どのような課題やニーズがありますか？なぜ今、それを解決することが重要ですか？

目標は機能や実装ではなく、成果やニーズとして記述します。

• 良い例：「食事の計画を立てる際、大規模なレシピカタログの中から探すのにユーザーが時間を取られています。」
• 悪い例：「ユーザーの入力に応じてレシピを絞り込む検索入力欄を追加します。」

ユーザーが解決策を説明した場合は、セクションを書く前に、その根底にあるニーズとして言い換えます。機能、UX、技術的なアプローチは、「望ましい動作」と「設計」のセクションで扱います。

2. 対象外

質問：明確に対象外とするのは何ですか？対象に含まれると思われる可能性があるものの、実際には含まれないものは何ですか？

3. 望ましい動作

質問：ユーザーから見える動作を説明してください。ユーザーは何を見て、クリックし、どのような体験をしますか？シナリオを順を追って説明してください。

各動作はチェックボックス形式で記述します。

- [ ] User sees a search input and a list of rules below it.
- [ ] Typing in the search input filters the visible rules by name.

4. 設計

質問：大まかに、どのように実装すべきですか？どのようなコンポーネント、サービス、またはデータ構造が関係しますか？

4a. 図

主要なコンポーネントと相互作用を示す Mermaid の flowchart を作成します。

凡例：

• 角が四角形 = Angular／React／Vue のコンポーネント、またはバックエンドの HTTP コントローラー
• 角が丸い（つまり [(xyz)]）= サービス
• 矢印：methodName({param1: Type1}): ReturnType
• [input1: Type1] = Angular／React／Vue の入力／props、またはバックエンドのリクエスト／イベントパラメーター
• (output1: Type1) = Angular／React／Vue の出力／コールバック、またはバックエンドのレスポンス／イベント
• ラベルが途切れないように、<br> を使用します

図を設計ドキュメントファイルに書き込み、そこでユーザーにレビューを依頼します。

4b. 実装の詳細

質問します：アルゴリズム、エッジケース、または規約はありますか？ 追加する内容がなければ空欄にします。

チェックボックスよりもコードスニペットを優先します。型、インターフェース、シグネチャのスニペットを記載するのは、それがまだ存在しない場合、分かりにくい場合、または大幅に変更される場合に限ります。分かりにくい動作は JSDoc に記載します。シグネチャから明らかな場合は JSDoc を省略します。既存の自明なコードや小さな編集は省略します。

型、インターフェース、シグネチャで表現できない詳細（配線、順序付け、登録など）に限り、チェックボックスを使用します。

PR 番号はまだ追加しないでください。PR 計画の後に追加します（下記の PR の関連付けを参照）。

```ts
/**
 * Empty cart returns `[]`, never null.
 * Does not create a cart.
 */
interface CartRepository {
  getItems(): CartItem[];
}
```

- [ ] Cart reads items with `inject(CartRepository)`.
- [ ] Register `CartRepository` in the cart feature providers.

5. テスト戦略

質問します：設計に含まれる各コンポーネントまたはユニットについて、テストすべき重要な動作は何ですか？

形式：コンポーネントごとにグループ化（##）し、各テストシナリオを ### 見出しにして、その下にプレーンな箇条書きで手順を記載します。PR 計画の後に追加するため、見出しにはまだチェックボックスや PR 番号を追加しないでください（下記の PR の関連付けを参照）。

例：

## Cart component

### Displays cart items

- Arrange fake cart repository to return 3 items: keyboard, mouse, monitor.
- Mount `Cart` component.
- Assert 3 items displayed with labels: "Keyboard", "Mouse", "Monitor".

6. PR 計画

次の条件を満たす、小規模で対象を絞った段階的な PR を順序立てて提案します。

• 既存の動作を決して壊さない
• 個別にレビューおよびマージできる
• 差分の範囲を絞る

ルール：

• スキャフォールディング PR：新規ファイルが多数ある場合、WIP のスキャフォールディングを独立した PR にまとめます
• 整理優先 PR：インターフェースの変更が必要な場合、まず後方互換性のある変更（オプションのパラメーター、非推奨化）を行います
• 機能 PR：それぞれ、ユーザーに見える機能またはテスト可能な機能の一部分を追加します

PR の依存関係を示す Mermaid の flowchart を含めます。各 PR をチェックボックスとして列挙します。

- [ ] PR#1 — Scaffold Cart component, repository interface, and test files.
- [ ] PR#2 — Display cart items from repository.

PR 計画を設計ドキュメントファイルに書き込み、そこでユーザーにレビューを依頼します。

7. PR の関連付け

ユーザーが PR 計画を確認した後：

1. 確認済みのチェックボックス一覧にある各 PR について、PR 計画の下に <summary> タイトルを持つ <details> ブロックを追加します。
2. 各ブロック内に タスク と テスト戦略 のセクションを追加します。
3. 実装の詳細の各項目を、該当する PR に割り当てます。コードスニペットは、その PR のタスク内にスニペットとしてコピーしないでください。
4. 最上位のテスト戦略にある各テストシナリオを、該当する PR に割り当てます。
5. 実装の詳細または最上位のテスト戦略に未割り当ての項目がないことを確認します。
6. 空になった実装の詳細と最上位のテスト戦略のセクションを削除します。
7. PR 計画からチェックボックス一覧を削除します。依存関係図は残します。

8. 検討した代替案

質問します：他のアプローチも検討しましたか？ それらを採用しなかった理由は何ですか？

9. その他

質問します：その他、未解決の質問、リスク、今後のアイデアはありますか？ 追加する内容がなければ空欄にします。

最終ステップ

すべてのセクションがファイルに含まれていることを確認し、まだ実施していない場合は PR の関連付けを適用し、最終的なパスをユーザーに示します。ドキュメントはすでにディスク上に存在するはずです。このステップは検証と整理であり、初回作成ではありません。

テンプレート

# Goals

{goals}

# Non-Goals

{non_goals}

# Desired Behavior

{desired_behavior}

# Design

{design}

## Diagram

```mermaid
{diagram}
```

## Implementation Details

{implementation_details}

# Testing Strategy

{testing_strategy}

# PR Plan

```mermaid
{pr_dependency_diagram}
```

{pr_details}

<details>
<summary>🚧 PR#N — {pr_title}</summary>

## Tasks

```ts
/**
 * Empty cart returns `[]`, never null.
 */
interface CartRepository {
  getItems(): CartItem[];
}
```

- [ ] {task_that_cannot_be_a_snippet}

## Testing Strategy

### 🚧 {test_title}

- {step_1}
- {step_2}

</details>

# Alternatives Considered

{alternatives}

# Kitchen Sink

{kitchen_sink}

追加リソース

• 完全な例については、resources/example-design-doc.md を参照してください。