⛓️

Claude Codeの「結合したら動かない」、5分の準備でだいぶ防げるようになった

に公開
AI
spec
LLM
Claude Code
tech

はじめに

こんにちは、かがわ（@shinpr_p）です。

2025年ももう終わりますね。今年（今年！？）はClaude Codeが登場し、AIコーディングの環境が急激に進化した1年でした。
捗った一方で、こんな経験もありませんでしたか？

  1. データ層、サービス層、API層と順番に実装を進めた
  2. 各パーツは一見正しく動いている
  3. 最後に全部繋げてみたら動かない

私も以前は何度かやらかしました。「各パーツは動いてるのになんで繋がらないの？」と思いながら何時間もデバッグする羽目になったりしました。

結局の原因は変更の影響範囲を把握しきれていなかったことだったりします。
直接触るコードは見えていたけど、間接的に影響する箇所を見落としていたみたいなやつです。

このような問題について、Design Docを書く段階で"5分"の追加作業をやるだけでかなり防げるようになりました。今回はその方法を共有します。

なぜ「結合したら動かない」が起きるのか

レイヤーごとに順番に作っていく（水平スライス）と、当たり前ですが最後まで正しく繋がるかどうかは分かりません。

水平スライス（レイヤーごとに作る）
Phase 1: データ層 ────────────────────→ 完成
Phase 2: ビジネスロジック層 ────────────→ 完成
Phase 3: API層 ──────────────────────→ 完成
Phase 4: UI層 ───────────────────────→ 完成
Phase 5: 統合確認 ← ここで初めて全部繋げる（そして動かないことに気づく）

特にLLMに実装を任せると、コンテキストウィンドウの制約から、プロジェクト全体を常に把握するわけではないので、レイヤー間の暗黙の契約を見落としやすいです。

やったこと： 統合ポイントを事前に洗い出す

Design Docを書くときに、どこが繋がるポイントなのかを最初にリストアップします。

これだけです。2ステップで書けます。

①何がどこに影響するか書く

まず「何がどこに影響するか」を書きます。

以下は実際のプロジェクト（Slack Bot）で画像生成機能を追加したときの例です。

変更対象: 画像生成機能の統合
直接影響:
  - src/infrastructure/gemini/functions.ts（generateImage関数追加）
  - src/application/services/queryClassificationService.ts（image_generation分類追加）
  - src/application/services/imageGenerationService.ts（新規作成）
  - src/infrastructure/gemini/imageClient.ts（新規作成）
間接影響:
  - src/application/services/conversationService.ts（Function Call実行フローで自動的に呼び出される）
波及なし:
  - 既存のGeminiService（テキスト生成）
  - 他のFunction Handler（Notion、DeepResearch等）

「直接影響」「間接影響」「波及なし」に分けることで、変更範囲が明確になります。

②どこで統合確認するか決めておく

次に、どこで統合が必要かとどうやって確認するかを書きます。

統合点1: Function Calling実行
  場所: ConversationService.generateContentWithFunctionCalling
  確認手順:
    1. Slackで「青空と山の画像を作って」と投稿
    2. QueryClassificationServiceが`image_generation`を返すことを確認
    3. Function Callingで`generateImage`関数が選択されることをログで確認
  期待結果:
    - ログに`[FUNCTION_CALLING] Executing function: generateImage`が出力される

統合点2: 画像生成とSlack投稿
  場所: ImageGenerationService.generate → SlackClient.uploadFile
  確認手順:
    1. ImageGenerationServiceがGeminiImageClientから画像データを取得
    2. SlackClient.uploadFileが呼び出され、画像がSlackに投稿される
  期待結果:
    - Slackスレッドに画像ファイルが投稿される

こうしておくと、実装を進めるときに「次はこの統合点を確認すればいい」ことがわかります。

なぜこれが効くのか

LLMに実装を依頼するとき、この統合ポイントをDesign Docやそれをもとに作成した作業計画書として渡してあげると「ここを繋げる必要があるんだな」を効率的に理解してくれます。
「いい感じに作って」ではなく、「ここからここまでを繋げるところがゴールだよ」と最初に教えてあげるイメージです。

また、これをやっておくと「レイヤーごと」ではなく「小さな機能を全部通して」作るアプローチが取れるようになります。
各機能の完成時点で動作確認できるので、最後になって繋がらないことに気づく事態を防げます。

小さい意味のある機能単位に通しで作る
機能A: データ層→サービス層→API層→UI層 → 動作確認ヨシ!
機能B: データ層→サービス層→API層→UI層 → 動作確認ヨシ!
機能C: データ層→サービス層→API層→UI層 → 動作確認ヨシ!

実際の効果

この方法を取り入れてから、「結合したら動かない」問題は明確に減りました。

Design Docを書く段階で5分程度の追加作業です。AIにやらせればすぐです。
AIが見落としがちな観点を先回りして示してあげるだけで、後工程の人間（私たち）が苦しむ数時間を短縮できます。

さいごに

今回はDesign Docに書く内容の小さなtipsを共有しました。
特にこんな方におすすめなので、良ければ実践してみてください。

  • Claude CodeなどAIコーディングエージェントで実装スピードは上がったが、統合でよく詰まる人
  • 設計書をガチガチに固めたくはないが、後戻りは減らしたい人
  • AIに実装を任せると、最後に辻褄が合わなくなることが多い人

Discussion