CLAUDE.md、AGENT.md、Skills完全攻略：AIコーディング生産性最大化ガイド

my-project/
  CLAUDE.md          # プロジェクト全体の設定
  src/
    CLAUDE.md        # srcディレクトリ固有の設定
    components/
      CLAUDE.md      # コンポーネント固有の設定
  backend/
    CLAUDE.md        # バックエンド固有の設定

# Project Overview

プロジェクトの目的、技術スタック、アーキテクチャ概要

# Tech Stack

- Language: TypeScript 5.x
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Testing Library

# Project Structure

src/
app/ # Next.js App Router
components/ # Reactコンポーネント
lib/ # ユーティリティ関数
types/ # TypeScript型定義

# Coding Standards

- 関数は最大50行
- any型の使用禁止
- すべての関数にJSDoc必須
- コンポーネントはnamed exportのみ使用

# Testing Requirements

- すべてのユーティリティ関数：単体テスト必須
- APIルート：統合テスト必須
- カバレッジ80%以上

# Git Conventions

- Conventional Commits準拠
- PRあたり200行以下

# Forbidden Patterns

- console.logをプロダクションコードで使用禁止
- any型禁止
- ハードコードされたURL禁止

# Project Structure

src/
app/ # Next.js App Router - ページとレイアウト
(auth)/ # 認証が必要なルートグループ
(public)/ # 公開ルートグループ
api/ # API Route Handlers
components/ # 再利用可能なReactコンポーネント
ui/ # shadcn/uiベースの基本UIコンポーネント
features/ # 機能別コンポーネント（auth、dashboardなど）
lib/ # 純粋なユーティリティ関数（フレームワーク依存なし）
hooks/ # カスタムReact Hooks
stores/ # Zustand状態管理
types/ # TypeScript型定義
server/ # サーバー専用コード（DB、外部APIなど）

# Forbidden Patterns

## 型関連

- `any`型の使用禁止 → `unknown`または具体的な型を使用
- `@ts-ignore`の使用禁止 → 型エラーの根本原因を解決
- `as any`型キャスト禁止

## コード品質

- `console.log`、`console.debug`をプロダクションコードで使用禁止 → loggerを使用
- TODOコメントなしで未完成のコードをコミットしない（TODOにはissueリンクが必須）
- マジックナンバー禁止 → 名前付き定数として抽出

## アーキテクチャ

- コンポーネントから直接fetchを呼び出すことを禁止 → カスタムhookまたはserver actionを使用
- クライアントコンポーネントからDBを直接クエリすることを禁止
- ハードコードされたURL禁止 → 環境変数を使用

## セキュリティ

- ユーザー入力を直接SQLに挿入することを禁止 → Prisma ORMを使用
- クライアントにシークレットキーを公開することを禁止
- 認証なしに管理者用APIエンドポイントを作成することを禁止

## パフォーマンス

- useEffect内で無限ループを引き起こす依存配列のエラーに注意
- 大量のデータセットをクライアントサイドでフィルタリングすることを禁止 → DBレベルでフィルタリング

# Before Creating New Code

新しいコードを書く前に、常に以下を確認してください:

1. src/lib/にすでに実装されたユーティリティがないか
2. src/hooks/に類似のカスタムフックがないか
3. src/components/ui/に再利用可能なコンポーネントがないか
4. src/server/に再利用可能なサーバーアクションがないか

重複実装はコードベースの保守性を著しく低下させます。

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    performance-check.md

現在のステージされた変更を分析し、Conventional Commits形式で
コミットメッセージを作成してください。日本語で記述。

形式:
type(scope): subject

body（任意、変更理由と影響の説明）

footer（任意、Breaking ChangeまたはIssue番号）

typeの選択基準:

- feat: 新機能追加
- fix: バグ修正
- refactor: 機能変更なしのコード改善
- test: テストの追加/修正
- docs: ドキュメント変更
- chore: ビルド/設定変更
- perf: パフォーマンス改善

scopeは変更されたモジュール/コンポーネント名を使用。
subjectは50文字以下、命令形で記述。

現在のブランチの変更を分析してPR説明を作成してください。

## 変更サマリー

- （箇条書きで主要な変更点を列挙）

## 変更理由

（なぜこの変更が必要かを説明）

## テスト方法

- [ ] （検証方法のチェックリスト）

## スクリーンショット

（UI変更がある場合、スクリーンショットが必要かどうかを明示）

## 注意事項

（レビュアーが知っておくべき特記事項）

選択されたコードの単体テストを作成してください。
Vitest + Testing Libraryを使用。

以下を含めること:

1. 正常系（ハッピーパス）
2. 境界値テスト
3. エラーケース（例外処理）
4. エッジケース（null、undefined、空配列など）

テスト命名: should [expected behavior] when [condition] 形式
モックは最小限に抑え、実際の実装に近い形で記述。

このコードをレビューしてください。以下の観点から分析し、
各項目に深刻度（Critical/Major/Minor）を表示してください:

1. バグの可能性
   - 論理エラー、未処理のエッジケース、競合状態など

2. セキュリティの脆弱性
   - 認証/認可エラー、インジェクション脆弱性、機密情報の露出など

3. パフォーマンス問題
   - 不要な再レンダリング、N+1クエリ、メモリリークなど

4. 可読性の改善点
   - 複雑なロジック、不明確な変数名、重複コードなど

5. テスタビリティ
   - 依存性の注入、純粋関数の使用、モックのしやすさなど

各指摘事項には改善コード例を含めてください。

このコードのJSDocドキュメントを作成してください。

各関数/クラス/型について:

- @description: 機能説明（2〜3文）
- @param: 各パラメータの型、説明、サンプル値
- @returns: 戻り値の型と説明
- @throws: 発生しうる例外
- @example: 実際の使用例コード

複雑なビジネスロジックがある場合はアルゴリズムの説明も含めてください。

このコードをリファクタリングしてください。

目標:

- 重複の除去（DRY原則）
- 可読性の向上（複雑度の削減）
- SOLID原則の適用
- テスタビリティの向上

制約:

- 既存の機能は変更しないこと
- パブリックAPI（関数シグネチャ、モジュールインターフェース）は維持すること
- 段階的にリファクタリング（一度に多く変えすぎない）

リファクタリング前後を比較して示し、各変更の理由を説明してください。

このコードのセキュリティ脆弱性をOWASP Top 10基準で確認してください。

特に確認すること:

1. インジェクション（SQL、コマンド、XSS）
2. 認証/認可エラー
3. 機密データの露出
4. セキュリティ設定の誤り
5. 既知の脆弱性を持つコンポーネントの使用

各脆弱性について:

- リスクレベル（High/Medium/Low）
- 攻撃シナリオの説明
- 修正方法とコード例

このコードのパフォーマンス問題を分析してください。

確認項目:

1. アルゴリズムの複雑度（時間/空間）
2. 不要な再計算（メモ化の可否）
3. データベースクエリの最適化（N+1、インデックス活用）
4. ネットワークリクエストの最適化（バッチ処理、キャッシュ）
5. レンダリングの最適化（Reactコンポーネントの場合）

各問題に対して改善コード例を含めてください。

# E-Commerce Platform

## Overview

B2Cイーコマースプラットフォーム。顧客ショッピング、
注文管理、管理者ダッシュボードで構成。
MAU 50万、1日5千件の注文を処理。

## Tech Stack

- Next.js 15 (App Router, RSC)
- TypeScript 5.x (strictモード)
- PostgreSQL 16 + Prisma ORM
- Redis（セッション、キャッシュ）
- Stripe（決済）
- Vercel（デプロイ）

## Domain Model

- User: 顧客アカウント、複数配送先対応
- Product: SKUベースの在庫管理、カテゴリツリー
- Order: Draft to Pending to Confirmed to Shipped to Delivered to Cancelled
- Cart: Redisベース、未ログインユーザーも対応（セッションベース）

## Architecture Rules

- サーバーコンポーネントからDBを直接クエリ（Prisma）
- クライアントからのAPI呼び出しは/apiルート経由
- 複雑なビジネスロジックはsrc/server/services/に配置
- 決済関連コードは必ずサーバーサイドで

## Forbidden

- クライアントコンポーネントでPrismaを直接使用
- 決済金額をクライアントで計算（必ずサーバーで）
- any型
- ハードコードされた価格/割引率

# Order Service

## Overview

注文処理マイクロサービス。gRPC内部通信、REST外部公開。
目標: 秒間500 TPS処理。

## Tech Stack

- Go 1.23
- Fiber（HTTP）、gRPC（内部通信）
- PostgreSQL + sqlc（型安全クエリ）
- Redis（分散ロック、キャッシュ）
- OpenTelemetry（分散トレーシング）

## Code Style

- エラーは必ず上位に伝搬（errors.Wrapを使用）
- すべてのDBクエリにコンテキストを含める（ctxパラメータ必須）
- ログはzerolog構造化ログのみ使用
- インターフェースを先に定義し、実装は後で

## Project Layout (Standard Go Layout)

cmd/ # mainパッケージ
internal/ # 外部に公開しないコード
domain/ # ドメインモデルとインターフェース
service/ # ビジネスロジック
repository/ # DBアクセス層
handler/ # HTTP/gRPCハンドラ
pkg/ # 外部公開可能なユーティリティ

## Forbidden

- recoverなしのpanic使用禁止
- ハンドラでcontext.Background()を直接使用禁止
- グローバル状態禁止
- goroutineリークを引き起こすパターン

# Payment Service

## Overview

決済処理サービス。PCI-DSS準拠が必須。
Kafkaイベントベースの非同期処理。

## Tech Stack

- Java 21（Virtual Threads活用）
- Spring Boot 3.x
- Spring Data JPA + Hibernate
- Apache Kafka（イベントストリーミング）
- Vault（シークレット管理）

## Architecture

Hexagonal Architecture（Ports & Adapters）:

- domain/: 純粋なドメインモデル（依存なし）
- application/: ユースケース、ポートインターフェース
- infrastructure/: アダプター（DB、Kafka、外部API）
- interfaces/: コントローラー、DTO

## Rules

- ドメイン層にSpringの依存なし
- すべての金額はBigDecimal（doubleやfloatは絶対禁止）
- 外部決済API呼び出しにはCircuit Breakerパターンを適用
- 補償トランザクションパターンで分散トランザクションを処理

## Forbidden

- BigDecimalの代わりにdoubleで金額計算
- 決済情報をマスキングなしでログ出力
- 同期決済API呼び出しのタイムアウト未設定

決済処理関数を作って

【背景】イーコマースプラットフォームでStripeを使って決済を処理しています。
現在src/server/services/payment.tsファイルに決済関連ロジックがあります。

【制約】
- 金額は必ずサーバーで計算する（クライアント入力を信頼しない）
- 決済失敗時のリトライは最大3回、指数バックオフを使用
- すべての決済イベントはaudit logに保存

【リクエスト】
カートのチェックアウト時にStripe Payment Intentを作成する
processCheckout関数を書いてください。TypeScript、async/awaitを使用。

ステップ1: 「ユーザー認証システムのデータベーススキーマを設計して」
ステップ2: 「このスキーマをベースにPrismaモデルを作成して」
ステップ3: 「ログインのビジネスロジックをサービス層に実装して」
ステップ4: 「このサービスを使うAPIルートハンドラを作って」
ステップ5: 「各レイヤーのテストを書いて」

私たちのプロジェクトはこのパターンでAPIルートを書いています:

【例】
export async function GET(req: NextRequest) {
  try {
    const session = await getServerSession(authOptions)
    if (!session) return unauthorized()

    const data = await getUserData(session.user.id)
    return ok(data)
  } catch (error) {
    logger.error('Failed to get user data', { error })
    return internalError()
  }
}

このパターンで注文リストを取得するAPIルートを作成してください。

商品検索機能を実装してください。

絶対にやってはいけないこと:
- クライアントサイドで全データを取得してフィルタリング（パフォーマンス問題）
- 検索ワードをSQLに直接挿入（インジェクション脆弱性）
- キャッシュなしで毎リクエストDBをフルスキャン

このコードにパフォーマンス問題があるか分析してください。
分析前に以下の順序で進めてください:
1. コードがどんな作業をしているかを説明
2. 時間/空間計算量の分析
3. 潜在的なボトルネックの特定
4. 改善案の提示

エラー発生 → コンテキスト収集 → AIに分析依頼 → 解決策の検証

コンテキスト収集チェックリスト:
- エラーメッセージ全文（スタックトレース含む）
- エラー発生時の入力値
- 最近変更されたコード（git diff）
- 関連ログ（エラーの前後30行）
- 環境情報（開発/ステージング/プロダクション）

AIへのリクエスト時:
「上記のエラーが発生しました。考えられる原因を3つ分析して、
それぞれのデバッグ方法を教えてください」

# チームAI活用ガイドライン

## 許可される範囲

- コード生成とリファクタリング
- テストコードの作成
- ドキュメント化とコメント
- デバッグ支援
- コードレビューの補助

## 常に人がレビューすべき領域

- セキュリティ関連コード（認証、認可、暗号化）
- 決済および金融処理ロジック
- 個人情報処理コード
- アーキテクチャレベルの決定

## AI生成コードの管理

- AIが生成したコードでも、コミット前に必ず理解してレビューする
- 「AIが作ったから正しいはずだ」は禁止
- 理解できないコードはAIに説明を依頼する

# 最初の作業スペース
git worktree add ../project-feature-a feature/payment-v2

# 2番目の作業スペース（別ディレクトリ、別ブランチ）
git worktree add ../project-feature-b feature/user-profile-v2

# ワークツリーの一覧を確認
git worktree list