🤖

Claude Codeを使った開発ワークフローの試行錯誤：個人的な体験談

2025/07/22に公開

 はじめにAI支援開発ツールの進化により、ソフトウェア開発の在り方が変わってきています。本記事では、Claude Codeを使った開発ワークフローを試行錯誤してきた中で、個人的に効果を感じられた方法をご紹介します。

 本記事の内容Claude Codeを使った開発プロセスの工夫
計画と実装を分ける際に気をつけていること
音声入力やMCP連携で楽をする方法
実際に使っているコマンド設定
個人的に感じている課題や改善点

 こんな方に読んでもらえたらAI支援開発ツールが気になってる開発者の方
開発をもう少し楽にしたいと思っているエンジニアの方
Claude Codeを使ってみたいけど、どう使えばいいか悩んでいる方
バックエンド中心のプロジェクトでの体験談ですが、フロントエンドの方にも参考になる部分があるかもしれません。

 開発環境とツール構成
 必要なツール

ツール
役割
必須度


Linear
タスク管理・要件定義
必須

Claude Code
AI支援による計画・実装
必須

Cursor
IDE（任意のIDEで代替可能）
推奨

GitHub
コード管理・レビュー
必須


 効率化のための補助ツール
 音声入力の活用長文の要件記述や複雑なフィードバックを効率的に行うため、音声入力を積極的に活用しています。
活用場面：
Linearチケットの概要記述
Claude Codeへの詳細なフィードバック
複雑な業務要件の説明
詳細な音声入力の設定方法については、以下の記事で解説しています：

https://zenn.dev/yutafujii/articles/41c137eca83177

 MCP（Model Context Protocol）連携LinearとClaude CodeをMCPで連携させることで、チケット情報の直接参照が可能になります。
# Linear MCP連携の設定
claude mcp add --transport sse linear https://mcp.linear.app/sse

# Claude起動
claude

# 初回認証（初回のみ）
$ /mcp

 開発ワークフローの全体像
 フローの概要
 開発サイクルの詳細ステップ
 1. Human｜Linearのチケットに概要を記述目的： Claude Codeが理解しやすい形で要件を整理
記述の指針：

「新入社員が1ヶ月後に理解できる内容」を基準として、以下の項目を記載します：

 必須項目（重要度順）## API実装の場合

### エンドポイント仕様
- **Method & Path:** `POST /api/v1/users`
- **Request Body:** JSON schema
- **Response Body:** JSON schema + エラーパターン
- **Query Parameters:** 必要に応じて

### 関連ファイル
- **Working Directory:** 作業メインとなるディレクトリ
- **Reference Files:** 参考になる類似実装

### 処理フロー
- **概要:** 何をする機能か（1-2行）
- **シーケンス:** 内部処理の流れ（mermaidで簡潔に）

### 補足事項
- **Important Notes:** 注意すべき制約や要件
- **Business Logic:** 複雑なビジネスロジックがある場合
## DB変更の場合

### DDL概要
- **対象テーブル:** テーブル名と変更内容
- **目的:** なぜこの変更が必要か
- **データ投入条件:** どんな時に値が入るか
- **既存データ:** マイグレーション方針

 実装複雑度による記述レベル調整

複雑度
記述レベル
記載項目


Simple CRUD
軽量
エンドポイント + 関連ファイル

Business Logic含む
標準
上記 + 処理フロー

複雑な処理
詳細
全項目 + mermaidシーケンス


 2. Claude Code｜計画策定計画専用のカスタムコマンドを実行し、ラフな要件を詳細設計に発展させます。

 計画コマンドの設定計画コマンド設定（クリックして表示）You are an experienced software architect. You read a Linear ticket and then plan the required development in this repository.
The goal is to make it easy for the actual developer (or worker AI Agent) to produce the code output with the consistent quality.

### What to do
1. **READ**: given ticket. You MUST ask human when you cannot read the entire description. Do not code without fully understanding the task.
2. **Think** Carefully
3. **Discuss** with human interactively. Don't hesitate to ask clarifying questions or hear human's thought.
4. **Plan** the development detail and summarize it in the ticket with the {{Recommended format}}.
5. **Ask** human for review
6. **Iterate** step 2 to 5 until human provides a green light

### NOTE
- You MUST NOT make any code change
- The ticket is most likely missing some context, or requirements. Thus, don't assume between the line, but ask human to fill missing pieces

### Recommended format
- A good ticket usually contains the following items:
  - API endpoint, or topic name for event consumer
  - I/F of API or event payload
  - response schema, including sub normal cases
  - Sequence diagram that focuses on internal flow (business logic, responsibility of each layer)
  - relevant files or directories
    - that the worker may work on, or that is worth referring
    - the more the better

**Example**
"""
## user-service

#### Endpoint

GET: /api/v1/users/[userId]
PUT: /api/v1/users/[userId]/profile
POST: /api/v1/users/[userId]/avatar
DELETE: /api/v1/users/[userId]/account

query parameter

include: string[] (nullable, fields to include: "profile", "settings", "preferences")

#### Response

Success (200):
\`\`\`json
{
  "id": "string",
  "email": "string",
  "profile": {
    "name": "string",
    "avatar_url": "string"
  },
  "created_at": "datetime"
}
\`\`\`

Error (404): User not found
Error (403): Access denied

#### internal sequence
\`\`\`mermaid
sequenceDiagram
  autoNumber
  participant caller
  participant c as controller
  participant s as service-layer
 
  caller->>c: POST: /api/v1/users
  c->>s: validate and execute
  s->>s: check any duplicate
  s->>s: generate random avatar
  s->>s: save to database
  s->>s: trigger notification
  c-->>caller: 200
\`\`\`

#### relevant files
- src/controllers/api/v1/users/[userId]/route.ts
- src/services/user/user.service.ts
- src/services/user/queries/get-user-by-id.ts (reference)
- src/models/user.model.ts (reference)

"""

 実行例claude

$ /plan https://linear.app/.../issue/ABC-213
重要： Claude Codeが実装まで進もうとする場合は明確に「No. LinearのDescriptionにまとめて」と指示し、計画のみに集中させます。

 3. Human｜計画レビューとフィードバック策定された計画を以下の観点でレビューします：

 レビューポイント

観点
チェック項目


完全性
必要な機能が全て含まれているか

妥当性
技術選択や実装方針は適切か

効率性
無駄な処理や過剰な実装はないか

保守性
将来的なメンテナンスを考慮しているか

音声入力を活用し、効率的にフィードバックを提供します。

 4. Claude Code｜実装計画が承認されたら、実装専用コマンドで開発を開始します。

 実装コマンドの設定You are an experienced individual contributor. You read a Linear ticket and then work on the required development in this repository.

### What to do
1. **READ**: given ticket. You MUST ask human when you cannot read the entire description. Do not code without fully understanding the task.
2. **Plan** Carefully
3. **Develop**, checkout branch from main (unless instructed) with a format `<ticket-id>/xxx` e.g. `ABC-123/api`
4. **Self Review** assuming as if you're a principal engineer, review your code changes and do some refactoring. You may not need to over refactoring unless asked.

### NOTE
- You MUST NOT make a commit and create a pull request unless instructed. Usually human reviews your code changes locally

 実行と注意点claude

$ /work https://linear.app/.../issue/ABC-213
重要： 計画セッションと実装セッションは必ず分離します（/exitで一度終了するか/clearでコンテキストをクリア）。計画時のコンテキストが残ると実装品質が低下する傾向があります。

 5. Human｜コードレビューとフィードバック実装されたコードを手元のIDEでレビューし、構造化されたフィードバックを提供します。

 実践的なレビューアプローチメンテナビリティを多少犠牲にしても動けばいいなら9割くらいの確率でこのままマージできる
品質の低いコードは嫌なので一旦手元のIDEで自分でレビューを行い，CLI上にフィードバックを書く
1つ2つならそのまま音声入力して文字にする．3つ以上あるような時は，まとめて箇条書きで返す
面倒だけど，ファイル名を入れてあげる．Cursorならcommand + option + shift + C でファイルパスがコピーできる

 フィードバック形式Feedback:
- [must] src/services/user.service.ts: エラーハンドリングでnullチェックが漏れています
- [should] src/controllers/user.controller.ts: バリデーション処理をサービス層に移動してください  
- [nit] src/types/user.types.ts: 型定義でoptionalプロパティの記述が不明確です
レベル分類：

[must]: 必須の修正（バグ、セキュリティ問題等）

[should]: 推奨修正（設計改善、保守性向上等）

[nit]: 軽微な改善（コードスタイル、可読性等）

 6-13. プルリクエストからマージまで残りのステップ（PR作成、自動レビュー、対応、マージ）については、従来通りの流れで進行します。

 自動レビューシステムGitHub Actionsによる自動レビューの詳細設定については、以下の記事で詳しく解説しています：

https://zenn.dev/yutafujii/articles/45a3481b2b8e20

 今後やってみたいことと課題
 次に試してみたいこと
設計の自動化: 要件から設計図をもっと楽に作れないか

テストも一緒に: 実装と同時にテストコードも書いてもらえないか

ドキュメント更新: API仕様書の更新も自動化できないか

 まだうまくいってないこと設計段階でまだまだ人間の負荷が高い
複雑なビジネスロジックを説明するのに時間がかかる
新しい技術が出てくると追いつくのが大変

 おわりに何かの参考になれば嬉しいです。質問や「こんなやり方もあるよ」といったフィードバックがあれば、コメントでお聞かせください！

ツール	役割	必須度
Linear	タスク管理・要件定義	必須
Claude Code	AI支援による計画・実装	必須
Cursor	IDE（任意のIDEで代替可能）	推奨
GitHub	コード管理・レビュー	必須

複雑度	記述レベル	記載項目
Simple CRUD	軽量	エンドポイント + 関連ファイル
Business Logic含む	標準	上記 + 処理フロー
複雑な処理	詳細	全項目 + mermaidシーケンス

観点	チェック項目
完全性	必要な機能が全て含まれているか
妥当性	技術選択や実装方針は適切か
効率性	無駄な処理や過剰な実装はないか
保守性	将来的なメンテナンスを考慮しているか

はじめに

本記事の内容

こんな方に読んでもらえたら

開発環境とツール構成

必要なツール

効率化のための補助ツール

音声入力の活用

MCP（Model Context Protocol）連携

開発ワークフローの全体像

フローの概要

開発サイクルの詳細ステップ

1. Human｜Linearのチケットに概要を記述

必須項目（重要度順）

実装複雑度による記述レベル調整

2. Claude Code｜計画策定

計画コマンドの設定

実行例

3. Human｜計画レビューとフィードバック

レビューポイント

4. Claude Code｜実装

実装コマンドの設定

実行と注意点

5. Human｜コードレビューとフィードバック

実践的なレビューアプローチ

フィードバック形式

6-13. プルリクエストからマージまで

自動レビューシステム

今後やってみたいことと課題

次に試してみたいこと

まだうまくいってないこと

おわりに

Discussion