AI開発ツール活用 2025年12月16日

AI支援開発成功事例②：新規プロダクト開発

本章では、AIコーディングツールを活用したAPI設計とドキュメント整備の実践的なワークフローを紹介します。 **注記**: 本章はAI活用テクニックを解説するためのチュートリアルです。具体的な生産性向上の数値については、実在企業の調査データ（Vol.6 第8章参照）をご確認ください。

川

川西智也

合同会社ロイヤルピース 代表

実践例②：API設計とドキュメント

本章では、AIコーディングツールを活用したAPI設計とドキュメント整備の実践的なワークフローを紹介します。

注記: 本章はAI活用テクニックを解説するためのチュートリアルです。具体的な生産性向上の数値については、実在企業の調査データ（Vol.6 第8章参照）をご確認ください。

よくある課題

課題:

  • 既存APIの一貫性がない
  • ドキュメントが古い/存在しない
  • 新規開発者のオンボーディングに時間がかかる

目標:

  • RESTful API設計の標準化
  • OpenAPI仕様書の自動生成
  • APIドキュメントの整備

技術スタック例:

  • Node.js + Express
  • TypeScript
  • OpenAPI 3.0
  • Swagger UI

フェーズ1: API設計標準の策定

10.2.1 Claude Codeで設計ガイドライン作成

プロンプト:
RESTful API設計のガイドラインを作成してください。

要件:
- リソース命名規則（複数形、ケバブケース）
- HTTPメソッドの使い分け
- ステータスコードの標準化
- エラーレスポンスの形式
- ページネーションの実装
- バージョニング戦略

対象: Node.js + Express + TypeScript

10.2.2 生成されたガイドラインの例

## API設計ガイドライン

### 1. リソース命名
- 複数形を使用: /users, /orders
- ケバブケース: /user-profiles
- ネストは2階層まで: /users/{id}/orders

### 2. HTTPメソッド
- GET: 取得（冪等）
- POST: 作成
- PUT: 全体更新（冪等）
- PATCH: 部分更新
- DELETE: 削除（冪等）

### 3. ステータスコード
- 200: 成功
- 201: 作成成功
- 204: 成功（レスポンスボディなし）
- 400: リクエスト不正
- 401: 認証エラー
- 403: 権限エラー
- 404: リソースなし
- 422: バリデーションエラー
- 500: サーバーエラー

### 4. エラーレスポンス形式
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力値が不正です",
    "details": [
      { "field": "email", "message": "有効なメールアドレスを入力してください" }
    ]
  }
}

フェーズ2: OpenAPI仕様書生成

10.3.1 既存APIの分析

プロンプト:
@src/routes/

このディレクトリ内のすべてのAPIエンドポイントを分析し、
OpenAPI 3.0仕様書を生成してください。

各エンドポイントについて:
- パス
- HTTPメソッド
- リクエストパラメータ
- レスポンス形式
- エラーケース

10.3.2 生成されたOpenAPI仕様

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
  description: ユーザー管理のためのRESTful API

paths:
  /users:
    get:
      summary: ユーザー一覧取得
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'

    post:
      summary: ユーザー作成
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 作成成功
        '422':
          description: バリデーションエラー

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

フェーズ3: 型定義とバリデーション

10.4.1 OpenAPIからTypeScript型生成

プロンプト:
OpenAPI仕様書から以下を生成してください:

1. TypeScript型定義
2. Zodバリデーションスキーマ
3. Express用のリクエストハンドラ型

@docs/openapi.yaml を参照

10.4.2 生成されたコード

// types/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

export interface CreateUserRequest {
  email: string;
  name: string;
  password: string;
}

export interface UserListResponse {
  data: User[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

// schemas/user.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  email: z.string().email('有効なメールアドレスを入力してください'),
  name: z.string().min(1, '名前は必須です').max(100),
  password: z.string().min(8, 'パスワードは8文字以上')
});

export const userQuerySchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().positive().max(100).default(20)
});

フェーズ4: ドキュメント整備

10.5.1 自動ドキュメント生成

プロンプト:
APIドキュメントを開発者向けに整備してください。

含めるべき内容:
1. クイックスタートガイド
2. 認証方法の説明
3. 各エンドポイントの使用例（curlコマンド）
4. エラーハンドリングのガイド
5. レート制限の説明
6. SDKの使い方（あれば）

対象読者: 社内の他チームの開発者

10.5.2 生成されたドキュメント例

# User Management API ドキュメント

## クイックスタート

### 1. 認証トークンの取得

curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

### 2. ユーザー一覧の取得

curl https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN"

### 3. ユーザーの作成

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com", "name": "New User", "password": "securepass123"}'

## エラーハンドリング

すべてのエラーは統一された形式で返されます:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人間が読めるメッセージ",
    "details": []
  }
}

## レート制限

- 認証済みユーザー: 1000リクエスト/時間
- 未認証: 100リクエスト/時間
- レート制限超過時: 429 Too Many Requests

効果的な開発プラクティス

10.6.1 段階的アプローチ

  1. 段階的アプローチ: 一度にすべてを変えない
  2. ガイドライン先行: 実装前に設計を合意
  3. 自動化: ドキュメント生成の自動化
  4. レビュー重視: AI出力を必ず人間がレビュー

10.6.2 実際の効果

API設計とドキュメント整備における実際の効果については、以下を参照：

出典: Duolingo Customer Story

Duolingoでの実績:
- 新規コードベース担当者の開発速度: 25%向上
- コードレビュー時間（中央値）: 67%短縮

再現のためのプロンプト集

10.7.1 API設計レビュー

以下のAPIエンドポイントをレビューしてください。

チェック項目:
- RESTful設計原則への準拠
- 命名規則の一貫性
- 適切なHTTPメソッドの使用
- エラーハンドリングの網羅性
- セキュリティ考慮（認証、認可）

改善提案がある場合は具体的なコード例も示してください。

10.7.2 OpenAPI生成

以下のExpressルーターからOpenAPI 3.0仕様を生成してください。

要件:
- すべてのパラメータを文書化
- レスポンススキーマを定義
- エラーレスポンスも含める
- 説明文は日本語

@src/routes/[ファイル名]

10.7.3 APIドキュメント生成

OpenAPI仕様書から開発者向けドキュメントを生成してください。

形式: Markdown
含める内容:
- 概要
- 認証方法
- 各エンドポイントの使用例（curl）
- エラーコード一覧
- FAQ

@docs/openapi.yaml

まとめ：重要ポイントの振り返り

  • 設計標準化: AIでガイドライン作成を加速
  • OpenAPI生成: 既存コードから仕様書を自動生成
  • 型とバリデーション: 仕様から型・スキーマを生成
  • ドキュメント整備: 自動化で常に最新を維持
  • 実際の効果: Vol.6 第8章の実在企業データを参照
  • 教訓：AIはAPI設計の標準化と文書化を強力に支援する

関連記事

AI開発ツール活用

AI支援開発成功事例①：レガシーシステム刷新

本章では、AIコーディングツールを活用した新規アプリ開発の実践的なワークフローを紹介します。 **注記**: 本章はAI活用テクニックを解説するためのチュートリアルです。具体的な生産性向上の数値については、実在企業の調査データ（Vol.6 第8章参照）をご確認ください。
AI開発ツール活用

AI支援開発成功事例③：チーム生産性向上

本章では、AIコーディングツールを活用した複雑なバグ調査と修正の実践的なワークフローを紹介します。 **注記**: 本章はAI活用テクニックを解説するためのチュートリアルです。具体的な生産性向上の数値については、実在企業の調査データ（Vol.6 第8章参照）をご確認ください。

実践的なスキルを習得しませんか？

ブログで学んだ知識を、研修で実践に変えましょう。

研修内容を見る 無料相談を申し込む