# Payload CMS コードリーディングガイドライン

## はじめに

このガイドラインは、Payload CMSのコードベースを効率的に理解するための手引きです。
TypeScriptに精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

**プロジェクト概要:**
Payload CMSは、Next.js上に構築されたヘッドレスCMSおよびアプリケーションフレームワークです。React Server Components（RSC）を活用したAdmin UIと、複数のデータベースアダプター（MongoDB、PostgreSQL、SQLite等）をサポートしています。

---

## 1. 言語基礎

> このセクションでは、TypeScriptの基本構文と概念を解説します。

### 1.1 プログラム構造

PayloadはTypeScript（ESモジュール形式）で記述されています。ファイルは`.ts`または`.tsx`（Reactコンポーネント用）拡張子を持ちます。

```typescript
// packages/payload/src/config/build.ts:1-20
import type { Config, SanitizedConfig } from './types.js'

import { sanitizeConfig } from './sanitize.js'

/**
 * @description Builds and validates Payload configuration
 * @param config Payload Config
 * @returns Built and sanitized Payload Config
 */
export async function buildConfig(config: Config): Promise<SanitizedConfig> {
  if (Array.isArray(config.plugins)) {
    let configAfterPlugins = config
    for (const plugin of config.plugins) {
      configAfterPlugins = await plugin(configAfterPlugins)
    }
    return await sanitizeConfig(configAfterPlugins)
  }

  return await sanitizeConfig(config)
}
```

**ポイント:**
- `import type` は型のみのインポート（ランタイムに含まれない）
- `import` は通常のモジュールインポート（値とともにランタイムに含まれる）
- `.js` 拡張子は TypeScript のモジュール解決設定に基づく（実際には `.ts` ファイルを参照）

### 1.2 データ型と変数

Payloadでは厳格な型定義を使用しています。型定義は主に`types.ts`ファイルに集約されています。

```typescript
// packages/payload/src/collections/config/types.ts:76-78
export type DataFromCollectionSlug<TSlug extends CollectionSlug> = TypedCollection[TSlug]

export type SelectFromCollectionSlug<TSlug extends CollectionSlug> = TypedCollectionSelect[TSlug]
```

**型パラメータ（ジェネリクス）の活用:**
- `<TSlug extends CollectionSlug>` はCollectionSlugを継承する型パラメータ
- これによりコレクションごとに適切な型が推論される

### 1.3 制御構造

```typescript
// packages/payload/src/utilities/traverseFields.ts:34-68
if (fillEmpty) {
  if (field.type === 'array') {
    traverseFields({
      callback,
      callbackStack,
      config,
      fields: field.fields,
      isTopLevel: false,
      // ...
    })
  }
  if (field.type === 'blocks') {
    for (const _block of field.blockReferences ?? field.blocks) {
      const block =
        typeof _block === 'string' ? config?.blocks?.find((b) => b.slug === _block) : _block
      // ...
    }
  }
  return
}
```

**ポイント:**
- `??` はNullish Coalescing演算子（左側がnull/undefinedの場合に右側を返す）
- `?.` はOptional Chaining（プロパティが存在しない場合にundefinedを返す）

### 1.4 関数/メソッド定義

Payloadでは関数を優先的に使用し、クラスはエラーやアダプターに限定しています。

```typescript
// packages/payload/src/collections/operations/local/find.ts:1-30
import type { PaginatedDocs } from '../../../database/types.js'
// ... 他のimport

type BaseFindOptions<TSlug extends CollectionSlug, TSelect extends SelectType> = {
  /**
   * the Collection slug to operate against.
   */
  collection: TSlug
  /**
   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
   */
  context?: RequestContext
  // ...
}
```

**コーディング規約:**
- 単一オブジェクトパラメータを優先（後方互換性向上のため）
- JSDocコメントは複雑な関数に付与
- `is`/`has`/`can`/`should` プレフィックスでboolean変数を命名

### 1.5 モジュール/インポート

```typescript
// packages/payload/src/index.ts:1-50
/* eslint-disable @typescript-eslint/no-explicit-any */
import type { ExecutionResult, GraphQLSchema, ValidationRule } from 'graphql'
import type { Request as graphQLRequest, OperationArgs } from 'graphql-http'
import type { Logger } from 'pino'
// ...

import { spawn } from 'child_process'
import crypto from 'crypto'
import { fileURLToPath } from 'node:url'
import path from 'path'
import WebSocket from 'ws'

// ローカルモジュール
import type { AuthArgs } from './auth/operations/auth.js'
import type { Result as ForgotPasswordResult } from './auth/operations/forgotPassword.js'
```

**インポート規約:**
- 型インポート（`import type`）と値インポート（`import`）を分離
- 同一モジュールでも型と値は別ステートメント
- 外部パッケージを先、ローカルモジュールを後

---

## 2. プロジェクト固有の概念

> このセクションでは、Payload CMS特有の概念を解説します。

### 2.1 フレームワーク固有の概念

#### Collections（コレクション）
データベースのテーブル/コレクションに相当する概念です。

```typescript
// test/fields/baseConfig.ts:46-60
export const collections: CollectionConfig[] = [
  {
    slug: 'users',
    admin: {
      useAsTitle: 'email',
    },
    auth: true,
    fields: [
      {
        name: 'canViewConditionalField',
        type: 'checkbox',
        defaultValue: true,
      },
    ],
  },
  // ...
]
```

#### Globals（グローバル）
単一インスタンスのデータ（サイト設定など）を管理します。

```typescript
// packages/payload/src/globals/config/types.ts:43-45
export type DataFromGlobalSlug<TSlug extends GlobalSlug> = TypedGlobal[TSlug]

export type SelectFromGlobalSlug<TSlug extends GlobalSlug> = TypedGlobalSelect[TSlug]
```

#### Fields（フィールド）
コレクションやグローバルのデータ構造を定義します。

```typescript
// packages/payload/src/fields/config/types.ts に各フィールド型が定義
// 例: TextField, NumberField, RelationshipField, ArrayField, BlocksField等
```

### 2.2 プロジェクト独自のパターン

#### Payloadシングルトンパターン

```typescript
// packages/payload/src/index.ts:1012-1015
const initialized = new BasePayload()

// eslint-disable-next-line no-restricted-exports
export default initialized
```

`getPayload()` 関数でインスタンスを取得し、キャッシュとHMRをサポートします。

#### Local API パターン
サーバーサイドでPayloadを直接操作するためのAPI群です。

```typescript
// packages/payload/src/index.ts:411-414
count = async <T extends CollectionSlug>(
  options: CountOptions<T>,
): Promise<{ totalDocs: number }> => {
  return countLocal(this, options)
}
```

#### Hooks パターン
データ操作の各段階でカスタムロジックを挿入できます。

```typescript
// packages/payload/src/collections/config/types.ts:170-176
export type BeforeOperationHook<TOperationGeneric extends CollectionSlug = string> = (
  arg: BeforeOperationArg<TOperationGeneric>,
) =>
  | Parameters<OperationMap<TOperationGeneric>[keyof OperationMap<TOperationGeneric>]>[0]
  | Promise<Parameters<OperationMap<TOperationGeneric>[keyof OperationMap<TOperationGeneric>]>[0]>
  | Promise<void>
  | void
```

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `types.ts` | 型定義ファイル | `collections/config/types.ts` |
| `index.ts` | ディレクトリのエントリーポイント | `auth/index.ts` |
| `client.ts` | クライアント専用コード | `config/client.ts` |
| `local/*.ts` | Local API実装 | `operations/local/find.ts` |
| `*.spec.ts` | テストファイル | `int.spec.ts`, `e2e.spec.ts` |
| `config.ts` | 設定ファイル | `test/fields/config.ts` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `is*` | boolean（状態判定） | `isUserLocked`, `isNextBuild` |
| `has*` | boolean（所有判定） | `hasHTTPS`, `hasData` |
| `can*` | boolean（能力判定） | `canViewConditionalField` |
| `should*` | boolean（推奨判定） | `shouldAutoRun` |
| `*Operation` | 操作関数 | `loginOperation`, `findOperation` |
| `*Local` | Local API実装 | `findLocal`, `createLocal` |
| `*Hook` | フック型/関数 | `BeforeChangeHook`, `AfterReadHook` |
| `*Config` | 設定型 | `CollectionConfig`, `GlobalConfig` |
| `Sanitized*` | サニタイズ済み型 | `SanitizedConfig`, `SanitizedCollectionConfig` |
| `Client*` | クライアント用型 | `ClientConfig`, `ClientCollectionConfig` |
| `Typed*` | 型付きヘルパー | `TypedCollection`, `TypedUser` |
| `Base*` | 基底クラス/型 | `BasePayload`, `BaseDatabaseAdapter` |

### 3.3 プログラム分類一覧

| 分類 | ディレクトリ | 説明 |
|-----|-------------|------|
| コアパッケージ | `packages/payload` | CMSコアロジック |
| Admin UI | `packages/ui` | 管理画面コンポーネント |
| Next.js統合 | `packages/next` | Next.jsとの連携 |
| DBアダプター | `packages/db-*` | データベース接続 |
| ストレージ | `packages/storage-*` | ファイルストレージ |
| プラグイン | `packages/plugin-*` | 追加機能 |
| リッチテキスト | `packages/richtext-*` | エディター |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
payload-main/
├── packages/                    # すべての公開パッケージ
│   ├── payload/                 # コアPayloadパッケージ
│   │   └── src/
│   │       ├── admin/           # 管理画面関連
│   │       ├── auth/            # 認証機能
│   │       ├── collections/     # コレクション管理
│   │       ├── config/          # 設定処理
│   │       ├── database/        # DB抽象化層
│   │       ├── errors/          # エラークラス
│   │       ├── fields/          # フィールド定義
│   │       ├── globals/         # グローバル管理
│   │       ├── queues/          # ジョブキュー
│   │       ├── uploads/         # アップロード処理
│   │       ├── utilities/       # ユーティリティ関数
│   │       ├── versions/        # バージョン管理
│   │       └── index.ts         # エントリーポイント
│   ├── ui/                      # Admin UIコンポーネント
│   │   └── src/
│   │       ├── elements/        # UI要素
│   │       ├── fields/          # フィールドコンポーネント
│   │       ├── forms/           # フォーム関連
│   │       ├── hooks/           # Reactフック
│   │       ├── providers/       # Contextプロバイダー
│   │       └── views/           # 画面ビュー
│   ├── next/                    # Next.js統合
│   ├── db-mongodb/              # MongoDBアダプター
│   ├── db-postgres/             # PostgreSQLアダプター
│   ├── db-sqlite/               # SQLiteアダプター
│   ├── drizzle/                 # Drizzle ORM統合
│   ├── graphql/                 # GraphQL API
│   ├── richtext-lexical/        # Lexicalエディター
│   ├── plugin-*/                # プラグイン群
│   └── storage-*/               # ストレージアダプター群
├── test/                        # テストスイート
│   ├── __helpers/               # テストヘルパー
│   ├── fields/                  # フィールドテスト
│   ├── auth/                    # 認証テスト
│   └── [feature]/               # 機能別テスト
├── docs/                        # ドキュメント
├── templates/                   # プロジェクトテンプレート
├── examples/                    # 実装例
├── tools/                       # モノレポツール
└── scripts/                     # ビルド/開発スクリプト
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `packages/payload/src` | CMSコアロジック | `index.ts`, `config/types.ts` |
| `packages/payload/src/collections` | コレクション管理 | `config/types.ts`, `operations/` |
| `packages/payload/src/auth` | 認証・認可 | `operations/login.ts`, `strategies/` |
| `packages/payload/src/fields` | フィールド定義 | `config/types.ts`, `validations.ts` |
| `packages/ui/src` | 管理画面UI | `elements/`, `providers/` |
| `packages/next/src` | Next.js統合 | `routes/`, `views/` |
| `test/` | テストスイート | `**/config.ts`, `**/int.spec.ts` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

Payload CMSは**プラグインベースのモジュラーアーキテクチャ**を採用しています。

```mermaid
graph TB
    subgraph "Next.js Application"
        A[App Router] --> B[Payload Next Integration]
    end

    subgraph "Payload Core"
        B --> C[Config]
        C --> D[Collections/Globals]
        D --> E[Fields]
        D --> F[Hooks]
        D --> G[Access Control]
    end

    subgraph "Data Layer"
        H[Database Adapter] --> I[(MongoDB)]
        H --> J[(PostgreSQL)]
        H --> K[(SQLite)]
    end

    subgraph "Admin UI"
        L[React Server Components]
        M[Client Components]
    end

    C --> H
    B --> L
    L --> M
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| **設定レイヤー** | Payload設定の定義・サニタイズ | `config/build.ts`, `config/sanitize.ts` |
| **操作レイヤー** | CRUD操作の実装 | `collections/operations/`, `globals/operations/` |
| **フィールドレイヤー** | フィールド定義・バリデーション | `fields/config/types.ts`, `fields/validations.ts` |
| **データベースレイヤー** | DB抽象化・アダプター | `database/types.ts`, `packages/db-*` |
| **認証レイヤー** | 認証・認可処理 | `auth/operations/`, `auth/strategies/` |
| **UIレイヤー** | 管理画面コンポーネント | `packages/ui/src/` |

### 5.3 データフロー

1. **リクエスト受信**: Next.jsルートハンドラーがリクエストを受信
2. **認証処理**: JWTまたはAPIキーで認証
3. **アクセス制御**: コレクション/フィールドレベルのアクセス制御
4. **Before Hooks**: beforeValidate, beforeChange等のフック実行
5. **データ操作**: データベースアダプターを通じたCRUD
6. **After Hooks**: afterChange, afterRead等のフック実行
7. **レスポンス**: JSON形式でレスポンス返却

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

**BasePayloadクラス** (`packages/payload/src/index.ts:389-1010`)

```typescript
// packages/payload/src/index.ts:389-400
export class BasePayload {
  /**
   * @description Authorization and Authentication using headers and cookies to run auth user strategies
   */
  auth = async (options: AuthArgs) => {
    return authLocal(this, options)
  }

  authStrategies!: AuthStrategy[]
  blocks: Record<BlockSlug, FlattenedBlock> = {}
  collections: Record<CollectionSlug, Collection> = {}
  config!: SanitizedConfig
  // ...
}
```

**getPayload関数** (`packages/payload/src/index.ts:1114-1261`)
- Payloadインスタンスのキャッシュ管理
- HMRサポート
- 設定変更時の自動リロード

### 6.2 ビジネスロジック

**操作関数 (Operations)**

```typescript
// packages/payload/src/auth/operations/login.ts:71-100
export const loginOperation = async <TSlug extends AuthCollectionSlug>(
  incomingArgs: Arguments<TSlug>,
): Promise<LoginResult<TSlug>> => {
  let args = incomingArgs

  if (args.collection.config.auth.disableLocalStrategy) {
    throw new Forbidden(args.req.t)
  }

  // beforeOperation - Collection
  args = await buildBeforeOperation({
    args,
    collection: args.collection.config,
    operation: 'login',
    overrideAccess: args.overrideAccess!,
  })

  // ... 認証ロジック
}
```

### 6.3 データアクセス

**データベースアダプターインターフェース** (`packages/payload/src/database/types.ts:17-100`)

```typescript
// packages/payload/src/database/types.ts:17-44
export interface BaseDatabaseAdapter {
  allowIDOnCreate?: boolean
  beginTransaction: BeginTransaction
  bulkOperationsSingleTransaction?: boolean
  commitTransaction: CommitTransaction
  connect?: Connect
  count: Count
  countGlobalVersions: CountGlobalVersions
  countVersions: CountVersions
  create: Create
  createGlobal: CreateGlobal
  createGlobalVersion: CreateGlobalVersion
  createMigration: CreateMigration
  createVersion: CreateVersion
  defaultIDType: 'number' | 'text'
  deleteMany: DeleteMany
  deleteOne: DeleteOne
  deleteVersions: DeleteVersions
  destroy?: Destroy
  find: Find
  findDistinct: FindDistinct
  // ...
}
```

### 6.4 ユーティリティ/共通機能

**traverseFields関数** (`packages/payload/src/utilities/traverseFields.ts`)

フィールド構造を再帰的に走査するユーティリティです。

```typescript
// packages/payload/src/utilities/traverseFields.ts:11-33
const traverseArrayOrBlocksField = ({
  callback,
  callbackStack,
  config,
  data,
  field,
  fillEmpty,
  leavesFirst,
  parentIsLocalized,
  parentPath,
  parentRef,
}: {
  callback: TraverseFieldsCallback
  // ...
}) => {
  // フィールド走査ロジック
}
```

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| Options Object | 関数パラメータをオブジェクトで受け取る | 高 | `operations/local/*.ts` |
| Type Inference | ジェネリクスによる型推論 | 高 | `collections/config/types.ts` |
| Hook Chain | フック関数のチェーン実行 | 中 | `auth/operations/login.ts` |
| Adapter Pattern | DB/Storage等のアダプター抽象化 | 中 | `database/types.ts` |
| Module Augmentation | 型のモジュール拡張 | 中 | `index.ts` |

### 各パターンの詳細

#### パターン1: Options Object パターン

**目的:** 関数パラメータの後方互換性を保ちながら拡張可能にする

**実装例:**
```typescript
// ファイル: packages/payload/src/collections/operations/local/find.ts:32-100
type BaseFindOptions<TSlug extends CollectionSlug, TSelect extends SelectType> = {
  collection: TSlug
  context?: RequestContext
  currentDepth?: number
  depth?: number
  disableErrors?: boolean
  fallbackLocale?: TypedFallbackLocale
  includeLockStatus?: boolean
  joins?: JoinQuery<TSlug>
  limit?: number
  locale?: 'all' | TypedLocale
  overrideAccess?: boolean
  page?: number
  pagination?: boolean
  populate?: PopulateType
  // ...
}
```

**解説:** 新しいオプションを追加しても既存のコードに影響しない

#### パターン2: Module Augmentation パターン

**目的:** 生成された型定義でPayloadの型を拡張する

**実装例:**
```typescript
// ファイル: packages/payload/src/index.ts:267-281
/**
 * Interface to be module-augmented by the `payload-types.ts` file.
 */
export interface GeneratedTypes {}

/**
 * PayloadTypes merges GeneratedTypes with UntypedPayloadTypes.
 */
export type PayloadTypes = IsAugmented extends true
  ? GeneratedTypes & Omit<UntypedPayloadTypes, keyof GeneratedTypes>
  : UntypedPayloadTypes
```

**解説:** `payload-types.ts`で`GeneratedTypes`を拡張すると、型安全なAPIが利用可能になる

#### パターン3: Provider Pattern (React)

**目的:** アプリケーション全体で設定を共有する

**実装例:**
```typescript
// ファイル: packages/ui/src/providers/Config/index.tsx:44-67
export const ConfigProvider: React.FC<{
  readonly children: React.ReactNode
  readonly config: ClientConfig
}> = ({ children, config: configFromProps }) => {
  const [config, setConfig] = useControllableState<ClientConfig>(configFromProps)

  const { collectionsBySlug, globalsBySlug } = useMemo(() => {
    const collectionsBySlug: Record<string, ClientCollectionConfig> = {}
    const globalsBySlug: Record<string, ClientGlobalConfig> = {}

    for (const collection of config.collections) {
      collectionsBySlug[collection.slug] = collection
    }
    // ...
    return { collectionsBySlug, globalsBySlug }
  }, [config])
  // ...
}
```

**解説:** O(1)ルックアップマップを構築し、パフォーマンスを最適化

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定
2. 処理の流れを追跡（呼び出し関係を追う）
3. データの変換を確認
4. 最終的な出力を確認

### 8.2 フロー追跡の実例

#### 例1: ドキュメント検索フロー

**概要:** Local APIを使用してコレクションからドキュメントを検索する流れ

**処理フロー:**
```
payload.find() → findLocal() → findOperation() → db.find() → 結果返却
```

**詳細な追跡:**

1. **エントリーポイント** (`packages/payload/src/index.ts:491-507`)
   ```typescript
   find = async <
     TSlug extends CollectionSlug,
     TSelect extends SelectFromCollectionSlug<TSlug>,
     TDraft extends boolean = false,
   >(
     options: { draft?: TDraft } & FindOptions<TSlug, TSelect>,
   ): Promise<PaginatedDocs</* ... */>> => {
     return findLocal<TSlug, TSelect, TDraft>(this, options)
   }
   ```

2. **Local API実装** (`packages/payload/src/collections/operations/local/find.ts`)
   ```typescript
   // オプションの検証とリクエストオブジェクト作成
   // findOperationの呼び出し
   ```

3. **操作関数** (`packages/payload/src/collections/operations/find.ts`)
   ```typescript
   // アクセス制御
   // フック実行（beforeRead）
   // データベースクエリ
   // フック実行（afterRead）
   ```

4. **データベースアダプター** (`packages/db-*/`)
   ```typescript
   // DBごとの実装（MongoDB/PostgreSQL/SQLite）
   ```

#### 例2: ログインフロー

**概要:** ユーザー認証の流れ

**処理フロー:**
```
loginOperation() → buildBeforeOperation() → authenticateLocalStrategy() → jwtSign() → addSessionToUser()
```

**詳細な追跡:**

1. **操作開始** (`packages/payload/src/auth/operations/login.ts:71-89`)
   ```typescript
   export const loginOperation = async <TSlug extends AuthCollectionSlug>(
     incomingArgs: Arguments<TSlug>,
   ): Promise<LoginResult<TSlug>> => {
     let args = incomingArgs

     if (args.collection.config.auth.disableLocalStrategy) {
       throw new Forbidden(args.req.t)
     }

     args = await buildBeforeOperation({
       args,
       collection: args.collection.config,
       operation: 'login',
       overrideAccess: args.overrideAccess!,
     })
     // ...
   }
   ```

2. **認証処理** (`packages/payload/src/auth/strategies/local/authenticate.ts`)
   - パスワード検証
   - ロック状態チェック

3. **JWT発行** (`packages/payload/src/auth/jwt.ts`)
   - トークン生成
   - 有効期限設定

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイントを特定したか
- [ ] 呼び出し関係を把握したか
- [ ] データの変換ポイントを確認したか
- [ ] エラーハンドリングを確認したか
- [ ] 最終的な出力を確認したか

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `README.md` - プロジェクト概要
2. `CLAUDE.md` - 開発ガイドライン
3. `CONTRIBUTING.md` - 貢献ガイド
4. `packages/payload/src/index.ts` - コアAPI

#### 特定機能を理解したい場合
1. `packages/payload/src/[機能]/config/types.ts` - 型定義
2. `packages/payload/src/[機能]/operations/` - 操作実装
3. `test/[機能]/` - テストコード（実装例として参照）

#### 改修作業を行う場合
1. 対象機能の`types.ts` - 型定義を把握
2. 対象機能の`operations/` - 現状の実装を確認
3. `test/[機能]/int.spec.ts` - テストケースを確認
4. `test/[機能]/e2e.spec.ts` - E2Eテストを確認

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要 | 最初に読む |
| `CLAUDE.md` | 開発ガイドライン | 開発開始前 |
| `CONTRIBUTING.md` | 貢献ガイド | PR作成前 |
| `packages/*/README.md` | パッケージ説明 | パッケージ理解時 |
| `docs/` | ユーザー向けドキュメント | 機能仕様確認時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: `.js`拡張子でインポートしているが、ファイルは`.ts`である
A: TypeScriptの`moduleResolution: "NodeNext"`設定により、ESモジュールとして`.js`拡張子を使用しています。実際には対応する`.ts`ファイルが参照されます。

#### Q: `GeneratedTypes`が空なのに型が効いている
A: `payload-types.ts`が生成されると、Module Augmentationにより`GeneratedTypes`インターフェースが拡張されます。生成前は`UntypedPayloadTypes`がフォールバックとして使用されます。

#### Q: `packages/ui`のコンポーネントがサーバーで動作する理由
A: React Server Components（RSC）を採用しているため、`'use client'`ディレクティブがないコンポーネントはサーバーで実行されます。

#### Q: テストの実行方法が分からない
A:
- `pnpm run test:int` - 統合テスト
- `pnpm run test:int <dir>` - 特定ディレクトリのテスト
- `pnpm run test:e2e` - E2Eテスト

### デバッグのヒント

1. **Local APIの動作確認**: `test/`ディレクトリの`int.spec.ts`が実例として参考になります
2. **型エラーの解決**: `payload-types.ts`の生成状態を確認（`pnpm run dev:generate-types`）
3. **HMRが効かない**: `.next`キャッシュを削除（`pnpm devsafe`）
4. **DBエラー**: Dockerコンテナの状態を確認（`pnpm docker:start`）

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| Collection | データベースのテーブル/コレクションに相当するエンティティ |
| Global | 単一インスタンスのデータ（サイト設定など） |
| Field | コレクション/グローバルのデータフィールド |
| Hook | データ操作の各段階で実行されるカスタムロジック |
| Access Control | コレクション/フィールドレベルのアクセス制御 |
| Slug | エンティティの一意識別子（URL安全な文字列） |
| Local API | サーバーサイドでPayloadを直接操作するAPI |
| Adapter | DB/Storage等の外部サービス抽象化層 |
| RSC | React Server Components |
| HMR | Hot Module Replacement |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `packages/payload/src/index.ts` | コアエントリーポイント | BasePayloadクラス、getPayload関数 |
| `packages/payload/src/config/types.ts` | 設定型定義 | Config, SanitizedConfig |
| `packages/payload/src/collections/config/types.ts` | コレクション型 | CollectionConfig, Hooks |
| `packages/payload/src/fields/config/types.ts` | フィールド型 | Field型の全定義 |
| `packages/payload/src/database/types.ts` | DB抽象化 | BaseDatabaseAdapter |
| `packages/ui/src/providers/` | Reactプロバイダー | Config, Auth, Theme等 |
| `test/` | テストスイート | 統合テスト、E2Eテスト |

### C. 参考資料

- [Payload CMS 公式ドキュメント](https://payloadcms.com/docs)
- [TypeScript 公式ドキュメント](https://www.typescriptlang.org/docs/)
- [Next.js 公式ドキュメント](https://nextjs.org/docs)
- [React Server Components](https://react.dev/reference/rsc/server-components)
- [LLMS.txt](https://payloadcms.com/llms.txt) - AI向けドキュメント
- [LLMS-FULL.txt](https://payloadcms.com/llms-full.txt) - AI向け詳細ドキュメント
