Claude Codeを開発の全フェーズで活用したら開発生産性が1.5倍に向上した

自分は今年の4月くらいから本格的にコーディングエージェントを使い始めて、主にCline、GitHub Copilot Agent(以降Copilot)、Claude Codeあたりを試してきました。

Claude CodeをメインにするまではCopilotを使っていて、便利だなと思いつつも自分:エージェント=6:4くらいの割合で自分でコードを書いていました。
しかし、5月にClaude 4モデルがリリースされてから精度がかなり上がり、とても感動したのを覚えています。それからは、3:7くらいでエージェントに任せる割合が増えていきました。

さらに、それから少ししてClaudeのProプランでもClaude Codeを使うことができるようになり、試してみたところ、精度も高く使い勝手もよかったので、それからはClaude Codeをメインに使っています。

それ以降は、開発の全てのフェーズにおいてClaude Codeを活用するようになり、開発スタイルが大きく変化しました。
そこで今回は、要件定義から設計、タスク分解、コーディング、動作確認に至るまで、具体的な活用方法について紹介したいと思います！

要件定義

要件定義の段階では、機能要件や機能仕様をまとめるために使用しています。
個人でのブレストや、複数人の議論で発散させた内容を収束させるために使用しています。

コンテキストとして議論した内容の議事録を丸々読み込ませて、そこから要件や仕様をまとめるように指示し、何回かラリーを行いながらブラッシュアップしていきます。
ここで嬉しいのが、議事録をコンテキストとして渡すことで、過去に議論した内容と整合性を保てる点です。

ラリーの中で「xxの部分はooという仕様にして」と指示をした際に、それが過去の議事録の内容と齟齬がある場合に「議事録では△△と言及されていましたがどちらが正しいでしょうか？」と提案してくれます。
議論から時間が経って忘れていたり、自分がミーティングに参加していない場合もありますが、
そのような場合に過去の議事録を参照してくれるので、脳内メモリで保持しなければならない情報量が減り、思考がしやすくなるので非常に助かっています。

また、ドキュメントツールにはNotionを使っているので、情報の入出力をNotion MCP経由でできないか試してみましたが、これはあまりうまくいきませんでした。
ページの参照は比較的問題ないのですが、ページの作成や更新が遅かったり、複雑なページやプロパティが多い場合だと作成が失敗することが多かったです。
参照に関してもトークンの消費量を考えると、必要な部分をコピーして直接プロンプトに含める方が良いかなと感じています。

このフェーズに関してはCLIである必要はないですが、ツールの行き来が面倒なのでClaude Codeを使っています。

DB設計

DB設計は下記の3ステップで進めています。

1. Claude Codeと対話しながらMermaidでERDを生成
2. 生成したERDをチーム内でレビュー
3. ERDを元にマイグレーション用のSQLを生成

Mermaidはテキストベースでダイアグラムを作成できるツールで、ER図も簡潔な記法で表現できます。

Mermaidのソースコード

erDiagram
    users {
        int user_id PK
        string email UK
        string name
    }
    posts {
        int id PK
        int user_id FK
        string title
        text content
    }
    users ||--o{ posts : "writes"

Mermaidを自分で書くのは面倒ですが、Claude Codeを使えば簡単に生成できる点が良いです。
また、Mermaidで出力することで、その後の実装でもClaude Codeがコンテキストとして参照しやすくなります。

以前はFigmaやMiroなどのツールを使ってERDを作成していましたが、それよりもはるかに早く作成することができるようになりました。

このステップでDB設計をするようになってから、ERDやマイグレーションファイルの作成で手を動かすことがほぼなくなり、思考することだけに集中できています！

既存テーブルの参照

既存のテーブル情報はtblsが生成したMarkdownファイルを活用しています。

tblsはデータベースのスキーマ情報を読み取ってMarkdown形式のドキュメントやSVG形式のER図を自動生成してくれるツールです。
テーブル構造やリレーション、インデックス情報などが整理された形で出力されるので、Claude Codeが既存テーブルの情報を理解しやすくなります。
GitHub Actionsを使用して、DBのスキーマに変更が加わった際に自動でtblsを実行し、最新のテーブル情報をコミットしています。

tblsで生成したMarkdownファイルをコンテキストとして渡すことで、既存のテーブル情報を参照しながら設計を進めることができます。
設計の際に参照して欲しい関連テーブルを、ファイル指定で指示できる点も非常に便利です。

DB設計用のカスタムスラッシュコマンド

ERDを生成するステップでは、Kiro風のアプローチを採用しています。
下記の記事を参考に、DB設計に特化したカスタムスラッシュコマンドを作成して使用しています。

https://zenn.dev/sosukesuzuki/articles/593903287631e9

DB設計用のカスタムスラッシュコマンド

table-design.md

---
description: 要件を3段階で分析してDB設計を行う
---

Claude Code を用いたテーブル設計を行います。最終的なアウトプットとして Mermaid 形式の ERD を生成します。

## コンテキスト

下記に現在のテーブルの設計が定義してあります。必要に応じて参照してください。

<!-- tblsで生成されたMarkdownファイル -->
- `docs/schema/*.md`

## テーブル設計フロー

以下の3つのフェーズに従ってテーブル設計を進めます。

### 1. 事前準備フェーズ

- ユーザーがClaude Codeに対して、**設計したいテーブルの概要**を伝えます。
- このフェーズで `mkdir -p ./.claude/specs` を実行します。
- `./.claude/specs` 内にテーブルの概要から適切な spec 名を考えて、その名前のディレクトリを作成します。
    - たとえば、「ユーザー管理テーブルを作成する」というタスクなら `./claude/specs/create-user-management-table` という名前のディレクトリを作成します。
- 後続のファイルはこのディレクトリの中に作成します。


### 2. 要件フェーズ

- Claude Codeがユーザーから伝えられたテーブルの概要に基づいて、**テーブルが満たすべき「テーブル要件ファイル」**を作成します。
    - 「テーブル要件ファイル」には、テーブルの目的、必要な情報、関連するエンティティ、パフォーマンス要件などが含まれます。
    - **具体的な項目例:**
        - テーブルの目的 (e.g., ユーザー情報の管理)
        - 保持するデータ項目 (e.g., ユーザーID、氏名、メールアドレス、パスワード、登録日時、更新日時)
        - 各データ項目の型、長さ、NULL許容、ユニーク制約の有無 (ただし、このフェーズでは詳細な型や長さは必須ではありません)
        - 主キーの候補
        - 外部キーの候補 (関連するテーブルとリレーションシップ)
        - データ量の見積もり
        - アクセス頻度の見積もり (読み取り/書き込み)
        - 整合性制約 (e.g., メールアドレスはユニークであること)
        - その他、ビジネスルールに関連する要件
- Claude Codeがユーザーに対して「テーブル要件ファイル」を提示し、問題がないかを尋ねます。
- ユーザーが「テーブル要件ファイル」を確認し、問題があればClaude Codeに対してフィードバックします。
- ユーザーが「テーブル要件ファイル」を確認し、問題がないと答えるまで「テーブル要件ファイル」に対して修正を繰り返します。


### 3. 設計フェーズ

- Claude Codeは、「テーブル要件ファイル」に記載されている要件を満たすような**「テーブル設計ファイル」**を作成します。
    - 「テーブル設計ファイル」には、具体的なテーブル名、カラム名、データ型、長さ、制約（NULL許容、DEFAULT値、UNIQUE、PRIMARY KEY、FOREIGN KEY）、インデックス、コメントなどが含まれます。
    - **具体的な項目例:**
        - **テーブル定義:**
            - テーブル名
            - エンコーディング、照合順序
        - **カラム定義:**
            - カラム名
            - データ型 (e.g., `VARCHAR(255)`, `INT`, `DATETIME`)
            - 長さ/精度
            - NULL許容 (NOT NULL / NULL)
            - デフォルト値 (DEFAULT)
            - コメント (カラムの用途説明)
        - **キー定義:**
            - 主キー (PRIMARY KEY)
            - ユニークキー (UNIQUE KEY)
            - 外部キー (FOREIGN KEY) とその参照テーブル、参照カラム、ON DELETE/ON UPDATEアクション
        - **インデックス定義:**
            - 必要に応じて、検索効率化のためのインデックス (種類、対象カラム)
        - **その他:**
            - テーブルコメント (テーブルの全体的な説明)
            - パフォーマンスに関する考慮事項 (e.g., パーティショニングの有無)
- Claude Codeがユーザーに対して「テーブル設計ファイル」を提示し、問題がないかを尋ねます。
- ユーザーが「テーブル設計ファイル」を確認し、問題があればClaude Codeに対してフィードバックします。
- ユーザーが「テーブル設計ファイル」を確認し、問題がないと答えるまで「テーブル設計ファイル」に対して修正を繰り返します。
- **最終的に、この「テーブル設計ファイル」の内容に基づいて、Mermaid 形式のERDを出力します。**

コマンド起動後は、機能としての要件定義は前のフェーズで済んでいるので、その内容を渡しつつDB設計に必要な制約やリレーションを明確にするため情報を追加で指示しています。

ただし、設計の選択肢がいくつかある際に回答がブレたり、指示の仕方でも結論が変わることがあるので、やはり指示する側の技術や経験が求められます。

タスク分解

DB設計が完了したら、タスク分解を行います。

個人開発であれば、要件定義・DB設計が完了したらそのまま実装に入っても良いと思います。
しかし、実務の場合は、スケジューリングのための作業時間の見積もりや、タスクの割り振り、ジュニアメンバーへの指示など、事前にタスク分解が必要なケースが多いため、このフェーズを設けています。

このフェーズでも、専用のカスタムスラッシュコマンドを作成して使用しています。
このコマンドを実行することで、要件から実装計画を複数ファイルに分割して作成しています。

タスク分解用のカスタムスラッシュコマンド

task-plan.md

---
description: 要件を3段階で分析して詳細な実装計画を作成する
argument-hint: [要件の概要]
---

$ARGUMENTSの要件を3段階のフェーズに従って分析し、詳細な実装計画を作成します。

## 実装計画フロー

以下の3つのフェーズに従って実装計画を進めます。

### 1. 事前準備フェーズ

- ユーザーから伝えられた要件の概要を把握します。
- `mkdir -p ./.claude/tasks` を実行します。
- `./.claude/tasks` 内に要件から適切なspec名を考えて、そのディレクトリを作成します。
  - 例：「フォームの項目追加」→ `./claude/tasks/add-form-field`
- 後続のファイルはこのディレクトリの中に作成します。

### 2. 機能仕様定義フェーズ

- **spec.md**ファイルを作成します。
- ユーザーに対してspec.mdファイルの場所を伝え、**中身は空の状態**から機能仕様を記入してもらいます。
- ユーザーがspec.mdの記入を完了したら次のフェーズに進みます。

### 3. 実装計画フェーズ

- spec.mdに記載されている機能仕様を満たす**実装計画を複数ファイルに分割**して作成します。
- 関連するファイルを特定するためにGrepやGlobツールを使用します。
- 以下のファイル構成で実装計画を作成します：

#### `00-overview.md` - 全体概要
```markdown
# [タイトル]の実装計画 - 全体概要

## 現状分析
### [機能名]の現在の実装
- 現在の実装状況の詳細

### [関連機能]との関連
- 関連する機能やシステムとの繋がり

## 実装計画の全体像
1. [大きなステップ1] - `01-[step-name].md`
2. [大きなステップ2] - `02-[step-name].md`
3. [大きなステップ3] - `03-[step-name].md`

## 全体的な注意点
- 重要な制約事項
- 全体に関わる考慮事項

## 影響範囲
- **[影響カテゴリ1]**: 影響の詳細
- **[影響カテゴリ2]**: 影響の詳細
```

#### `01-[step-name].md`, `02-[step-name].md`... - 各実装ステップ
```markdown
# [ステップ名]の実装

## 目的
[このステップの目的]

## 修正対象ファイル
- `ファイルパス1`
- `ファイルパス2`

## 修正内容
[具体的な修正内容やコード例]

## 実装手順
1. [具体的な手順1]
2. [具体的な手順2]

## 注意点
- このステップ固有の注意事項

## 検証方法
- 実装後の確認方法
```

- ユーザーに対して分割された実装計画ファイル群を提示し、問題がないかを確認します。
- ユーザーが問題ないと答えるまで実装計画ファイルの修正を繰り返します。

## 出力要件

- 各フェーズのファイルは`.claude/tasks/[task-name]/`内に保存
- ファイルパスは絶対パスで記載
- 既存のコードパターンや命名規則に従った提案
- 影響範囲を最小限に抑える方法を優先

成果物イメージ

.claude/tasks/user-profile-update-api/
├── spec.md                   # 機能仕様（ユーザーが記入）
├── 00-overview.md            # 全体概要と影響範囲
├── 01-db-schema-update.md    # データベーススキーマ変更
├── 02-model-definition.md    # モデル定義とバリデーション
├── 03-business-logic.md      # ビジネスロジック実装
└── 04-test-cases.md          # テストケース作成

このコマンドで作成したファイルを元に、その機能の見積もりを行ったり、メンバーにタスクとして割り振ったりしています。
分解の粒度はメンバーのスキルレベルに応じて調整しています。

タスク管理はNotionで行っているのですが、そこに記載する際はコピペしてるのが微妙な箇所で、もう少し自動化したいと思っています。

コーディング

git worktreeを使った並列開発

コーディングフェーズでは、基本的にgit worktreeを使って2つのClaude Codeを並列で動かしています。

具体的には下記のような流れで進めています。

1. Claude Code Aに指示
2. Claude Code Aの実行中にClaude Code Bに指示
3. Claude Code Bへの指示中にClaude Code Aの実装が完了
4. Claude Code Aの実装内容を確認して、必要に応じて修正を依頼
5. Claude Code Aの修正依頼中にClaude Code Bの実装が完了
6. Claude Code Bの実装内容を確認して、必要に応じて修正を依頼
7. ...

ただし、かなりコンテキストスイッチが発生するため、相当の集中力を使います。
人によっては、1つのタスクに集中して取り組む方が効率的な場合もあると思うので、個人のスタイルに合わせるのが良いと思います。
自分もシンプルなタスクの場合には並列で実装し、複雑で難しいものについては1セッションに集中して取り組むようにしています。

また、並行で進める場合は目を離している時間が長いので、実装のスコープを大きくすると変な方向に進んだ場合に軌道修正が遅れてしまいます。
そのため、指示内容のスコープは小さくなるように心がけています。

バックエンドの実装

バックエンドの実装では、処理の実装→テストの順番で進めていて、テストが通るまで修正するように指示しています。
本当はテスト→処理の実装の順番（TDD）の方が実装の精度が上がりそうと思いつつ、テスト対象がない状態からテストコードを生成する指示が難しいと感じているため、この順番で実装しています。
実装の指示をする際も、できるだけスコープを小さくしながら刻んで指示をしているので、実装の精度にあまり不満は感じていません。

また、実装もテストも最初は必ずPlanモードを使って進めています。
Planモードの出力をしっかりとレビューし固めた上で実装することで、多少目を離していても大きく方向を外れることが少なくなります。
テストコードを書く際は、Planモードでテストケースの列挙を行い網羅性を高めるようにしています。

フロントエンド開発

フロントエンドの実装では、Figma MCPを使ってUI生成を行っています。
初めてFigma MCPを使った際は、期待していたコードがほぼ一発で生成されてかなり感動しました。
これからのフロントエンド開発には必須のツールだと感じています。

https://help.figma.com/hc/ja/articles/32132100833559-Dev-Mode-MCPサーバー利用ガイド

下記は公式に載っているルールの例なのですが、デザイントークンを優先して使用するように指示するだけでも、精度がかなり向上します。

- 重要: `/path_to_your_design_system`のコンポーネントを可能な限り毎回使用してください。
- デザインを正確に一致させるために、Figmaの忠実度を優先してください。
- ハードコードされた値を避け、Figmaのデザイントークンが利用可能な場合はそれを使用してください。
- アクセシビリティに関するWCAG要件に従ってください。
- コンポーネントのドキュメントを追加してください。
- UIコンポーネントを`/path_to_your_design_system`に配置し、本当に必要な場合を除き、インラインスタイルは使用しないでください。

より一層デザインシステムの重要性が増してきており、デザインシステムが整備されている状態であれば、体感ですがUI実装の8割くらいの工数が削減されています。

PR作成・動作確認

PR作成・動作確認も、カスタムスラッシュコマンドを作成してClaude Codeに実行してもらっています。
コマンドの詳細については下記の記事で紹介しています。

https://zenn.dev/drsprime/articles/a84672659f8497

ローカルでサーバーを複数起動すると管理が面倒なのと、最終的にstaging環境で動作確認を行うため、ローカルのテストが通ったタイミングでstagingにデプロイして確認しています。
カスタムスラッシュコマンドを実行して、staging環境のAPIに対してリクエストを送って動作確認を行っています。

フロントエンドはバックエンドと違い、テストだけで挙動の担保ができる状況ではないため、ローカルでサーバーを起動して自分で動作確認を行っています。
この辺りに関しても、もっと自動化したいです。

まとめ

Claude Codeを導入して開発フローを変化させていくにつれて、手を動かすことが圧倒的に減りました。
その分、思考することにフォーカスできるようになったのが最も大きな変化だと感じています。
手を動かすことは減りましたが、その分どう活用するかやチームに定着させるかなど、考えることも多く、この変化をとても楽しめています！

また、tblsやMermaidなど、人間には図として直感的に理解しやすく、エージェントにはテキストファイルとして処理しやすい、2wayで使えるデータの価値が上がったと感じています。

実際に生産性も上がっていて、Claude Codeを使い始める前後1ヶ月のPR数を比較すると、64PR -> 97PRと約1.5倍に増加しました。
同期間に自分がレビューしているPR数も増加しているので、作業時間あたりのPR作成数はもっと増えていそうです。
ただ、2並列で進めているものの、片方の実装に張り付いている場合があったり、コンテキストスイッチが発生したりしているので、単純に2倍にはならなかったです。

直近ではPR作成数の増加により、CIの待機時間がボトルネックになり始めたので、その辺りの改善を進めています。
現時点では1.5倍の向上に留まっていますが、この調子でボトルネックを改善しつつ、活用の幅を広げていけば、2倍以上の生産性向上も可能という確信を持っています。

その先では、人間の思考スピードや言語化能力がボトルネックになると考えています。
今後はそこも見据えながら、思考や言語化を補助・拡張できるような生成AIの使い方や、よりアウトカムを最大化する仕組みを考えていきたいです。

コーディングエージェント登場により、開発スタイルがかなり変化しました。
みなさんもぜひ開発のあらゆるフェーズにおいて、Claude Codeの活用を試してみてください！