2026年07月10日

Claude Codeと設計を徹底的に詰める開発スタイルについて

AWS, システム開発, Amazon Bedrock, Claude

1. はじめに

Claude Codeをはじめとするコーディングエージェントは、今や多くの開発者が日常的に使う道具になりました。私自身も毎日のように使っていますが、最近は使い方が少しずつ変わってきました。コードを書かせる道具としてではなく、設計を詰めるための相手として使う比重が、明らかに増えてきたと感じています。

私は現在、生成AIプラットフォームの開発に携わっています。システムはAWS上に構築されているのですが、私自身はインフラ側の経験がそれほど多いわけではなく、設計の中でクラウドサービスの構成を詰める場面では、自分の判断材料が不足していると感じることが少なくありません。

今の私の開発スタイルは「9割の時間を設計にあて、残り1割の時間で実装する」です。実装に使う時間を極限まで減らし、その手前の設計をClaude Codeと徹底的に詰める。設計書さえ固まれば、実装はほぼ一気に終わる、という進め方をしています。いわゆる仕様駆動開発に近い考え方です。

本記事では、

なぜ「9割設計・1割実装」という進め方に行き着いたのか（2章）
設計フェーズでClaude Codeをどう使い、どんな課題にぶつかって、どう解決したのか（3章）
詰めた設計書をもとに、どう一気に実装させるのか（4章）
そして、このやり方を続ける中で見えてきた課題（5章）

を共有します。なお、本記事で紹介するスキルや進め方は私個人のスタイルに寄せたものです。「こういう使い方をしている人もいる」という参考程度に読んでいただければと思います。

2. Claude Codeを使った設計と実装の進め方

2.1 なぜ設計に9割の時間をかけるのか

最初に実践していたClaude Codeの使い方は、ざっくり次のような流れでした。

やりたいことを伝える
コードが出てくる
動かしてみる
違うところを直してもらう
2〜4を繰り返す

簡単なスクリプトであればこのループで十分なのですが、ある程度の規模の機能を作る場合、このやり方には明確な限界を感じました。特に顕著だったのは、自分の頭の中の設計の解像度が、そのまま成果物の解像度の上限になるということです。リトライ方針、重複実行時の挙動、運用時の監視ポイントなど、自分の中で詰め切れていない論点は、AIが自分の解釈で補完してしまうため、後から「思っていたのと違う」と気づき、結局そこから作り直すことになります。

この手戻りの根幹をたどると、いつも「設計の解像度が低いまま実装に入っていた」という一点に行き着きました。ならば、実装に入る前に設計を徹底的に詰めてしまえば、手戻りそのものが減るはずです。こうして、設計に時間の大半をかけ、実装は最後にまとめて一気に終わらせる、というスタイルに切り替えました。設計が完全に固まっていれば、実装は設計書を順番にコードへ落とすだけの作業になり、ほとんど迷いが生じません。

2.2 全体の流れ

私の進め方を俯瞰すると、次のような流れになります。

設計フェーズ：まずは、Claude Codeを要所で使いながら、自分の頭で8割程度まで設計を作り込んだ上で、Claude Codeとの対話で残り2割を詰める。その結果を詳細設計書としてまとめる。
実装フェーズ：設計書をもとに、Claude Codeに一気に実装させる

この流れを支えるために、私はいくつかの自作スキルを用意しています。スキルは設計フェーズで使うものと、実装フェーズで使うものの2階層に分かれています。

本記事では、設計フェーズで使うaws-bedrock-research / aws-infra-advisorと、実装フェーズで使うspec-driven-implementationを取り上げます。前者は設計の判断材料を補うためのスキル、後者は固めた設計から実装を逸脱させないためのスキルです。

3. Claude Codeを使った設計

ここからが、本記事の中心である設計フェーズの話です。

3.1 まず自分の頭で設計し、残りをClaude Codeと詰める

設計フェーズで私が最も大事にしているのは、設計の主導権を自分の側に置くことです。 Claude Codeは優秀なので、最初から「この機能の設計を一通り考えて」と投げてしまっても、それらしい設計は出てきます。ただ、そうすると自分の思考がAIの出力に引っ張られてしまい、本来は自分の頭で詰めるべきだった部分が薄れていき、大事なことを見落としてしまいがちです。システム開発においては、「ベストプラクティス的にはA案だけど、お客様の意向もあってB案にする」のような事情があったりするため、全てをAIに任せるのは現実的ではないと感じています。もちろん、Claude Codeはとても優秀なので、それら全てのコンテキストを渡せれば完璧なものが完成すると思います。ただ、プロジェクトに関する情報は、お客様との会議、社内ミーティング、Slackなどに散らばっているため、全てのコンテキストを渡して設計させることは現実的に難しいです。そのため、プロジェクトの背景やお客様の意向、社内の事情など、どうしても自分でしか判断ができない箇所が必ずあるため、まずは自分の頭である程度設計を作り込んでから、Claude Codeと対話して残りを詰める、というスタイルを取っています。粒度としては基本設計から詳細設計の手前あたり、つまり、具体的なコードレベルまでは落ちていないものの、全体の構造や処理の流れは固まっている、というレベルです。

Claude Codeに期待しているのは、その今までの設計のレビュー+残りの2割を一緒に詰めることです。ここでやってもらうことは、大きく分けて4つあります。

1つ目は、異常系やエッジケースの洗い出しです。設計対話の中で、Claude Code側から「この処理が異常終了したときに、再実行はどのトリガーから走らせる想定ですか」「外部側でデータが論理削除された場合は、こちら側でも反映する想定ですか」といった確認が入ります。自分の中で詰め切れていなかった例外パターンや考慮漏れが、対話を通じて順次言語化されていきます。正常系は自分でも比較的簡単に詰められますが、異常系の網羅性は一人だと抜けが出やすく、ここを問いかけてもらえるのは大きな価値があります。

2つ目は、実装してみないとわからない部分の事前確認です。設計の段階ではうまく組み立てたつもりでも、いざ作り始めると「使おうとしていたライブラリがその処理に対応していなかった」「逆に、そこまで作り込まなくてもライブラリの機能で実現できた」といったことに後から気づくことがあります。人間は設計レベルで考えるぶん、こうした具体的な実現コードレベルまでは踏み込まないことが多いのですが、ここを設計フェーズのうちにClaude CodeにAWS等の公式ドキュメントを調べてもらいます。そうすることで、設計の段階で新たな論点が出てくることもよくあります。

3つ目は、全体レビューです。設計の全体を通して、矛盾している部分や、抜けている部分がないかをレビューしてもらいます。特に、設計の中で複数の選択肢がある場合は、それぞれのメリット・デメリットを整理してもらい、どの選択肢が自分のプロジェクトにとって最適かを一緒に考えます。

最後に、詳細設計書の作成です。設計対話の中で詰めた内容をもとに、実装フェーズで迷いなくコードに落とせるような詳細設計書を作成してもらいます。この設計書を作成する目的は、「実装フェーズにおいて、Claude Codeが設計書を参照しながらコードに落とすだけの状態にすること」です。設計対話の中で出てきた論点や、選択肢の比較、各異常系に対してどう対応するのかなど、対話した内容は整理してできる限り全て設計書に盛り込んでもらいます。調査した内容は実装時に参照できるように、設計書の中に公式ドキュメントのURLも必ず含めてもらいます。

上記のように設計を進めたのですが、実際にやってみると、2つの壁にぶつかりました。次は、その壁と、私がどう解決したのかを紹介します。

3.2 課題：Claude Codeの知識は古いことがある

1つ目の壁は、Claude Codeの知識が、必ずしも最新ではないという問題です。

AIにはナレッジカットオフがあります。ナレッジカットオフとは、AIが学習したデータの最新日時のことです。たとえば、Claude Sonnet 4.6の場合は、2025年8月です。つまりそれ以降にリリースされた新機能や、APIの変更、SDKのアップデートなどについては知らないことが多々あります（参照：Claudeのトレーニングデータはどの程度最新ですか？）。特に今回のプロジェクトで私が触っている領域はAmazon BedrockやAgentCoreなど、LLM系の変化の速いサービスが中心です。新機能、API変更、SDKのアップデートが頻繁に入り、半年前の情報でもすでに古くなっていることがあります。Claude Codeに「この機能はどう使うのが現在の推奨か」と尋ねても、ナレッジカットオフ時点の知識で自信を持って回答されると、古い情報をもとに設計してしまうリスクがあります。

これを解決するために作成したのが、aws-bedrock-researchスキルです。これは、BedrockやAgentCoreに関する話題のとき、Claude Codeが回答する前に Web検索で最新情報を強制的に取得させるためのものです。

スキルのdescriptionには、明示的に「調べて」と言わなくても、Bedrock周りの話題であれば必ず発火するよう書いています。

---
name: aws-bedrock-research
description: Amazon BedrockおよびAgentCoreの最新情報をWebから取得して日本語レポートにまとめるスキル。
（中略）AWSの生成AI関連サービスについて調査が必要なときは、たとえ明示的に「調べて」と
言われなくても、ナレッジカットオフ以降に変更がありそうな話題であればこのスキルを使うこと。
---

「明示的に『調べて』と言われなくても」の部分は、自分が毎回指示を忘れたとしてもClaude Code側が自動で発火するようにするための記述です。

スキル本体には、検索の進め方をかなり具体的に書いています。一度の検索では情報が偏るため、複数の角度から並列に検索を走らせるよう指示しています。

### Step 2: 多層Web検索

1回の検索で満足せず、複数の角度から検索する。検索クエリには必ず現在の年（または年月）を含める。

**検索ラウンド1 — 公式ソース（必須・並列実行）**
クエリA: "Amazon Bedrock AgentCore {トピック} {現在の年}"
クエリB: "AWS Bedrock {トピック} docs.aws.amazon.com {現在の年}"

**検索ラウンド2 — 日本語テックブログ・実践情報（必須・並列実行）**
クエリD: "Bedrock AgentCore {トピック} やってみた OR 使ってみた {現在の年}"
クエリE: "Amazon Bedrock {トピック} DevelopersIO {現在の年}"

工夫しているのは、検索クエリに現在の年を強制的に含めて古い記事を除外することと、公式ドキュメントだけでなくDevelopersIO・Qiita・Zennなどの日本語テックブログも並列で叩くことです。特に日本語テックブログは、公式ドキュメントだけでは見えにくい実装上の落とし穴や、検証時のハマりどころを拾えるため、実現可否の確認では実用上の効果が大きいと感じています。

3.3 課題：インフラの判断材料が足りない

もう1つの壁は、私自身のインフラ知識の薄さです。設計の中でクラウドサービスの構成やCDKの書き方を詰める場面では、自分の判断では自信が持てない場面が少なくありません。Claude Codeに頼るのは自然なのですが、特にAWSのベストプラクティスにマッチしているか、最新の推奨パターンに沿っているか、という点は、前述のナレッジカットオフの問題もあって、Claude Codeの回答をそのまま採用するのはリスクがあると感じています。

ここを補うのがaws-infra-advisorスキルです。CDK・Lambda・IAM・VPC・S3・API Gatewayなど、AWS/インフラ全般の実装相談を扱います。aws-bedrock-researchが「Bedrockの最新情報リサーチ」に特化しているのに対し、こちらはより広いインフラ領域の「実装の相談」をカバーします。

スキルの冒頭には、Claude Codeの「知っているつもり」を抑え、必ずWeb検索を挟ませる方針を明記しています。

ユーザーはAWSやCDK、インフラ周りに強くない。だからこそ、Claudeの「知っているつもり」で答えると古いAPIや非推奨パターンを案内してしまう。このスキルは、必ずWebSearchで最新の公式情報を取得し（中略）実装アドバイスを返すことを最優先する。

検索の進め方はaws-bedrock-researchと同様に、公式ドキュメントと日本語テックブログを並列で叩く構造です。加えて、Claude Codeが返すアドバイスの構造も指定しています。

要点（1〜2文で結論）
公式ドキュメントなどの根拠
コード例（必要な場合）
選択肢が複数ある場合は比較表
未確認・要追加調査の項目（推測で埋めず正直に書く）

「結論から先に書く」「複数選択肢がある場合は比較してから提示する」あたりは、インフラ判断に自信が持てない私にとって、論点を整理して出してもらえると判断しやすいためです。理想を言えば、ここに自プロジェクトのコーディング規約（タイムアウト・命名・IAMの最小権限など）まで参照させ、規約と整合する形で提案を返せるとさらに有効です。私も案件によっては規約ファイルを明示的に読み込ませますが、規約をどこまで整備するかはチームの状況次第なので、必須というわけではありません。

4. 設計書をもとに一気に実装させる

設計フェーズで設計を9割方詰め切ると、実装フェーズはほとんど「設計書を順番にコードへ落とす」だけの作業になります。残り1割、というのはこの感覚です。ただし、ここにも落とし穴があります。

4.1 課題：実装に入ると設計から逸脱する

設計対話で時間をかけて方針を整理しても、いざ実装に入るとClaude Codeは「ここはこう書いた方が綺麗だ」「ここは一旦省略しても問題ない」といった判断を勝手に挟み込み、設計書とコードが少しずつズレていきます。せっかく9割詰めた設計が、実装の段階で崩れてしまっては意味がありません。

4.2 対策：実装フェーズでは設計書を唯一の正にする

実装フェーズで大事にしているのは、Claude Codeに自由に判断させることではなく、設計書を唯一の正として扱わせることです。

そのために、私はspec-driven-implementationというスキルを用意しています。このスキルは「便利に実装してもらう」ためのものではなく、実装中に設計書から逸脱しないようにするための規律をClaude Codeに渡すものです。

具体的には、次の2つを必ず守らせています。

実装前に設計書の不備を洗い出す
仕様変更が発生したら、コードより先に設計書へ反映する

以降では、この2つの規律を順に説明します。

4.3 規律1：実装前に設計書の不備を洗い出す

実装に入る前に設計書を読み直させる理由は、設計フェーズで詰め切れなかった曖昧さをここで検出するためです。そのため、スキルには次のように書いています。

## フェーズ 0: スタート確認（必須・最初に行う）
実装に着手する前に必ず以下の2点をユーザーに聞く。
1. 実装対象の機能
2. 参照する設計書

## フェーズ 1: 実装前（必須）
### 設計書の不備チェック
読み込み後、実装に必要な情報が揃っているか確認し、以下を識別する：
- A: 明確に定義されている → そのまま実装
- B: 記載がない・曖昧 → ユーザーに確認
- C: 矛盾している → ユーザーに報告して判断を仰ぐ
不備が1件でもある場合、実装開始前に全件まとめてユーザーに確認する。

設計書を最初から最後まで読み、不備や矛盾を全件洗い出してから確認を返してくるため、実装開始の時点で、設計書側の抜けや矛盾があぶり出されるという副次的な効果があります。9割詰めたつもりでも、ここで残った曖昧さに気づくことは少なくありません。設計フェーズでもレビューを実施し、実装段階でも最初にレビューするという二段構えにすることで、設計の精度をさらに高めることができます。また、意識していることとして、実装に入る際には、一旦/clearしてコンテキストウィンドウを0にしてから、このスキルを呼びます。理由としては、

コンテキストウィンドウを0にすることにより、Claude Codeの最大限の能力を発揮させるため
「設計書に落とし込まれていない、未確認の仕様」をClaude Codeに認識させるため

です。これにより、仮に設計段階で詰め切れていない論点があったとしても、実装段階でそれがあぶり出されるようになります。

4.4 規律2：仕様変更はコードより先に設計書へ反映する

もうひとつ大事にしているのは、仕様が変わった瞬間に設計書へ反映することです。コードだけを先に直すと、設計書が古くなり、次回以降Claude Codeが誤った前提で実装してしまいます。そのため、スキルには次のように書いています。

### 仕様確定時の即時設計書反映（必須）
ユーザーとのやりとりで仕様が確定したその場で、実装前・実装後を問わず設計書に反映する。
完了後まで溜め込まない。

反映トリガー:
- ユーザーが選択肢を選んだ
- 曖昧だった仕様がやりとりを通じて確定した
- 実装上の制約から設計書の記述を変更することにした

これを徹底すると、設計書とコードのどちらが新しいのかという状態がそもそも発生しなくなります。Gitの履歴を見れば「いつ、なぜ設計が変わったか」が辿れるようになり、半年後にコードを読み返す自分自身にとってもありがたい状態が維持されます。設計に9割の力を注ぐスタイルは、この「設計書が常に正である」という前提があって初めて成立します。実装と設計書に乖離が出てしまうと、どちらが正しいのかわからなくなり、結局コードを見ながら設計書を修正するという手戻りが発生してしまいます。そうならないように、仕様が変わったらコードより先に設計書を更新する、という規律を徹底しています。

5. 残された課題：人間による設計書レビュー

ここまで「うまくいっている部分」を中心に書いてきましたが、このスタイルを続ける中で、まだ解けていない課題があります。むしろ本記事で一番伝えたいのはここかもしれません。それは、設計を徹底的に詰めるほど、設計書がAI向けに最適化されていき、人間がレビューしづらくなるという問題です。

spec-driven-implementationは「実装で迷わないこと」を最優先にしているため、データ構造、状態遷移、APIの入出力、エラーパターン、リトライ条件といった部分まで、できるだけ具体的に書き込まれる方向に動きます。9割を設計に注ぎ込んだ結果として出来上がる設計書は、事実上の詳細設計書になります。

Claude Codeにとってはこれで何の問題もありません。むしろ詳細であればあるほど、実装は正確かつ高速になります。ところが、人間のレビュアーには読み切れないという別の問題が出てきました。レビューしようとしても粒度が細かすぎて、指摘ポイントが拡散し、本質的な議論にたどり着くまでに時間がかかります。

5.1 現時点の落とし所：設計書の二層化

現時点での自分なりの答えは、設計書を二層に分けて運用することです。

概要設計書（人間向け）：背景・目的・主要な意思決定・全体構造を1〜2ページにまとめたもの。レビュアー向け
詳細設計書（AI向け）：spec-driven-implementationが参照する完全仕様。Claude Codeが実装で迷わないレベルまで具体化したもの

両者をリンクで紐付けたうえで、人間は概要を読み、AIは詳細を読む、という分担です。ここまでAIが発達すると、AIが詳細設計書を完璧に詰めてくれる前提のもとで、人間がレビューすべき対象は、実装レベルの細かい部分ではなく、なぜこの設計にしたのか、他の選択肢と比べてどうなのか、といった設計の背景・目的・主要な意思決定・全体構造という、より上位の論点にシフトしていくのではないかと感じています。そのためには、人間がレビューしやすい解像度で、設計の背景や目的、主要な意思決定、全体構造をまとめた概要設計書を別途用意する必要があると考えています。

ただし、この二層化も完成形ではなく、いくつか課題が残っています。

概要設計書を別途書き起こす手間が増える
概要と詳細の整合性を維持するために、片方を更新したらもう片方も更新する必要がある

個人的には、概要設計書を人間が手で書き、概要設計書をもとに詳細設計書をAIと対話しながら作成するかAIと対話して作成した詳細設計書をもとにAIに概要設計書を作成させるのがいいのかなと考えています。この領域はまだ明確な正解がないと感じており、今後も試行錯誤しながら整備していきたいと考えています。

6. まとめ

本記事では、Claude Codeを使って「9割を設計に、1割を実装に」という進め方をどう実践しているか、そこでぶつかった課題とその解決、そしてまだ解けていない課題を共有しました。

私自身、インフラやAWSの経験が豊富とは言えない立場ですが、設計フェーズにClaude Codeを組み込み、そこに時間を注ぐことで、踏み込める領域は確実に広がってきたと感じています。そして同時に、「人間は設計の何をレビューすべきか」という問いにも向き合うことになりました。AIが詳細設計を高い精度で詰めてくれるのであれば、人間の役割は実装レベルの細部ではなく、なぜこの設計にしたのか、他の選択肢と比べてどうか、といったより上位の意思決定へとシフトしていくのではないかと感じています。設計の主導権は人間が握りつつ、詰める力はAIを借りる。その先にある「人間にも読める設計書」をどう両立させるかは、これから多くの開発者が向き合うテーマだと思っています。本記事が、Claude Codeの使い方を一段深く考えるきっかけになれば幸いです。