Claude Code: CLAUDE.md 使用ガイド

# CLAUDE.md

## Project Overview
[プロジェクトが何で何をするかの一行説明]

## Tech Stack
[言語、フレームワーク、データベース、ツールチェーン]

## Common Commands
[ビルド、テスト、デプロイ、開発コマンド]

## Code Conventions
[命名規則、ファイル構成、スタイル要件]

## Constraints and Limitations
[やってはいけないこと、やらなければならないこと]

## Known Issues
[技術的負債と特别注意が必要な落とし穴]

# CLAUDE.md

## Project Overview
SaaS 課金プラットフォームバックエンド、サブスクリプション管理、請求書生成、決済統合を担当。

## Tech Stack
- Node.js 20 + TypeScript 5.3
- Express 4.18 + middleware chain
- Prisma 5.x (PostgreSQL)
- Redis (cache + queue)
- Jest + Supertest (testing)

## Common Commands
- `npm run dev` — 開発サーバー起動（ポート3000）
- `npm test` — 全テスト実行
- `npm run lint` — ESLint チェック
- `npx prisma migrate dev` — データベースマイグレーション

## Code Conventions
- Service レイヤーはビジネスロジックのみを処理、HTTP オブジェクトへの直接アクセス禁止
- Controller レイヤーはリクエスト/レスポンス変換を処理
- すべてのデータベース操作は Repository パターン経由
- エラーは statusCode と code を持つ AppError クラスを使用
- API レスポンス形式：`{ success: boolean, data: T, error?: string }`

## Constraints
- ❌ pg クライアントを直接使用せず、必ず Prisma を使用
- ❌ Service レイヤーで req/res にアクセスしない
- ❌ シークレットや認証情報をハードコードしない
- ✅ すべての API エンドポイントにインテグレーションテストが必要
- ✅ 金額はすべてセント（整数）を使用、浮動小数点エラーを回避

## Known Issues
- PaymentService.processRefund に同時実行の問題あり（ISSUE-342 参照）
- InvoiceService.generatePDF は項目数が多い場合にパフォーマンス低下（ISSUE-156 参照）

~/.claude/CLAUDE.md          # グローバル：個人の好み
project-root/CLAUDE.md       # プロジェクト：チームの規約
project-root/src/api/CLAUDE.md  # ディレクトリ：ローカルの指示

<!-- ~/.claude/CLAUDE.md -->
# Global Preferences

## Code Style
- TypeScript strict モードを使用
- const を優先し、let を避ける
- 関数は20行以内
- JSDoc コメントを追加

## Testing Preferences
- describe/it スタイルを使用
- 各テストは独立、実行順序に依存しない
- 外部依存をモックし、内部モジュールはモックしない

<!-- src/api/CLAUDE.md -->
# API Module Conventions

## Route Registration
- すべてのルートは index.ts に一元登録
- ミドルウェアの順序：auth → rateLimit → validate → handler

## Response Format
- 成功：{ success: true, data: T }
- 失敗：{ success: false, error: { code, message } }

## Prohibited
- ❌ ハンドラにビジネスロジックを直接書かない
- ❌ パラメータバリデーションをスキップしない

> Update CLAUDE.md based on recent code changes

Claude Code:
  → 最近のコミットを読み取り中
  → 変更を検出：Express → Fastify、Redis 追加、Jest → Vitest
  → CLAUDE.md を現在の技術スタックとコマンドで更新
  CLAUDE.md updated ✓