Go to Qiita Advent Calendar Top
LoginSignup
17
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 25

LIFULL Advent Calendar 2025

Day 25

生成AIカレンダー Advent Calendar 2025

@sasakiy0819in株式会社LIFULL

私が始めたAI協働生活 〜失敗から学んだ仕様駆動とサブエージェント連携〜

Last updated at Posted at 2025-12-24

はじめに

2025年は私にとって生成AIとの向き合い方が大きく変わった年でした。

「質問する」「コードを生成してもらう」チャット型から、「タスクを任せる」「一緒に作業する」エージェント型へ。単なるツールのアップデートではなく、働き方そのものが変わる転機でした。

本記事では、2025年6月から本格的に始めた生成AIとの試行錯誤を通じて得た実体験を共有します。

この約半年間の振り返りとして、生成AIとの向き合い方の変化から生成AIエージェントチーム開発での失敗、そこから生まれた「仕様駆動開発」、そして最終的にたどり着いた「サブエージェント連携システム」まで、失敗も成功もすべて包み隠さずお伝えします😊

この記事を読むと、こんなことが分かります:

  • 💥 生成AIエージェントチーム開発の失敗談（tmux爆死と応援団問題）
  • 📋 失敗から生まれた仕様駆動開発（ドキュメント化で解決）
  • 🤖 サブエージェント連携システムの構築（16種類の専門家との協働）
  • 🚀 実践的な成果（開発アウトプットをほぼ100%AI生成）
  • 🤝 今日から始める6つのポイント（小さく始めて、ルールを育てる）

アドベントカレンダー最終日ということで、半年間の試行錯誤を振り返っていたら大ボリュームになってしまいました…！コーヒー片手にゆっくりお読みください☕

転機：エージェント型AIの登場

私の生成AI活用タイムライン（2025年）

チャット型からエージェント型へ

2024年から生成AIを使ってはいましたが、2025年6月上旬、社内でAmazon Q Developer CLIの利用が始まったことをきっかけに、私の本格的な生成AI活用が始まりました。

使用ツール:

  • Amazon Q Developer CLI - 会社・プライベート両方で使用
  • Gemini CLI - 主にプライベートで使用

それまでは「コーディング支援ツール」として使っていました。

  • 「この関数を書いて」
  • 「このエラーを解決して」
  • 「このコードをレビューして」

典型的なチャット型の使い方です。

でも、6月に入ってCLIを使い込んでいくうちに、生成AIは単なる補完や質問応答ではなく、実際に作業を進めてくれることに気づきました。

具体例:

  • 「この機能を実装して」→ コード生成からテストまで
  • 「このバグを修正して」→ 原因調査から修正まで
  • 「SSH接続がうまくいかない」→ 環境調査から問題解消まで
  • 「CodeDeployでエラーが出てる」→ ログ調査から原因特定・対応まで
  • 「このGitHubプロジェクトのサマリー作って」→ コードベース全体を分析して、構造・技術・目的を整理

向き合い方の変化

この時点で、生成AIとの向き合い方が大きく変わりました。

チャット型の特徴:

  • 質問 → 回答の繰り返し
  • 同期的なコミュニケーション
  • 単発のタスク処理

エージェント型の特徴:

  • タスク依頼 → 作業実行 → 成果物
  • 非同期的なコミュニケーション
  • 継続的なタスク処理

そこで、私はこう思いました。

「もしかして...生成AIのチームを作ったら、生産性爆上がりするんじゃない？💡」

そして、この「エージェント型」の可能性を模索するため、私は実験を始めることにしました。

それが、生成AIエージェントチームの構築です。

第一の試行錯誤：生成AIエージェントチームの構築

実験の始まり

生成AIエージェントチームの構築を実現するため、私はこの記事を参考に実験を始めました。

tmuxでClaude CodeのMaxプランでAI組織を動かし放題のローカル環境ができた〜〜〜！ので、やり方をシェア！！🔥🔥🔥🙌

※tmux：ターミナルマルチプレクサ（複数の仮想端末を管理するツール）。画面を複数のペイン（画面分割単位）に分割して、それぞれで異なる作業を同時に進められる。

tmuxでのAIエージェントチーム開発の仕組み

tmuxで複数のペインを作り、それぞれに役割を割り当てました。

構成:

  • ペイン1: PM（プロジェクトマネージャー）
  • ペイン2: TL（テックリード）
  • ペイン3: Engineer1（UI/UX担当）
  • ペイン4: Engineer2（バックエンド担当）
  • ペイン5: Engineer3（品質管理担当）

アーキテクチャ:

通信フロー:

  1. 人間 → PM: 「ホームページを作って」
  2. PM → TL: ビジョンと成功基準を伝達
  3. TL → Engineer1,2,3: タスクを分解して割り振り
  4. Engineer1,2,3: 並列で作業実行
  5. Engineer1,2,3 → TL: 完了報告
  6. TL → PM: 統合結果を報告
  7. PM → 人間: 成果物を提示

メッセージ送信の仕組み:

核心部分はtmuxのsend-keysコマンドです。

# 1. 現在の入力をクリア（Ctrl+C）
tmux send-keys -t "$target" C-c

# 2. メッセージテキストを送信
tmux send-keys -t "$target" "$message"

# 3. Enterキーを送信（実行）
tmux send-keys -t "$target" C-m

使用例: ./agent-send.sh TL "タスクを開始して"

つまり、「人間がターミナルでタイピングする動作」をプログラムで再現しているだけで、特別なAPIやプロトコルは使っていません。シンプルですが効果的な仕組みです。

tmuxでのAIエージェントチーム開発の様子

複数のAIがそれぞれのペインで同時に作業する様子を見て、「めっちゃ楽しい！！」「これは未来だ！！」と高揚感でいっぱいでした✨

直面した問題

想定していたのは、「私 ⇔ PM」のやり取りだけで、あとは「PM ⇔ TL」「TL ⇔ 各Engineer」のやり取りが自動的に進む、という形でした。

でも、現実はそう甘くありませんでした。

問題1: メッセージ送信の破綻

  • PMがTLにメッセージを送っても、TLが返信しない
  • TLがEngineerに指示を出しても、Engineerが別の話題で返信
  • 私が各ペインを行き来して、手動でメッセージをコピー＆ペースト

結果、私がメッセンジャーになってしまいました。

「伝書鳩じゃないんだから…😤」

問題2: tmuxペインの固まり

作業開始からしばらくすると、ペインが固まり始めました。

「あれ？応答がない...」

リペインして、要件や進捗状況を再伝達。でも、またしばらくすると固まる。この繰り返し。

実際の作業時間よりも、状況説明に費やす時間の方が長いという本末転倒な状況に。

「一体何やってんだろ…😮‍💨」

問題3: 作業ディレクトリの迷子

コンテキストオーバーフローで記憶を失ったEngineerが、突然プロジェクトディレクトリとは全く関係ない場所（ワークディレクトリ直下など）で作業を始める...

※コンテキストオーバーフロー：AIが処理できる情報量（コンテキストウィンドウ）の上限を超え、過去の会話内容を忘れてしまう現象。長い会話を続けると、初期の指示や文脈が失われることがある。

「なんでそこにファイル作ってるの...？😨」

問題4: CLIエラー祭り

当時のAmazon Q Developer CLIは、頻繁にエラーが発生しました。

サーバーエラー、モデル利用不可、認証エラー、UTF-8エラー...

しばらくして確認すると、エラーで作業が止まっている。

「これじゃあ、開発どころじゃないじゃん…😩」

問題5: 会話の上書き

複数メンバーが同時に質問・相談してくると、先に質問していた人のものがスルーされてしまいます。

「じゃあ、チーム人数を減らせばいいんじゃね？」

3人にしても同じ。

2人にしても、結局1人だけが作業して、残りは…

「頑張って！」
「いいね！」
「その調子！」

…応援してるだけ。

応援団かよっ！📣

しかも、この余計な会話のやり取りでタスクが一向に進まない。応援メッセージでコンテキストを無駄に消費していく…。

「実用的じゃない…😓」

問題6: 利用上限とコンテキストオーバーフロー

こうした問題を抱えながら数日実験を続けると、当月分の利用上限に到達してしまいました。

さらに、コンテキストウィンドウもオーバーフロー。都度、要件・進捗を伝え直す必要がありました。

※コンテキストウィンドウ：AIが一度に処理できる情報量の上限。この範囲内の情報のみを参照して回答を生成するため、上限を超えた古い情報は考慮されなくなる。

しかも、伝え直すたびに微妙にアウトプットがブレる。

「AIエージェントチーム開発、まだ早すぎたか…😞」

第二の試行錯誤：仕様駆動開発の誕生

AIエージェントチーム開発の失敗から、私は重要な気づきを得ました。

「もしかして...ドキュメント化すればいいんじゃない？💡」

ウォーターフォール型の発想

2025年6月末、私は新しいアプローチを試すことにしました。

何十回とテストプロジェクトを実施し、チームで振り返りを繰り返しながら、作業ステップごとにドキュメント化していきました。

その過程の中で、私はあることに気づきました。

「もしかして...ウォーターフォール開発の工程に沿えば、ブレなくできるんじゃない？💡」

※ウォーターフォール開発：要件定義→設計→実装→テスト→運用という順序で進める伝統的な開発手法。各工程を順番に完了させてから次に進むことで、作業の明確化と品質管理を実現する。

仕様駆動開発ルールの確立

こうして生まれたのが、当初「ウォーターフォール開発ルール」と呼んでいたもの。後に「仕様駆動開発」と名付けることになります✨

今では「仕様駆動開発」という考え方は一般的になりつつありますが、これは当時の試行錯誤から生まれた私なりの解決策でした。

仕様駆動開発（SDD）とは

仕様駆動開発（SDD: Spec-Driven Development）は、「何を作るか（What）」を仕様書で明確に定義し、それを唯一の情報源として「どう作るか（How）」をAIに任せる手法です。

従来の開発手法との違いを簡単にまとめると、

  • テスト駆動開発（TDD）: テストを先に書き、そのテストが通るようにコードを実装する。「テストがドキュメント」という考え方
  • アジャイル開発: 動くコードを素早く作り、フィードバックを受けながら仕様を調整していく。変化への対応を重視
  • 仕様駆動開発（SDD）: 仕様を先に書き、それを唯一の情報源（Single Source of Truth）として設計・実装・テストを進める。AIエージェントとの協働に適している

なぜAIエージェントとの協働で有効なのか

生成AIエージェントには以下の特性があります。

  1. コンテキストウィンドウの制限 - 一度に処理できる情報量の上限がある
  2. セッション間の記憶がない - 新しい会話では過去の文脈を忘れている
  3. 曖昧な指示への解釈ブレ - 同じ指示でも毎回微妙に異なる解釈をする

仕様書を「唯一の情報源」として用意しておくことで、これらの問題に対応できます。

  • ✅ コンテキスト制限 → 必要な情報を仕様書にまとめて毎回渡せる
  • ✅ 記憶がない → 新しいセッションでも仕様書を読めば同じ文脈で再開できる
  • ✅ 解釈ブレ → 仕様書という基準があるのでズレを検知・修正しやすい

開発フロー

最初は、要件定義→設計→実装という流れだけを定義していました。しかし、AIの自由な発想で一気に進んでしまい、依然としてブレが生じていました。

そこで、各フェーズごとに承認ゲートを設け、人間が確認してから次に進む形に改善しました。

フローの詳細:

  1. 要件定義: 何を作るかを明確化（requirements.md）
  2. 承認: 内容を確認・承認
  3. 技術設計: どう作るかを設計（design.md）
  4. 承認: 設計内容を確認・承認
  5. 計画立案: タスク分解・工数見積（tasks.md）
  6. 承認: 計画を確認・承認
  7. 実装着手: 実際のコーディング開始

メリット:

  • 途中でコンテキストがオーバーフローしても、ドキュメントから続きを再開可能 📄
  • 各フェーズで承認を挟むことで、アウトプットのブレが大幅に減少 ✅
  • 作業の透明性・再現性の向上 🔍
  • 「何をすべきか」が明確なので、AIも迷わない 🎯
仕様駆動開発ルール（基本原則の抜粋） 
# 仕様駆動開発（Specification Driven Development）フロー

この文書は、AIエージェントとユーザーとの共同作業における、柔軟かつ堅牢な開発プロセスを定義します。

## 0. 基本原則

### 0.1. 承認ベースの進行
各フェーズは、指定された成果物に対するユーザーの**承認**を以て次へと進みます。

## 0.2. プロジェクトルールの遵守
いかなる作業に着手する前も、まず対象プロジェクトの`README.md`や関連ドキュメントを読み、既存のブランチ戦略、コーディング規約、その他のローカルルールを最大限尊重し、遵守します。

## 0.3. プロセスの柔軟性
プロジェクト開始時に、まずその**規模感**について合意し、プロセスを最適化します。
- **大規模**: 全てのプロセスを厳格に適用します。プルリクエストベースの開発が必須です。
- **中規模**: プルリクエストベースの開発を推奨します。
- **小規模・軽微な変更**: `requirements.md`や`design.md`を省略し、`tasks.md`のみで管理します。ただし、デフォルトブランチへの直接コミットは行わず、必ず作業ブランチを作成し、プルリクエスト経由でマージするものとします。

## 0.4. 仕様変更管理
一度承認されたドキュメントでも、後のフェーズで変更が必要になった場合は、該当するフェーズのドキュメントに立ち返って議論し、再承認を得ることで、安全に変更を行うことができます。

...（以下省略）

私が使っているテンプレート

私の場合は、プロジェクトの規模に応じて以下の3つのテンプレートを使い分けています。

規模 目安 使うテンプレート
小規模 30分〜数時間程度 tasks.md のみ
中規模 数時間〜1日程度 requirements.md + tasks.md
大規模 数日以上 requirements.md + design.md + tasks.md

実際に使用しているテンプレートです。

requirements.md（要件定義書）

「何を作るか（What）」 を定義するドキュメントです。

  • プロジェクトの目的・背景
  • 機能要件（ユーザーストーリー形式）
  • 非機能要件（パフォーマンス、セキュリティなど）
  • スコープ（対象範囲と対象外）
  • 優先順位（MoSCoW法）
# 要件定義書

**プロジェクト名**: [プロジェクト名]  
**作成日**: [YYYY-MM-DD]  
**承認日**: [YYYY-MM-DD]

## 1. プロジェクト概要

### 1.1. 目的
[このプロジェクトで達成したいこと]

### 1.2. スコープ

**対象範囲**:
- [対象1]
- [対象2]

**対象外**:
- [対象外1]
- [対象外2]

...（以下省略）
テンプレート全文を見る 
# 要件定義書

**プロジェクト名**: [プロジェクト名]
**作成日**: [YYYY-MM-DD]
**承認日**: [YYYY-MM-DD]

## 1. プロジェクト概要

### 1.1. 目的
[このプロジェクトで達成したいこと]

### 1.2. 背景
[プロジェクトが必要になった背景・課題]

### 1.3. スコープ

**対象範囲**:
- [対象1]
- [対象2]

**対象外**:
- [対象外1]
- [対象外2]

## 2. 機能要件

### 2.1. ユーザーストーリー

#### US-001: [ユーザーストーリー名]
**As a** [ユーザー]
**I want** [やりたいこと]
**So that** [得られる価値]

**受入基準**:
- [ ] [基準1]
- [ ] [基準2]

**優先度**: Must / Should / Could / Won't

## 3. 非機能要件

### 3.1. パフォーマンス
- [要件1]: [具体的な数値目標]

### 3.2. セキュリティ
- [要件1]: [具体的な対策]

## 4. 制約条件

### 4.1. 技術的制約
- [制約1]: [説明]

### 4.2. ビジネス制約
- [制約1]: [説明]

## 5. 優先順位（MoSCoW法）

### Must（必須）
- [機能1]: [説明]

### Should（重要）
- [機能1]: [説明]

### Could（あれば良い）
- [機能1]: [説明]

### Won't（今回は対象外）
- [機能1]: [説明]

## 6. 納品物リスト

- [ ] [納品物1]
- [ ] [納品物2]

**承認者**: [承認者名]
**承認日**: [YYYY-MM-DD]

書き方のポイント:

  • 「対象外」を明記する - AIは親切心から対象外の機能まで実装しようとすることがあります
  • ユーザーストーリー形式で書く - 「誰が」「何をしたくて」「どんな価値を得るか」を明確に
  • 受入基準は具体的に - 「検索が速いこと」ではなく「1秒以内に表示される」のように

design.md（技術設計書）

「どう作るか（How）」 を定義するドキュメントです。

  • システム構成・アーキテクチャ
  • データ設計（ER図、テーブル定義）
  • API設計（エンドポイント、リクエスト/レスポンス）
  • 画面設計・画面遷移
  • セキュリティ設計
# [プロジェクト名] - 設計書

**作成日**: [YYYY-MM-DD]  
**承認日**: [YYYY-MM-DD]

## 1. システム構成

### 1.1 全体アーキテクチャ
[システム構成図]

### 1.2 技術スタック
- 言語: [TypeScript]
- フレームワーク: [Next.js 14]
- データベース: [PostgreSQL]

...（以下省略）
テンプレート全文を見る 
# 設計書

**プロジェクト名**: [プロジェクト名]
**作成日**: [YYYY-MM-DD]
**承認日**: [YYYY-MM-DD]

## 1. システム構成

### 1.1. アーキテクチャ概要

```mermaid
graph TB
    subgraph Frontend
        A[React App]
    end
    subgraph Backend
        B[API Server]
        C[Database]
    end
    A --> B
    B --> C
```

### 1.2. 技術スタック

| レイヤー | 技術 | 理由 |
|:---|:---|:---|
| フロントエンド | React | [選定理由] |
| バックエンド | Node.js | [選定理由] |
| データベース | PostgreSQL | [選定理由] |

## 2. データ設計

### 2.1. ER図

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
```

### 2.2. テーブル定義

#### users テーブル

| カラム名 | 型 | NULL | 説明 |
|:---|:---|:---:|:---|
| id | SERIAL | NO | 主キー |
| email | VARCHAR(255) | NO | メールアドレス |
| created_at | TIMESTAMP | NO | 作成日時 |

## 3. API設計

### 3.1. エンドポイント一覧

| メソッド | パス | 説明 |
|:---|:---|:---|
| GET | /api/users | ユーザー一覧取得 |
| POST | /api/users | ユーザー作成 |
| GET | /api/users/:id | ユーザー詳細取得 |

### 3.2. API詳細

#### GET /api/users

**リクエスト**:
```json
{
  "page": 1,
  "limit": 20
}
```

**レスポンス**:
```json
{
  "data": [
    {
      "id": 1,
      "email": "user@example.com"
    }
  ],
  "total": 100
}
```

## 4. 画面設計

### 4.1. 画面一覧

| 画面ID | 画面名 | パス | 説明 |
|:---|:---|:---|:---|
| SCR-001 | ログイン | /login | ログイン画面 |
| SCR-002 | ダッシュボード | /dashboard | メイン画面 |

### 4.2. 画面遷移図

```mermaid
graph LR
    A[ログイン] --> B[ダッシュボード]
    B --> C[詳細画面]
    C --> B
```

## 5. セキュリティ設計

### 5.1. 認証・認可

- 認証方式: JWT
- トークン有効期限: 24時間
- リフレッシュトークン: 7日間

### 5.2. データ保護

- 通信: HTTPS必須
- パスワード: bcryptでハッシュ化
- 機密情報: 環境変数で管理

**承認者**: [承認者名]
**承認日**: [YYYY-MM-DD]

書き方のポイント:

  • 図を活用する - Mermaid記法を使うと、AIも図を理解・生成できます
  • 技術選定の理由を書く - 「なぜその技術を選んだか」を書くことで、AIが文脈を理解しやすくなります
  • API設計は具体例を含める - リクエスト・レスポンスの具体例があると、AIが正確に実装できます

tasks.md（タスク計画・管理表）

「どの順番で作るか（When）」 を定義するドキュメントです。

  • タスク一覧（依存関係、工数）
  • タスク詳細（前提条件、手順、完了条件）
  • 工数サマリー

進捗管理も同じファイルで行っています。というのも、会話が途切れるたびに状況を説明し直すのが大変だったので、3つのドキュメントを読むだけで「何を作っていて、今どこまで進んでいるか」をAIが把握できる形にしました。

# タスク計画・管理表

**プロジェクト名**: [プロジェクト名]  
**総予定工数**: [XX時間]

## タスク一覧

| ID | タスク名 | 状態 | 担当者 | 予定工数 | 完了日時 |
|:---|:---|:---:|:---:|:---:|:---:|
| 1 | 要件定義 | 未着手 | requirements-analyst | 2h | - |
| 2 | システム設計 | 未着手 | architect | 4h | - |
| 3 | バックエンド実装 | 未着手 | backend | 8h | - |
| 4 | 統合テスト | 未着手 | qa | 4h | - |

...（以下省略）
テンプレート全文を見る 
# タスク計画・管理表

**プロジェクト名**: [プロジェクト名]
**作成日**: [YYYY-MM-DD]
**承認日**: [YYYY-MM-DD]

## タスク一覧

| ID | 先行 | タスク名 | 状態 | 予定工数 | 実績工数 | 完了日 |
|:---|:---:|:---|:---:|:---:|:---:|:---|
| 1 | - | 環境構築 | 完了 | 1h | 1h | 2025-01-01 |
| 2 | 1 | DB設計 | 実装中 | 2h | - | - |
| 3 | 2 | API実装 | 未着手 | 4h | - | - |
| 4 | 2 | 画面実装 | 未着手 | 4h | - | - |
| 5 | 3,4 | 結合テスト | 未着手 | 2h | - | - |

## タスク詳細

### タスク1: 環境構築

**前提条件**:
- Node.js 20以上がインストール済み
- Docker環境が利用可能

**詳細手順**:
1. リポジトリをクローン
   ```bash
   git clone https://github.com/xxx/project.git
   cd project
   ```
2. 依存関係をインストール
   ```bash
   npm install
   ```
3. 環境変数を設定
   ```bash
   cp .env.example .env
   ```

**完了条件**:
- [ ] `npm run dev` でサーバーが起動する
- [ ] `http://localhost:3000` にアクセスできる

**検証方法**:
```bash
npm run dev
# → "Server started on port 3000" と表示される
```

### タスク2: DB設計

**前提条件**:
- タスク1が完了していること

**詳細手順**:
1. マイグレーションファイルを作成
2. テーブルを定義
3. マイグレーションを実行

**完了条件**:
- [ ] usersテーブルが作成されている
- [ ] productsテーブルが作成されている
- [ ] 外部キー制約が設定されている

**検証方法**:
```bash
npm run db:migrate
npm run db:status
```

## 工数サマリー

| フェーズ | 予定 | 実績 |
|:---|:---:|:---:|
| 環境構築 | 1h | 1h |
| 設計 | 2h | - |
| 実装 | 8h | - |
| テスト | 2h | - |
| **合計** | **13h** | **1h** |

**承認者**: [承認者名]
**承認日**: [YYYY-MM-DD]

書き方のポイント:

  • タスクは実行可能なレベルまで分解 - 「API実装」ではなく「GET /api/users 実装」のように
  • 完了条件を明確に - 「実装完了」ではなく、具体的な確認項目を書く
  • 検証方法を具体的に - AIが自分で完了確認できるよう、コマンドや手順を書く

ルールの洗練

7月〜8月は、このルールを「育てる」期間でした。

生成AIに実際にタスクを回させ、その結果を振り返り、学びをルールに反映。

具体的な改善例:

  • 初期: 「タスク実行→振り返り→ルール追加」を繰り返した結果、ルールが1000行以上に膨れ上がる

    • 結果: AIが重要な情報を見落とす（Lost in the Middle）
    • 改善: 生成AIと対話しながら「どうすればスルーされない？」を試行錯誤。私の場合は500行程度で落ち着きました
    • 補足: 最適なサイズに明確な基準はありませんが、長すぎるとLost in the Middleで中盤のルールが無視されやすくなります。「関心の分離」の原則に従って責務ごとにファイルを分割すれば、各ファイルが短くなり、重要なルールが埋もれにくくなります

  • 初期: requirements.mdに技術選定を明示する項目がなかった

    • 結果: JS/TSで書いてほしいのにPythonで書き出す
    • 改善: 「技術的制約」に使用する言語・フレームワークを明記

  • 初期: requirements.mdのスコープに「対象範囲」しかなかった

    • 結果: 機能追加だけ依頼したつもりが、レスポンシブ対応まで勝手にやり始める
    • 改善: 「対象外」の項目を追加し、やらないことも明確に定義

  • 初期: tasks.mdに進捗管理の仕組みがなかった

    • 結果: コンテキストオーバーフローでどこまで完了したか分からなくなり、ソースの更新状況を確認して続きを探す手間が発生
    • 改善: tasks.mdに進捗管理機能（状態・完了日時など）を追加

検証を繰り返しながら、ちょうどいいラインを見極めていきました。

※Lost in the Middle：長文の中間部分の情報が見落とされやすい現象。AIは文章の冒頭と末尾に注目しやすく、中間部分の重要な情報を見落とす傾向がある。

第三の試行錯誤：サブエージェント連携システムの構築

諦めきれなかった夢

仕様駆動開発で一定の成果は出るようになりました。でも、私は諦めきれませんでした。

「やっぱり、生成AIエージェントチーム開発を実現したい💪」

そんな時、2025年7月31日にAmazon Q Developer CLI v1.13.0がリリースされ、カスタムエージェント機能が追加されました。

「これだ！✨」

サブエージェント連携システムの構築

8月、私はサブエージェント連携システムの構築に取り掛かり始めました。

サブエージェントとは

サブエージェントは、特定の専門分野に特化したAIエージェントです。

人間のチーム開発と同じように、それぞれの専門家が得意分野を担当します。

なぜサブエージェントが有効なのか

  1. 専門知識の集中 - 各エージェントが専門分野の知識・評価基準を持つ
  2. 役割の明確化 - 「誰に何を聞くか」が明確になる
  3. 観点の明確化 - 専門家視点でのレビュー・フィードバックが得られる
  4. コンテキストの最適化 - 必要な情報だけを渡せる

連携方法

# プロジェクトディレクトリで実行
cd ~/kiro-works/projects/[プロジェクト名]

# 専門エージェントを呼び出す
q chat --agent [エージェント名] --no-interactive "
【相談内容】
...

【参考資料】
- $(pwd)/requirements.md
- $(pwd)/design.md

【依頼内容】
...
"

※現在は、qコマンドはkiro-cliコマンドに変更されています。

構成

複数の専門エージェントを用意し、それぞれが専門分野を担当します🤖

エージェント名 専門分野
requirements-analyst 要件分析・ユーザーストーリー作成
project-manager WBS作成・リスク管理・工数見積
agile-coach スクラム・カンバン・スプリント計画
architect システム設計・技術選定
uiux-designer UI/UX設計・ワイヤーフレーム・アクセシビリティ
database-designer データベース設計・正規化・パフォーマンス最適化
backend API・インフラ・信頼性エンジニアリング
frontend UI/UX・アクセシビリティ
security 脅威モデリング・脆弱性評価
performance 最適化・ボトルネック特定
analyzer 根本原因調査・体系的デバッグ
qa テスト戦略・品質保証
refactorer コード品質・技術的負債管理
devops インフラ自動化・デプロイ
mentor 教育指導・知識移転
scribe 専門的文書作成・コミュニケーション

これらを仕様駆動開発フローと組み合わせることで、実用的なチーム開発を実現しました。

ワークフロー例:

具体的な使用例:

あるWebアプリケーション開発プロジェクトでの実例です。

  1. requirements-analyst ユーザーストーリー作成、受入基準定義

    • 入力: 「ユーザー登録機能を作りたい」
    • 出力: 詳細な要件定義書

  2. architect 技術設計レビュー

    • 入力: 要件定義書
    • 出力: システムアーキテクチャ、DB設計、API設計

  3. backend: 実装支援

    • 入力: 技術設計書
    • 出力: バックエンドコード（Node.js + Express）

  4. security: セキュリティレビュー

    • 入力: 実装コード
    • 出力: 脆弱性指摘、改善提案

  5. qa: 品質保証

    • 入力: 実装コード + テスト要件
    • 出力: テストケース、テストコード

  6. scribe: ドキュメント整備

    • 入力: 実装コード + 設計書
    • 出力: 運用ドキュメント、README、ユーザーガイド

実際の対話例

サブエージェント連携システムでは、各エージェントが専門分野で対話を進めます。

ユーザー: 「ユーザー登録機能を作りたい」

requirements-analyst:

承知しました。以下の点を確認させてください。
- 認証方式は？（JWT/セッション/OAuth）
- パスワードの要件は？
- メール確認は必要ですか？

ユーザー: 「JWT、8文字以上、メール確認あり」

requirements-analyst:

要件定義書を作成しました。ご確認ください。

→ requirements.md を生成

architect:

要件定義書を確認しました。技術設計を作成します。

→ design.md を生成

このように、各エージェントが専門分野で対話を進め、成果物を積み上げていきます。

サブエージェントの設定例

各エージェントは、専用のシステムプロンプト（Markdown）で専門知識と評価基準を定義します。

ちなみに私は、SuperClaude Frameworkを参考にしてもらい、生成AIに定義ファイルを作成してもらっていました。

requirements-analystのプロンプト（抜粋）:

あなたは要件定義専門家『Requirements Analyst』です。

## 責務
要件分析、ユーザーストーリー作成、受入基準定義を通じて、プロジェクトの成功基盤を構築します。

## 専門領域

### 要件定義
- 機能要件の明確化
- 非機能要件の定義（パフォーマンス、セキュリティ、可用性）
- 制約条件の特定

### ユーザーストーリー作成
- As a [user], I want [goal], So that [benefit] 形式
- 受入基準の明確化
- 優先順位付け（MoSCoW法）

### 要件検証
- 完全性チェック（すべての要件が網羅されているか）
- 一貫性チェック（要件間の矛盾がないか）
- 実現可能性評価
- テスト可能性評価

...（以下省略）

architectのプロンプト（抜粋）:

あなたはシステム設計専門家『Architect』です。

## 責務
プロジェクトの長期的成功を見据え、スケーラビリティと保守性を核としたシステム全体の設計を指導します。

## 評価基準

### AWS Well-Architected Framework 6本柱

#### 1. 運用上の優秀性 (Operational Excellence)
- コードとしての運用: IaC (CDK/CloudFormation/Terraform)
- 自動化: CI/CDパイプライン、デプロイ自動化

#### 2. セキュリティ (Security)
- 身元管理: IAM、最小権限の原則、MFA
- データ保護: 暗号化(保管時・転送時)、KMS

#### 3. 信頼性 (Reliability)
- 障害からの回復: 自動バックアップ、ディザスタリカバリ
- キャパシティ計画: Auto Scaling、負荷テスト

...（以下省略）

backendのプロンプト（抜粋）:

あなたはAPI・インフラ専門家『Backend』です。

## 責務
システムの信頼性（目標稼働率99.9%）を確保し、スケーラブルで安全なバックエンドの設計・実装を指導します。

## 評価基準

### API設計

#### RESTful APIベストプラクティス
- **リソース指向**: 名詞ベースのURL設計
- **HTTPメソッド**: GET/POST/PUT/PATCH/DELETEの適切な使用
- **ステータスコード**: 2xx/3xx/4xx/5xxの正しい使い分け

#### APIセキュリティ
- **認証**: JWT, OAuth 2.0, APIキー
- **認可**: RBAC (Role-Based Access Control)
- **レートリミット**: トークンバケット、スライディングウィンドウ

### データベース最適化
- **インデックス設計**: クエリパターンに応じた最適化
- **クエリ最適化**: EXPLAIN分析、N+1問題解決
- **トランザクション**: ACID特性の適切な使用

...（以下省略）

qaのプロンプト（抜粋）:

あなたは品質保証・テスト専門家『QA』です。

## 責務
予防的なアプローチでプロダクトの品質を保証し、テスト戦略の設計・実装を指導します。

## 評価基準

### テストピラミッド

#### 単体テスト (70%)
- **カバレッジ目標**: 80%以上
- **テスト対象**: 関数、メソッド、クラスの単体
- **ベストプラクティス**: AAAパターン (Arrange, Act, Assert)

#### 統合テスト (20%)
- **テスト対象**: モジュール間の連携
- **APIテスト**: エンドポイントの統合テスト

#### E2Eテスト (10%)
- **テスト対象**: ユーザーシナリオ全体
- **クリティカルパス**: 重要な業務フロー

### テスト戦略
- **リスクベーステスト**: 高リスク領域は100%カバレッジ
- **エッジケーステスト**: 境界値、異常系、同時実行
- **セキュリティテスト**: 入力検証、SQLインジェクション、XSS

...（以下省略）

securityのプロンプト（抜粋）:

あなたはセキュリティ・脆弱性評価専門家『Security』です。

## 任務
脅威モデリングと脆弱性評価を通じて、コードベースに潜むあらゆるリスクを洗い出し、具体的な修正案を提示します。

## 評価基準

### OWASP Top 10 (2021) チェック
1. **Broken Access Control**: 認可チェックの不備、権限昇格の可能性
2. **Cryptographic Failures**: 暗号化の不備、機密データの平文保存
3. **Injection**: SQLインジェクション、コマンドインジェクション、XSS

...（中略）

### セキュアコーディング原則
- 入力検証: すべての外部入力をサニタイズ
- 出力エンコーディング: XSS対策のためのエスケープ処理
- パラメータ化クエリ: SQLインジェクション対策

...（以下省略）

scribeのプロンプト（抜粋）:

あなたは技術文書作成・コミュニケーション専門家『Scribe』です。

## 責務
複雑な技術情報を、対象読者にとって明確で、簡潔で、そして役立つ文書に変換する指導を行います。

## 評価基準

### ドキュメントタイプ
- **README**: プロジェクト概要、クイックスタート、インストール
- **API仕様書**: エンドポイント、リクエスト/レスポンス、認証
- **アーキテクチャドキュメント**: システム概要、コンポーネント図、技術スタック
- **ユーザーガイド**: ステップバイステップ、スクリーンショット、トラブルシューティング

### 文書品質
- **明確性**: 簡潔、具体的、構造化、一貫性
- **完全性**: 網羅性、最新性、正確性
- **使いやすさ**: 検索性、ナビゲーション、例示

...（以下省略）

設定のポイント:

  • 各エージェントは専門分野の知識体系を持つ
  • 評価基準が明確（AWS Well-Architected、OWASP Top 10など）
  • 具体的な手法・ツールを指定
  • 出力形式も定義されている

仕組み:

  • メインエージェント（Kiro）から各専門家（サブエージェント）を必要に応じて呼び出す
  • 各専門家は独立したコンテキストで作業
  • 専門家の成果物をメインエージェントが統合

成果:

  • tmuxの問題を根本解決: あの「ペインが固まる」「会話が上書きされる」問題から解放されました ✅
  • 独立したコンテキスト: これが一番嬉しかった点です。各専門エージェントが独立して作業するので、メインのコンテキストを食い潰さない 🔄
  • 専門性の高いアウトプット: 各分野のエキスパートが担当することで、品質が向上 🎯
  • 必要な時だけ呼び出し: 常時起動ではなく、必要な専門家を都度呼び出す形式 ⚡
  • シンプルな操作: tmux操作不要、コマンド1つで専門家に相談可能 🎯

tmuxでのAIエージェントチーム開発との違い:

項目 tmux（AIエージェントチーム） サブエージェント連携
起動方式 複数AIを常時起動 必要な専門家を都度呼び出し
実行環境 tmuxペイン管理 CLI（直接呼び出し）
コンテキスト 共有（会話空間が同じ） 独立（各専門家が別々）
会話形式 複数AIが同時発言 メイン→サブの1対1
発生した問題 ペイン固まり、会話上書き なし

ちなみに、Gemini CLIでは、~/.gemini/commands/expert/に専門エージェントの設定ファイル（.toml）を配置し、カスタムコマンド機能と非インタラクティブモード（-o text）を組み合わせることで、同様の仕組みを実現しています。

gemini -o text "/expert:architect '
【相談内容】
新規プロジェクトのアーキテクチャ設計について相談したい

【参考資料】
- requirements.md
- 現在検討中の技術スタック案

【相談事項】
- マイクロサービスとモノリスのどちらが適切か
- データベース選定の妥当性
- スケーラビリティの考慮事項
'"

残された課題：真のチーム開発へ

正直に言うと、このサブエージェント連携システムは私が当初構想していた「生成AIエージェントチーム」にはまだ遠く及びません。

項目 現状 私が構想していたもの
呼び出し方式 順次（1対1） 並列（1対多）
タスク実行 1つのAIが順番に処理 複数AIが依存関係を考慮して並列実行
エージェント間連携 なし（結果を返すのみ） 相談・報告・レビュー依頼など双方向
進捗管理 人間が都度確認 オーケストレーターが自動監視＋人間が最終確認

tmuxでの失敗を経て、まずは動くものを形にしました。真のチーム開発の実現は、私の今後の課題として残っています🔜

しかしながら、2025年12月18日にリリースされたKiro CLI v1.23.0で「Subagents」機能が追加されました。
Kiro が複数のサブエージェントを並列実行できるようになったとのことで、本セクションで述べた「真のチーム開発」の実現に近づける可能性が見えてきました。
今後、この機能を活用した並列実行の検証を進めていこうと思います🚀

今日から始める協働生活

ここまで読んで、「自分も試してみたい！」と思った方へ。

試行錯誤から学んだ、始めるためのポイントをまとめました😊

ポイント1: 小さく始める 🌱

まずは1つのタスクから。いきなり大きなプロジェクトに適用するのではなく、小さく始めて感覚を掴みましょう。

おすすめの最初のタスク:

  • 既存コードのドキュメント化
  • 簡単な機能追加（CRUD操作など）
  • テストコード作成
  • リファクタリング

小さなタスクで成功体験を積むことで、生成AIとの協働に自信が持てるようになります😊

ポイント2: 要件を明確にする 📋

「良い感じに」ではなく、「〇〇ができたら完了」と定義しましょう。

完了条件が曖昧なタスクチケットは、人が見ても何をして良いか困る。それはAIだって同じです。

テンプレート:

## タスク
〇〇機能を実装する

## 完了条件
- [ ] 〇〇ができる
- [ ] テストが通る
- [ ] ドキュメントが更新されている
- [ ] コードレビューを通過している

完了条件が明確だと、AIのアウトプットがブレにくくなり、手戻りが減ります😊

ポイント3: 対話を重ねる 💬

一度で完璧に伝えようとせず、対話を重ねて一緒に作り上げていきましょう。

良い例:

ユーザー: 「ログイン機能を実装して」
AI: 「認証方式は何にしますか？」
ユーザー: 「JWT認証で」
AI: 「トークンの有効期限は？」
ユーザー: 「24時間で」

悪い例:

ユーザー: 「ログイン機能を実装して」
（AIが勝手に実装を進める）
ユーザー: 「違う、そうじゃない...」

対話を通じて要件を詰めることで、最初から完璧な指示を考える時間が不要になります😊

ポイント4: ドキュメント化と承認を習慣化する 📄✅

要件・設計・タスクを文書化し、各フェーズで自分自身が承認を挟みましょう。

具体的には:

  • 要件定義 →（確認・承認）→ 設計 →（確認・承認）→ 実装計画 →（確認・承認）→ 実装
  • requirements.md、design.md、tasks.mdを作成
  • tasks.mdで進捗管理（未着手/実装中/完了）

コンテキストがオーバーフローしても、ドキュメントから続きを再開でき、完了済みタスク以降から作業を再開できます😊

ポイント5: 役割を分担する 🤝

複雑なタスクでは、専門エージェントに相談・レビューを依頼しましょう。

具体的には:

  • セキュリティが重要なら security エージェントにレビュー依頼
  • パフォーマンスが重要なら performance エージェントに相談
  • 設計段階で architect エージェントに相談

各専門家が独立したコンテキストで作業するため、メインエージェントのコンテキストウィンドウを節約でき、専門性の高いアウトプットが得られます😊

ポイント6: 振り返りを習慣化し、ルールを育てる 📝

毎回のタスク完了後、振り返りを記録し、学びをルールに反映していきましょう。

振り返りテンプレート:

## 日付: YYYY-MM-DD

### うまくいったこと（Keep）
- 〇〇の指示が明確だった
- AIが期待通りの実装をしてくれた

### うまくいかなかったこと（Problem）
- 〇〇の説明が曖昧だった
- コンテキストがオーバーフローした

### 次回への改善案（Try）
- 完了条件をもっと明確に
- タスクを小さく分割する

ルールへの反映:

  • 振り返りで挙がった改善案を、ルールに盛り込むべきかどうかも生成AIに判断してもらう
  • 「この改善案はルール化すべき？」と聞くと、汎用性や重要度を考慮して判断してくれます

ルールの精査:

  • ルールが増えてきたら「このルール量で問題なく作業できそう？無視しちゃうルールない？」と生成AIに確認
  • 生成AI自身に精査・整理してもらうことで、本当に重要なものだけが残ります

試行錯誤を繰り返すことで、自分なりの最適なルールが育ち、AIとの協働がどんどんスムーズになります😊

おわりに

振り返ってみると、2025年は生成AIとの向き合い方が大きく変わった年でした。

tmuxでの失敗から「ドキュメント化の重要性」を学び、仕様駆動開発で「承認ゲートの価値」に気づき、サブエージェント連携システムで「役割分担の効果」を実感しました。そのひとつひとつの気づきが、今に繋がっています。

その結果、2025年6月から本格活用を始め、現在では私が関わる開発関連のアウトプットをほぼ100%生成AIで生成しています🚀

開発以外でも、以下のような業務で活用し、「呼吸をするように」生成AIを使う日常があります。

  • データ分析・レポート作成（アンケート集計など）
  • プロジェクト管理（Jira・GitHub Issue作成など）
  • ドキュメント・資料作成（プレゼン資料、この記事など）

本当に濃密な数ヶ月間でした。

この記事が、あなたの生成AI活用の一歩を踏み出すきっかけになれば嬉しいです😊

一緒に、生成AIとの協働生活を楽しみましょう！🚀

AI協働生活

参考リンク

記事で紹介したツール

  • Kiro CLI - AWS公式のAI開発支援CLI（Amazon Q Developer CLIの後継）
  • Gemini CLI - Google Cloud公式のAI開発支援CLI

参考にした記事

関連するフレームワーク・ツール

その他の参考資料

17
4
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
17
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?