Claude Code CLAUDE.md完全設計ガイド｜3層構造・@インポート・自動メモリでAIとのコンテキスト共有を最大化

# プロジェクト概要
ECサイトのバックエンドAPI。Node.js + TypeScript + PostgreSQL + Prismaで構築。
認証はJWT、外部決済にStripeを使用。

## よく使うコマンド
- `npm run dev`: 開発サーバー起動（port 3000）
- `npm test`: テスト実行（Jest、--watchは使わない）
- `npm run build`: TypeScriptビルド
- `npm run db:migrate`: Prismaマイグレーション実行
- `npm run lint`: ESLint実行
- `npm run typecheck`: 型チェックのみ（ビルドなし）

## アーキテクチャ
- `src/routes/`: Expressルーター（ルーティングのみ、ビジネスロジックを含めない）
- `src/services/`: ビジネスロジック（ここに実装する）
- `src/repositories/`: Prismaを使ったDB操作（直接SQLは書かない）
- `src/middleware/`: 認証・バリデーション・エラーハンドリング

## コーディング規約
- TypeScript strict モードを遵守（anyは禁止）
- 関数は100行以内に収める
- エラーはResult型でハンドリング（例外を使わない）
- console.logは本番コードに残さない
- すべてのAPIエンドポイントにzodバリデーションを追加する

## 禁止事項
- mainブランチへの直接コミット（PRを通すこと）
- ORMを使わない生のSQL（セキュリティリスク）
- src/外へのファイル作成（設定ファイルはルートに置く）

## テスト方針
- ユニットテスト必須（新機能・バグ修正どちらも）
- テストファイルは対象ファイルと同じディレクトリに配置（.test.tsサフィックス）
- モックはRepositoryレイヤーのみ（Serviceのテストは実Repositoryを使わない）

project/
├── CLAUDE.md                    ← メインファイル（概要・インポート宣言）
└── docs/
    ├── architecture.md      ← アーキテクチャの詳細
    ├── testing.md           ← テスト規約の詳細
    ├── deployment.md        ← デプロイ手順
    └── security.md          ← セキュリティルール

# ECサイト バックエンドAPI

## クイックリファレンス
- 開発サーバー: `npm run dev`
- テスト: `npm test`
- DB操作: `npm run db:migrate`

## 詳細ルール
@docs/architecture.md
@docs/testing.md
@docs/deployment.md
@docs/security.md

## アーキテクチャルール

### レイヤー構造
- `routes/`: ルーティングのみ（ビジネスロジックを含めない）
- `services/`: ビジネスロジック（ここに実装する）
- `repositories/`: Prisma経由のDB操作（生SQLは書かない）
- `middleware/`: 認証・バリデーション・エラーハンドリング

### 依存関係のルール
- routes → services → repositories（この方向のみ）
- services間の直接呼び出しは禁止（循環依存防止）
- 外部APIアクセスはすべて`services/external/`に集約

### 命名規則
- ファイル名: kebab-case（例: user-service.ts）
- クラス名・インターフェース名: PascalCase
- 関数・変数: camelCase
- 定数: UPPER_SNAKE_CASE

### 型定義の置き場所
- ドメインモデルは`src/types/`に集約
- リクエスト/レスポンス型はzodスキーマから自動生成（`z.infer<>`）
- Prismaの型は直接使用可（Prismaクライアントから）

# 個人設定

## 開発スタイル
- コードを書く前に必ず既存の実装を読んでから変更を提案する
- 変更が大きい場合は先に計画を提示して承認を取ってから実装する
- テストを書かずに実装だけ終わらせることを避ける

## コミットスタイル
- コミットメッセージは日本語で書く
- フォーマット: [種別] 変更内容（50文字以内）
  - [feat] 新機能追加
  - [fix] バグ修正
  - [refactor] リファクタリング
  - [test] テスト追加・修正
  - [docs] ドキュメント更新
- 1コミットは1つの変更にまとめる

## 回答スタイル
- 長い説明より短い説明を優先する
- コードの変更前後を明示する
- 「確認してください」という終わり方を減らし、完成したものを提示する

## セキュリティ
- APIキー・パスワード・シークレットをコードに書かない
- 環境変数は.envファイルで管理し、.gitignoreに追加する

# 個人用のプロジェクト設定は共有しない
CLAUDE.local.md

## CLAUDE.mdの更新方針

このファイルへの変更はPRを通してチームレビューを受けること。

更新すべきタイミング:
- 新しいアーキテクチャパターンを採用したとき
- バグや問題が繰り返し発生してルール追加が必要なとき
- テスト方針・命名規則が変わったとき

更新してはいけないこと:
- 個人の好みによる変更（チームの合意なしに）
- 一時的な対処（永続的なルールとしてではなく）

~/.claude/projects/<project>/memory/
├── MEMORY.md             # 索引。毎セッション読み込まれる
├── user_role.md          # 1つのメモ
├── feedback_testing.md   # 1つのメモ
└── ...                   # Claudeが作るその他のトピックファイル

# セッション中に
> このプロジェクトではAuthorizationヘッダーにBearerトークンを使う。
> このことをメモリに記録しておいて。

# CLAUDE.mdに追加したいときは、そう頼むか /memory から編集する
> /memory
# CLAUDE.mdやAuto Memoryのファイル一覧が開き、選んだファイルをエディタで編集できる

project/
├── CLAUDE.md
└── docs/
    ├── database.md    ← DBスキーマ・テーブル設計の詳細（安定した参照情報）
    ├── api-spec.md    ← 主要APIのエンドポイント仕様
    └── decisions.md   ← アーキテクチャの決定記録（ADR）

## アーキテクチャ決定記録（ADR）

### [2026-03-10] 状態管理にZustandを採用
- 背景: Reduxは複雑すぎてチームのキャッチアップコストが高かった
- 決定: Zustandを採用。シンプルなAPIでチーム全員が即時使える
- 影響: 既存のReduxストアを順次Zustandに移行（完了目標: 2026-Q2）

### [2026-02-20] APIクライアントにtanstack-queryを採用
- 背景: フロントエンドのキャッシュ戦略が複雑になっていた
- 決定: tanstack-queryで統一。キャッシュ・リフェッチを自動化
- 影響: カスタムフックでAPIアクセスをラップする規約を追加

### [2026-01-15] 認証トークンをhttpOnlyクッキーに変更
- 背景: XSS攻撃でlocalStorageのトークンが盗まれるリスクを排除
- 決定: JWTをhttpOnlyクッキーで管理。Refresh tokenローテーションを実装
- 影響: フロントエンドのAuthヘッダー送信が不要に。Cookieが自動送信される

## よくある間違い（修正済み）

- **認証ミドルウェアの順序**: `verifyToken`は`rateLimit`の後、`validateRequest`の前に置くこと
  （理由: レート制限の前にトークン検証すると無効トークンへのブルートフォースを防げない）

- **Prismaトランザクション**: 複数テーブルを更新する場合は必ず`prisma.$transaction()`を使うこと
  （理由: 一部だけ更新されてデータ不整合が起きたことがある）

- **型アサーション禁止**: `as SomeType`を使わず型ガードを実装すること
  （理由: asを使うと型チェックをバイパスしてランタイムエラーの原因になる）