Feature design doc

Instructions

全体フロー（必ずこの順序で進める）

Step 1: 調査          → 関連コードベースを並行探索し現状を把握
Step 2: 実現可能性判定  → 技術的制約・リスクをユーザーに報告
Step 3: 設計判断の収集   → AskUser で方針を確定（1回で最大4問）
Step 4: 設計書作成      → 確定方針で Markdown を書き出す
Step 5: セルフチェック   → Phase 1: 初見読み3名で理解の一致を検証 ＋ Phase 2: 実装者目線2名でギャップ検出

調査不足のまま設計判断を求めない。設計判断なしに設計書を書き始めない。セルフチェック（Phase 1・2 の両方）を飛ばさない。

---

Step 1: 調査

影響を受けるシステムごとに Agent tool で並行 dispatch する（コード変更が発生するシステム数 = 並列数。FE+BE 両方にコード変更があれば 2 並列、BE のみなら 1 つ。「新イベントを受信するだけ・実装は別チーム」のシステムは調査対象に含めるが、テストケースのテーブルは省略してよい）。把握する内容:

• 現状のデータフロー（入力→処理→出力の経路、イベント種別、状態遷移）
• 技術的制約（プラットフォーム固有制限、ライブラリ制約、プロトコル制限）
• 既存の拡張点（使えるフック・設定・インターフェース）
• 変更箇所の一覧（ファイル名・関数シグネチャレベルまで特定する。設計書には書かないが、TOBE の実現可能性を裏付ける根拠になる）

Agent prompt テンプレート:

<対象システム名>のコードベースを調査してください。
調査対象: <機能に関連する領域を列挙>

以下を報告してください:
1. 現状のデータフロー（入力→処理→出力。関連するイベント・状態遷移）
2. 技術的制約（プラットフォーム制限、ライブラリの制約）
3. 既存の拡張点（今回の機能で使えるインターフェース・フック）
4. 変更が必要な箇所の一覧（ファイルパス・関数名レベルで特定）
5. リスク（実機でしか検証できない項目、未知の制約）

ファイルパスとコードスニペットを含めて報告してください。

調査の粒度: 設計書に書くのは抽象レベルだが、調査は具体レベルまで掘る。「リクエストをキャンセルできる」と書くためには、SDKが AbortSignal に対応しているか、実際の関数シグネチャがどうなっているかを確認しておく必要がある。

---

Step 2: 実現可能性判定

調査結果を受け取ったら、以下を整理してユーザーに報告する:

観点	確認内容
技術的に可能か	致命的なプラットフォーム制約の有無。回避策の有無
変更の複雑度	変更箇所の数、既存ロジックへの影響度を 低/中/高 で判定
技術リスク	実機でしか検証できない項目（スパイク検証の必要性）
機能間の依存	機能Aの基盤が機能Bにも必要、等の順序制約

ここでの成果物は会話上のサマリー（ドキュメントにしない）。ユーザーが Go/No-Go を判断できる材料を渡す。表形式で変更箇所と複雑度を一覧すると伝わりやすい。

---

Step 3: 設計判断の収集（AskUser 必須）

設計書を書く前に、AskUser で 1 回にまとめてユーザーの判断を仰ぐ（最大 4 問）。

質問すべきカテゴリ

カテゴリ	例
実現方式の選択	「VAD自動検出 vs ボタンタップ、どちらで実装しますか？」
トレードオフの判断	「シンプルだが制約あり vs 高機能だがリスク高い」
スコープの確認	「段階的にやるか一括か」「このイベントは追加するか」
UX の方針	「中断時の音声を即停止 vs 最後まで再生」
優先順位	「機能A/B どちらを先に実装するか」
ファイル構成	「1ファイルにまとめるか、機能別に分割するか」

質問の書き方ルール

• 各選択肢にトレードオフを description に書く。「方式A」だけでは判断材料にならない
• おすすめがあればラベルに (推奨) を付ける。技術寄りの判断では特に
• 「おすすめは？」と返されたら即答する。質問時点で自分の推奨を持っておく
• 聞くべきでないこと: 実装の内部詳細（関数名等）、調査すればわかること、「これでいいですか？」系の確認

AskUser が使えない場合（headless / subagent 実行）

非対話環境では AskUser を呼べないが、ここで止まらない（[[clear-document-writing]] Step 1 の縮退方針と同じ）:

1. 各設計判断について、調査結果・既存コードの慣例・依頼文から最も妥当な選択肢を仮定として自分で確定する（質問時点で持つべき「自分の推奨」をそのまま採用する）。
2. 置いた仮定とその根拠を、設計書の冒頭に「設計判断（仮定）」として必ず明記する。読み手が前提を検証でき、誤りなら後から正せる。
3. 根拠の乏しい重要な判断には「要確認」と印を添え、Step 5 のセルフチェックを合意の代替とする。

---

Step 4: 設計書の作成

ファイル構成の決定

独立してレビュー・実装できる単位で分割する（機能別が基本）。共通基盤が複数機能にまたがる場合でも、各ファイル内で必要な範囲を自己完結的に説明する。

ユーザーから指定がない場合の判断基準: 独立して実装・テストできる単位があれば分割、一連の流れとしてしか理解できない場合は 1 ファイル。迷ったら AskUser で聞く（Step 3 の「ファイル構成」カテゴリ）。

設計書テンプレート（全セクション必須）

# 機能名: 〇〇〇〇

## 概要

1-2文で機能を説明する。技術用語は最小限。

## この実装が解決する問題

（ユーザー目線で書く。後述の「抽象度ルール」に従う）

## ASIS-TOBE

### I/Oの変更点

| 項目 | ASIS | TOBE |
|------|------|------|

### 処理内容の変更点

| 項目 | ASIS | TOBE |
|------|------|------|

## 処理フロー

（mermaid 記法。後述の「図の選び方」に従う）

## テストケース

### <システム名1>(BE等)

| テスト大分類 | テスト小分類 | 品質特性 | テスト内容 |
|---|---|---|---|

### <システム名2>(FE等)

| テスト大分類 | テスト小分類 | 品質特性 | テスト内容 |
|---|---|---|---|

---

セクション別の書き方ルール

「この実装が解決する問題」の抽象度ルール

書く	書かない
ユーザー体験上の問題（「AIが考えている間は発言できない」）	技術的原因（「FIFOキューが中断不可」）
人間同士の自然なやりとりとの対比	ファイル名・関数名・クラス名
変化後のユーザー体験	実装方式の詳細

2-3 段落。長くしない。

ASIS-TOBE の分類ルール

テーブル	書くもの	書かないもの
I/Oの変更点	ユーザー操作、画面表示、API/WSイベント、プラットフォーム設定	内部処理の変更
処理内容の変更点	キュー方式、エラーハンドリング方針、セッション管理方式	関数名、クラス名、import文

処理フローの図の選び方

使う図	適するケース
sequenceDiagram	複数アクター間のメッセージのやりとり。正常系に最適
flowchart	条件分岐が主体。エラー判別や状態分類に最適
stateDiagram-v2	状態遷移の ASIS/TOBE 対比に最適

構成: 正常系 1 つ + 異常系/補足 1 つの 2 図構成が基本。

書き方:

• アクターは役割名（「ユーザー」「モバイルアプリ」「AIサーバー」）で書く。クラス名やファイル名は使わない
• 1 図 7-15 メッセージが読みやすい上限。超えたら分割する
• Note over で「ここで〇〇が起きている」を補足する
• 図の前に ### 正常系: 〇〇のケース のように見出しをつける

テストケースの書き方

変更対象のシステムごとにテーブルを分ける（BE / FE 等）。変更がないシステムのテーブルは省略する（空テーブルは置かない）。

テストケース数の目安: 1 システムあたり 5-15 件。正常系・異常系・境界値をバランスよく含める。網羅を狙わず、実装者が「これを通せば出せる」と判断できる粒度にする。

列	書き方
テスト大分類	機能の構成要素または検証観点で切る（「中断基盤」「テキスト統合」「VAD」「後方互換性」等。切り方に正解はないが、実装者がテストファイルを分ける単位に近づける）
テスト小分類	具体的な観点（「リクエストキャンセル」「連続中断」）
品質特性	ISO/IEC 25010:2011（JIS X 25010:2013 相当）の 8 特性から 1 つ選ぶ（現行の ISO/IEC 25010:2023 は safety を加えた 9 特性に改訂されているが、本スキルは日本の実務で通用する 2011 年版の分類を使う）
テスト内容	「〇〇した場合、△△であること」の形式。「正常に動作する」は禁止

品質特性の判断基準:

症状	品質特性
正しく動かない	機能適合性
動くが遅い/重い	性能効率性
特定デバイス/環境で動かない	互換性
動くが使いにくい	使用性
普段は動くが特定条件で壊れる	信頼性
不正アクセス/漏洩の懸念	セキュリティ
変更・調査がしにくい	保守性
他環境への移行が困難	移植性

迷ったら「テストが落ちたとき、修正するのはどのチームか？」で判断する。デバイス/OS 固有の対応チーム → 互換性、アプリロジックの対応チーム → 信頼性。どちらとも取れる場合はどちらを選んでもよい（品質特性の分類自体が目的ではなく、テスト設計の観点を明確にすることが目的）。

スパイク検証: 実機でしか確認できない項目はテスト大分類を「スパイク検証」にして明示する。

文章の書き方（[[clear-document-writing]] のエッセンス）

設計書の散文（概要・解決する問題・図の Note・テーブル内の説明文）には、ドキュメント作成スキル [[clear-document-writing]] の文章原則を適用する:

• 要点を先に: 各セクション・各段落の先頭に結論（中心文）を置く。1段落1主張
• 曖昧語を排除: 「適宜」「なるべく」「等」を数値・条件・固有名に置き換える（テスト内容の「正常に動作する」禁止と同じ原則）
• 一文一義: 長い説明は文を分割する。手順は番号リスト、対比は表にする
• 読み手視点: 仕組みの説明ではなく、ユーザー・実装者が得るもの／すべきことで書く
• 肯定形で書く: 回りくどい否定は肯定形に言い換える（禁止の強調だけ例外）

[[clear-document-writing]] が配置されている環境では、Step 4 の執筆時にその references/sentence-refinement.md を Read し、文レベルの詳細基準と改善前→改善後の実例を適用する（配置されていなければ上の5項目で足りる）。

---

抽象度の全体指針

セクション	抽象度	理由
この実装が解決する問題	高（ユーザー体験）	技術者以外も読む。合意形成
ASIS-TOBE	中（I/O・処理方針）	何が変わるかの全体像
処理フロー	中（アクター間のやりとり）	判断の分岐点を明示
テストケース	中〜低（検証可能な具体性）	「何を確認するか」は具体的に

設計書に書かないもの: 関数シグネチャ、クラス図、ディレクトリ構成、import 文。これらは実装フェーズで決める。

---

Step 5: セルフチェック（2フェーズ）

設計書を書いた本人は曖昧さにも抜け漏れにも気づけない。Phase 1 で理解の一致を、Phase 2 で仕様の抜け漏れを検証する。両方通って初めて完了。

---

Phase 1: 理解度一致（書いてあることが伝わるか）

目的: 初見の読み手全員が同じ理解に到達するか確認する。

1. 3 つの独立サブエージェントを並列 dispatch する。各エージェントは設計書を初見で読み、以下の 4 問に回答する。エージェント同士は互いの回答を見ない。

2. Agent prompt テンプレート:

以下の設計書を初見で読み、4つの質問に各1-2文で回答してください。
設計書の外にある情報（コードベース等）は参照しないでください。
設計書に書かれていることだけから判断してください。

## 設計書
（Read で対象ファイルを読む指示、またはファイルパスを指定）

## 質問
Q1: この機能はユーザーのどんな困りごとを解決するか？
Q2: 変更の影響を受けるシステムを全て挙げよ
Q3: ASIS と TOBE の最大の違いは何か？
Q4: テストケースで最も重要な検証ポイントはどれか？（1つ選んで理由を述べよ）

3. 回答を突き合わせる。判定基準:

質問	一致の基準
Q1	3 名とも同じ問題を指しているか（表現の違いは許容、指している対象が同じなら一致）
Q2	3 名ともシステム名の集合が一致するか（1 名でも漏れ/追加があれば不一致）
Q3	3 名とも同じ変化を最大の違いとして挙げているか（複数の大きな変更が並立し「最大」の選択が正当に分かれる場合は、挙げられた変化がいずれも設計書に明記され相互に矛盾しなければ一致とみなす）
Q4	完全一致は求めない。3 名中 2 名以上が同じテストを選べば一致

4. 不一致があれば修正して再検証（新しいサブエージェントで。最大 3 回）。3 回で一致しない場合は無限に再試行せず打ち切り、残る不一致を「要確認」としてユーザーに提示したうえで Phase 2 へ進む（不一致の黙殺はしない）。

---

Phase 2: ギャップ検出（書かれていないことを炙り出す）

目的: 実装者が「で、これどうするの？」と思う箇所 — 書かれていないが必要な情報 — を検出する。Phase 1 は「書いてあることの明確さ」、Phase 2 は「書かれていないことの発見」で、検証する軸が異なる。

1. 2 つの独立サブエージェントを並列 dispatch する（3 名でなく 2 名で十分。ギャップの発見は一致判定ではなく集合の和を取るため）。

2. Agent prompt テンプレート:

あなたはこの設計書を渡されて実装を担当するエンジニアです。
設計書を読み、実装に着手する前に確認したい疑問点を3-5個挙げてください。

ルール:
- 設計書に書かれていることへの質問は不要（それは読めばわかる）
- 「書かれていないが、実装するには知る必要があること」を挙げる
- コードレベルの質問（関数名、ライブラリ選定等）ではなく、
  仕様・振る舞いレベルの疑問に限る
  例: ○「新イベントを受信したとき受信側は何をするか？」
  例: ×「AbortControllerはどの関数に渡すか？」

## 設計書
（Read で対象ファイルを読む指示、またはファイルパスを指定）

3. 疑問点を集約する:

   • 2 名の疑問点を統合し、重複を除去する
   • 各疑問が設計書で答えるべきレベルかをフィルタする:
     • 設計書に追記すべき: 仕様・振る舞い・I/O の抜け（例: 「新イベント受信時のFE動作が未定義」）
     • 実装フェーズで決めること: コードレベルの詳細（例: 「どのライブラリを使うか」）→ 対応不要
   • 設計書に追記すべき項目が 0 件なら Phase 2 通過

4. 追記すべき項目があれば設計書を修正:

   • ASIS-TOBE テーブルに行を追加するか、処理フローの Note で補足する
   • Phase 2 の検出ループ自体は再実行しない（一致判定ではなく、指摘の和集合を取って対応するだけ）。ただし追記した本文はどの検証も通っていない（書いた本人は自分の曖昧さに気づけない——Step 5 冒頭の前提は追記にも当てはまる）ため、新しいサブエージェント1名に追記箇所と前後の文脈を読ませ、「追記が単独で意味が通るか・既存記述と矛盾しないか」を確認する（問題があれば直して同様に確認）
   • 追記が Q2（影響システムの集合）や Q3（ASIS/TOBE の最大の違い）の答えを変えるほど大きい場合は、Phase 1 を再実行する

よくあるギャップのパターン

パターン	例
送信側だけ書いて受信側の動作が未定義	「turn.interrupted を送信する」→ 受信した FE は何をする？
正常系だけ書いて異常系の振る舞いが未定義	「自動リトライする」→ リトライ中にユーザーが別操作したら？
新しい状態を追加して遷移条件が未定義	「リトライ中は入力を抑制」→ 抑制を解除する条件は？
既存機能との相互作用が未定義	「バージインで再生停止」→ 表示済みのカードはどうなる？

---

検証の抽象度ルール（Phase 1・2 共通）

検証は設計書の抽象度と同じレベルで行う。

聞く（設計書の抽象度）	聞かない（実装の具体度）
「どんな問題を解決するか」	「どの関数を変更するか」
「影響を受けるシステムは」	「影響を受けるファイルは」
「受信側は何をするか」	「どのハンドラで処理するか」
「異常時の振る舞いは」	「例外クラスは何を使うか」

具体的すぎる検証は設計書を具体に引きずり下ろす。設計書に関数名やファイルパスを書かせる圧力になるため、質問の抽象度を守る。

進捗の可視化

• Phase 1 開始: 「理解度検証を開始します（3名の独立レビューア）」
• Phase 1 完了: 「理解度一致 完了（全問一致、N回目で収束）」
• Phase 2 開始: 「ギャップ検出を開始します（2名の実装者目線レビュー）」
• Phase 2 完了: 「ギャップ検出 完了（追記N件 / 対応不要M件）」

---

よくある失敗

失敗パターン	対策
調査が浅いまま設計書を書き始める	Step 1 で具体レベルまで掘ってから抽象化する。逆はできない
「解決する問題」に技術用語が入る	「FIFOキューが中断不可」→「AIが考えている間は発言できない」
フローが 1 つの巨大な図になる	正常系と異常系を分ける。1 図 15 メッセージ以内
テスト内容が「正常に動作すること」	「〇〇した場合、△△であること」の形式に統一
散文が曖昧語だらけ・結論が段落の後ろにある	「文章の書き方（clear-document-writing のエッセンス）」の5項目に従う
設計判断をユーザーに聞かずに決め打つ	方式選択・UX 方針・優先順位は AskUser で聞く
質問を 1 問ずつ聞く	関連する質問を 1 回の AskUser で最大 4 問まとめる
スパイク検証の必要性を見落とす	実機依存の項目をテストケースで「スパイク検証」として明示
機能間の依存を暗黙にする	各ファイル内で前提を自己完結的に書く
理解度検証を自分で代替する	書いた本人の再読は客観視できない。必ず新規サブエージェントに読ませる
検証の質問が具体的すぎる	「どの関数を変更するか」は実装の話。設計書と同じ抽象度で聞く
同じサブエージェントで再検証する	前回の回答を学習している。毎回新しいエージェントを使う
Phase 1 だけで終わりにする	理解の一致は「書いてあることの明確さ」しか検証しない。Phase 2 で「書かれていないこと」を炙り出す
Phase 2 の指摘を全て設計書に入れる	コードレベルの詳細は実装フェーズで決めること。仕様・振る舞いの抜けだけ追記する
送信側だけ書いて受信側を忘れる	イベント・メッセージを追加したら、受信側の動作も ASIS-TOBE に必ず書く