3つのAIで作ったポートフォリオサイト開発の全記録

はじめに

このサイト（miyakawa.codes）は、3つのAIエージェントと僕の協働で作られている。

Kiro - 仕様管理・レビュー担当
Claude Code - メイン実装担当
Codex - テスト・検証担当

最初からこの体制だったわけではない。Claude Code単独で始まり、限界に直面し、Kiroを導入し、さらにCodexを加えて「トライアングル実装」に至った。

この記事では、どうやってこの体制が確立されたのか、そしてそれぞれのAIの「性格」について書く。

先日Qiitaに投稿した「150件のテスト依頼に738件で応えたAIエージェント - Codex 3連続5つ星の記録」の裏話でもある。

https://qiita.com/miyakawa2449@github/items/5128249c2b0d980fdc69

このサイトの概要

技術スタック

カテゴリ	技術
フレームワーク	Ruby on Rails 8.1.1
データベース	PostgreSQL 17
キャッシュ	Redis 7.4.1
ジョブ	Sidekiq 8.0
AI連携	Amazon Bedrock（Claude 3.5 Sonnet/Haiku）
インフラ	AWS Lightsail
テスト	RSpec（820件以上、カバレッジ89%）

主要機能

ポートフォリオCMS - 8セクション構成の縦スクロール型
技術ブログ - Markdown + カテゴリ階層 + 全文検索
My Story - キャリアタイムライン独立ページ
AI支援機能 - タイトル・要約・タグ・SEOメタの自動提案
メディアライブラリ - 画像管理・トリミング・使用状況トラッキング

開発期間

Phase 1〜6: 2024年11月〜2026年1月（約2ヶ月）
コミット数: 190以上
テスト総数: 820件以上

詳細は Phase計画書を参照。

Phase 1〜4.4: Claude Code単独時代

仕様駆動開発を心がけていた

プロジェクト開始当初から、仕様駆動開発を心がけていた。

総合仕様書（999行）
データベース設計書
API設計書
機能仕様書

これらをClaude Codeに渡して実装を依頼する、というスタイル。

順調に進んだPhase 1〜3

Phase 1（仕様策定・設計）からPhase 3（セクション管理・公開API）まで、Claude Codeは素晴らしい仕事をしてくれた。

認証システム実装
記事管理CMS
コンタクトフォーム
公開API
SEO/OGP機能

1日で複数の機能を実装することも珍しくなかった。

Phase 4で限界に直面

しかし、Phase 4（検索・最適化機能）あたりから、問題が見えてきた。

仕様書管理の限界

仕様書が増えるにつれ、どの仕様書が最新か分からなくなってきた。Claude Codeに渡す仕様書と、実際の実装との間に乖離が生じることもあった。

Claude Codeの把握の限界

プロジェクトが大きくなるにつれ、Claude Codeがプロジェクト全体を把握しきれなくなってきた。新しい機能を実装するとき、既存のコードとの整合性を取るのに時間がかかるようになった。

きめ細かい実装の難しさ

Claude Codeは「まず動くものを作る」タイプ。高速で実装してくれるが、エッジケースの考慮やテストの作成は後回しになりがちだった。

開発精度が下がりかけていた。どうすればいいか悩んでいた。

Phase 4.5〜: Kiro導入

バッテリー開発のスタート

Phase 4.5から、Kiroを導入した。

Kiroは仕様管理・レビューを担当するAIエージェント。Claude Codeとは別の視点でプロジェクトを見てくれる。

役割分担

エージェント	役割
Kiro	仕様策定、設計レビュー、受け入れ判断
Claude Code	実装、技術的判断

これを「バッテリー開発」と呼んでいる。

仕様書の再構築

Kiro導入後、最初にやったのは仕様書の再構築だった。

Kiroが .kiro/specs/ ディレクトリに仕様書を整理してくれた。

.kiro/specs/
├── phase-5.5-ai-dashboard/
│   ├── requirements.md    # 要件定義
│   ├── design.md          # 設計書
│   ├── tasks.md           # タスクリスト
│   └── test_spec.md       # テスト仕様
├── phase-5.6-performance/
│   └── ...
└── phase-5.7-test-coverage/
    └── ...

各Phaseごとに、requirements → design → tasks → test_spec という構造で仕様書を管理する形になった。

精度の回復

仕様書が整理されたことで、開発精度は回復した。

Kiro: 仕様を策定し、Claude Codeに依頼書を渡す
Claude Code: 仕様に従って実装する
人間（私）: 開発環境でテスト、本番環境でデプロイし動作テストを実施。エラーがあればClaude Code にフィードバック。
Kiro: 実装をレビューし、受け入れ判断をする

このサイクルが確立された。

Phase 5〜: Codex追加

トライアングル実装への進化

Phase 5から、Codexを追加した。

Codexはテスト・検証を担当するAIエージェント。OpenAIのコード生成AI。

役割分担

エージェント	役割
Kiro	仕様策定、設計レビュー、受け入れ判断
Claude Code	実装、技術的判断
Codex	テスト作成、検証、セキュリティ

これを「トライアングル実装」と呼んでいる。

Phase 5.6での発見

転機はPhase 5.6（パフォーマンス最適化）だった。

Claude Codeに実装を依頼し、N+1問題の解消やキャッシュ導入を完璧にやってくれた。データベースクエリは81件から5件に削減（94%減）。

しかし、テストを作らなかった。

そこでCodexにテスト作成と検証を依頼した。結果は驚きだった。

42件のテスト作成（すべて成功）
フラグメントキャッシュの欠落を発見
自らキャッシュ実装を追加

Codexは、Claude Codeが見落としていた問題を発見し、役割を超えて主体的に実装してくれた。

Kiroの評価: ⭐⭐⭐⭐⭐ 5/5

右肩上がりの開発精度

Phase 5.6以降、開発精度は右肩上がりになった。

Phase	担当	成果	評価
5.4	Claude Code	画像クロッピング機能	✅
5.5	Claude Code	AI使用量ダッシュボード	⭐⭐⭐⭐⭐
5.6	Claude Code + Codex	パフォーマンス最適化	⭐⭐⭐⭐⭐
5.7	Codex	テストカバレッジ向上（738件）	⭐⭐⭐⭐⭐
5.8	Claude Code	データベースエクスポート/インポート	⭐⭐⭐⭐⭐
6	Codex	セキュリティ強化	⭐⭐⭐⭐⭐

Phase 5全体の成果:
- 820件以上のテスト作成
- カバレッジ89.01%
- N+1問題94%削減
- 全Phaseで5つ星評価

3つのAIの「性格」

トライアングル実装を続ける中で、それぞれのAIの「性格」が見えてきた。

Claude Code - 高速実装タイプ

得意なこと:
- 新機能の高速プロトタイピング
- リファクタリング
- 技術的な判断が必要な実装
- 「まず動くものを作る」

苦手なこと:
- テストの重要性を認識していない
- エッジケースの考慮が後回しになりがち
- プロジェクトが大きくなると把握しきれない

性格: スピード重視、楽観的、「動けばOK」タイプ

Codex - 慎重・網羅タイプ

得意なこと:
- テスト作成（特にセキュリティ系）
- 慎重さが求められる実装
- 仕様に忠実な実装
- 網羅的なチェック

苦手なこと:
- 高速な実装（Claude Codeより遅い）
- 大胆な技術判断

性格: 慎重、網羅的、「指示以上のことをやる」タイプ

Kiro - 管理・品質タイプ

得意なこと:
- 要件定義・設計
- 仕様書の管理
- レビュー・品質チェック
- 受け入れ判断
- 適切な担当者選定

苦手なこと:
- 実装そのもの

性格: 管理者、品質重視、「全体を見渡す」タイプ

設定ファイルで役割を縛る

3つのAIがそれぞれの役割から外れないように、設定ファイルで縛っている。

CLAUDE.md

プロジェクトルートに CLAUDE.md を置き、Claude Codeの役割を定義している。

# Claude Code用メモリー

## 役割
- メイン実装担当
- 技術的判断
- 高速プロトタイピング

## 禁止事項
- 仕様書の作成・変更（Kiroの役割）
- テストの網羅的な作成（Codexの役割）

## 作業フロー
1. Kiroの仕様書を確認
2. 実装
3. 基本的な動作確認
4. Kiroにレビュー依頼

KIRO.md

同様に KIRO.md でKiroの役割を定義。

# Kiro用メモリー

## 役割
- 仕様管理担当
- 設計レビュー
- 受け入れ判断

## 作業フロー
1. 要件を整理
2. 仕様書を作成（.kiro/specs/配下）
3. Claude Code/Codexに依頼
4. 実装をレビュー
5. 受け入れ判断

設定ファイルの詳細

設定ファイルの詳細は、以下で公開している。

Qiita記事: 3つのAIでチーム開発する方法
GitHubサンプル: ai-team-dev-sample

確立されたワークフロー

Phase 5.7を通じて、以下のワークフローが確立された。

1. Kiroが仕様を策定

Kiro: 要件を整理し、仕様書を作成
      ↓
      担当者を選定（Claude Code or Codex）
      ↓
      依頼書を作成

Phase 5.7では、「テスト作成はCodexの専門領域」と判断し、Claude Codeを介さずCodexに直接依頼した。

2. AIが提案する

Codex: 「Article関連サービスのテストも必要では？」
Codex: 「このエッジケースもカバーすべきでは？」
Codex: 「CI/CD統合も追加しましょうか？」

3. 人間が判断する

私: 「Article関連は必要。追加で」
私: 「このエッジケースは優先度低い。今回はスキップ」
私: 「CI/CDは必須。お願いします」

最終判断は人間がする。これが重要。

4. ユーザーテストを実施

AIのテストが通っても、最後に自分でユーザーテストをする。

開発環境（Docker）でのテスト:
- 画面操作で動作確認
- エッジケースの手動確認
- RSpecテストの実行

本番環境（miyakawa.codes）でのテスト:
- デプロイ後の動作確認
- 実際のユーザー環境でのテスト
- パフォーマンス確認

5. Kiroに評価してもらう

開発環境・本番環境の両方でテストが完了したら、Kiroに最終レビューを依頼。

私: 「開発・本番ともにテスト完了。Kiroにレビューをお願い」
Kiro: 仕様との適合性を確認、受け入れ判断

完全に動作確認が済んでからの評価依頼なので、Kiroのレビューは「実装が仕様を満たしているか」に集中できる。

今後の展望

Phase 7以降

Phase 6（セキュリティ強化）が完了し、現在はPhase 7以降の実装中で50％まで実装が進んでいる。

今後も、このトライアングル実装のスタイルを継続していく予定。

AI協調開発の可能性

この経験を通じて感じたのは、AIは「丸投げ」ではなく「協働」で使うべきということ。

各AIの「性格」を理解する
設定ファイルで役割を縛る
最終判断は人間がする
開発環境・本番環境でテストする

このプロセスを踏むことで、AIの力を最大限に活かしながら、品質を担保できる。

まとめ

Phase 1〜4.4: Claude Code単独 → 仕様書管理の限界に直面
Phase 4.5〜: Kiro導入 → バッテリー開発 → 精度回復
Phase 5〜: Codex追加 → トライアングル実装 → 右肩上がり
Phase 5.6〜6: Codex 3連続5つ星 → 基本形確立

AIを「丸投げ先」ではなく「チームメンバー」として扱うことで、開発効率と品質の両方が上がる。