本日のゴール

今日持ち帰っていただくこと

1. AI 開発の環境整備が成功の鍵 - 型定義・関数のパーツ化でコード品質を保つ
2. Single Source of Truth - DTO を唯一の型定義源とする設計思想
3. パーツ提供の思想 - すべてを自動生成せず、必要なものだけ提供（shadcn/ui 方式）
4. 実測データの説得力 - 47 ファイル移行で 70-79%効率化、バンドル 20-30%削減

前提：仕様書ベースでの開発

このセミナーは、計画ドキュメント（仕様書）をもとに実装する開発スタイルを前提としています。

なぜ仕様書が必要なのか

• 開発時間の短縮: 1 週間 → 2 日（実測データ）
• 手戻りの削減: 平均 3-4 回 → 平均 1 回
• 意思決定の明文化: AI に技術選定を委ねる危険性を回避
• 品質保証: 計画の品質が成果物の品質を決定

参考記事:
AI 協働で仕様書アレルギー克服！開発時間を 1 週間 →2 日に短縮する実践法

2025 年のトレンド：仕様駆動開発

主要なツール

• Kiro（AWS）: エージェント型 AI IDE（2025 年一般提供）
• OpenSpec（GitHub）: GitHub Copilot 統合の仕様駆動ツールキット
• OpenAPI Specification: API 仕様の標準フォーマット

本セミナーのアプローチ

セミナー構成

AI がハチャメチャなコードを出す 3 つの原因

AI 開発の本質的な課題

AI が情報を忘れてしまうリスク

具体的なリスク

• フロントとバックで型定義が異なる
• 既存の実装パターンを無視した新規実装
• 変更時に関連ファイルの更新を忘れる
• コンパイルエラーにならないため、発見が遅れる

解決策: モノレポでコンテキスト一元管理

ポイント: AI に「正しいコンテキスト」を提供する基盤を作る

プロジェクト全体構成（4 つのアプリケーション）

モノレポで一元管理 → AI に全体像を一度に提供

参考記事: AI チャットで話すだけ!X 予約投稿を完全自動化するシステム構築術

モノレポが AI 協業に最適な理由

CLAUDE.md 階層構造の概要

9 つの CLAUDE.md ファイルでコンテキスト管理

CLAUDE.md 階層構造の効果

詳細: モノレポ ×AI 協業環境構築術

モノレポが次のステップの基盤となる

なぜフェーズを分けるのか

従来のペアコーディング（Vibe Coding）の限界

フェーズ分離のメリット

フェーズを分けることで役割を明確化

実際のプロジェクト構造（モノレポ）

workspace/
├── application/          # 実装コード（4つのアプリ）
│   ├── frontend/        # Next.js 15 + React 19
│   ├── backend/         # NestJS 11
│   ├── x-scheduler/     # Azure Functions
│   └── mcp-functions/   # Azure Functions
├── docs/                # 計画・知見
│   ├── features/        # 機能仕様書
│   ├── research/        # 実装レビュー
│   ├── data/            # 調査データ
│   └── templates/       # テンプレート
├── CLAUDE.md            # ルートレベル設定
└── package.json         # モノレポ設定

ディレクトリ分離の 3 つの利点

フェーズ分離の実践的メリット

モノレポと 3 フェーズの組み合わせ

Backend DTOs を唯一の真実とする

ステップ 1: DTO を唯一の型定義源とする

DTO クラスがすべての型定義のマスター

役割

• デコレーターから制約情報も自動抽出
• OpenAPI Spec に自動変換
• すべての型定義の起点

AI との協業

AI は DTO クラスを編集するだけで、フロントエンドの型定義が自動更新されることを理解

重要: エラー型設計の必要性

なぜエラー型が重要なのか

自動生成パイプラインを構築しても、エラー型を定義しなければ型安全性が崩壊する

問題: エラー型が自動生成されない

フロントエンド実装が破綻

実際に起きた深刻な影響

解決: RFC 7807 準拠の統一エラー型

エラー型の実装方法

実装のポイント

重要

エラー型を定義しないと、自動生成パイプラインの恩恵が半減する

エラー型定義の効果

try {
  await api.createUser(data);
} catch (error: any) {
  // errorが何を持っているか不明
  console.error(error.message);
  // ↑ 実行時エラーの可能性
}

try {
  await api.createUser(data);
} catch (error: ApiError) {
  // errorの型が明確
  console.error(error.detail);
  // ↑ IDEの補完が効く
  // AIも正しいコードを生成
}

結論: 仕様書と DTO の品質が全て

レビューで品質を担保する

結論: ちゃんと仕様書も作ろう！DTO の質の担保（レビュー）をしっかりと！

ステップ 2: 型・関数のパーツ化（Orval の役割）

Orval とは: OpenAPI 仕様から TypeScript コード自動生成

ステップ 3: AI への通知と制御

2 つのアプローチ

1. DO NOT EDIT コメント：ファイル先頭に警告
2. CLAUDE.md での明文化：AI へのルール提示

アプローチ 1: DO NOT EDIT コメント

自動生成ファイルの先頭に警告コメントを挿入

/**
 * DO NOT EDIT THIS FILE
 *
 * This file is auto-generated from OpenAPI specification.
 * If you need to make changes, edit the DTO in backend/
 * and run `npm run generate:api` to regenerate this file.
 */

効果: AI がファイルを読んだ際に、編集してはいけないことを理解

アプローチ 2: CLAUDE.md での明文化

プロジェクトルールとして記述

## 自動生成ファイル

以下のファイルは自動生成されています。直接編集しないでください：

- `lib/api/generated.ts`
- `types/generated/`

変更が必要な場合：

1. `backend/` の DTO を修正
2. `npm run generate:api` で再生成

効果: AI が CLAUDE.md を読み込んだ時点でルールを把握

重要：AI は約 10-20%の確率で無視する

パーツ提供の考え方（shadcn/ui との類似性）

shadcn/ui の成功と同じアプローチ

なぜパーツ化が必要なのか

家具づくりの比喩で理解する

Part 3 の本質: 人間の判断が必要な領域

パーツの質は人間次第

実例: 粗悪なパーツを作っていた失敗

初期設定: 全 API エンドポイントに SWR フック自動生成

最適化された設定

Orval 設定の変更

mode: "single" → 直接エクスポート
client: "axios-functions" → パーツのみ生成（型定義 + Axios 関数）

パーツ化の Before / After

適材適所のアプローチ

結果: 自動生成フック 41 個 → 9 個（必要な分だけ手動実装）

パーツ化最適化の効果

なぜこれほど効率化できたのか

Axios の関数がパーツとして提供されていた

• AI に実装を任せる際もスムーズに進行
• 型定義が自動生成されているため、型エラーで即座に問題検出

AI がハチャメチャなコードを出さなくなった実体験

実感した変化

• 型定義の齟齬がなくなった
• フロントエンドで型定義ファイルが増殖しなくなった
• すっきりとしたコードで実装できるようになった

重要ポイントの整理

環境整備

1. モノレポ構成で AI に全体像を提供
2. CLAUDE.md 階層構造でコンテキスト管理
3. docs/ と application/ の分離

パイプライン

4. Single Source of Truth（DTO → OpenAPI → Frontend）
5. パーツ提供の思想（shadcn/ui 方式）
6. エラー型設計で型安全性確保

段階的導入ステップ

Step 1: 基本パイプラインの構築（1-2 日）

1. Backend DTO クラス作成
2. OpenAPI 生成設定
3. Orval 設定（mode: "single", client: "axios-functions"）
4. エラー型定義

Step 2: 既存コードの移行（規模による）

1. 小さな機能から移行開始
2. 効果を実感しながら拡大
3. チーム全体で共有

よくある質問

今日から試せること

小さく始める

1. 1 つの API エンドポイントで DTO クラス作成
2. OpenAPI 生成を試してみる
3. Orval で型定義生成を確認
4. 効果を実感したら拡大

重要: 完璧を目指さず、小さく始めて効果を実感することが成功の鍵

4 フェーズ目: 記事化フェーズ

検証結果を知見として資産化

参考記事:
検証 → 記事化で知見を資産化！Claude Code×RAG もどきで AI 技術ブログ執筆を効率化

フェーズ 3: 研究記録（/docs/research/）

フェーズ 4: 記事化（/docs/article/）

4 フェーズワークフローの効果

測定条件: 中規模記事（800-1000 行）での実測値

開発者の実感

AI 協業開発手法シリーズ

環境構築・ワークフロー

• モノレポ ×AI 協業環境構築術
  CLAUDE.md 階層構造、モノレポと AI 協業の相性、コンテキスト管理

• 明日から始められる 3 フェーズ開発手法
  計画・実装・検証の 3 フェーズ詳細、フェーズ分離のメリット

• AI 協働で仕様書アレルギー克服！開発時間を 1 週間 →2 日に短縮
  仕様書ベース開発の効果測定、手戻り削減の実測データ

• 検証 → 記事化で知見を資産化！Claude Code×RAG もどき
  4 フェーズワークフロー、RAG もどきシステム、記事執筆効率化

技術実装・パイプライン構築

自動生成パイプライン

• AI 開発で型定義を同期！DTO から OpenAPI・Frontend まで完全自動化
  DTO → OpenAPI → Frontend 型定義の自動生成、エラー型設計の重要性

• Orval 設定最適化でバンドル 20-30%削減！
  SWR フック自動生成からパーツ提供へ移行、47 ファイル移行で 70-79%効率化

プロジェクト事例

• AI チャットで話すだけ!X 予約投稿を完全自動化
  Azure Functions v4、Next.js 15 + NestJS 11、本セミナーの実例プロジェクト

Spec 駆動開発関連リソース

ツール・フレームワーク

• AWS Kiro - エージェント型 AI IDE（AWS、2025 年一般提供）
• GitHub Spec Kit - 仕様駆動ツールキット（GitHub Copilot 統合）
• OpenAPI Initiative - API 仕様の標準フォーマット（Linux Foundation）
• RFC 7807 - HTTP API のエラー型標準（IETF）

使用技術

• Orval - OpenAPI 仕様から TypeScript コード自動生成
• NestJS - Node.js フレームワーク（DTO・OpenAPI 生成）
• shadcn/ui - パーツ提供思想の UI ライブラリ

さらに学ぶためのリソース

• SIOS Tech Lab（技術ブログ）
  AI 協業開発シリーズを連載中、実測データに基づく実践的な記事

• 本セミナーのスライド
  本日の資料を Web 公開、SVG 図解もすべて利用可能