対象読者
- Claude Codeの導入を検討しているエンジニア
- AIを開発に取り入れたいと考えている方
結論
Claude Codeは、以下の用途において特に高い有用性を発揮しました
- ひな形生成 (Docker / UI)
- コードの修正
- READMEや仕様書の更新
- CI構築 (継続的インテグレーション)
- 開発環境のDockerfileと同じ作りで作成してくれる
一方で、以下の点には注意が必要と考えられます
- ビジネスロジックが肥大化する
- 適切なタイミングで分割指示を出す必要がある
- 指示があいまいだと破綻しやすい
- 変更箇所などを指定したりしないとコスト(トークン消費)が大きくなる
そのため、完全に任せるツールではなく、ベース作成や既存環境の改善に適したツールだと感じました
小規模かつそこまで複雑ではないプロジェクトを想定で検証しましたので、規模や複雑度によっては違った強みが出るかもしれません
また、今回は限定的な期間かつ低予算での検証でしたので許容できるコストによっても変わる可能性もあります
目次
- 1. はじめに
- 2. Claude Codeの概要
- 3. Claude Codeを使う注意点
- 4. 準備
- 5. compose.yml作成 (データベース作成含む)
- 6. バックエンド - 実装
- 7. フロントエンド - 実装
- 8. バックエンド - ユニットテスト
- 9. フロントエンド - ユニットテスト
- 10. E2Eテスト
- 11. CI (継続的インテグレーション)
- 12. CD (継続的デプロイメント)
- 13. まとめ
- 14. 参考
1. はじめに
背景
昨今のAI需要の高まりを受け、社内でもAI活用を推進する方針が決定されました
その一環として、AIエージェントツールであるClaude Codeの調査および検証を行うことになりました
目的
Claude Codeを使い実装からデプロイまでの開発プロセスを通して、Claude Codeの強みと弱みを明らかにすることを目的としました
2. Claude Codeの概要
Claude Codeは、Anthropic社が提供する開発特化型のAIエージェントです
単なるコード生成だけでなく、プロジェクトの理解、ファイルの編集、テストの実行、修正ループの実施までを自律的に行います
3. Claude Codeを使う注意点
信じすぎない
AIであるため、意図通りにコード生成やコマンド実行が行われるとは限りません
権限を与えすぎない
公開してはいけないものを公開したり、削除してはいけないものを削除する恐れがあります
丸投げしない
漠然とした命令では求めているものを作ったり実行したりしてくれません
やりたいことをしっかり言語化・整理してからの利用を推奨します
Claude Codeと対話しながらまとめるのもお勧め
4. 準備
環境
今回はWSL2環境でホスト環境に影響が出にくいように構築しました
実行ユーザー
rootユーザーを避け一般ユーザーで運用することで、AIがアクセスできる範囲を制限しました
CLAUDE.mdの作成
Claude Codeに遵守してほしいルールを事前に決めておきます
私は下記を記載しました (主要なものだけ掲載)
- 技術スタック
| 対象 | 技術 | コンテナ |
|---|---|---|
| フロントエンド | React + MUI + TypeScript | Node 20 |
| バックエンド | NestJS + Prisma | Node 20 |
| データベース | PostgreSQL | PostgreSQL 15 |
- ルール
| 対象 | ルール |
|---|---|
| フロントエンド | MUIを使用 |
| バックエンド | controller / service / repositoryの形式で作成 |
| Prisma | PrismaをプライマリORMとして使用 |
| APIデザイン | RESTful APIデザインを使用 |
| 開発 | 環境が完全に設定されているとは想定しない エラーが発生した場合は、修正する前に根本原因を説明 |
- データフロー
フロントエンド → バックエンド API → サービス → リポジトリ → データベース → レスポンス
細かく設定を記述することでより制御することができますが、その分トークンを使用するので注意が必要です
CLAUDE.md記載例
記載例
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
A search application with a three-tier structure:
- `frontend/` — UI layer
- `backend/` — Server-side logic and API
- `database/` — Database schemas and migrations
## Tech Stack
### Frontend
- React
- TypeScript
- MUI (Material UI)
### Backend
- NestJS
- TypeScript
- Prisma
### Database
- PostgreSQL
### Container
- Docker
- docker-compose
## Git Workflow Rules
- Always create a new branch before starting any work
- Never commit directly to main or master branch
- Use descriptive branch names (e.g., feature/search-api, fix/pagination-bug)
- Each task should be done in its own branch
## Container Rules
- All services must run in Docker containers
- Use docker-compose for local development
- Backend, frontend, and database must be separated into containers
## Docker Rules
- Use Docker for all services
- Development mode should support hot reload
- Production optimization is not required at initial stage
## Frontend Rules
- Use MUI components for UI consistency
- Avoid custom styling unless necessary
- Focus on usability over design
## Backend Rules
- Do not put business logic in controllers
- Controllers should only handle request/response
- Services must contain business logic
- Repositories handle database access only
## Prisma Rules
- Use Prisma as the primary ORM
- Allow raw SQL when necessary for performance
- Keep queries simple and readable
## API Design Rules
- Use RESTful API design
- All endpoints must support pagination when returning lists
- Support filtering and sorting for list endpoints
- Use consistent naming conventions (e.g., /items, /users)
## AI Development Rules (for Claude Code)
- Do NOT assume the environment is perfectly set up
- Always verify dependencies and versions
- Prefer minimal working code over completeness
- When errors occur, explain root cause before fixing
- Do not introduce unnecessary abstractions
## Architecture Strategy
- Start as a modular monolith
- Design services to be separable in the future
- Avoid tight coupling between modules
## Architecture
The intended architecture is a separated frontend/backend with a dedicated database layer. As the project evolves, update this file with:
- Chosen frameworks (e.g., React, Express, PostgreSQL)
- How to run build, lint, and test commands
- How data flows between layers
- Any environment variable setup (`.env` is gitignored; `dist/` is excluded from version control)
## Backend Architecture
- Use layered architecture (Controller / Service / Repository)
- Use DTO for request/response validation
- Use ORM or Query Builder for database access
## Container Architecture
- Use docker-compose for local development
- Frontend runs on port 3000
- Backend runs on port 4000
- PostgreSQL runs on port 5432
- Services communicate via service name
## API Response Format
- All responses must follow this structure:
{
"data": any,
"meta": {
"total": number,
"page": number,
"limit": number
},
"error": string | null
}
## Data Flow
Frontend → Backend API → Service → Repository → Database → Response
## Search Specification
- The `search` parameter performs a broad OR search across multiple fields (name, description)
- Additional filters (name, description, createdAt) are applied using AND conditions
- This allows users to first retrieve a wide result set and then narrow it down
開発指示について
全体を一気に作るのではなく下記の順番で作成を指示していきました
- compose.yml作成 (データベース作成含む)
- バックエンド - 実装
- フロントエンド - 実装
- バックエンド - ユニットテスト
- フロントエンド - ユニットテスト
- E2Eテスト
- CI (継続的インテグレーション)
- CD (継続的デプロイメント)
5. compose.yml作成 (データベース作成含む)
開発環境を用意するためにCLAUDE.mdに沿ってDockerを用いて作成を指示しました
特筆することはなく問題なくCLAUDE.mdに記載した通り作成してくれました
強み
構成がパターン化されている領域は人間よりも早く生成できます
弱み
ポートフォワーディングやボリュームなどの環境毎に変えたいところはしっかりと指示する必要がありますが、どこまで細かく指示するか手動で修正したほうが早いかを切り分ける必要があります
6. バックエンド - 実装
バックエンドの作成に関してCLAUDE.mdにある程度実装方針を記載していたので大きく違うものが実装されるようなことはありませんでした
強み
いきなり完成形を作ってもらうより大枠を作ってもらってから、細かく指示することで整っていきました
弱み
方針を与えてもビジネスロジックをサービスに書き続けるので、自分が読みにくいなと思った時に指摘し分離してもらうようにするとよさそうです
失敗点
Claude Codeは制約が、ある方が初期実装の精度は高くなると考えられます
NestJSのように構造や書き方が統一されている為、生成されるコードのブレが少なく感じました
ただ、サービス層にロジックが集中など設計が崩れることはありました
今回の調査としてはコードのブレも知りたかったので制約が少ないExpressで検証すべきだったと思いました
7. フロントエンド - 実装
フロントエンドは細かい実装方法を与えないで見た目を重視しました
画面の見た目なので文字よりも簡単な絵を作って絵の通りにデザインを作ってくださいと指示しました
実際に見たり操作を行い、変更したい部分は指示を出して修正しました
強み
ラベルやボタンの配置は絵で指示し、修正や追加してもらいたい場合はざっくり作ってもらったコードから特定箇所だけを指摘するだけで直してくれます
弱み
バックエンドと連携する必要があるため、トークンが増えがちです
バックエンドの設計をしっかり固めるか、使われるバックエンドのファイルおよびコード箇所を指定してあげるかのどちらかをするとコストが下げられそうです
8. バックエンド - ユニットテスト
今回開発の工程を一通り行った中で一番指示しないと正しく動かない箇所でした
実装によってテスト内容が変わってくるので、問題があるたびに指摘し修正してもらっていきました
強み
ある程度のテストケースを素早く生成してくれます
弱み
網羅的なテストは適切に指示しないと実装されませんでした
また、テストが通ればよいと判断されテストデータは作りっぱなしで、不要なテストデータがたまり続ける構造になっていました
どのようなテストを行うか、継続的に利用できるかも考慮して指示する必要があります
9. フロントエンド - ユニットテスト
今回フロントエンドに関しては簡素な作りでしたのでバックエンドほど問題は起きませんでしたが、同様に実装によってテスト内容が変わっていくので、問題があるたびに指摘し修正してもらっていきました
強み
バックエンド同様にある程度のテストケースを素早く生成してくれます
弱み
バックエンド同様に網羅的なテストは適切に指示しないと実装されませんでした
10. E2Eテスト
Playwrightでの作成を指示したところバージョンの問題はありましたが、それ以外は問題なく作成されました
強み
フロントエンドやバックエンドでのテストを読み込めば、Claude Codeの方である程度考えてE2Eテストも作成してくれます
弱み
最初に作成されたものはバージョンが低く動かなかったのと存在しないバージョンに修正されたので、比較的新しい問題には弱いと感じました
11. CI (継続的インテグレーション)
今回はGitHub Actionsを使用しmainへのプルリクエスト時とmainへのプッシュ時に自動テストされることとPrismaを使っている関係上、データベースが必要である点を注意事項として指示するだけで大きな問題なく作成されました
強み
Dockerfileとcompose.ymlを参照して同じ構成で作成されるのでかなり安定して作成される傾向があります
弱み
今回の検証では大きな課題は見られませんでした
12. CD (継続的デプロイメント)
CIのE2Eが正常だった場合にGitHub Secretsを使用して公開サーバーへデプロイできるように指示しました
今回はかなり簡単なgit pullしてdocker compose up -d --buildするだけのデプロイ方式にしたので問題は起きませんでした
強み
一般的なデプロイ方式なら問題なく素早く作成できそうです
弱み
CDに関しても今回の検証では大きな課題は見られませんでした
13. まとめ
Claude Codeを開発プロセス全体で利用した結果、以下の点が明確になりました
- ひな形生成
- コードの修正
- READMEや仕様書の更新
- CI構築 (継続的インテグレーション)
といったパターン化された作業や仕様が決まっている作業においては強力であり、開発速度を大きく向上させました
一方で、以下の課題もありました
- ビジネスロジックが肥大化
- 指示があいまいだと破綻しやすい
といった指示がない箇所についてはいい感じにはしてくれないので適切に主導して指示する必要があります
これらを踏まえるとClaude Codeは完全にお任せツールではなくベース作成や軌道に乗った環境での改善に最適なツールだと考えられます
- 新規開発の立ち上げ
- 既存コードの改善
- 要件が多く変わりコードから設計書のリバース作業が頻繁に発生する場合
といった場面では高い効果を発揮するのではないかと考えています
最後に
使う場面を考えていかないとクレジットがすぐなくなってしまうので、利用量課金の場合は利用頻度や用途を見極めて活用することが重要です