AI駆動開発実践者によるリアルな機能開発プロセスを丁寧に解説してみた

Posted at 2025-11-03

こんにちは、とまだです。

Claude Code で機能開発をする際、「どこから手をつければいいか分からない」「途中で仕様がブレて手戻りが発生する」といった悩みはありませんか?

私が運営するコミュニティサイトに新機能を追加する際、要件定義から実装、レビューまでを一貫したフローで進める方法を実践してみました。

今回は、cc-sdd(仕様駆動開発ツール)とMCPを組み合わせた開発プロセスを、実際の試行錯誤も含めてお伝えします！

「使い方を伝える」よりも今回は「どうやって実践したか」を伝えることを目指しています！！

ちなみに私は本業ではフリーランスエンジニア、ならびにAI駆動開発の導入支援を行っています。
また、Udemy で AI 駆動開発講座を複数開講しており、いくつかベストセラーもいただいています。

その経験を活かして、初心者の方でもわかりやすいよう、丁寧に解説しています！

また、実際の様子はYoutube動画でも公開していますので、ぜひご覧ください！

忙しい人のために要約

この記事では、仕様駆動開発とMCPを活用した機能開発の実践例をご紹介します。

仕様駆動開発で要件定義→設計→実装の流れを体系的に進められる
Codexによる自動レビューで設計段階での問題を早期発見できる
MCPを使った自動動作確認で手動テストの負担を軽減できる
/smart-commit で関連する変更を自動的にグループ化してコミット可能

ここから、実際にどのように進めたかを詳しく見ていきます。

まずは、今回作成した機能の背景と実装アプローチから説明します。

作成した機能

Claude Code のカスタムコマンドを公開するページを実装しました。
出来立てほやほやなので、まだ公開しているものは少ないことはご容赦くださいませ。

このセクションでは、なぜこの機能が必要だったのか、どのようなアプローチで実装したのかを説明します。

背景にあった課題

Claude Code にはカスタムコマンドを共有できるプラグイン機能があります。しかし、X(旧Twitter)などで見かけたコマンドを確認・利用するには、プラグイン導入のハードルが高いという問題がありました。

解決策として選んだアプローチ

そこで、自サイトにマークダウン形式でカスタムコマンドを整理し、ユーザーが気軽にコピペできるページを用意することにしました。

データベースは使わず、リポジトリ内のマークダウンファイルを直接読み込む方式を採用しています。これにより、メンテナンスが容易になります。

また、フロントマター(説明、使用可能なツール、引数など)も含めて表示することで、ユーザーは完全な形式でコピーできます。

実際に作成したページはこちらです。
https://www.vibecodingstudio.dev/claude-code/commands

機能の概要が分かったところで、次は開発全体の流れを見ていきましょう。

開発の全体像

今回の開発は、以下のような7つのフェーズで進めました。

ブランチ作成とcc-sdd の準備
要件定義フェーズ
設計フェーズとCodexレビュー
実装計画(TDD形式)
実装とコミット
MCPによる自動動作確認
PR作成と自動レビュー

それぞれのフェーズで何を考え、どう進めたかを順に説明していきます。

では、最初のフェーズである仕様駆動開発の準備から見ていきましょう。

仕様駆動開発による実装プロセス

ここでは、要件定義から実装計画までのプロセスを詳しく解説します。仕様駆動開発を使うことで、各フェーズでの試行錯誤を効果的に進められました。

ブランチ作成とcc-sddの準備

まず、feature/publish-custom-commands という名前でブランチを作成しました。実装内容が明確に分かるよう、機能名をそのまま含めています。

比較的大きな機能開発では、cc-sdd(仕様駆動開発ツール)を使っています。

要件定義→設計→計画→実装→品質チェックという流れを体系的に進められるため、特に要件や設計段階でAIと対話しながら仕様を固められる点が有効です。

要件定義での試行錯誤

まず以下のようなコマンドで初期化しました。

/kiro:spec-init カスタムコマンド公開機能を構築

これにより .kiro/specs/custom-commands-publish/ フォルダが自動作成されます。その後、プロジェクト説明が CLAUDE.md に記録されます。

次に要件定義を進めます。

/kiro:spec-init xxxx で初期化された内容はまだ浅いので、ドラフトとして作成された requirements.md に詳細を追記してから、以下のコマンドで要件定義を進めます。
（詳細は Youtube動画をご覧ください）

/kiro:spec-requirements custom-commands-publish

AIとの対話を通じて、以下の要件が整理されました。

/claude-code/commands で一覧ページを表示
各コマンドにはタイトル・説明・タグを表示
詳細ページではマークダウン全体をコードブロック形式で表示
フロントマターもそのまま含めてコピー可能にする

要件定義の段階で、AIが「フロントマターをメタデータとして解釈して表示」と記述していることに気づきました。実際にはフロントマターをコードブロック内にそのまま含めて表示したかったのです。そのため、この時点で修正指示を出しました。実装前にこうした問題が見つかるのが、仕様駆動開発の利点です。

当初はタグによる検索・分類機能も含める予定でしたが、複雑さが増し規模が大きくなりすぎると判断し、初版では削除しました。
後続チケットとして別管理することで、MVP(最小限の機能)に絞り込んでいます。

実際のカスタムコマンド(convert-video.md)をサンプルとして提示することで、AIが正確にイメージを理解できるようにしました。

Youtube動画版でもお見せしていますが、この要件定義フェーズではしっかりと確認し、何往復かしています。
ここで方向性をミスすると、後の手戻りが大きいからです。

要件定義が固まったら、次は設計フェーズに進みます。

設計フェーズとCodexレビュー

要件定義が完了したら、次は設計書を作成します。ここでは、Codexによる自動レビューも活用して、設計の質を高めました。

設計書の自動生成

以下のコマンドで設計書を生成しました。

/kiro:spec-design custom-commands-publish -y

生成された設計には、データ構造、ページレイアウト、ローディング状態、エラーハンドリング、SEO対応、アクセシビリティなどが含まれています。

特に詳細ページでは、ファイル名からタイトルケースへ自動変換する仕組みになっていました。また、フロントマターの情報を補足メタデータとして別表示する設計になっていました。

Codexによる自動審査

設計書が完成した時点で、Codexを使って自動レビューを実施しました。

@design.md について要件定義に対する設計の正確性とシンプルさをレビューしてください。

設計などコーディング観点での高度な視点が欲しいときは、Codex CLI をよく使っています。

Codexからは以下のフィードバックが返ってきました。

詳細ページのタイトルはファイル名から常に生成する
フロントマターのタイトルは補足メタデータとして別表示する
スケルトン表示の実装詳細を精緻化する

このフィードバックに基づき、設計を修正しました。

要件定義と設計がブレていると、後の修正・手戻りが非常に大変になります。
そのため、最初は大変かもしれませんが、要件定義をしっかり確認することをお勧めします。

設計が固まったら、次は実装計画を立てます。

実装計画とTDD形式の採用

設計が完了したら、具体的な実装計画を立てます。ここでは、TDD(テスト駆動開発)形式を採用することにしました。

以下のコマンドで実装計画を生成しました。

/kiro:spec-tasks custom-commands-publish -y

生成されたタスクには、プロジェクト基盤準備、データレイヤー実装、UIコンポーネント実装、ページルート実装などが含まれています。

当初は上から順に実装する計画でしたが、マークダウン読み込みなど複雑な処理があるため、TDD(テスト駆動開発)形式に変更しました。

具体的には、以下の流れで進めます。

テストを先に書く
テストがパスするように実装
リファクタリング

実装前にテストが明確な目標として機能し、手戻りを最小化できます。

タグによる検索・分類機能、国際化対応、パフォーマンス監視の自動化などは、初版の複雑さを軽減するため後回しにしました。これらは後でチケット化して対応します。

実装計画が整ったところで、いよいよ実装に入ります。
実装自体は計画に沿っていくだけですので、あらかじめ決められたフェーズごとに進めていくだけです。
言い換えると、ここは特に工夫の余地はありません。

大規模な新機能であればこのタイミングでコミット前のレビューを入れることもありますが、今回はそもそも小規模となるように工夫して切り出しているので、一括のレビューで問題ないレベル感です。
この準備も大事だと思っています。

さて、ここからは、実装、動作確認、PRレビューまでの品質チェックの流れを見ていきます。この段階では、様々なツールを活用して効率化を図りました。

実装から品質チェックまで

各段階で工夫したポイントや、活用したツールをご紹介します。

段階的な実装とコミット戦略

各タスクごとにテストを作成し、テストがパスするまで実装し、コミットという流れを繰り返しました。

/smart-commit というオリジナルのカスタムコマンドを使い、関連性のある変更を自動的にまとめてコミットしています。

私が普段使っているものであり、こちらもコミュニティサイト内で公開しています。
（Claude Code 向けですが、フロントマターを削れば Cursor や Codex でも使えます）

まず、このコマンドは未コミットの変更内容を解析します。次に、グループ化して各グループごとに自動的にコミットします。そのため、手動でコミット内容を考える必要がなく、開発の生産性が向上します。

実装が完了したら、以下のコマンドで品質チェックを実施しました。

npm run check:all

このコマンドは、ESLintによるコード品質チェック、TypeScript型チェック、すべてのユニットテスト実行、ビルド確認を一括で行います。
自分で package.json に書いておいたものです。

なお、Prettier や ESLint がチェックする際には、エラーや Warning だけを出力 するようにしています。

デフォルトの設定だとチェックしたファイルの情報が多く出力されてしまい、AI が実行した際に無駄にコンテキストを圧迫してしまうからです。

実装が完了したら、次は動作確認です。

MCPを使った自動動作確認

実装が完了した時点で、MCPを使って自動動作確認を実施しました。

@.kiro/specs/custom-commands-publish の仕様に基づいて実装したので Chrome DevTools MCP で動作確認して

以下の項目を自動で確認しました。

一覧ページでサンプルが正しく表示されるか
詳細ページへのナビゲーションが機能するか
コピーボタンでフロントマターも含めて正確にコピーできるか
スケルトン表示が適切に機能するか
レスポンシブデザインがモバイル・タブレット・PCで対応しているか
アクセシビリティが適切に設定されているか

これである程度、要件はクリアしているという判断ができます。

その後、AIによる自動確認だけでなく、人間の目でブラウザ上での見た目も最終確認しました。また、フロントマターの表示形式、UIの使いやすさもチェックしました。

このあたりは AI では難しいので、人間の目で確認する必要があります。
ただし、MCP で既に基本機能は確認済みなので、本当に大事なところだけを確認すれば良いです。

そしてこの段階で、ページ間のリンク(例:フッターのカスタムコマンド一覧へのリンク)を実装する必要があることに気づき、追加で対応しました。

動作確認が完了したら、いよいよPR作成です。

GitHub PR作成と自動レビュー

動作確認が完了したら、PRを作成してレビューを実施します。ここでも自動化ツールを活用して効率化しました。

PR作成までの流れ

ブランチをリモートへプッシュすると、GitHubが自動的にPR作成ボタンを表示します。

PR概要は以下のコマンドで自動生成しました。

/pr-description 13

このコマンドは、GitHub CLIを使ってPRの内容を分析します。その後、変更内容を自動的に抽出してグループ化し、タイトルと概要をAIが作成します。

---
description: Create or update PR title and description for a given PR number
---

# PR Description Generator

指定されたPR番号に対して、タイトルと概要欄を作成または更新します。

## 使い方

```
/pr-description <pr-number>
```

例:
```
/pr-description 10
/pr-description 5
```

---

## 実行内容

PR番号: **$ARGUMENTS**

### 1. PR情報の収集

以下の情報を収集します:

```bash
# PR基本情報
gh pr view $ARGUMENTS --json title,body,headRefName,baseRefName,state

# 変更ファイルリスト
gh pr diff $ARGUMENTS --name-only

# コミット履歴
gh pr view $ARGUMENTS --json commits --jq '.commits[] | "\(.oid[0:7]) \(.messageHeadline)"'
```

### 2. 関連仕様書の確認

Kiro仕様書が存在する場合、以下を確認:

- `.kiro/specs/*/requirements.md` - 要件定義
- `.kiro/specs/*/design.md` - 技術設計
- `.kiro/specs/*/tasks.md` - タスク一覧と進捗

ブランチ名や変更内容から関連する仕様を特定します。

### 3. 変更内容の分析

以下の観点で変更を分析:

- **アーキテクチャ変更**: Domain, Application, Infrastructure, Presentationの各層への影響
- **機能追加**: 新規機能、画面、コンポーネント
- **リファクタリング**: 構造改善、コード整理
- **バグ修正**: 不具合修正、エラーハンドリング改善
- **ドキュメント**: README, ガイド、コメント
- **テスト**: 新規テスト、テスト改善
- **設定**: 依存関係、ビルド設定、環境変数

### 4. PR概要の構成

以下の構造でPR概要を作成:

```markdown
## 概要

[変更の要約を3-5行で記述]

## 背景・目的

### 現状の課題
[解決しようとしている問題]

### 目標
[このPRで達成したいこと]

## 主な変更内容

### 1. [カテゴリ1]
- [変更内容1]
- [変更内容2]

### 2. [カテゴリ2]
- [変更内容1]
- [変更内容2]

## テスト結果

### 品質ゲート
\`\`\`bash
npm run check:all
\`\`\`
- ✅/❌ ESLint
- ✅/❌ Prettier
- ✅/❌ TypeScript
- ✅/❌ Jest

### カバレッジ
[主要レイヤーのカバレッジ情報]

### 追加テスト
- [新規追加したテスト]

## 動作確認

[Expo MCP / RevenueCat MCPでの動作確認結果]

## 次のステップ

[このPR後の予定、残タスク]

## レビュー観点

### アーキテクチャ
- [ ] [確認ポイント1]
- [ ] [確認ポイント2]

### テスト
- [ ] [確認ポイント1]
- [ ] [確認ポイント2]

### ドキュメント
- [ ] [確認ポイント1]
- [ ] [確認ポイント2]

## 関連リンク

- [Kiro仕様書へのリンク]
- [関連Issue/PRへのリンク]
```

### 5. タイトルの生成

Conventional Commits形式でタイトルを生成:

**形式**: `<type>(<scope>): <subject>`

**タイプ**:
- `feat`: 新機能
- `fix`: バグ修正
- `refactor`: リファクタリング
- `docs`: ドキュメント
- `test`: テスト
- `chore`: ビルド、設定
- `perf`: パフォーマンス改善

**例**:
- `feat(subscription): 月額・年額サブスクリプション対応`
- `refactor(architecture): サブスク判定経路の一本化`
- `docs(guide): Clean Architecture + DDD ガイドライン整備`

### 6. PRの更新

生成した内容でPRを更新:

```bash
# タイトル更新
gh pr edit $ARGUMENTS --title "<new-title>"

# 概要更新
gh pr edit $ARGUMENTS --body "$(cat <<'EOF'
<new-body>
EOF
)"
```

## 成功基準

- ✅ PR概要が構造化されており、変更内容が明確
- ✅ タイトルがConventional Commits形式
- ✅ テスト結果が記載されている
- ✅ レビュー観点が明確
- ✅ 関連リンク（仕様書、Issue）が含まれている

## 注意事項

### Kiro仕様書との連携

- タスク番号（例: `Task 1.1`, `Phase 0-A`）を明記
- 要件ID（例: `Requirements: 13.1, 13.2`）を参照
- 完了基準との対応を示す

### マージ済みPRの場合

- マージ済みでも概要は更新可能
- 履歴として残すため、詳細な記録を推奨

### 大規模PRの場合

- セクションを折りたたみ可能にする（`<details>`タグ）
- 主要な変更のみハイライト
- 詳細は別ドキュメントへのリンク

## 実装方針

1. **情報収集フェーズ**: すべての関連情報を並列で取得
2. **分析フェーズ**: 変更内容をカテゴライズ
3. **生成フェーズ**: テンプレートに従って概要を作成
4. **検証フェーズ**: 品質チェック（文字数、必須項目）
5. **更新フェーズ**: ghコマンドでPRを更新

生成された概要には、仕様駆動開発による仕様書の整備、データレイヤー実装、UIコンポーネント実装などの情報が含まれます。また、ページルート実装、テスト結果、要件定義書に基づく動作確認内容も含まれています。

次は以下のコマンドでPRを自動レビューしました。
これは Claude Code の /review コマンドです。引数で PR 番号を指定すると、PR の全変更内容を分析してレビューしてくれます。

/review 6

このコマンドは、PRの全変更内容を分析します。その後、コード品質を複数観点でチェックします。また、改善提案を優先度付きで提示します。指摘事項として、タイトル生成ロジックの国際化対応やクリップボードAPIのフォールバック強化などがありました。

即座に直せない課題はGitHub Issueとして登録し、PRマージ前の必須修正と後続タスクを分離しました。関連Issueリンク付きで自動記載されるため、後々の対応が容易です。

問題がないことを最終確認し、Squash Mergeでメインブランチへ統合しました。コミット履歴が整理され、後々のリバート時に1コマンドで対応可能です。

PRがマージされたら、開発は完了です。次は、開発プロセス全体で意識したポイントを振り返ります。

開発プロセスで意識したポイント

ここまでの開発プロセスを通じて、特に重要だと感じたポイントをまとめます。これらは、他のプロジェクトでも応用できる考え方のはずです。

要件定義と設計での重点

要件定義と設計がブレていると、後の修正・手戻りが非常に大変になります。そのため、最初は大変かもしれませんが、要件定義をしっかり確認することをお勧めします。

スコープ管理の重要性

初版はMVP(最小限の機能)に絞り、必須要件のみを実装します。たとえば、検索・分類タグは除外し、後続タスクとして自動でIssue登録します。

優先度付けで後対応することで、完成を加速できます。

コンテキスト最適化

コンテキストが圧迫されている場合は、不要なMCPを一時無効化したり、ホームディレクトリの共通ルールファイルを活用したりします。また、段階ごとのセッションリセットを行うことも有効です。

スキルの切り出し(複雑な処理を別コマンド化)も有効です。

TDDの適用判断

複雑なロジックやテスト可能な機能にはTDDを適用します。一方で、不確実性が高い場合は実装先行でもよいでしょう。

まず動かしてから確認する方が効率的な場合もあります。

AIレビューの活用

要件定義段階では仕様の妥当性確認、設計段階では実装可能性・シンプルさの検証を行います。また、コード段階では複数観点からの自動チェックが有効です。

ただし、優先度が低い指摘が見落とされる可能性があります。また、規模が大きいと不完全になる可能性があることも認識しておく必要があります。

これらのポイントを意識することで、スムーズな開発が可能になります。

次は、実際に使用したツールを改めてご紹介します。

使用したツール

今回の開発で使用した主なツールをまとめます。

cc-sdd(仕様駆動開発ツール)

以下のコマンドでインストールできます。

npx cc-sdd@latest --lang ja

フェーズごとのコマンドは以下の通りです。

/kiro:spec-init <プロジェクト説明>
/kiro:spec-requirements <スペック名>
/kiro:spec-design <スペック名>
/kiro:spec-tasks <スペック名>
/kiro:spec-impl <スペック名>

詳しくはこちらで解説しています。

`/smart-commit` コマンド

ホームディレクトリに配置したカスタムコマンドです。変更内容を自動分析し、グループ化してコミット、プッシュまで実行します。
（実務ではコミットには注意が必要ですが、個人開発なら多少ゆるくても良いかなと。）

プッシュに慎重な方であれば、コマンドは調整すると良いでしょう。

MCP(Model Context Protocol)

Chrome DevTools MCPを使い、ブラウザの自動操作、スクリーンショット取得、動作確認の自動化を実施しました。

Playwright MCP を使うこともありますが、今回はパフォーマンスチェックまで行うので Chrome DevTools MCP を使いました。

こちらでも詳しく解説していますので、ぜひご覧ください！

PRレビューコマンド

Claude Codeの /review コマンドで、PR番号を指定して自動レビューを実施できます。

これらのツールを組み合わせることで、効率的な開発が可能になります。

まとめ

仕様駆動開発とMCPを活用した機能開発についてまとめると以下の通りです。

仕様駆動開発で要件定義→設計→実装の流れを体系的に進められる
AIとの対話を通じた仕様の言語化により、人間は判断・方針決定に集中できる
MVPに絞ることで完成を加速し、後続チケット化で継続的改善を実現できる
ドキュメントが自動生成・蓄積されるため、後々のメンテナンス・改修が容易
カスタムコマンド活用で生産性を大幅に向上できる

小規模機能でもこの流れを部分的に適用可能ですし、コンテキスト管理の工夫で大規模機能にも対応できます。

今後の開発の参考になっていれば幸いです！

Youtube動画では実際の開発プロセスをほぼノーカットでお見せしています！

なお、今回の開発プロセスを動画でも公開していますので、興味がある方はぜひご覧ください。
1時間超えでとてもボリューミーなのですが、考え方や試行錯誤をほぼノーカットでお見せしています！

AI駆動開発を学ぶ同士が集まるDiscordコミュニティを運営しています。

また、Discord無料コミュニティ「Vibe Coding Studio」では、Claude Code、Codex、Cursorの最新情報を共有しています。また、実装例も公開しています。参加者によるナレッジシェアも活発ですので、興味がある方はぜひご参加ください！

参加したら、まずは times を作って日々の学びをシェアしてくれると嬉しいです！！！

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