DEV Community: myougaTheAxo

Claude Codeで非同期ジョブパターンを設計する：長時間処理の非同期化・ポーリング・Webhook通知

myougaTheAxo — Thu, 19 Mar 2026 12:00:00 +0000

はじめに

「PDF生成処理が30秒かかってタイムアウトする」「レポート生成中にユーザーが待ちきれず何度もボタンを押す」——長時間処理を非同期ジョブとして切り出し、ポーリングまたはWebhookで完了を通知する設計をClaude Codeに生成させる。

CLAUDE.mdに非同期ジョブパターン設計ルールを書く

## 非同期ジョブパターン設計ルール

### ジョブ登録
- 長時間処理（>2秒）は非同期ジョブに変換
- 即座にジョブIDを返す（202 Accepted）
- ジョブIDでステータスをポーリング可能

### ステータス管理
- PENDING → RUNNING → COMPLETED / FAILED
- 実行中は進捗率（0-100%）も提供
- 失敗時はエラー詳細を記録

### 通知
- ポーリング: GET /jobs/{id} でステータス確認
- Webhook: 完了時にクライアントのURLにPOST
- SSE: クライアントが接続中はリアルタイムでプッシュ

非同期ジョブ実装の生成

非同期ジョブシステムを設計してください。

要件：
- ジョブキューとワーカー
- ステータスポーリングAPI
- Webhook通知
- 進捗追跡

生成ファイル: src/jobs/

生成される非同期ジョブ実装

// src/jobs/jobManager.ts — ジョブ管理

export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';

export interface Job<TInput = unknown, TOutput = unknown> {
  id: string;
  type: string;
  status: JobStatus;
  input: TInput;
  output?: TOutput;
  progress: number;       // 0-100
  errorMessage?: string;
  createdAt: Date;
  startedAt?: Date;
  completedAt?: Date;
  webhookUrl?: string;    // 完了時の通知先
}

export class JobManager {
  // ジョブを登録（即座にIDを返す）
  async enqueue<TInput>(jobType: string, input: TInput, options: {
    webhookUrl?: string;
    priority?: 'normal' | 'high';
  } = {}): Promise<{ jobId: string }> {
    const jobId = ulid();
    const job: Job<TInput> = {
      id: jobId,
      type: jobType,
      status: 'pending',
      input,
      progress: 0,
      createdAt: new Date(),
      webhookUrl: options.webhookUrl,
    };

    // DBに保存
    await prisma.job.create({
      data: {
        id: jobId,
        type: jobType,
        status: 'pending',
        input: JSON.stringify(input),
        progress: 0,
        createdAt: new Date(),
        webhookUrl: options.webhookUrl,
      },
    });

    // ジョブキューに追加
    const queueKey = options.priority === 'high' ? 'queue:jobs:high' : 'queue:jobs:normal';
    await redis.xAdd(queueKey, '*', {
      jobId,
      jobType,
      payload: JSON.stringify(input),
    });

    logger.info({ jobId, jobType }, 'Job enqueued');
    return { jobId };
  }

  // ジョブステータスを取得
  async getStatus(jobId: string): Promise<Job | null> {
    const row = await prisma.job.findUnique({ where: { id: jobId } });
    if (!row) return null;

    return {
      id: row.id,
      type: row.type,
      status: row.status as JobStatus,
      input: JSON.parse(row.input),
      output: row.output ? JSON.parse(row.output) : undefined,
      progress: row.progress,
      errorMessage: row.errorMessage ?? undefined,
      createdAt: row.createdAt,
      startedAt: row.startedAt ?? undefined,
      completedAt: row.completedAt ?? undefined,
      webhookUrl: row.webhookUrl ?? undefined,
    };
  }

  // 進捗を更新（ワーカーから呼び出す）
  async updateProgress(jobId: string, progress: number): Promise<void> {
    await prisma.job.update({
      where: { id: jobId },
      data: { progress: Math.min(100, Math.max(0, progress)) },
    });

    // SSEクライアントに通知
    sseManager.broadcast(jobId, { type: 'progress', progress });
  }

  // ジョブ完了（ワーカーから呼び出す）
  async complete<TOutput>(jobId: string, output: TOutput): Promise<void> {
    const job = await prisma.job.update({
      where: { id: jobId },
      data: {
        status: 'completed',
        output: JSON.stringify(output),
        progress: 100,
        completedAt: new Date(),
      },
    });

    // SSEクライアントに通知
    sseManager.broadcast(jobId, { type: 'completed', output });

    // Webhook通知
    if (job.webhookUrl) {
      await this.sendWebhook(job.webhookUrl, {
        jobId,
        status: 'completed',
        output,
        completedAt: new Date().toISOString(),
      });
    }
  }

  async fail(jobId: string, errorMessage: string): Promise<void> {
    const job = await prisma.job.update({
      where: { id: jobId },
      data: { status: 'failed', errorMessage, completedAt: new Date() },
    });

    sseManager.broadcast(jobId, { type: 'failed', errorMessage });

    if (job.webhookUrl) {
      await this.sendWebhook(job.webhookUrl, { jobId, status: 'failed', errorMessage });
    }
  }

  private async sendWebhook(url: string, payload: unknown): Promise<void> {
    try {
      await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'X-Myouga-Event': 'job.completed' },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(5000),
      });
    } catch (error) {
      logger.error({ url, error }, 'Webhook delivery failed');
    }
  }
}

// APIエンドポイント
const jobManager = new JobManager();

// ジョブ登録: 202 Acceptedで即座にIDを返す
router.post('/api/reports/generate', requireAuth, async (req, res) => {
  const { startDate, endDate, webhookUrl } = req.body;

  const { jobId } = await jobManager.enqueue('generate-report', {
    startDate, endDate, userId: req.user.id,
  }, { webhookUrl });

  res.status(202).json({
    jobId,
    statusUrl: `/api/jobs/${jobId}`,
    message: 'Report generation started',
  });
});

// ポーリング: ステータス確認
router.get('/api/jobs/:jobId', requireAuth, async (req, res) => {
  const job = await jobManager.getStatus(req.params.jobId);

  if (!job) return res.status(404).json({ error: 'Job not found' });

  res.json({
    jobId: job.id,
    status: job.status,
    progress: job.progress,
    output: job.status === 'completed' ? job.output : undefined,
    error: job.status === 'failed' ? job.errorMessage : undefined,
    createdAt: job.createdAt,
    completedAt: job.completedAt,
  });
});

// SSE: リアルタイム進捗ストリーム
router.get('/api/jobs/:jobId/stream', requireAuth, async (req, res) => {
  res.set({
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  });

  sseManager.subscribe(req.params.jobId, (event) => {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
    if (event.type === 'completed' || event.type === 'failed') {
      res.end();
    }
  });

  req.on('close', () => sseManager.unsubscribe(req.params.jobId));
});

まとめ

Claude Codeで非同期ジョブパターンを設計する：

CLAUDE.md に2秒超の処理は非同期ジョブ化・202 Acceptedでジョブを即座に返す・ポーリング/Webhook/SSEの3方式で完了を通知を明記
202 Accepted + jobId パターンでクライアントを即座に解放——PDF生成中に「30秒待ってください」ではなく「ジョブを受け付けました。/api/jobs/01H...で確認してください」とすぐ返答
ポーリング→SSE→Webhook の3方式で異なるクライアントに対応——ブラウザはSSEでリアルタイム更新、バックエンドサービスはWebhookで自動通知、古いクライアントはポーリング
進捗率（0-100%） でUXを改善——「処理中...」ではなく「45%完了」を表示することでユーザーの不安を軽減。updateProgress()を処理の節目に呼ぶ

信頼性設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeで集約を設計する：集約境界の決定・不変条件の保護・集約間の参照

myougaTheAxo — Thu, 19 Mar 2026 11:00:00 +0000

はじめに

「集約の境界をどこで引くか迷う」「集約Aから集約Bの内部を変更している」——DDDの集約設計で不変条件を守り、集約間の正しい参照方法を設計をClaude Codeに生成させる。

CLAUDE.mdに集約設計ルールを書く

## 集約設計ルール

### 集約境界の決定基準
- 同時に変更される必要があるエンティティをひとまとめにする
- 集約は小さく保つ（大きすぎると競合が多発）
- 集約のルート（Aggregate Root）のみが外部から直接参照される

### 不変条件
- 集約内の全エンティティの整合性を保証するビジネスルール
- 不変条件の検証は集約ルートのメソッドで行う
- 外部から集約の内部エンティティを直接変更しない

### 集約間の参照
- 集約間はIDのみで参照（直接の集約オブジェクト参照禁止）
- 複数集約にまたがる操作はアプリケーション層（ユースケース）で調整
- 集約間の整合性は結果整合（eventual consistency）

集約設計実装の生成

集約設計のベストプラクティスを実装してください。

要件：
- 集約ルートによる不変条件の保護
- 内部エンティティへのアクセス制限
- 集約間のID参照
- コレクション変更の制御

生成ファイル: src/domain/aggregates/

生成される集約設計実装

// src/domain/aggregates/order/order.ts — 集約ルート

// エラー: OrderItemは集約内部エンティティ（外部から直接操作しない）
class OrderItem {
  private constructor(
    private readonly _id: string,
    private readonly _productId: string,    // 商品集約のID参照（集約オブジェクトは持たない）
    private _quantity: number,
    private readonly _price: Money
  ) {}

  static create(productId: string, quantity: number, price: Money): OrderItem {
    if (quantity <= 0) throw new DomainError('Quantity must be positive');
    return new OrderItem(ulid(), productId, quantity, price);
  }

  increaseQuantity(amount: number): void {
    if (amount <= 0) throw new DomainError('Increase amount must be positive');
    this._quantity += amount;
  }

  get id(): string { return this._id; }
  get productId(): string { return this._productId; }
  get quantity(): number { return this._quantity; }
  get subtotal(): Money { return this._price.multiply(this._quantity); }
}

// 集約ルート
export class Order extends AggregateRoot {
  private _items: OrderItem[];
  private _status: OrderStatus;

  private constructor(
    private readonly _id: string,
    private readonly _userId: string,    // User集約のID参照
    items: OrderItem[],
    status: OrderStatus
  ) {
    super();
    this._items = items;
    this._status = status;
  }

  static create(userId: string, initialItems: Array<{ productId: string; quantity: number; price: Money }>): Order {
    if (initialItems.length === 0) {
      throw new DomainError('Order must have at least one item');
    }
    if (initialItems.length > 100) {
      throw new DomainError('Order cannot have more than 100 items');
    }

    const items = initialItems.map(i => OrderItem.create(i.productId, i.quantity, i.price));
    const order = new Order(ulid(), userId, items, 'draft');

    order.addDomainEvent({
      eventId: ulid(),
      eventType: 'OrderCreated',
      occurredAt: new Date(),
      orderId: order._id,
      userId,
      totalAmount: order.total,
    });

    return order;
  }

  // 集約ルートを通じた操作（内部エンティティを外部から直接変更しない）
  addItem(productId: string, quantity: number, price: Money): void {
    if (this._status !== 'draft') {
      throw new DomainError(`Cannot add items to order in status '${this._status}'`);
    }

    // 不変条件: アイテム数の上限
    if (this._items.length >= 100) {
      throw new DomainError('Order cannot have more than 100 items');
    }

    const existingItem = this._items.find(i => i.productId === productId);
    if (existingItem) {
      // 既存商品の数量を増やす
      existingItem.increaseQuantity(quantity);
    } else {
      this._items.push(OrderItem.create(productId, quantity, price));
    }
  }

  removeItem(productId: string): void {
    if (this._status !== 'draft') {
      throw new DomainError(`Cannot remove items from order in status '${this._status}'`);
    }

    const index = this._items.findIndex(i => i.productId === productId);
    if (index === -1) throw new NotFoundError(`Item with productId ${productId} not found`);

    this._items.splice(index, 1);

    // 不変条件: アイテムが0になったらキャンセル
    if (this._items.length === 0) {
      this._status = 'cancelled';
    }
  }

  submit(): void {
    if (this._status !== 'draft') throw new DomainError('Can only submit draft orders');

    // 不変条件: 提出前に少なくとも1アイテムが必要
    if (this._items.length === 0) throw new DomainError('Cannot submit empty order');

    this._status = 'pending_payment';
    this.addDomainEvent({
      eventId: ulid(), eventType: 'OrderSubmitted', occurredAt: new Date(),
      orderId: this._id, total: this.total,
    });
  }

  // コレクションを外部に返す場合は読み取り専用コピー（防御的コピー）
  get items(): ReadonlyArray<{ id: string; productId: string; quantity: number; subtotal: Money }> {
    return this._items.map(item => ({
      id: item.id,
      productId: item.productId,
      quantity: item.quantity,
      subtotal: item.subtotal,
    }));
  }

  get total(): Money {
    if (this._items.length === 0) return Money.zero('JPY');
    return this._items.reduce((sum, item) => sum.add(item.subtotal), Money.zero('JPY'));
  }

  get id(): string { return this._id; }
  get userId(): string { return this._userId; }
  get status(): OrderStatus { return this._status; }
}

// 間違った設計の例（集約外から内部を操作 — やってはいけない）
// ❌ order.items[0].increaseQuantity(2); // 直接OrderItemを変更

// 正しい設計
// ✅ order.addItem('prod-123', 2, price); // 集約ルート経由で操作

// 集約間の正しい参照（IDのみ）

// ❌ 間違い: 集約Aが集約Bのオブジェクトを直接持つ
class Order {
  private _user: User;  // Userオブジェクトを直接参照 → やってはいけない
}

// ✅ 正しい: IDのみを持ち、必要な時にリポジトリで取得
class Order {
  private readonly _userId: string;  // UserのIDのみ
}

// 複数集約にまたがる操作はアプリケーション層で調整
export class ShipOrderUseCase {
  async execute(orderId: string): Promise<void> {
    return UnitOfWorkFactory.run(async (uow) => {
      // Order集約
      const order = await uow.orderRepository.findById(orderId);

      // Inventory集約（Order集約は直接持たない、IDで取得）
      for (const item of order.items) {
        const inventory = await uow.inventoryRepository.findByProductId(item.productId);
        inventory.deductStock(Quantity.of(item.quantity, 'piece'));
        await uow.inventoryRepository.save(inventory);
      }

      order.ship();
      await uow.orderRepository.save(order);
    });
  }
}

まとめ

Claude Codeで集約を設計する：

CLAUDE.md に集約ルートのみが外部から参照可能・内部エンティティへの直接変更禁止・集約間はIDのみで参照・集約間の操作はアプリ層で調整を明記
不変条件をメソッドで保護 order.addItem()内でアイテム数100未満チェック——外部からorder._items.push()を許してしまうと不変条件を守れない。状態変更は必ず集約ルートのメソッド経由
防御的コピー（get items） で内部コレクションをReadonlyArrayとして公開——外部がorder.items.push(newItem)でコレクションを直接変更できないようにする。内部状態を完全にカプセル化
集約間のIDのみ参照 でトランザクション境界を明確化——order._userIdはUserオブジェクトではなくstring。UserのロードはリポジトリがUser集約のトランザクションで行い、Orderのトランザクションに混在しない

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでエラー分類システムを設計する：運用エラーvsプログラマーエラー・エラーカタログ・一貫したAPIエラーレスポンス

myougaTheAxo — Thu, 19 Mar 2026 10:00:00 +0000

はじめに

「エラーハンドリングがバラバラでAPIが一貫したエラーを返さない」「500エラーと400エラーが混在していて原因が追えない」——エラーを体系的に分類し、一貫したエラーレスポンスとロギングを設計をClaude Codeに生成させる。

CLAUDE.mdにエラー分類設計ルールを書く

## エラー分類設計ルール

### エラーの種類
- Operational Error（運用エラー）: 予期される失敗（バリデーション、認証失敗、NotFound）
  → ユーザーにエラーを返す。ログはWARNレベル
- Programmer Error（プログラマーエラー）: バグ（NullPointer、型エラー）
  → 500エラー。ログはERRORレベル。Sentryに通知

### エラーカタログ
- エラーコードを定義（例: USER_NOT_FOUND, INSUFFICIENT_BALANCE）
- コード、HTTPステータス、メッセージのマッピング
- エラーコードはドキュメント化してフロントエンドと共有

### レスポンス形式
- { code: string, message: string, details?: object }
- エラーコードはアルファベット大文字スネークケース
- 内部エラーの詳細は本番で非表示（devのみ表示）

エラー分類システム実装の生成

エラー分類システムを設計してください。

要件：
- Operational/Programmerエラーの分離
- エラーカタログ
- 一貫したAPIエラーレスポンス
- エラーミドルウェア

生成ファイル: src/errors/

生成されるエラー分類システム実装

// src/errors/appError.ts — アプリケーションエラー基底

export class AppError extends Error {
  readonly isOperational: boolean;  // true = 運用エラー、false = プログラマーエラー

  constructor(
    message: string,
    readonly code: string,
    readonly statusCode: number,
    readonly details?: Record<string, unknown>,
    isOperational = true
  ) {
    super(message);
    this.name = this.constructor.name;
    this.isOperational = isOperational;
    Error.captureStackTrace(this, this.constructor);
  }
}

// エラーカタログ定義
export const ErrorCatalog = {
  // 認証・認可 (401, 403)
  UNAUTHORIZED:           { code: 'UNAUTHORIZED', status: 401, message: '認証が必要です' },
  FORBIDDEN:              { code: 'FORBIDDEN', status: 403, message: 'この操作を行う権限がありません' },
  INVALID_TOKEN:          { code: 'INVALID_TOKEN', status: 401, message: 'トークンが無効または期限切れです' },

  // リソース (404, 409)
  NOT_FOUND:              { code: 'NOT_FOUND', status: 404, message: 'リソースが見つかりません' },
  ALREADY_EXISTS:         { code: 'ALREADY_EXISTS', status: 409, message: 'リソースが既に存在します' },
  CONFLICT:               { code: 'CONFLICT', status: 409, message: 'データが競合しています' },

  // バリデーション (400)
  VALIDATION_ERROR:       { code: 'VALIDATION_ERROR', status: 400, message: '入力値が正しくありません' },
  INVALID_PARAMETER:      { code: 'INVALID_PARAMETER', status: 400, message: 'パラメーターが無効です' },

  // ビジネスロジック (422)
  INSUFFICIENT_BALANCE:   { code: 'INSUFFICIENT_BALANCE', status: 422, message: '残高が不足しています' },
  OUT_OF_STOCK:           { code: 'OUT_OF_STOCK', status: 422, message: '在庫が不足しています' },
  INVALID_STATE:          { code: 'INVALID_STATE', status: 422, message: '現在の状態では操作できません' },
  PAYMENT_FAILED:         { code: 'PAYMENT_FAILED', status: 422, message: '決済に失敗しました' },

  // レート制限 (429)
  RATE_LIMIT_EXCEEDED:    { code: 'RATE_LIMIT_EXCEEDED', status: 429, message: 'リクエスト制限を超えました' },

  // サービス利用不可 (503)
  SERVICE_UNAVAILABLE:    { code: 'SERVICE_UNAVAILABLE', status: 503, message: 'サービスが一時的に利用できません' },
} as const;

// エラーファクトリー
export function createError(
  catalog: (typeof ErrorCatalog)[keyof typeof ErrorCatalog],
  details?: Record<string, unknown>
): AppError {
  return new AppError(catalog.message, catalog.code, catalog.status, details);
}

// 具体的なエラークラス
export class NotFoundError extends AppError {
  constructor(resource: string, id?: string) {
    super(
      `${resource}${id ? ` (${id})` : ''} not found`,
      ErrorCatalog.NOT_FOUND.code,
      ErrorCatalog.NOT_FOUND.status,
      { resource, id }
    );
  }
}

export class ValidationError extends AppError {
  constructor(violations: Array<{ field: string; message: string }>) {
    super(
      ErrorCatalog.VALIDATION_ERROR.message,
      ErrorCatalog.VALIDATION_ERROR.code,
      ErrorCatalog.VALIDATION_ERROR.status,
      { violations }
    );
  }
}

export class ConflictError extends AppError {
  constructor(message: string, details?: Record<string, unknown>) {
    super(message, ErrorCatalog.CONFLICT.code, ErrorCatalog.CONFLICT.status, details);
  }
}

export class InsufficientBalanceError extends AppError {
  constructor(required: Money, available: Money) {
    super(
      ErrorCatalog.INSUFFICIENT_BALANCE.message,
      ErrorCatalog.INSUFFICIENT_BALANCE.code,
      ErrorCatalog.INSUFFICIENT_BALANCE.status,
      { required: required.toValue(), available: available.toValue() }
    );
  }
}

// src/errors/errorMiddleware.ts — Expressエラーミドルウェア

export interface ErrorResponse {
  code: string;
  message: string;
  details?: unknown;
  requestId?: string;
  // 本番では非表示
  stack?: string;
}

export function errorMiddleware(
  error: Error,
  req: Request,
  res: Response,
  _next: NextFunction
): void {
  const requestId = req.headers['x-request-id'] as string ?? ulid();

  if (error instanceof AppError && error.isOperational) {
    // 運用エラー: ユーザーに詳細を返す
    logger.warn({
      requestId,
      code: error.code,
      statusCode: error.statusCode,
      url: req.url,
      method: req.method,
    }, `Operational error: ${error.message}`);

    const response: ErrorResponse = {
      code: error.code,
      message: error.message,
      requestId,
    };

    if (error.details) {
      response.details = error.details;
    }

    res.status(error.statusCode).json(response);
    return;
  }

  // プログラマーエラー / 未知のエラー: 詳細を隠して500を返す
  logger.error({
    requestId,
    error: error.message,
    stack: error.stack,
    url: req.url,
    method: req.method,
  }, 'Unexpected error');

  // エラー監視サービスに通知
  sentryClient.captureException(error, { extra: { requestId } });

  const response: ErrorResponse = {
    code: 'INTERNAL_SERVER_ERROR',
    message: 'An unexpected error occurred',
    requestId,
    // 開発環境のみスタックトレースを含める
    ...(process.env.NODE_ENV === 'development' ? { stack: error.stack } : {}),
  };

  res.status(500).json(response);
}

// Zodバリデーションエラーの変換
export function zodErrorToValidationError(zodError: ZodError): ValidationError {
  const violations = zodError.issues.map(issue => ({
    field: issue.path.join('.'),
    message: issue.message,
  }));
  return new ValidationError(violations);
}

// 使用例
app.post('/api/orders', async (req, res, next) => {
  try {
    const input = OrderSchema.parse(req.body); // Zodバリデーション
    const order = await orderService.create(input);
    res.status(201).json(order);
  } catch (error) {
    if (error instanceof ZodError) {
      next(zodErrorToValidationError(error));  // ValidationErrorに変換
    } else {
      next(error);  // その他はミドルウェアに委ねる
    }
  }
});

まとめ

Claude Codeでエラー分類システムを設計する：

CLAUDE.md に運用エラー（予期される失敗）はWARNログ＋詳細をユーザーに返す・プログラマーエラーはERRORログ＋Sentry通知＋500で詳細を隠すを明記
エラーカタログ でcode/status/messageをセットで定義——フロントエンドがresponse.code === 'INSUFFICIENT_BALANCE'で判定してUIに「残高不足」と表示できる
isOperationalフラグ で運用エラーとバグを判別——if (error instanceof AppError && error.isOperational)で安全にユーザーへのレスポンスを決定。不明なエラーは全て500
requestIdでエラーを追跡 ——ユーザーが「requestId: 01H...でエラーが出た」と言えば、ログから原因を追跡。X-Request-Idヘッダーで連携

信頼性設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでアンチコラプションレイヤーを設計する：外部システム統合・型変換・ドメインの保護

myougaTheAxo — Thu, 19 Mar 2026 09:00:00 +0000

はじめに

「外部決済APIのモデルがドメインに漏れて、Stripeの概念がビジネスロジックに混在した」——アンチコラプションレイヤー（ACL）で外部システムとの境界を明確にし、外部の概念がドメインを汚染しないよう保護する設計をClaude Codeに生成させる。

CLAUDE.mdにアンチコラプションレイヤー設計ルールを書く

## アンチコラプションレイヤー設計ルール

### 役割
- 外部システムのデータモデルをドメインモデルに変換
- 外部APIのインターフェースをドメインに合わせたインターフェースでラップ
- 外部システムの概念（Stripe/Twilio等の用語）がドメイン層に出てこない

### 翻訳
- 外部→内部: Mapper/Translatorで変換
- 内部→外部: Adapterで変換
- エラーも変換: Stripe APIエラー → ドメインエラー

### 依存の方向
- ドメイン層はACLに依存しない（インターフェースのみに依存）
- ACLがインフラ層に位置（ドメイン層より外側）
- テスト: ACLをモック/スタブして差し替え可能

ACL実装の生成

アンチコラプションレイヤーを設計してください。

要件：
- 決済サービス（Stripe）のACL
- ドメインインターフェース
- エラー変換
- テスト容易性

生成ファイル: src/infrastructure/acl/

生成されるACL実装

// src/domain/payment/paymentGateway.ts — ドメインのインターフェース（Stripeを知らない）

export interface PaymentIntent {
  paymentId: string;
  amount: Money;
  status: 'pending' | 'succeeded' | 'failed';
  errorCode?: PaymentErrorCode;
}

export type PaymentErrorCode =
  | 'insufficient_funds'
  | 'card_declined'
  | 'expired_card'
  | 'invalid_cvc'
  | 'processing_error';

export interface IPaymentGateway {
  createPaymentIntent(amount: Money, customerId: string): Promise<PaymentIntent>;
  confirmPayment(paymentId: string): Promise<PaymentIntent>;
  refundPayment(paymentId: string, amount?: Money): Promise<void>;
  getPaymentStatus(paymentId: string): Promise<PaymentIntent>;
}

// src/infrastructure/acl/stripePaymentGateway.ts — Stripe ACL

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2023-10-16' });

export class StripePaymentGateway implements IPaymentGateway {
  async createPaymentIntent(amount: Money, customerId: string): Promise<PaymentIntent> {
    try {
      // ドメインのMoney → Stripeのamount（通貨の最小単位）
      const stripeIntent = await stripe.paymentIntents.create({
        amount: this.toStripeAmount(amount),
        currency: amount.currency.toLowerCase(),
        customer: customerId,  // StripeのcustomerID（内部ではドメインのuserIdと別で管理）
        automatic_payment_methods: { enabled: true },
      });

      return this.toPaymentIntent(stripeIntent);
    } catch (error) {
      throw this.translateError(error);
    }
  }

  async confirmPayment(paymentId: string): Promise<PaymentIntent> {
    try {
      const stripeIntent = await stripe.paymentIntents.confirm(paymentId);
      return this.toPaymentIntent(stripeIntent);
    } catch (error) {
      throw this.translateError(error);
    }
  }

  async refundPayment(paymentId: string, amount?: Money): Promise<void> {
    try {
      await stripe.refunds.create({
        payment_intent: paymentId,
        amount: amount ? this.toStripeAmount(amount) : undefined,
      });
    } catch (error) {
      throw this.translateError(error);
    }
  }

  async getPaymentStatus(paymentId: string): Promise<PaymentIntent> {
    const stripeIntent = await stripe.paymentIntents.retrieve(paymentId);
    return this.toPaymentIntent(stripeIntent);
  }

  // Stripe PaymentIntent → ドメインのPaymentIntent（翻訳）
  private toPaymentIntent(stripe: Stripe.PaymentIntent): PaymentIntent {
    const currency = stripe.currency.toUpperCase() as Currency;

    return {
      paymentId: stripe.id,
      amount: Money.of(stripe.amount, currency),
      status:
        stripe.status === 'succeeded' ? 'succeeded' :
        stripe.status === 'canceled' ? 'failed' :
        'pending',
    };
  }

  // ドメインのMoney → Stripeのamount
  private toStripeAmount(money: Money): number {
    // JPYは1円=1（最小単位）、USD/EURは1セント=100
    return money.currency === 'JPY' ? money.amount : money.amount;
  }

  // StripeエラーをドメインエラーへPayment翻訳
  private translateError(error: unknown): Error {
    if (error instanceof Stripe.errors.StripeCardError) {
      const errorCode = this.mapStripeDeclineCode(error.code ?? '');
      return new PaymentError(errorCode, error.message);
    }

    if (error instanceof Stripe.errors.StripeInvalidRequestError) {
      return new PaymentError('processing_error', 'Invalid payment request');
    }

    if (error instanceof Stripe.errors.StripeAPIError) {
      return new PaymentGatewayUnavailableError('Payment service temporarily unavailable');
    }

    return error as Error;
  }

  private mapStripeDeclineCode(code: string): PaymentErrorCode {
    const mapping: Record<string, PaymentErrorCode> = {
      'insufficient_funds': 'insufficient_funds',
      'card_declined': 'card_declined',
      'expired_card': 'expired_card',
      'incorrect_cvc': 'invalid_cvc',
      'processing_error': 'processing_error',
    };
    return mapping[code] ?? 'processing_error';
  }
}

// ドメインサービス: IPaymentGatewayを使う（Stripeを知らない）
export class PaymentService {
  constructor(private readonly gateway: IPaymentGateway) {}

  async processPayment(orderId: string, amount: Money, customerId: string): Promise<string> {
    const intent = await this.gateway.createPaymentIntent(amount, customerId);

    if (intent.status === 'failed') {
      throw new PaymentError(intent.errorCode ?? 'processing_error', 'Payment failed');
    }

    logger.info({ orderId, paymentId: intent.paymentId, amount: amount.toString() }, 'Payment intent created');
    return intent.paymentId;
  }
}

// テスト: ACLをスタブに差し替え
class StubPaymentGateway implements IPaymentGateway {
  private _shouldFail = false;

  simulateFailure(): void {
    this._shouldFail = true;
  }

  async createPaymentIntent(amount: Money): Promise<PaymentIntent> {
    if (this._shouldFail) {
      throw new PaymentError('card_declined', 'Card declined (test)');
    }
    return {
      paymentId: `test-${ulid()}`,
      amount,
      status: 'succeeded',
    };
  }

  async confirmPayment(paymentId: string): Promise<PaymentIntent> {
    return { paymentId, amount: Money.zero('JPY'), status: 'succeeded' };
  }

  async refundPayment(): Promise<void> {}
  async getPaymentStatus(paymentId: string): Promise<PaymentIntent> {
    return { paymentId, amount: Money.zero('JPY'), status: 'succeeded' };
  }
}

// 本番: DIコンテナで依存を解決
const paymentService = new PaymentService(new StripePaymentGateway());

// テスト: スタブを注入
const stubGateway = new StubPaymentGateway();
stubGateway.simulateFailure();
const testPaymentService = new PaymentService(stubGateway);

まとめ

Claude Codeでアンチコラプションレイヤーを設計する：

CLAUDE.md にドメインはインターフェースのみに依存（IPaymentGateway）・ACLが外部→内部の変換を担当・Stripeの用語はACL内にのみ出現を明記
toPaymentIntent()翻訳メソッド でStripeのPaymentIntent.statusをドメインの'succeeded' | 'pending' | 'failed'にマッピング——Stripeが'processing' → 'requires_confirmation'と変更してもドメインに影響しない
エラー変換 でStripeCardErrorをPaymentErrorに変換——ドメイン層がStripeのエラークラス階層を知る必要がなく、テスト時も簡単にエラーをシミュレートできる
スタブ実装のテスト容易性 でStripeなしで決済ロジックをテスト——IPaymentGatewayを実装したスタブを注入するだけで「カード拒否」「決済成功」のシナリオをテスト

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude CodeでUnit of Workパターンを設計する：複数リポジトリのトランザクション統一・変更追跡・原子コミット

myougaTheAxo — Wed, 18 Mar 2026 22:00:00 +0000

はじめに

「複数のリポジトリを使う処理でトランザクションが統一されていなかった」——Unit of Workパターンで複数リポジトリへの変更を1つのトランザクションにまとめ、原子的にコミット/ロールバックする設計をClaude Codeに生成させる。

CLAUDE.mdにUnit of Work設計ルールを書く

## Unit of Workパターン設計ルール

### 役割
- 1つのユースケース（トランザクション）スコープを管理
- スコープ内で取得した集約を追跡（変更検出）
- commit()で全変更を一括保存、rollback()で全変更を取り消し

### リポジトリとの関係
- リポジトリはUoWが管理するDBコネクション/Prismaトランザクションを使用
- UoWを通じてリポジトリを取得する（UoW.getOrderRepository()）
- UoW外でリポジトリを直接使用しない

### Prismaとの統合
- Prisma.$transaction(async (tx) => { ... }) をUoWのスコープとして使用
- リポジトリはPrismaトランザクション（tx）を受け取る

Unit of Work実装の生成

Unit of Workパターンを設計してください。

要件：
- Prismaトランザクションとの統合
- リポジトリアクセスのファクトリー
- ドメインイベントの収集とコミット後の発行
- エラー時の自動ロールバック

生成ファイル: src/infrastructure/unitOfWork/

生成されるUnit of Work実装

// src/infrastructure/unitOfWork/unitOfWork.ts — Unit of Work

export interface IUnitOfWork {
  orderRepository: IOrderRepository;
  userRepository: IUserRepository;
  inventoryRepository: IInventoryRepository;
  commit(): Promise<void>;
  rollback(): Promise<void>;
}

export class PrismaUnitOfWork implements IUnitOfWork {
  private _orderRepository: IOrderRepository | null = null;
  private _userRepository: IUserRepository | null = null;
  private _inventoryRepository: IInventoryRepository | null = null;
  private _aggregates: AggregateRoot[] = [];
  private _committed = false;

  constructor(private readonly tx: PrismaTransactionClient) {}

  get orderRepository(): IOrderRepository {
    this._orderRepository ??= new PrismaOrderRepository(this.tx, this);
    return this._orderRepository;
  }

  get userRepository(): IUserRepository {
    this._userRepository ??= new PrismaUserRepository(this.tx);
    return this._userRepository;
  }

  get inventoryRepository(): IInventoryRepository {
    this._inventoryRepository ??= new PrismaInventoryRepository(this.tx);
    return this._inventoryRepository;
  }

  // リポジトリが集約を登録（変更追跡用）
  registerAggregate(aggregate: AggregateRoot): void {
    this._aggregates.push(aggregate);
  }

  async commit(): Promise<void> {
    if (this._committed) throw new Error('Unit of Work already committed');
    this._committed = true;
    // コミット自体はPrismaトランザクションが行う（tx.commit相当）
    // ドメインイベントを収集
    const events = this._aggregates.flatMap(a => a.collectDomainEvents());

    // コミット後のイベント発行はスコープ外で行う
    this._pendingEvents = events;
  }

  private _pendingEvents: DomainEvent[] = [];

  getPendingEvents(): DomainEvent[] {
    return this._pendingEvents;
  }

  async rollback(): Promise<void> {
    // Prismaトランザクションのロールバックはthrowで発動
    this._aggregates = [];
    this._pendingEvents = [];
  }
}

// UoWファクトリー
export class UnitOfWorkFactory {
  static async run<T>(
    fn: (uow: PrismaUnitOfWork) => Promise<T>,
    afterCommit?: (events: DomainEvent[]) => Promise<void>
  ): Promise<T> {
    let pendingEvents: DomainEvent[] = [];

    const result = await prisma.$transaction(async (tx) => {
      const uow = new PrismaUnitOfWork(tx as any);
      const result = await fn(uow);
      await uow.commit();
      pendingEvents = uow.getPendingEvents();
      return result;
    });

    // トランザクション成功後にドメインイベントを発行
    if (pendingEvents.length > 0 && afterCommit) {
      await afterCommit(pendingEvents).catch(err =>
        logger.error({ err }, 'Post-commit event dispatch failed')
      );
    }

    return result;
  }
}

// src/infrastructure/repositories/orderRepository.ts — UoW対応リポジトリ

export class PrismaOrderRepository implements IOrderRepository {
  constructor(
    private readonly tx: PrismaTransactionClient,
    private readonly uow: PrismaUnitOfWork
  ) {}

  async findById(id: string): Promise<Order | null> {
    const row = await this.tx.order.findUnique({
      where: { id },
      include: { items: true },
    });

    if (!row) return null;

    const order = OrderMapper.toDomain(row);
    this.uow.registerAggregate(order); // 変更追跡に登録
    return order;
  }

  async save(order: Order): Promise<void> {
    await this.tx.order.upsert({
      where: { id: order.id },
      create: OrderMapper.toCreateData(order),
      update: OrderMapper.toUpdateData(order),
    });
  }
}

// アプリケーション層: UoWを使ったユースケース
export class PlaceOrderUseCase {
  async execute(input: PlaceOrderInput): Promise<Order> {
    return UnitOfWorkFactory.run(
      async (uow) => {
        // 同一トランザクション内で複数リポジトリを操作
        const user = await uow.userRepository.findById(input.userId);
        if (!user) throw new NotFoundError('User not found');

        // 在庫確認
        for (const item of input.items) {
          const inventory = await uow.inventoryRepository.findByProductId(item.productId);
          if (!inventory.hasEnough(Quantity.of(item.quantity, 'piece'))) {
            throw new OutOfStockError(item.productId);
          }
        }

        // 注文作成
        const order = Order.create(input.userId, input.items);

        // 在庫を減らす
        for (const item of input.items) {
          const inventory = await uow.inventoryRepository.findByProductId(item.productId);
          inventory.decrement(Quantity.of(item.quantity, 'piece'));
          await uow.inventoryRepository.save(inventory);
        }

        // 注文保存
        await uow.orderRepository.save(order);

        return order;
        // commit()は自動（UnitOfWorkFactory.runが呼ぶ）
      },
      // コミット後にドメインイベントを発行
      async (events) => {
        await eventDispatcher.dispatch(events);
      }
    );
  }
}

まとめ

Claude CodeでUnit of Workパターンを設計する：

CLAUDE.md にUoWがPrismaトランザクションをスコープとして管理・リポジトリはUoWから取得・コミット後にドメインイベントを発行・エラーはthrowでロールバックを明記
UnitOfWorkFactory.run(tx => { ... }) でユースケース全体を1トランザクションに——注文作成・在庫更新・ユーザーポイント更新を全て同一txで実行してアトミックに成功/失敗
registerAggregateで変更追跡 し、commit()時にドメインイベントを収集——「どの集約が変更されたか」をUoWが把握してイベント収集を自動化
コミット後のイベント発行 で「DBは成功したがイベントが出なかった」問題を防止——トランザクション外でのイベント発行でロールバック済みイベントが流れることもない

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeで値オブジェクトを設計する：不変性・等値性・ドメイン表現の型安全化

myougaTheAxo — Wed, 18 Mar 2026 21:00:00 +0000

はじめに

「金額をnumberで扱っていて通貨単位の混在バグが起きた」「メールアドレスをstringで渡し続けていてバリデーションが散らばった」——値オブジェクトでドメイン概念を型として表現し、不正な値が作れない設計をClaude Codeに生成させる。

CLAUDE.mdに値オブジェクト設計ルールを書く

## 値オブジェクト設計ルール

### 特性
- 不変（Immutable）: 作成後に変更不可（全フィールドreadonly）
- 等値性: IDではなく値で等しいかを判定（equals()メソッド）
- 自己検証: コンストラクタでバリデーション（無効な値は作れない）

### 設計
- プリミティブ型（string/number）の代わりに使用
- privateコンストラクタ + static create()でファクトリーメソッド
- toValue()でプリミティブに変換（DBへの保存など）

### 適用対象
- 金額・通貨・価格
- メールアドレス・URLなどの文字列
- 住所・座標などの複合値
- 数量・サイズ（単位付き数値）

値オブジェクト実装の生成

値オブジェクトを設計してください。

要件：
- 不変・等値性・自己検証
- Moneyクラス（金額+通貨）
- EmailAddress
- URL
- Quantity（単位付き数値）

生成ファイル: src/domain/valueObjects/

生成される値オブジェクト実装

// src/domain/valueObjects/money.ts — 金額値オブジェクト

export type Currency = 'JPY' | 'USD' | 'EUR' | 'GBP';

export class Money {
  private constructor(
    private readonly _amount: number,  // 最小単位（円/セント）
    private readonly _currency: Currency
  ) {}

  static of(amount: number, currency: Currency): Money {
    if (!Number.isInteger(amount)) {
      throw new DomainError(`Money amount must be an integer (got ${amount})`);
    }
    if (amount < 0) {
      throw new DomainError(`Money amount cannot be negative (got ${amount})`);
    }
    return new Money(amount, currency);
  }

  static zero(currency: Currency): Money {
    return new Money(0, currency);
  }

  add(other: Money): Money {
    if (this._currency !== other._currency) {
      throw new CurrencyMismatchError(this._currency, other._currency);
    }
    return new Money(this._amount + other._amount, this._currency);
  }

  subtract(other: Money): Money {
    if (this._currency !== other._currency) {
      throw new CurrencyMismatchError(this._currency, other._currency);
    }
    if (this._amount < other._amount) {
      throw new DomainError('Insufficient amount');
    }
    return new Money(this._amount - other._amount, this._currency);
  }

  multiply(factor: number): Money {
    if (factor < 0) throw new DomainError('Factor cannot be negative');
    return new Money(Math.round(this._amount * factor), this._currency);
  }

  isGreaterThan(other: Money): boolean {
    this.ensureSameCurrency(other);
    return this._amount > other._amount;
  }

  equals(other: Money): boolean {
    return this._amount === other._amount && this._currency === other._currency;
  }

  toValue(): { amount: number; currency: Currency } {
    return { amount: this._amount, currency: this._currency };
  }

  toString(): string {
    const formatter = new Intl.NumberFormat('ja-JP', {
      style: 'currency',
      currency: this._currency,
    });
    return formatter.format(this._currency === 'JPY' ? this._amount : this._amount / 100);
  }

  get amount(): number { return this._amount; }
  get currency(): Currency { return this._currency; }

  private ensureSameCurrency(other: Money): void {
    if (this._currency !== other._currency) {
      throw new CurrencyMismatchError(this._currency, other._currency);
    }
  }
}

// src/domain/valueObjects/emailAddress.ts — メールアドレス値オブジェクト

export class EmailAddress {
  private readonly _value: string;

  private constructor(value: string) {
    this._value = value.toLowerCase().trim();
  }

  static create(email: string): EmailAddress {
    const normalized = email.toLowerCase().trim();
    const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

    if (!EMAIL_REGEX.test(normalized)) {
      throw new DomainError(`Invalid email address: ${email}`);
    }
    if (normalized.length > 255) {
      throw new DomainError('Email address too long');
    }

    return new EmailAddress(normalized);
  }

  equals(other: EmailAddress): boolean {
    return this._value === other._value;
  }

  get domain(): string {
    return this._value.split('@')[1];
  }

  toValue(): string {
    return this._value;
  }

  toString(): string {
    return this._value;
  }
}

// src/domain/valueObjects/quantity.ts — 数量値オブジェクト（単位付き）

export type QuantityUnit = 'piece' | 'kg' | 'liter' | 'meter';

export class Quantity {
  private constructor(
    private readonly _value: number,
    private readonly _unit: QuantityUnit
  ) {}

  static of(value: number, unit: QuantityUnit): Quantity {
    if (value < 0) throw new DomainError('Quantity cannot be negative');
    if (!Number.isFinite(value)) throw new DomainError('Quantity must be finite');
    return new Quantity(value, unit);
  }

  add(other: Quantity): Quantity {
    if (this._unit !== other._unit) {
      throw new UnitMismatchError(this._unit, other._unit);
    }
    return new Quantity(this._value + other._value, this._unit);
  }

  isEnough(required: Quantity): boolean {
    if (this._unit !== required._unit) throw new UnitMismatchError(this._unit, required._unit);
    return this._value >= required._value;
  }

  equals(other: Quantity): boolean {
    return this._value === other._value && this._unit === other._unit;
  }

  toValue(): { value: number; unit: QuantityUnit } {
    return { value: this._value, unit: this._unit };
  }

  get value(): number { return this._value; }
  get unit(): QuantityUnit { return this._unit; }
}

// 使用例: 値オブジェクトを使ったドメインモデル

class OrderItem {
  constructor(
    readonly productId: string,
    readonly price: Money,      // numberではなくMoney
    readonly quantity: Quantity // numberではなくQuantity
  ) {}

  get subtotal(): Money {
    return this.price.multiply(this.quantity.value);
  }
}

class Order {
  constructor(
    readonly id: string,
    readonly customerEmail: EmailAddress,  // stringではなくEmailAddress
    readonly items: OrderItem[]
  ) {}

  get total(): Money {
    if (this.items.length === 0) return Money.zero('JPY');
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal),
      Money.zero(this.items[0].price.currency)
    );
  }
}

// 型安全な使用例
const price = Money.of(1980, 'JPY');
const qty = Quantity.of(3, 'piece');
const email = EmailAddress.create('customer@example.com');

const item = new OrderItem('prod-1', price, qty);
console.log(item.subtotal.toString()); // "¥5,940"

// 通貨混在を型でブロック
const usdPrice = Money.of(100, 'USD');
try {
  price.add(usdPrice); // CurrencyMismatchError: JPY vs USD
} catch (e) {
  console.error(e.message);
}

// Prismaでの保存/復元
const savedOrder = await prisma.order.create({
  data: {
    customerEmail: email.toValue(),  // string
    totalAmount: total.amount,       // number
    currency: total.currency,        // string
  },
});

// 復元
const restoredEmail = EmailAddress.create(savedOrder.customerEmail);
const restoredTotal = Money.of(savedOrder.totalAmount, savedOrder.currency as Currency);

まとめ

Claude Codeで値オブジェクトを設計する：

CLAUDE.md にprivateコンストラクタ + static create()・不変（readonlyフィールド）・equals()で等値比較・toValue()でプリミティブ変換を明記
通貨混在防止（Money） でprice.add(usdPrice) → CurrencyMismatchError——TypeScriptの型ではMoney同士なら防げないが、実行時に通貨を検証することで「JPY金額にUSD金額を加算」バグを確実に防止
自己検証コンストラクタ でEmailAddressの不正な値が作れない——EmailAddress.create('invalid')でDomainErrorを即スロー。バリデーションが値オブジェクトに集約されてサービス層に散らばらない
toValue()でプリミティブ変換 してDBへの保存と値オブジェクトの使用を分離——Prismaにはemail.toValue()でstringを渡し、取得後はEmailAddress.create(row.email)で復元

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでドメインイベントを設計する：集約内イベント・ドメイン層の疎結合・副作用の分離

myougaTheAxo — Wed, 18 Mar 2026 20:00:00 +0000

はじめに

「注文確定処理の中にメール送信・在庫更新・ポイント付与が混在して保守できない」——ドメインイベントで集約の状態変化を記録し、副作用をイベントハンドラーに分離する設計をClaude Codeに生成させる。

CLAUDE.mdにドメインイベント設計ルールを書く

## ドメインイベント設計ルール

### イベントの生成
- 集約のメソッドがドメインイベントを生成（return/throwではなく内部に蓄積）
- イベントは過去形の名前（OrderPlaced, PaymentReceived）
- イベントには何が起きたか（型＋識別子＋必要データ）を含める

### イベントの発行
- アプリケーション層がDBコミット後にドメインイベントを発行
- コミット前に発行しない（ロールバックしたイベントが発行されるのを防ぐ）
- 発行はOutboxパターンと組み合わせてトランザクション保証

### ハンドラーの設計
- 各ハンドラーは1つのイベントに対して1つの副作用を担当
- ハンドラーは失敗してもドメインの整合性に影響しない（副作用の分離）

ドメインイベント実装の生成

ドメインイベントシステムを設計してください。

要件：
- 集約内でのイベント蓄積
- DBコミット後のイベント発行
- イベントハンドラーの登録と実行
- アウトボックスとの統合

生成ファイル: src/domain/events/

生成されるドメインイベント実装

// src/domain/events/domainEvent.ts — ドメインイベント基底

export interface DomainEvent {
  readonly eventId: string;
  readonly occurredAt: Date;
  readonly eventType: string;
}

export abstract class AggregateRoot {
  private _domainEvents: DomainEvent[] = [];

  protected addDomainEvent(event: DomainEvent): void {
    this._domainEvents.push(event);
  }

  // アプリケーション層がDBコミット後に呼ぶ
  collectDomainEvents(): DomainEvent[] {
    const events = [...this._domainEvents];
    this._domainEvents = []; // クリア
    return events;
  }
}

// src/domain/order/order.ts — 集約ルート（Order）

export class Order extends AggregateRoot {
  private _status: OrderStatus;
  private _items: OrderItem[];
  private _totalAmount: number;

  private constructor(
    private readonly _id: string,
    private readonly _userId: string,
    items: OrderItem[],
    status: OrderStatus
  ) {
    super();
    this._items = items;
    this._status = status;
    this._totalAmount = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  }

  static create(userId: string, items: OrderItem[]): Order {
    const order = new Order(ulid(), userId, items, 'draft');

    // ドメインイベントを内部に蓄積（発行はアプリ層に委ねる）
    order.addDomainEvent({
      eventId: ulid(),
      eventType: 'OrderCreated',
      occurredAt: new Date(),
      orderId: order._id,
      userId,
      totalAmount: order._totalAmount,
    } as OrderCreatedEvent);

    return order;
  }

  confirm(): void {
    if (this._status !== 'pending_payment') {
      throw new DomainError(`Cannot confirm order in status '${this._status}'`);
    }

    this._status = 'confirmed';

    this.addDomainEvent({
      eventId: ulid(),
      eventType: 'OrderConfirmed',
      occurredAt: new Date(),
      orderId: this._id,
      userId: this._userId,
      totalAmount: this._totalAmount,
      items: this._items,
    } as OrderConfirmedEvent);
  }

  cancel(reason: string): void {
    if (['delivered', 'refunded'].includes(this._status)) {
      throw new DomainError(`Cannot cancel order in status '${this._status}'`);
    }

    this._status = 'cancelled';

    this.addDomainEvent({
      eventId: ulid(),
      eventType: 'OrderCancelled',
      occurredAt: new Date(),
      orderId: this._id,
      userId: this._userId,
      reason,
    } as OrderCancelledEvent);
  }

  get id(): string { return this._id; }
  get status(): OrderStatus { return this._status; }
  get totalAmount(): number { return this._totalAmount; }
}

// ドメインイベント型定義
export interface OrderCreatedEvent extends DomainEvent {
  eventType: 'OrderCreated';
  orderId: string;
  userId: string;
  totalAmount: number;
}

export interface OrderConfirmedEvent extends DomainEvent {
  eventType: 'OrderConfirmed';
  orderId: string;
  userId: string;
  totalAmount: number;
  items: OrderItem[];
}

export interface OrderCancelledEvent extends DomainEvent {
  eventType: 'OrderCancelled';
  orderId: string;
  userId: string;
  reason: string;
}

// src/application/eventDispatcher.ts — イベントディスパッチャー

type EventHandler<T extends DomainEvent> = (event: T) => Promise<void>;

export class DomainEventDispatcher {
  private readonly handlers = new Map<string, EventHandler<DomainEvent>[]>();

  on<T extends DomainEvent>(eventType: string, handler: EventHandler<T>): void {
    const existing = this.handlers.get(eventType) ?? [];
    existing.push(handler as EventHandler<DomainEvent>);
    this.handlers.set(eventType, existing);
  }

  async dispatch(events: DomainEvent[]): Promise<void> {
    for (const event of events) {
      const handlers = this.handlers.get(event.eventType) ?? [];

      // ハンドラーを並列実行（独立した副作用）
      await Promise.allSettled(
        handlers.map(handler =>
          handler(event).catch(err =>
            logger.error({ eventType: event.eventType, eventId: event.eventId, err }, 'Event handler failed')
          )
        )
      );
    }
  }
}

// ハンドラー登録
const dispatcher = new DomainEventDispatcher();

// OrderConfirmedEvent ハンドラー群
dispatcher.on<OrderConfirmedEvent>('OrderConfirmed', async (event) => {
  await emailService.sendOrderConfirmation(event.userId, event.orderId);
});

dispatcher.on<OrderConfirmedEvent>('OrderConfirmed', async (event) => {
  await inventoryService.reserveItems(event.orderId, event.items);
});

dispatcher.on<OrderConfirmedEvent>('OrderConfirmed', async (event) => {
  await pointsService.awardPoints(event.userId, event.totalAmount);
});

// アプリケーション層: DB保存 → イベント発行
export class ConfirmOrderUseCase {
  async execute(orderId: string): Promise<void> {
    const order = await orderRepository.findById(orderId);

    order.confirm();  // ドメインイベントを内部に蓄積

    // DBにコミット
    await orderRepository.save(order);

    // コミット後にイベントを発行（トランザクション外）
    const events = order.collectDomainEvents();
    await dispatcher.dispatch(events);  // メール・在庫・ポイントの副作用を分離実行
  }
}

まとめ

Claude Codeでドメインイベントを設計する：

CLAUDE.md に集約メソッドがイベントを内部蓄積・アプリ層がDBコミット後にcollectして発行・ハンドラー失敗はドメインに影響しないを明記
AggregateRoot基底クラス でイベント蓄積/収集のライフサイクルを統一——order.confirm() → order.collectDomainEvents() → dispatcher.dispatch(events) という一貫したフロー
DBコミット後に発行 することでトランザクションロールバック後にイベントが流れることを防止——「DBは失敗したのにメールだけ送った」問題を解消
ハンドラーの分離（1イベント × 複数ハンドラー） でOrderConfirmedに対してメール/在庫/ポイントを独立したハンドラーで実装——新しい副作用の追加がdispatcher.on()の1行で済む

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでスペシフィケーションパターンを設計する：ビジネスルールの型安全な表現・AND/OR合成・クエリ変換

myougaTheAxo — Wed, 18 Mar 2026 19:00:00 +0000

はじめに

「ビジネスルールがサービス層に散らばっていて、同じ条件を複数の場所で書いている」——スペシフィケーションパターンでビジネスルールをオブジェクトとして表現し、AND/OR合成・テスト容易性・クエリ変換を実現する設計をClaude Codeに生成させる。

CLAUDE.mdにスペシフィケーション設計ルールを書く

## スペシフィケーションパターン設計ルール

### スペック設計
- 各スペックは単一のビジネスルールを表現
- `isSatisfiedBy(entity): boolean` で検証
- `toQuery(): WhereClause` でDBクエリに変換（in-memory判定とDB判定を統一）

### 合成
- `spec1.and(spec2)`: 両方を満たす
- `spec1.or(spec2)`: どちらかを満たす
- `spec.not()`: 条件を反転

### 名前付きスペック
- ビジネス用語に対応した名前（例: `EligibleForDiscount`, `PremiumUser`）
- ドメイン語彙でドキュメント化される

スペシフィケーション実装の生成

スペシフィケーションパターンを設計してください。

要件：
- 基底Specificationクラス
- AND/OR/NOT合成
- Prismaクエリへの変換
- 複数スペックの組み合わせ

生成ファイル: src/domain/specifications/

生成されるスペシフィケーション実装

// src/domain/specifications/specification.ts — 基底Specification

export type WhereClause = Record<string, unknown>;

export abstract class Specification<T> {
  abstract isSatisfiedBy(entity: T): boolean;
  abstract toQuery(): WhereClause;  // Prismaのwhere句に変換

  and(other: Specification<T>): Specification<T> {
    return new AndSpecification(this, other);
  }

  or(other: Specification<T>): Specification<T> {
    return new OrSpecification(this, other);
  }

  not(): Specification<T> {
    return new NotSpecification(this);
  }
}

class AndSpecification<T> extends Specification<T> {
  constructor(private readonly left: Specification<T>, private readonly right: Specification<T>) {
    super();
  }

  isSatisfiedBy(entity: T): boolean {
    return this.left.isSatisfiedBy(entity) && this.right.isSatisfiedBy(entity);
  }

  toQuery(): WhereClause {
    return { AND: [this.left.toQuery(), this.right.toQuery()] };
  }
}

class OrSpecification<T> extends Specification<T> {
  constructor(private readonly left: Specification<T>, private readonly right: Specification<T>) {
    super();
  }

  isSatisfiedBy(entity: T): boolean {
    return this.left.isSatisfiedBy(entity) || this.right.isSatisfiedBy(entity);
  }

  toQuery(): WhereClause {
    return { OR: [this.left.toQuery(), this.right.toQuery()] };
  }
}

class NotSpecification<T> extends Specification<T> {
  constructor(private readonly spec: Specification<T>) {
    super();
  }

  isSatisfiedBy(entity: T): boolean {
    return !this.spec.isSatisfiedBy(entity);
  }

  toQuery(): WhereClause {
    return { NOT: this.spec.toQuery() };
  }
}

// src/domain/specifications/orderSpecs.ts — 注文のスペック定義

interface Order {
  id: string;
  status: string;
  totalAmount: number;
  createdAt: Date;
  userId: string;
  isPaid: boolean;
  hasInternationalShipping: boolean;
}

// スペック: 確定済み注文
export class ConfirmedOrderSpec extends Specification<Order> {
  isSatisfiedBy(order: Order): boolean {
    return order.status === 'confirmed';
  }
  toQuery(): WhereClause {
    return { status: 'confirmed' };
  }
}

// スペック: 高額注文（5万円以上）
export class HighValueOrderSpec extends Specification<Order> {
  constructor(private readonly threshold: number = 50_000) {
    super();
  }

  isSatisfiedBy(order: Order): boolean {
    return order.totalAmount >= this.threshold;
  }

  toQuery(): WhereClause {
    return { totalAmount: { gte: this.threshold } };
  }
}

// スペック: 最近の注文（30日以内）
export class RecentOrderSpec extends Specification<Order> {
  constructor(private readonly daysAgo: number = 30) {
    super();
  }

  isSatisfiedBy(order: Order): boolean {
    const cutoff = new Date(Date.now() - this.daysAgo * 86400_000);
    return order.createdAt >= cutoff;
  }

  toQuery(): WhereClause {
    return { createdAt: { gte: new Date(Date.now() - this.daysAgo * 86400_000) } };
  }
}

// スペック: 海外配送あり
export class InternationalOrderSpec extends Specification<Order> {
  isSatisfiedBy(order: Order): boolean {
    return order.hasInternationalShipping;
  }
  toQuery(): WhereClause {
    return { hasInternationalShipping: true };
  }
}

// スペック: 支払済み
export class PaidOrderSpec extends Specification<Order> {
  isSatisfiedBy(order: Order): boolean {
    return order.isPaid;
  }
  toQuery(): WhereClause {
    return { isPaid: true };
  }
}

// 合成スペック: 優先処理が必要な注文（高額 かつ 確定済み かつ 未払い）
export const PriorityOrderSpec = new HighValueOrderSpec(50_000)
  .and(new ConfirmedOrderSpec())
  .and(new PaidOrderSpec().not());

// 合成スペック: レポート対象（直近30日の確定済み注文 または 5万円以上の全確定済み注文）
export const ReportableOrderSpec = new RecentOrderSpec(30)
  .and(new ConfirmedOrderSpec())
  .or(new HighValueOrderSpec(50_000).and(new ConfirmedOrderSpec()));

// src/domain/specifications/orderRepository.ts — スペックを使ったリポジトリ

export class OrderRepository {
  // スペックでフィルタ（DB側のクエリに変換）
  async findBySpec(spec: Specification<Order>): Promise<Order[]> {
    return prisma.order.findMany({
      where: spec.toQuery(), // Prismaのwhere句として使用
    });
  }

  // スペックで検証（in-memory）
  filterInMemory(orders: Order[], spec: Specification<Order>): Order[] {
    return orders.filter(o => spec.isSatisfiedBy(o));
  }
}

// 使用例
const repo = new OrderRepository();

// DB側でフィルタ（効率的）
const priorityOrders = await repo.findBySpec(PriorityOrderSpec);

// 海外配送付きの高額確定済み注文
const internationalHighValue = await repo.findBySpec(
  new InternationalOrderSpec()
    .and(new HighValueOrderSpec(100_000))
    .and(new ConfirmedOrderSpec())
);

// クーポン対象のチェック（in-memory validation）
function isEligibleForCoupon(order: Order): boolean {
  const eligibilitySpec = new RecentOrderSpec(90)
    .and(new PaidOrderSpec())
    .and(new HighValueOrderSpec(10_000));

  return eligibilitySpec.isSatisfiedBy(order);
}

// ビジネスルールをドキュメント化（スペック名がそのままルール説明）
const DISCOUNT_ELIGIBILITY_SPEC = new PaidOrderSpec()
  .and(new HighValueOrderSpec(30_000))
  .and(new RecentOrderSpec(60));

// テスト（スペック単独でテスト可能）
describe('HighValueOrderSpec', () => {
  it('should satisfy orders above threshold', () => {
    const spec = new HighValueOrderSpec(50_000);
    const order = { totalAmount: 60_000 } as Order;
    expect(spec.isSatisfiedBy(order)).toBe(true);
  });

  it('should generate correct Prisma query', () => {
    const spec = new HighValueOrderSpec(50_000);
    expect(spec.toQuery()).toEqual({ totalAmount: { gte: 50_000 } });
  });
});

まとめ

Claude Codeでスペシフィケーションパターンを設計する：

CLAUDE.md に各スペックは単一ビジネスルール・isSatisfiedBy（in-memory）とtoQuery（Prisma変換）を両方実装・AND/OR/NOT合成でルールを組み合わせを明記
toQuery()でPrismaのwhere句に変換 することでin-memoryとDBの判定ロジックを統一——同じスペックが「ドメインオブジェクトの検証」と「DBクエリ生成」の両方に使える
スペックの合成 で「高額 AND 確定済み AND 未払い」という複合ルールを読みやすく表現——if文のネストではなくスペックオブジェクトの組み合わせでビジネスルールをドキュメント化
スペック単体テスト で各ビジネスルールを独立して検証——HighValueOrderSpec.isSatisfiedBy({ totalAmount: 60000 })のような純粋関数のテストが書ける

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeで楽観的並行制御を設計する：バージョニング・競合検出・自動リトライ

myougaTheAxo — Wed, 18 Mar 2026 18:00:00 +0000

はじめに

「2ユーザーが同時に同じデータを更新したら片方の変更が消えた」——楽観的並行制御でバージョン番号を使って競合を検出し、自動リトライまたはユーザーへの通知でデータ損失を防ぐ設計をClaude Codeに生成させる。

CLAUDE.mdに楽観的並行制御設計ルールを書く

## 楽観的並行制御設計ルール

### バージョン管理
- 全てのエンティティにversionフィールド（整数）を持つ
- UPDATE時にWHEREにversion条件を追加（WHERE id=? AND version=?）
- 更新成功でversionをインクリメント（version + 1）
- 更新失敗（0行更新）= 競合発生

### 競合処理
- RETRY可能な操作: 最新データを再取得して自動リトライ（最大3回）
- RETRY不可能な操作: 競合エラーをUIに返してユーザーに再入力を促す
- 楽観的ロック失敗のエラーはHTTP 409 Conflict

### 対象選定
- 競合が稀なリソースに使用（同時編集が多い場合は悲観的ロックを検討）
- 読み取りが多く書き込みが少ないデータが最適

楽観的並行制御実装の生成

楽観的並行制御を設計してください。

要件：
- バージョンフィールドによる競合検出
- 自動リトライデコレーター
- 競合時のマージ戦略
- HTTPレスポンスのバージョン管理

生成ファイル: src/concurrency/optimistic/

生成される楽観的並行制御実装

// src/concurrency/optimistic/optimisticLock.ts — 楽観的ロック

export class OptimisticLockError extends Error {
  constructor(
    public readonly entityType: string,
    public readonly entityId: string,
    public readonly expectedVersion: number,
    public readonly actualVersion: number
  ) {
    super(`Optimistic lock conflict: ${entityType}[${entityId}] expected v${expectedVersion}, but current is v${actualVersion}`);
  }
}

export class OptimisticLockRepository<T extends { id: string; version: number }> {
  constructor(
    private readonly tableName: string,
    private readonly db: PrismaClient
  ) {}

  async update(
    id: string,
    expectedVersion: number,
    updateData: Partial<Omit<T, 'id' | 'version'>>
  ): Promise<T> {
    // version一致チェック付きでUPDATE
    const result = await this.db.$executeRaw`
      UPDATE ${this.db.sql.raw(this.tableName)}
      SET ${this.buildSetClause(updateData)},
          version = version + 1,
          updated_at = NOW()
      WHERE id = ${id}
        AND version = ${expectedVersion}
      RETURNING *
    `;

    if (result === 0) {
      // 更新行数が0 = バージョン不一致（競合）
      const current = await this.db.$queryRaw<Array<{ version: number }>>`
        SELECT version FROM ${this.db.sql.raw(this.tableName)} WHERE id = ${id}
      `.then(rows => rows[0]);

      throw new OptimisticLockError(
        this.tableName,
        id,
        expectedVersion,
        current?.version ?? -1
      );
    }

    return this.findById(id);
  }

  private buildSetClause(data: Record<string, unknown>): string {
    return Object.entries(data)
      .map(([key, value]) => {
        const snakeKey = key.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
        return `${snakeKey} = ${typeof value === 'string' ? `'${value}'` : value}`;
      })
      .join(', ');
  }

  async findById(id: string): Promise<T> {
    const rows = await this.db.$queryRaw<T[]>`
      SELECT * FROM ${this.db.sql.raw(this.tableName)} WHERE id = ${id}
    `;
    if (!rows[0]) throw new NotFoundError(`${this.tableName}[${id}] not found`);
    return rows[0];
  }
}

// 自動リトライデコレーター
export function withOptimisticRetry<T>(
  operation: () => Promise<T>,
  maxAttempts = 3,
  delayMs = 100
): Promise<T> {
  return retry(operation, {
    retries: maxAttempts - 1,
    factor: 2,
    minTimeout: delayMs,
    onRetry: (error, attempt) => {
      if (error instanceof OptimisticLockError) {
        logger.debug({ attempt, entityId: error.entityId }, 'Retrying after optimistic lock conflict');
        return;
      }
      throw error; // OptimisticLockError以外はリトライしない
    },
  });
}

// src/concurrency/optimistic/userProfileService.ts — 楽観的ロック付きサービス

export class UserProfileService {
  private readonly repo = new OptimisticLockRepository<User>('users', prisma);

  // 自動リトライ: プロフィール更新は競合しても自動解決
  async updateProfile(userId: string, version: number, updates: UpdateProfileInput): Promise<User> {
    return withOptimisticRetry(async () => {
      // 最新バージョンを取得してリトライ
      const current = await this.repo.findById(userId);

      return this.repo.update(userId, current.version, {
        displayName: updates.displayName ?? current.displayName,
        bio: updates.bio ?? current.bio,
        avatarUrl: updates.avatarUrl ?? current.avatarUrl,
      });
    });
  }

  // 競合をユーザーに通知: 残高操作は自動リトライ不可
  async transferBalance(fromId: string, version: number, amount: number): Promise<User> {
    const from = await this.repo.findById(fromId);

    if (from.balance < amount) {
      throw new InsufficientBalanceError();
    }

    try {
      return await this.repo.update(fromId, version, {
        balance: from.balance - amount,
      });
    } catch (error) {
      if (error instanceof OptimisticLockError) {
        // 残高操作は競合を自動解決しない（二重送金リスク）
        throw new ConflictError(
          'Another operation modified this account simultaneously. Please refresh and try again.',
          { currentVersion: error.actualVersion }
        );
      }
      throw error;
    }
  }
}

// REST APIエンドポイント: ETagでバージョン管理
router.get('/api/users/:id', async (req, res) => {
  const user = await userService.findById(req.params.id);

  // ETagにバージョンを埋め込む
  res.set('ETag', `"${user.version}"`);
  res.json(user);
});

router.put('/api/users/:id', async (req, res) => {
  // クライアントはIf-Matchヘッダーでバージョンを指定
  const ifMatch = req.headers['if-match'];
  if (!ifMatch) {
    return res.status(428).json({ error: 'If-Match header required' }); // 428 Precondition Required
  }

  const expectedVersion = parseInt(ifMatch.replace(/"/g, ''));

  try {
    const updated = await userService.updateProfile(req.params.id, expectedVersion, req.body);
    res.set('ETag', `"${updated.version}"`);
    res.json(updated);
  } catch (error) {
    if (error instanceof ConflictError) {
      res.status(409).json({
        error: 'Version conflict',
        message: error.message,
        currentVersion: (error as any).metadata.currentVersion,
      });
    } else {
      throw error;
    }
  }
});

/*
クライアントフロー:
1. GET /api/users/123  → ETag: "5"
2. PUT /api/users/123  If-Match: "5"  → 200 ETag: "6"
3. 別ユーザーが先に PUT → バージョンが"6"に
4. 元ユーザーが PUT /api/users/123 If-Match: "5" → 409 Conflict
5. クライアントが再度 GET → 最新データを取得して再編集
*/

まとめ

Claude Codeで楽観的並行制御を設計する：

CLAUDE.md に全エンティティにversionフィールド・UPDATE時にWHERE version=?を付与・0行更新で競合検出・自動リトライは競合が安全な操作のみを明記
WHERE id=? AND version=? で競合を原子的に検出——チェックしてから更新する間に別トランザクションが割り込む問題がない。0行更新=競合という単純で確実な検出方法
操作別の競合戦略 でリトライの安全性を判断——プロフィール更新は自動リトライOK（最終状態が正しければよい）、残高移動はリトライ禁止（二重送金リスク）
ETag/If-Matchによるバージョン伝播 でHTTP標準仕様でバージョン管理——クライアントがGETで取得したETagをPUTのIf-Matchに使う。RFC 7232準拠のキャッシュ/競合制御

DB設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでカーソルページネーションを設計する：大量データの高速ページング・ソート安定性・無限スクロール

myougaTheAxo — Wed, 18 Mar 2026 17:00:00 +0000

はじめに

「OFFSET/LIMITページネーションが1000ページ目あたりから遅い」「ページ表示中に新データが追加されて同じ投稿が2回出た」——カーソルベースページネーションで大量データを高速に、かつ安定してページングする設計をClaude Codeに生成させる。

CLAUDE.mdにカーソルページネーション設計ルールを書く

## カーソルページネーション設計ルール

### カーソルの設計
- カーソル = ソートキーの値をBase64エンコードしたもの
- 複合ソート（created_at DESC, id DESC）で安定したページングを保証
- カーソルは不透明（クライアントはparse不要、そのまま次のリクエストに使う）

### クエリの効率化
- WHERE created_at < cursor_created_at OR (created_at = cursor_created_at AND id < cursor_id)
- id列にインデックスがあれば高速（OFFSET/LIMITと違いフルスキャン不要）
- 最後のページかどうかはlimit+1件取得して判定

### API設計
- レスポンス: { data: [...], nextCursor: string | null, hasMore: boolean }
- nextCursorがnullで全データ取得完了
- prevCursorは持たない（戻るはfirstPageに戻す設計を推奨）

カーソルページネーション実装の生成

カーソルベースページネーションを設計してください。

要件：
- 複合ソートキーによる安定ページング
- Base64カーソルエンコード
- 双方向ページング
- GraphQL/REST両対応

生成ファイル: src/pagination/

生成されるカーソルページネーション実装

// src/pagination/cursorPagination.ts — カーソルページネーションエンジン

export interface PageInfo {
  hasNextPage: boolean;
  hasPreviousPage: boolean;
  startCursor: string | null;
  endCursor: string | null;
}

export interface Connection<T> {
  edges: Array<{ node: T; cursor: string }>;
  pageInfo: PageInfo;
  totalCount?: number;
}

export interface CursorFields {
  [key: string]: unknown;  // ソートキーのフィールドと値
}

export class CursorEncoder {
  static encode(fields: CursorFields): string {
    return Buffer.from(JSON.stringify(fields)).toString('base64url');
  }

  static decode(cursor: string): CursorFields {
    try {
      return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
    } catch {
      throw new InvalidCursorError('Invalid cursor format');
    }
  }
}

export interface PaginationArgs {
  first?: number;   // 前向き（N件取得）
  after?: string;   // 前向き（このカーソルより後）
  last?: number;    // 後向き（N件取得）
  before?: string;  // 後向き（このカーソルより前）
}

export class CursorPaginator<T extends Record<string, unknown>> {
  constructor(
    private readonly defaultLimit: number = 20,
    private readonly maxLimit: number = 100
  ) {}

  // PostgreSQL用のWHERE条件を生成
  buildWhereClause(
    cursor: CursorFields | null,
    sortFields: Array<{ field: string; direction: 'ASC' | 'DESC' }>
  ): string {
    if (!cursor) return '';

    // 複合ソートのカーソル条件
    // 例: (created_at, id) DESC の場合
    // WHERE (created_at, id) < (cursorCreatedAt, cursorId)
    const pairs = sortFields.map(({ field }) => field).join(', ');
    const values = sortFields
      .map(({ field }) => {
        const val = cursor[field];
        return typeof val === 'string' ? `'${val}'` : val;
      })
      .join(', ');

    const operator = sortFields[0].direction === 'DESC' ? '<' : '>';

    return `AND (${pairs}) ${operator} (${values})`;
  }

  buildConnection(
    items: T[],
    args: PaginationArgs,
    cursorFields: Array<keyof T>
  ): Connection<T> {
    const limit = Math.min(args.first ?? args.last ?? this.defaultLimit, this.maxLimit);
    const hasMore = items.length > limit;

    // limit+1件取得して最後の1件を切り捨てる
    const edges = items.slice(0, limit).map(item => ({
      node: item,
      cursor: CursorEncoder.encode(
        Object.fromEntries(cursorFields.map(f => [f, item[f]]))
      ),
    }));

    return {
      edges,
      pageInfo: {
        hasNextPage: args.first !== undefined ? hasMore : false,
        hasPreviousPage: args.last !== undefined ? hasMore : !!args.after,
        startCursor: edges[0]?.cursor ?? null,
        endCursor: edges[edges.length - 1]?.cursor ?? null,
      },
    };
  }
}

// src/pagination/postRepository.ts — 投稿一覧のカーソルページネーション

interface Post {
  id: string;
  title: string;
  createdAt: Date;
  authorId: string;
}

export class PostRepository {
  private readonly paginator = new CursorPaginator<Post>(20, 100);

  async findMany(args: PaginationArgs & { userId?: string }): Promise<Connection<Post>> {
    const limit = Math.min(args.first ?? args.last ?? 20, 100);

    let cursorWhere = '';
    if (args.after) {
      const cursor = CursorEncoder.decode(args.after);
      // (created_at, id) の複合カーソル（作成日時降順、同時刻はID降順）
      cursorWhere = `
        AND (p.created_at < '${cursor.createdAt}'
          OR (p.created_at = '${cursor.createdAt}' AND p.id < '${cursor.id}'))
      `;
    }

    // limit+1件取得（次ページ存在チェック用）
    const posts = await prisma.$queryRaw<Post[]>`
      SELECT p.id, p.title, p.created_at as "createdAt", p.author_id as "authorId"
      FROM posts p
      WHERE 1=1
        ${args.userId ? prisma.sql`AND p.author_id = ${args.userId}` : prisma.sql``}
        ${prisma.sql.raw(cursorWhere)}
      ORDER BY p.created_at DESC, p.id DESC
      LIMIT ${limit + 1}
    `;

    return this.paginator.buildConnection(posts, args, ['createdAt', 'id']);
  }
}

// REST APIエンドポイント
router.get('/api/posts', async (req, res) => {
  const repo = new PostRepository();

  const result = await repo.findMany({
    first: req.query.first ? parseInt(req.query.first as string) : 20,
    after: req.query.after as string | undefined,
  });

  // REST形式のレスポンス
  res.json({
    data: result.edges.map(e => e.node),
    pagination: {
      nextCursor: result.pageInfo.hasNextPage ? result.pageInfo.endCursor : null,
      hasMore: result.pageInfo.hasNextPage,
    },
  });
});

// GraphQLリゾルバー（GraphQL Connection仕様準拠）
const postsResolver = async (_: unknown, args: PaginationArgs) => {
  const repo = new PostRepository();
  return repo.findMany(args);
};

// 無限スクロールの使用例（フロントエンド側のロジック）
/*
let cursor: string | null = null;

async function loadMore() {
  const { data, pagination } = await fetch(`/api/posts?${cursor ? `after=${cursor}` : ''}`).then(r => r.json());

  appendPosts(data);
  cursor = pagination.nextCursor;

  if (!pagination.hasMore) {
    hideLoadMoreButton();
  }
}
*/

まとめ

Claude Codeでカーソルページネーションを設計する：

CLAUDE.md にカーソル = Base64エンコードされたソートキー・複合ソート（created_at+id）で安定ページング・limit+1件取得で次ページ存在判定を明記
複合カーソル条件 (created_at, id) < (cursorCreatedAt, cursorId) でOFFSET/LIMITのフルスキャンを回避——インデックスを使ってO(1)でカーソル位置にジャンプ。100万件のテーブルでも1ページ目と最後のページで速度差なし
不透明なカーソル（Base64） でクライアントがカーソルの内部構造に依存しない——ソートキーをcreated_at+idからscoreに変えてもAPIの互換性を維持できる
limit+1件取得 でSELECT COUNTを使わずにhasNextPageを判定——COUNTは大テーブルで遅いため、limit+1件取得して「limit超えたかどうか」だけ見る

DB設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude Codeでコンテンツベースルーティングを設計する：ペイロード内容によるメッセージ振り分け・動的ルーティング

myougaTheAxo — Wed, 18 Mar 2026 16:00:00 +0000

はじめに

「メッセージのペイロード内容によって送り先を変えたい」「高額注文は優先Workerへ、通常注文は通常Workerへ」——コンテンツベースルーティングで、メッセージの内容を評価して動的に送り先を決定する設計をClaude Codeに生成させる。

CLAUDE.mdにコンテンツベースルーティング設計ルールを書く

## コンテンツベースルーティング設計ルール

### ルーティングルール
- ルールはコードではなく設定として外部化（DB/Redis）
- ルール評価は高速（JSONPathまたはシンプルな条件式）
- デフォルトルート: どのルールにも一致しない場合の送り先

### ルーティング先の種類
- キュー名（Redis Stream/RabbitMQ Exchange）
- サービスエンドポイント（HTTP POST）
- 複数送り先（Fanout的な複数ルート）

### 動的ルール更新
- ルールのホットリロード（再起動不要）
- ルール変更はRedisキャッシュを即座に無効化
- ルール評価のテスト機能（test modeでメッセージを渡してルートを確認）

コンテンツベースルーティング実装の生成

コンテンツベースルーティングシステムを設計してください。

要件：
- 設定ベースのルーティングルール
- JSONPathによるペイロード評価
- 動的ルール更新
- ルーティングログ

生成ファイル: src/messaging/routing/

生成されるコンテンツベースルーティング実装

// src/messaging/routing/contentRouter.ts — コンテンツベースルーター

export type RouteCondition =
  | { type: 'field_equals'; field: string; value: unknown }
  | { type: 'field_greater_than'; field: string; value: number }
  | { type: 'field_in'; field: string; values: unknown[] }
  | { type: 'field_exists'; field: string }
  | { type: 'regex'; field: string; pattern: string }
  | { type: 'and'; conditions: RouteCondition[] }
  | { type: 'or'; conditions: RouteCondition[] };

export interface RoutingRule {
  id: string;
  name: string;
  priority: number;         // 低いほど優先（0が最高優先）
  condition: RouteCondition;
  destination: string;      // ルーティング先（キュー名またはURL）
  destinationType: 'queue' | 'http' | 'multi';
  destinations?: string[];  // destinationType='multi'の場合
  enabled: boolean;
}

export class ContentRouter {
  private rulesCache: RoutingRule[] | null = null;
  private cacheExpiresAt = 0;
  private readonly CACHE_TTL_MS = 30_000;

  async route(message: { messageId: string; eventType: string; payload: unknown }): Promise<{
    destination: string | string[];
    ruleName: string | 'default';
  }> {
    const rules = await this.getRules();

    for (const rule of rules) {
      if (!rule.enabled) continue;

      if (this.evaluate(message.payload, rule.condition)) {
        logger.debug({ messageId: message.messageId, ruleName: rule.name, destination: rule.destination }, 'Message routed');
        metrics.routingDecision.inc({ rule: rule.name });

        const destination = rule.destinationType === 'multi'
          ? (rule.destinations ?? [rule.destination])
          : rule.destination;

        return { destination, ruleName: rule.name };
      }
    }

    // デフォルトルート
    return { destination: 'queue:default', ruleName: 'default' };
  }

  private evaluate(payload: unknown, condition: RouteCondition): boolean {
    const obj = payload as Record<string, unknown>;

    switch (condition.type) {
      case 'field_equals':
        return this.getField(obj, condition.field) === condition.value;

      case 'field_greater_than':
        return Number(this.getField(obj, condition.field)) > condition.value;

      case 'field_in':
        return condition.values.includes(this.getField(obj, condition.field));

      case 'field_exists':
        return this.getField(obj, condition.field) !== undefined;

      case 'regex': {
        const value = String(this.getField(obj, condition.field) ?? '');
        return new RegExp(condition.pattern).test(value);
      }

      case 'and':
        return condition.conditions.every(c => this.evaluate(payload, c));

      case 'or':
        return condition.conditions.some(c => this.evaluate(payload, c));

      default:
        return false;
    }
  }

  // ネストされたフィールドへのアクセス（例: 'order.totalAmount'）
  private getField(obj: Record<string, unknown>, field: string): unknown {
    return field.split('.').reduce((current: unknown, key) => {
      if (current && typeof current === 'object') {
        return (current as Record<string, unknown>)[key];
      }
      return undefined;
    }, obj);
  }

  private async getRules(): Promise<RoutingRule[]> {
    if (this.rulesCache && Date.now() < this.cacheExpiresAt) {
      return this.rulesCache;
    }

    const rules = await prisma.routingRule.findMany({
      where: { enabled: true },
      orderBy: { priority: 'asc' },
    });

    this.rulesCache = rules.map(r => ({
      ...r,
      condition: JSON.parse(r.conditionJson),
    }));
    this.cacheExpiresAt = Date.now() + this.CACHE_TTL_MS;

    return this.rulesCache!;
  }

  // ルール変更時にキャッシュを無効化
  invalidateCache(): void {
    this.rulesCache = null;
    this.cacheExpiresAt = 0;
  }
}

// src/messaging/routing/routingRuleExamples.ts — ルール定義例

// ルール設定例（DBに保存）
const ROUTING_RULES: RoutingRule[] = [
  {
    id: 'vip-high-value',
    name: 'VIPユーザーの高額注文を優先キューへ',
    priority: 0,
    condition: {
      type: 'and',
      conditions: [
        { type: 'field_equals', field: 'user.tier', value: 'VIP' },
        { type: 'field_greater_than', field: 'order.totalAmount', value: 100_000 },
      ],
    },
    destination: 'queue:orders-priority',
    destinationType: 'queue',
    enabled: true,
  },
  {
    id: 'international-orders',
    name: '海外注文を国際配送チームへ',
    priority: 1,
    condition: {
      type: 'field_in',
      field: 'shipping.country',
      values: ['US', 'GB', 'AU', 'CA', 'DE', 'FR'],
    },
    destination: 'queue:orders-international',
    destinationType: 'queue',
    enabled: true,
  },
  {
    id: 'fraud-risk-review',
    name: '詐欺リスク高の注文を審査キューと通知へ',
    priority: 2,
    condition: {
      type: 'field_greater_than',
      field: 'fraudScore',
      value: 0.7,
    },
    destinations: ['queue:orders-review', 'queue:fraud-alerts'],
    destination: 'queue:orders-review',
    destinationType: 'multi',
    enabled: true,
  },
];

// 管理者API
router.get('/api/admin/routing/rules', requireAdmin, async (req, res) => {
  const rules = await prisma.routingRule.findMany({ orderBy: { priority: 'asc' } });
  res.json(rules);
});

router.put('/api/admin/routing/rules/:id', requireAdmin, async (req, res) => {
  await prisma.routingRule.update({ where: { id: req.params.id }, data: req.body });

  // ルーター全インスタンスのキャッシュを無効化
  await redis.publish('routing:cache-invalidate', 'rules-updated');
  res.json({ message: 'Rule updated' });
});

// テストモード: メッセージをルーターに通してどのルールが一致するか確認
router.post('/api/admin/routing/test', requireAdmin, async (req, res) => {
  const router = new ContentRouter();
  const result = await router.route({ messageId: 'test', eventType: req.body.eventType, payload: req.body.payload });
  res.json({ matched: result });
});

まとめ

Claude Codeでコンテンツベースルーティングを設計する：

CLAUDE.md にルールはDBに外部化してコード変更不要・JSONPath的な条件式で評価・デフォルトルートを必ず設定・ルール変更はキャッシュを即座に無効化を明記
条件式のAND/OR合成 でネストした条件を宣言的に記述——「VIPユーザーかつ 10万円以上」を{ type: 'and', conditions: [...] }で表現し、コードを変えずにルールを変更可能
multi destinationType で同じメッセージを複数キューに同時ルーティング——詐欺リスクが高い注文を審査キュー+アラートキューの両方に送る（Fan-outとの組み合わせ）
テストモードAPI でルール変更前に動作確認——「このペイロードはどのルールに一致するか」を本番ルールで事前検証して意図しないルーティングを防止

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。

Claude CodeでPipes and Filtersパターンを設計する：データ変換パイプライン・ミドルウェアチェーン・型安全な処理

myougaTheAxo — Wed, 18 Mar 2026 15:00:00 +0000

はじめに

「データ変換の処理が増えるたびにサービスが肥大化している」——Pipes and Filtersパターンで各変換ステップを独立したFilterにし、Pipeline（パイプ）で組み合わせて再利用可能なデータ変換チェーンを構築する設計をClaude Codeに生成させる。

CLAUDE.mdにPipes and Filters設計ルールを書く

## Pipes and Filters設計ルール

### Filterの設計
- 各Filterは単一責任（1つの変換だけを行う）
- 入力と出力の型を明示（TypeScript Generics）
- Filterはステートレス（状態を持たない）
- エラーはFilterがスローしてPipelineがキャッチ

### Pipeline構成
- Filterを配列で順番に指定
- 途中でエラーが出たら後続のFilterは実行しない
- 非同期FilterとStream Filterを混在可能

### テスト容易性
- 各Filterは独立してテスト可能（入力→出力の純粋関数）
- Pipelineは結合テスト（全Filterの連結）

Pipes and Filters実装の生成

Pipes and Filtersパターンを設計してください。

要件：
- 型安全なGenericパイプライン
- 非同期Filter対応
- エラーハンドリング
- 条件付きFilter（スキップ可能）

生成ファイル: src/pipeline/

生成されるPipes and Filters実装

// src/pipeline/pipeline.ts — 型安全なパイプラインエンジン

export type Filter<TIn, TOut> = (input: TIn, context: PipelineContext) => Promise<TOut> | TOut;

export interface ConditionalFilter<TIn, TOut> {
  filter: Filter<TIn, TOut>;
  when?: (input: TIn, context: PipelineContext) => boolean;
}

export interface PipelineContext {
  pipelineId: string;
  startedAt: Date;
  metadata: Record<string, unknown>;
  filterResults: Map<string, unknown>;
}

// 型推論でパイプラインの入出力型を連鎖させるビルダー
export class Pipeline<T> {
  private readonly filters: Array<ConditionalFilter<unknown, unknown>> = [];

  pipe<TOut>(
    filter: Filter<T, TOut>,
    options: { when?: (input: T, ctx: PipelineContext) => boolean; name?: string } = {}
  ): Pipeline<TOut> {
    this.filters.push({
      filter: filter as Filter<unknown, unknown>,
      when: options.when as ((input: unknown, ctx: PipelineContext) => boolean) | undefined,
    });
    return this as unknown as Pipeline<TOut>;
  }

  async execute(input: T): Promise<T> {
    const context: PipelineContext = {
      pipelineId: ulid(),
      startedAt: new Date(),
      metadata: {},
      filterResults: new Map(),
    };

    let current: unknown = input;

    for (let i = 0; i < this.filters.length; i++) {
      const { filter, when } = this.filters[i];

      // 条件フィルタ: whenがfalseなら現在の値をそのまま通す
      if (when && !when(current, context)) {
        logger.debug({ pipelineId: context.pipelineId, filterIndex: i }, 'Filter skipped by condition');
        continue;
      }

      const filterStartMs = Date.now();

      try {
        const result = await filter(current, context);
        context.filterResults.set(`filter-${i}`, result);
        current = result;

        logger.debug(
          { pipelineId: context.pipelineId, filterIndex: i, durationMs: Date.now() - filterStartMs },
          'Filter completed'
        );
      } catch (error) {
        logger.error(
          { pipelineId: context.pipelineId, filterIndex: i, error },
          'Pipeline filter failed'
        );
        throw new PipelineError(`Filter ${i} failed: ${(error as Error).message}`, i, error as Error);
      }
    }

    return current as T;
  }
}

export class PipelineError extends Error {
  constructor(message: string, public readonly filterIndex: number, public readonly cause: Error) {
    super(message);
  }
}

// src/pipeline/filters/orderFilters.ts — 注文処理パイプラインのFilter群

interface RawOrderInput {
  userId: string;
  items: Array<{ productId: string; quantity: number }>;
  couponCode?: string;
}

interface ValidatedOrder extends RawOrderInput {
  items: Array<{ productId: string; quantity: number; price: number; stockAvailable: boolean }>;
  user: User;
}

interface PricedOrder extends ValidatedOrder {
  subtotal: number;
  discountAmount: number;
  totalAmount: number;
}

interface TaxedOrder extends PricedOrder {
  taxAmount: number;
  finalAmount: number;
}

// Filter 1: バリデーション + データエンリッチメント
const validateAndEnrichFilter: Filter<RawOrderInput, ValidatedOrder> = async (input) => {
  const user = await userService.getUser(input.userId);
  if (!user) throw new ValidationError(`User ${input.userId} not found`);

  const enrichedItems = await Promise.all(
    input.items.map(async item => {
      const product = await productService.getProduct(item.productId);
      const stock = await inventoryService.checkStock(item.productId, item.quantity);
      return { ...item, price: product.price, stockAvailable: stock.available };
    })
  );

  const outOfStock = enrichedItems.filter(i => !i.stockAvailable);
  if (outOfStock.length > 0) {
    throw new OutOfStockError(outOfStock.map(i => i.productId));
  }

  return { ...input, items: enrichedItems, user };
};

// Filter 2: 価格計算 + クーポン適用
const calculatePriceFilter: Filter<ValidatedOrder, PricedOrder> = async (input) => {
  const subtotal = input.items.reduce((sum, item) => sum + item.price * item.quantity, 0);

  let discountAmount = 0;
  if (input.couponCode) {
    const coupon = await couponService.validate(input.couponCode, subtotal);
    discountAmount = coupon.discountAmount;
  }

  return { ...input, subtotal, discountAmount, totalAmount: subtotal - discountAmount };
};

// Filter 3: 税計算（任意: 課税ユーザーのみ）
const calculateTaxFilter: Filter<PricedOrder, TaxedOrder> = async (input) => {
  const taxRate = await taxService.getTaxRate(input.user.country);
  const taxAmount = Math.round(input.totalAmount * taxRate);
  return { ...input, taxAmount, finalAmount: input.totalAmount + taxAmount };
};

// Filter 4: 詐欺チェック
const fraudCheckFilter: Filter<TaxedOrder, TaxedOrder> = async (input) => {
  const riskScore = await fraudService.calculateRisk(input.userId, input.finalAmount);
  if (riskScore > 0.8) throw new FraudDetectedError(`High risk score: ${riskScore}`);
  return input;
};

// パイプライン組み立て
export function createOrderPipeline() {
  return new Pipeline<RawOrderInput>()
    .pipe(validateAndEnrichFilter)
    .pipe(calculatePriceFilter)
    .pipe(calculateTaxFilter, {
      // 課税対象ユーザーのみ税計算
      when: (input, _ctx) => (input as ValidatedOrder).user.taxable === true,
    })
    .pipe(fraudCheckFilter, {
      // 金額が1万円以上の場合のみ詐欺チェック
      when: (input, _ctx) => (input as PricedOrder).totalAmount >= 10_000,
    });
}

// 使用例
const pipeline = createOrderPipeline();

const processedOrder = await pipeline.execute({
  userId: 'user-123',
  items: [{ productId: 'prod-abc', quantity: 2 }],
  couponCode: 'SAVE10',
});

まとめ

Claude CodeでPipes and Filtersパターンを設計する：

CLAUDE.md に各Filterは単一責任・ステートレス・TypeScript Genericsで入出力型を明示・エラーはFilterがスローしてPipelineがインデックスとともに記録を明記
型推論による連鎖 Pipeline<RawInput>.pipe(filter1).pipe(filter2)でTypeScriptが各Filterの入出力型を自動推論——Filter2はFilter1の出力型しか受け取れない型安全なチェーン
条件付きFilter（whenオプション） でユーザー属性や金額に応じてFilterをスキップ——「課税ユーザーにだけ税計算、1万円以上にだけ詐欺チェック」を宣言的に記述
FilterResultsのコンテキスト保存 で後続Filterが前のFilterの結果を参照可能——「Filter2が計算した小計をFilter4が参照する」といった依存関係をContextで解決

アーキテクチャ設計のレビューは **Code Review Pack（¥980）* の /code-review で確認できます。*

prompt-works.jp

みょうが (@myougatheaxo) — ウーパールーパーのVTuber。