Applibot Advent Calendar 2025

ジョインして3ヶ月のプロジェクトでClaude Code仕様駆動開発を試してみた

Last updated at 2025-12-04Posted at 2025-12-04

Applibot Advent Calendar 2025の5日目の記事です。

前日の記事は@fss_bassさんの激推しターミナルアプリ「Ghostty」でカスタムシェーダーを設定してみるです。

今回は、新しくジョインしたプロジェクトで「 仕様駆動開発 」を実践してみた事例について紹介します。
開発にはClaude Codeを使用しており、Claude Codeを活用した開発スタイルの一つとして、どのように取り組み、どんな効果があったのかを紹介します。

なぜ仕様駆動開発を始めたのか

バックグラウンド

私は株式会社サイバーエージェントで約10年、スマホゲームのサーバサイド開発に携わってきました。

これまでは主にPHPのプロジェクトでゲーム開発をしていたのですが、
今年の夏に株式会社アプリボットのGoプロジェクトにジョインすることとなりました。

今回が初めてのグループ内異動、初めてのGoでの開発と初めて尽くしの状態でした。

ぶつかった壁

ジョイン後、大きめの機能改善や新機能開発を担当することになりましたが、主に以下のような理由から思うような開発速度が出ませんでした。

言語の壁
- Goの勉強のためになるべく自分で書こうとしていたが、不慣れで時間がかかった
コードベースの理解
- これまでの経験から「こう書くだろう」「こんな仕組みがあるだろう」と推測はできるものの、既存コードを調査して合わせて実装するのに時間がかかった
Claude Codeとの協業の難しさ
- 機能が大きいと都度プロンプトで指示するやり方では思ったような結果が得られるまで時間がかかった
セッション管理の問題
- 機能が大きいとセッションが長くなり、compactionが失敗してセッションが切れることもあった。新規セッションで一から指示し直すのが大変だった

一方で、これまでの経験から「プランナーが書いた仕様書を読んでシステム設計を考える」「ワークフロー的にこんなものを作りたい」を言語化することはできました。

そこで、「自分が得意な"設計"部分を活かしつつ、Claude Codeに効率よく開発してもらえないか？」 という発想から、仕様駆動開発にチャレンジして解決が図れないかと考えました。

仕様駆動開発とは

仕様駆動開発は、AIに渡す「仕様書」を起点に開発を進めるスタイルです。

都度プロンプトで設計具体を説明しながら指示を出すのではなく、あらかじめ構造化されたドキュメントを用意しておき、AIがそれを参照しながら開発を進めます。

私が用意した仕様駆動開発の土台

以下のようなディレクトリ構成でAIが読むためのドキュメント群を整備しました。
今回はClaude Codeを用いて開発を行っています。

├── spec/                  # Claude Codeが読む仕様（≠ プランナーが書いた仕様）
│   └── feature_name/      # 機能ごとにディレクトリを切る
│       ├── spec.md        # 作りたいものの仕様
│       └── note.md        # 議論のメモ・検討過程の記録
├── plan/                  # 作業計画書
│   └── feature_name/
│       └── plan.md
├── design/                # システム設計書
│   └── feature_name/
│       └── design.md
└── learn/                 # 開発で得た学びをまとめた資料

これらに加えて、チームで整備されている .claude/setting.json なども活用しています。

各ドキュメントの役割

spec.md：Claude Codeに渡す「仕様書」

Claude Codeに渡す一次情報となる仕様書です。
プランナーが作った仕様をそのまま渡すのではなく、エンジニア観点で必要な情報を整理して以下のように記述しています。

作るもの
- ひとことで今回作成する機能を記述
技術
- 利用する技術や制約について記述
実現したいこと
- ユーザーができるようになることやそのフロー、運用のフロー、体験向上のため行いたい効率化などを記述
フローの詳細
- ユーザーが行う手順、やり取りされる情報、ユーザー目線から見て起きることなどを箇条書きで記載

最初は人間が叩きを作り、その後Claude Codeと対話しながら詳細を詰めて更新させています。

記述例

# 作るもの
ユーザーがアイテムAを消費して操作Bができる機能を追加

# 技術
- Go
- AWS xxx
- AWS yyy
- ここに挙げたもの以外は利用しないこと

# 実現したいこと
- ユーザーはアイテムAを消費して操作Bできるようになる
  - 操作Bは〇〇アルゴリズムを用いて実現する
  - 操作Bは重いのでキャッシュを利用する
- 管理画面のhogeメニューを新規に作成してアイテムAをユーザーに付与できるようにする

## ユーザーがアイテムAを消費して操作Bができるフローの詳細
- ユーザーはアイテムAの個数を指定して実行
- 操作Bの計算結果はAWS xxx へキャッシュする
- 分析のためログをAWS yyyへ送る
- 操作Bの結果をサーバーから返して演出を見せる

## 管理画面hogeメニューを通じたアイテムA付与フローの詳細
（前述のフロー詳細と同様に記載）

plan.md：作業計画書

spec.md をもとにClaude Codeと生成する「作業計画書」です。

タスク一覧と工数見積もり
マイルストーン
- マイルストーンごとに実行タスクや工数、備考を記載
- 工数変動リスクもあれば備考として記載

Claude Codeが開発時にどの順序で実装するか判断するために参照する他、チームへのスケジュール説明にも活用しています。

記述例

# タスク一覧と工数見積もり

## マスタデータ定義
...

## DB設計
...

## API定義・実装
...

# マイルストーン

## 1. モックAPIを使って最速で機能を体験できるようにする

### 対象作業
API定義・実装
1. API定義
2. モックレスポンスを返す

## 2. 仮マスタデータを使って機能を体験できるようにする

### 対象作業
マスタ定義
1. マスタデータAの作成
2. マスタデータBの作成

DB定義
1. テーブルCの作成

API定義・実装
3. 操作B実行APIを実装
 - アイテムを消費
 - 機能Bを実行

### 備考
- キャッシュ・ログは次のマイルストーンで対応

## 3. ...

design.md：システム設計書

spec.md をもとにClaude Codeと生成する「システム設計書」です。

フロー設計
- PlantUMLを用いて書かれたシーケンス図など）
インフラ構成
データモデル
- マスタ定義、テーブル定義、マスタ・テーブル外に配置されるメタデータのスキーマなど
API設計
- リクエスト/レスポンスのスキーマ
アルゴリズム詳細

plan.mdと同じくこちらを元にClaude Codeが実装するため、 「design.mdに書かれた内容をそのままコードで表現すればいい」 というレベルまで詳細に記述します。

記述例

次のような雰囲気のドキュメントになります。
実際には他のドキュメントと同じくmarkdownで記述するのですが、図表が多くなりがちな性質のドキュメントのため、視覚的に分かりやすいようスクリーンショットを記載しておきます。

note.md：議論のメモ

Claude Codeやステークホルダーと議論したトピックをまとめたメモです。

開発を進める中で、仕様が変更になったり、より良い設計案が浮かんできたり、Claude Codeと対話するうちに別の手法で進めたくなることがあります。そうした議論の過程や結論、選ばれなかった案も含めて記録しておきます。

結論だけは spec.md、plan.md、design.md に反映させ、各ドキュメントの鮮度を最新に保ちます。

記述例

# 2025-12-01 操作Bは重いのでキャッシュを持つ方がいいのではないか

## 持たない
- ○○なリスクがある

## Sync.Mapで持つ
- メリットは〜〜〜
- デメリットは〜〜〜

## AWS xxxで持つ
- メリットは〜〜〜
- デメリットは〜〜〜

## 結論
- ○○リスクへの対策と運用を経てデータ量が大きくなることが予想されるためAWS xxx を利用する

# 2025-12-02 分析用のログ構造を既存機能Aと合わせるか
...

# 2025-12-03 クライアントと操作Bの演出に必要なレスポンスについて再相談
...

また、note.mdは開発中に「あの時どういう議論をして今の設計に決めたんだっけ？」と振り返りたい時にも役立ったり、既存コードの調査や設計案の提案を指示し構造的にまとめさせ、自分が結果を見て判断をするといった読みやすい中間的な文書としても役に立ちました。

ADRなどに近いイメージかもしれません。

開発フロー

Step 1：仕様作成

spec.md に、作るもの・技術・前提・実現するためのフローを記載する
Claude Codeと対話して詳細を詰める
対話中に新しい気づきがあれば note.md にも記録し、spec.md へ反映させる

Step 2：作業計画書・システム設計書の生成

spec.md を元にClaude Codeに plan.md と design.md を作成させる
出力内容を確認し、必要に応じて追加・修正指示を行い反映させる
スケジュールや設計に関する新しい気づきがあれば note.md を活用して各ドキュメントへ反映させる

Step 3：開発

完成した spec.md、plan.md、design.md をもとにClaude Codeへ開発を指示する
1. plan.mdで定めたマイルストーンの1項目ずつ作って、ここまで作ってみてと指示することが多かったです
開発中に新しい気づきがあれば、Step 1, 2と同様に各ドキュメントへ反映し、常に最新の状態を保つ

Option：学びを learn/ に記録する

仕様駆動開発と直接関係はありませんが、私は異動して間もないことからClaude Codeと詳細を詰める過程や提示してきたコードからも新たな学びが多かったです。そうした学びがあった場合、コンテキストを含めてClaude Codeに [学んだこと].md を出力させています。

例：

プロジェクトでのキャッシュ戦略の使い分け.md
アイテム付与パターンABメリデメ.md

後から「アイテム付与パターンABメリデメ.mdのうちAの方で実装してほしい」とClaude Codeに指示をしたり、メンバーにABどちらかで悩んでると相談する際の情報整理や共有としても役に立ちました。

実践してみての成果や気づき

解決できたこと

当初の懸念だった「やりたいことは浮かんでいるのに速度が出ない」という課題を解決できたと思います。

今回は1ヶ月以上かかる機能の開発を担当していますが、ほぼ全てのコードをClaude Codeが書き、自身でコーディングをしていた時よりも圧倒的な速度が出るようになりました。

自分で直したのは、変数のシャドーイングが起きている部分を数文字直す（err := を err = にする程度）、など指示をするまでもなくコンテキストに残しておかなくても支障がない部分のみでした。

気づき

直接的な成果の他に、これまでの開発と比較して次のような気づきが得られたことも挑戦してみて良かったと思います。

plan.md、design.md があることでClaude Codeへのタスク渡しが楽になり、出力されるコードも想定に近いものが出力されることが多かった
plan.md、design.md があることで、メンバーへの説明やメンバーがタスクの一部を途中から引き継いでAIに任せる形のヘルプや委譲も楽になった
note.md があることで、誰と何を話して今の設計になったか思い出したり、他人に説明するのが楽になった
各ドキュメントは開発の最序盤でClaude Codeとの対話を通じてプロジェクトのコードを参照しながら詰められたので、「やってみないと分からない」という不安や作業のずれが減った

今後の展望

異動前後のタイミングと重なってしまい、盛り上がっていたKiroなどの仕様駆動開発を補助してくれるツールを試せていないので試してみたい
.md は人間にとっては扱いやすいが、Claude Codeにとってより作業しやすい形がありそうなので模索してみたい

まとめ

今回は新しいプロジェクトにジョインして思うような開発速度が出ないという悩みに対して、仕様駆動開発で解決を図るアプローチを紹介しました。

構造化されたドキュメントを用意することで、Claude Codeとの協業がスムーズになり、開発速度と品質の両方を向上させることができました。

同じような悩みを抱えている方がいればぜひ参考に試してみてもらえると嬉しいです。
また、今後も様々な仕様駆動開発の手法の記事が執筆されて自分も参考に成長できると嬉しいです。

それでは明日の記事もお楽しみに！

We are Hiring!

株式会社アプリボットでは、 エンジニアをはじめ全職種で積極採用中 です。
記事を読んで少しでも興味を持たれた方やお話を聞きたい方は、是非お気軽にご連絡ください！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up