Claude Code タスクの範囲設定：曖昧な要求からコミットまで

なぜあいまいな機能要求は時間を浪費するのか

あいまいな要求は無害に聞こえます：「検索を良くして」「オンボーディングを滑らかにして」「ユーザーに通知が必要」。実際のチームではワンライナーのチャット、矢印つきのスクリーンショット、あるいは半分だけ思い出した顧客の話として届きます。皆が賛成しますが、頭の中のイメージはバラバラです。

コストは後で現れます。スコープが不明瞭だと、人は推測で作業を進めます。最初のデモが別の確認ラウンドに変わり、「そういう意味じゃない」と言われます。作業はやり直され、変更はこっそり大きくなります。デザイン調整がコード変更を促し、それがさらにテストを呼びます。曖昧な変更は検証が難しいためレビューが遅れます。誰も「正しい」状態を定義できなければ、レビュワーは品質をチェックする代わりに振る舞いの議論をしてしまいます。

早い段階であいまいなタスクは見分けられます：

• ユーザーが何をできるかのステップごとの例がない
• エッジケース（空状態、権限、エラー）がない
• 「念のため」の作業が巨大な PR に膨らむ
• レビューコメントが実装ではなく振る舞いを巡る議論になる
• 「進めながら決めよう」が計画になっている

よくスコープされたタスクはチームにゴール地点を与えます：明確な受け入れ基準、最小限の UI／API 計画、含めないことの明示的境界。これが「検索を改善する」と「小さくて作りやすくレビューしやすい変更」の違いです。

実用的な習慣の一つ：「Done」の定義と「Nice-to-have」を分けること。「Done」は簡単なチェックリストです（例えば：「検索はタイトルで結果を返す、空なら『結果なし』を表示する、クエリを URL に保持する」）。「Nice-to-have」は後回しにできるもの（同義語対応、ランキング調整、ハイライト、分析など）。最初にラベルを付けることで意図しないスコープの膨張を防げます。

成果から始め、解決策から始めない

あいまいな要求はしばしば提案された修正として始まります：「ボタンを追加して」「新しいフローに切り替えて」「別のモデルを使って」。一旦立ち止まり、まずは提案を成果に翻訳してください。

シンプルなフォーマットが役立ちます：「As a [ユーザー], I want to [すること], so I can [達成したい目標]」。平易に書いてください。一息で言えないならまだあいまいです。

次に、完了したときユーザーにとって何が変わるかを書きます。実装の詳細ではなく可視の振る舞いに注目します。例えば：「フォームを送信した後、確認メッセージが表示され、新しいレコードがリストで見つけられるようになる」。これが明確なゴールを作り、「あと一つだけ」の微調整が紛れ込むのを難しくします。

また、何が変わらないかも書いてください。非ゴールはスコープを守る盾になります。例えば「オンボーディングを改善する」リクエストなら、非ゴールは「ダッシュボードの再設計は行わない」「料金プランのロジックは変更しない」などです。

最後に、まずは一つの主要パス（エンドツーエンドのスライス）をサポートすることを選びます。

例："あちこちにスナップショットを追加する"ではなく、こう書きます："プロジェクトオーナーとして、アプリの最新スナップショットを復元できるようにし、誤った変更を元に戻せるようにする"。非ゴール：「一括復元は行わない、UI再設計は行わない」。

あいまいさを取り除くために聞くべき少数の質問

あいまいな要求はたいてい努力不足ではなく、決定不足です。

スコープを静かに変える制約から始めます。期限は重要ですが、アクセスルールやコンプライアンス要件も重要です。プラットフォームに階層やロールがあるなら、誰が機能を使えるのか、どのプランで提供するのかを早めに決めてください。

次に具体的な例を求めます。スクリーンショット、競合の振る舞い、以前のチケットは「より良い」とは何かを明らかにします。リクエスタに例がないなら、痛みを感じた最後の瞬間を再現してもらいましょう：どの画面で何をクリックして何を期待したか。

エッジケースはスコープが膨らむ場所なので、大きなものは早めに名前を出します：空データ、バリデーションエラー、遅い／失敗するネットワーク呼び出し、そして「元に戻す」が実際に何を意味するか。

最後に、成功をどう検証するかを決めます。テスト可能な結果がないとタスクは意見の集まりになります。

これら五つの質問はたいていの曖昧さを解消します：

• 誰がアクセスできるか（プランとロール）？
• 期限は？最小限の受け入れバージョンは何か？
• 期待する振る舞いの一つの例は？
• 空状態、エラー、遅延接続では何が起きるか？
• どうやって動作を確認するか（具体的な基準や指標）？

例：「クライアント向けのカスタムドメインを追加する」は、どのプランに属するか、誰が設定できるか、コンプライアンスのためにホスティング場所が重要か、無効な DNS に対してどんなエラーを出すか、そして「完了」の定義（ドメインが検証され HTTPS が有効でロールバック手順がある）を決めればクリアになります。

混乱したメモを受け入れ基準に変換する

混乱した要求は目標、推測、半分思い出したエッジケースを混ぜます。あなたの仕事は、それを誰でもテストできる文に変えることです。同じ基準がデザイン、コーディング、レビュー、QA を導くべきです。

シンプルなパターンが分かりやすさを保ちます。Given/When/Then を使うか、それと同様の短い箇条を使ってください。

受け入れ基準の簡単なテンプレート

各基準は誰かが実行できる一つのテストとして書きます：

• Given（前提）ある状態、When（操作）ユーザーが X をする、Then Y が起きる。
• バリデーションルールを含める（どんな入力が許されるか）。
• 少なくとも一つの失敗ケース（ユーザーにどんなエラーが見えるか）を含める。
• 「Done の合図」（QA が確認する項目、レビュワーが期待すること）を定義する。

実際に適用してみましょう。メモが「スナップショットを簡単にしたい。最後の変更が壊れたらロールバックしたい」と言っているとします。これをテスト可能な文にします：

• 前提：スナップショットが2つあるプロジェクトがある。操作：Snapshots を開く。結果：両方が時間と短いラベル付きで見える。
• 前提：スナップショットがある。操作：Roll back をクリックして確認する。結果：プロジェクトがそのスナップショットに戻り、アプリがビルドに成功する。
• 前提：私はプロジェクトオーナーではない。操作：ロールバックを試みる。結果：エラーが表示され、何も変更されない。
• 前提：ロールバックが進行中。操作：ページをリロードする。結果：ステータスと最終結果が引き続き見える。
• 前提：ロールバックが失敗する。操作：処理が停止する。結果：明確なメッセージが表示され、現在のバージョンがアクティブのままになる。

QA がこれらを実行でき、レビュワーが UI とログで検証できれば、UI と API 作業を計画し小さなコミットに分割する準備が整ったことになります。

最小限の UI 計画を草案する

最小限の UI 計画は約束です：機能が動くことを示す最小の可視変更。

まず、どの画面が変わるか、そして人が10秒で何に気付くかを名前で示します。「もっと簡単に」「きれいに」などの指示があれば、それを指差せる一つの具体的変更に翻訳します。

リデザインではなく小さな地図として書きます。例えば：「Orders ページ：テーブルの上にフィルタバーを追加する」や「Settings：Notifications の下に新しいトグルを追加する」。画面と変わる要素を名前で言えないならスコープはまだ不明瞭です。

主要な UI 状態を定義する

ほとんどの UI 変更には予測可能な状態がいくつか必要です。該当するものだけを列挙してください：

• 読み込み
• 空状態
• エラー（リトライの有無）
• 成功（トースト、インラインメッセージ、更新された一覧）

ユーザーに見せる文言を確認する

UI コピーもスコープの一部です。承認が必要なラベルやメッセージをキャプチャしてください：ボタンテキスト、フィールドラベル、ヘルパーテキスト、エラーメッセージ。文言が未決ならプレースホルダーである旨と誰が確定するかを書きます。

レスポンシブな仕上げ、アニメーション、新しいアイコンなど、必要でない磨きは「今はやらない」メモに入れておきます。

最小限の API とデータ計画を草案する

スコープされたタスクには UI、バックエンド、データ間の小さな明確な契約が必要です。目的はシステム全体を設計することではなく、機能が動くことを証明するために必要最小限のリクエストとフィールドを定義することです。

まず必要なデータとその出どころをリストアップします：既存の取得可能なフィールド、新しく保存する必要のあるフィールド、計算ですませられる値。各フィールドの出どころを言えないなら計画は不十分です。

API の表面積を小さく保ちます。多くの機能で、1つの読み取りと1つの書き込みで十分です：

• GET /items/{id} は画面描画に必要な状態を返す
• POST /items/{id}/update はユーザーが変更できるものだけを受け取り、更新された状態を返す

入力と出力は段落ではなくプレーンなオブジェクトで書きます。必須フィールドと任意フィールド、一般的なエラー（not found、validation failed）の振る舞いも含めます。

データベースに触る前に認可を簡単に確認してください。誰が読めて誰が書けるかを一文で決めます（例：「サインイン済みの全ユーザーが読めるが、書けるのは管理者のみ」）。これを飛ばすと手戻りが発生しやすいです。

最後に、何を保存し何を計算でまかなうかを決めます。シンプルなルール：事実を保存し、ビューは計算する。

Claude Code を使ってスコープ済みタスクを作る

Claude Code は明確なターゲットと厳密な枠を与えると最も効果を発揮します。まず混沌とした要求と制約（期限、影響ユーザー、データルール）を貼り付け、次のようなスコープ済み出力を求めてください：

1. 平易な言葉でのスコープの言い換えと短い受け入れ基準チェックリスト。
2. 3〜7 の小さなコミット列、それぞれの明確な成果。
3. 各コミットで触る可能性のあるファイルやフォルダとその変更内容。
4. 各コミットにつき簡単なテスト計画（1つのハッピーパスと1つのエッジケース）。
5. 明確なスコープ外メモ。

返答を受け取ったらレビュワーのように読みます。「パフォーマンス改善」や「きれいにする」などのフレーズがあれば測定可能な文言に置き換えるよう依頼してください。

ミニ例（良い例）

リクエスト：「サブスクリプションを一時停止する方法を追加して」

スコープ済みのバージョン：「ユーザーは1〜3か月で一時停止できる。次の請求日は更新される。管理者は一時停止状態を確認できる。」スコープ外：「課金の按分変更は行わない。」

そこからコミット計画は実務的になります：DB と API の形を作るコミット、UI コントロールのコミット、バリデーションとエラー状態のコミット、エンドツーエンドテストのコミット、など。

作業を小さなレビューしやすいコミットに分割する

大きな変更はバグを隠します。小さなコミットはレビューを速くし、ロールバックを安全にし、受け入れ基準から外れたときに気付きやすくします。

便利なルール：各コミットは一つの新しい振る舞いをアンロックし、それを証明する簡単な方法を含むべきです。

よくある順序は：

• データモデルやマイグレーション（必要なら）＋テスト
• API の振る舞いとバリデーション
• UI の配線（空／エラー状態を含む）
• ロギングや分析は必要なら最後に小さく追加

各コミットを焦点化してください。「ここにいるついでに」リファクタは避けます。UI が簡素でもアプリがエンドツーエンドで動くように保ってください。マイグレーション、振る舞い、UI を一つのコミットにまとめるのは強い理由がない限り避けてください。

実例ウォークスルー：「レポートのエクスポート」

利害関係者が「Export reports を追加できる？」と言った場合、多くの選択が隠れています：どのレポート、どの形式、誰がエクスポートできるか、配信方法はどうするか。

設計を変える質問だけを尋ねます：

• v1 で対象になるレポートタイプは？
• v1 の形式は？（CSV、PDF）
• 誰がエクスポートできるか（管理者、特定のロール）？
• 直接ダウンロードかメールで配信か？
• 制限はあるか（日付範囲最大、行数制限、タイムアウト）？

仮に回答が「Sales Summary レポート、CSV のみ、manager ロール、直接ダウンロード、過去90日まで」としたら、v1 の受け入れ基準は具体的になります：マネージャーは Sales Summary ページで Export をクリックできる；CSV は画面上のテーブル列に一致する；フィルタを尊重する；90日を超える期間を指定すると明確なエラーを表示する；最大 50k 行で 30 秒以内にダウンロードが完了する、など。

最小 UI 計画：テーブルアクション付近に Export ボタン一つ、生成中の読み込み状態、問題があればユーザーが直せるエラーメッセージ（例：「90日以内を選択してください」）。

最小 API 計画：フィルタを受け取り生成された CSV をファイルレスポンスとして返す1つのエンドポイント。テーブルと同じクエリを再利用しサーバー側で 90 日ルールを強制する。

それを数回のタイトなコミットで出荷します：まず固定のハッピーパス用エンドポイント、次に UI 接続、次にバリデーションとユーザー向けエラー、最後にテストとドキュメント。

よくあるスコーピングの失敗（と回避法）

隠れた要件が紛れ込む

「チームロールを追加する」は招待や編集、既存ユーザーに何が起きるかというルールを隠していることが多いです。推測していると気づいたら仮定を書き出し、それを質問か明示的なルールに変えてください。

UI の磨き込みがコア挙動と混ざる

1つのタスクで「動くようにする」と「きれいにする」を混ぜると何日も失います。最初のタスクは振る舞いとデータに集中しましょう。スタイルやアニメーションはフォローアップタスクに回します（必須でない限り）。

v1 で全てのエッジケースを解決しようとする

エッジケースは重要ですが全てを最初に解く必要はありません。信頼を壊すもの（ダブルサブミット、競合編集など）だけは扱い、残りは後回しにして明確にメモしてください。

エラー状態と権限が「後で」に回される

書き留めないと見落とします。少なくとも1つの失敗パスと1つの権限ルールを受け入れ基準に含めてください。

検証できない基準を書く

「高速」や「直感的」だけではダメです。数字や具体的なチェックを付けてレビューで証明できるようにしてください。

コーディングを始める前の簡単チェックリスト

チームメンバーが心を読むことなくレビューとテストができるようタスクを固定します：

• 成果と非ゴール：成果を一文、非ゴールを1〜3個
• 受け入れ基準：5〜10のテスト可能なチェックを平易に
• UI 状態：最小の読み込み、空、エラー、成功
• API とデータメモ：最小のエンドポイント形とデータ変更、誰が読めるか書けるか
• コミット計画とテスト：3〜7 のコミット、それぞれの簡単な証明

例：「Saved searches を追加」は「ユーザーがフィルタを保存して後で再適用できる」になり、非ゴールは「共有なし」「ソート変更なし」などになります。

次のステップ：構築中にスコープを安定させる

スコープ済みタスクができたら、それを守ってください。コーディング前に依頼者と簡単な整合チェックを行います：

• 受け入れ基準を読み、成果と一致するか確認する。
• 権限、空状態、失敗時挙動を確認する。
• スコープ外を再確認する。
• 基準を満たす最小の UI と API 変更に合意する。
• どのようにデモするか、何が「Done」かを決める。

その後、基準をチケット、PR 説明、チームが実際に見る場所に保存します。

Koder.ai (koder.ai) で構築する場合は、まずプランをロックしてからコードを生成すると便利です。Planning Mode はそのワークフローに適しており、試したアプローチを戻す必要があるときにスナップショットやロールバックが安全性を高めます。

構築中に新しいアイデアが出てきたら、スコープを安定させておきます：フォローアップリストに書き留め、受け入れ基準を変えるなら一旦作業を止めて再スコープし、コミットは一度に一つの基準に紐づけてください。