# CLAUDE.md

このファイルはClaude Codeがコード生成・編集・ドキュメント作成を行う際に従うべきプロジェクトルールを定義する．
各ルールの詳細は `docs/01_GUIDE/` 配下の対応ファイルを参照すること．

---

## 1. ドキュメント作成ルール (GUIDE_01)

ドキュメント（`.txt`）を新規作成・編集する際は以下に従う．

- **文字コード**: UTF-8，**改行コード**: LF，**インデント**: 半角スペース4つ（タブ禁止）
- **句読点**: 「，」「．」を使用する．「、」「。」は使用しない
- **コロン**: 半角コロン＋半角スペース `": "` を使用する（全角コロン禁止）
- **ファイルヘッダー**: ファイル先頭に `=` で囲ったタイトルブロックを必ず記述する
- **見出し階層**:
  - レベル1: `1. タイトル (English)` ＋ 下行にハイフン区切り線
  - レベル2: `1-1. タイトル`
  - レベル3: `■ タイトル`（並列）または `1. ` 番号付き（手順）
  - レベル4（リスト）: `・`（全角中黒）
  - レベル5（詳細）: `- `（半角ハイフン＋スペース），インデントはスペース8つ
- **改行ルール**: 大見出し前に2行，中見出し・小見出し前に1行空ける
- **コマンド**: 先頭に `$ ` を付ける

詳細: `docs/01_GUIDE/GUIDE_01_ドキュメント作成ガイド.txt`

---

## 2. ファイル命名規則 (GUIDE_02)

ドキュメントファイルを新規作成する際は以下の形式に従う．

```
[カテゴリ]_[連番2桁]_[ファイル名].txt
```

| カテゴリ | 内容 |
|----------|------|
| `GUIDE_` | チームルール，規約，運用フロー |
| `PLAN_`  | 進行計画，スケジュール，要件定義 |
| `ENV_`   | 開発環境，ディレクトリ構造，技術スタック |
| `SPEC_`  | ゲームルール，UI/UX仕様 |
| `TECH_`  | 実装詳細，通信プロトコル，データ構造 |
| `TEST_`  | テスト計画，テストケース，品質基準 |

- 区切り文字: アンダースコア `_`
- 連番: `01` から始まる2桁
- 拡張子: `.txt`
- 1ファイル1テーマで分割する

詳細: `docs/01_GUIDE/GUIDE_02_ファイル命名規則.txt`

---

## 3. Git運用ルール (GUIDE_03)

### ブランチ命名

```
[プレフィックス][日付(YYMMDD)]_[名前]_[概要]
```

| プレフィックス | 用途 |
|----------------|------|
| `feature/` | 新機能実装，仕様変更 |
| `fix/`     | バグ修正 |
| `refactor/`| コード整理（挙動変更なし） |
| `docs/`    | ドキュメント追記・修正 |
| `chore/`   | ビルド設定，ツール導入 |

例: `feature/260214_yamada_player_jump`

### コミットメッセージ

```
[タグ] 日本語で内容を記述（末尾の句点不要）
```

| タグ | 用途 |
|------|------|
| `[add]`    | ファイルや機能の追加 |
| `[update]` | 機能やデータの更新・修正 |
| `[fix]`    | バグ修正 |
| `[remove]` | 削除 |
| `[clean]`  | 整理，リファクタリング |

### 禁止事項

- `main` への直接コミット・直接プッシュは禁止（必ずPR経由）
- 作業ブランチのベースは常に最新の `main` から作成する

詳細: `docs/01_GUIDE/GUIDE_03_Git運用ルール.txt`

---

## 4. コードコメント規則 (GUIDE_04)

### 基本方針

- **言語**: 日本語
- **句読点**: 「，」を使用，文末の句点「．」は付けない
- **文体**: 体言止め，または「〜する」形で統一

### コメントの種類

**ファイルヘッダー**（全ファイル先頭に必須）

```ts
/**
 * [ファイル名（拡張子なし）]
 * [ファイルの主な責務を1行で説明]
 */
```

**型・定数**（`export` されるものに必須）

```ts
/** [何を表すかを端的に説明] */
export type / const ...
```

**関数・コンポーネント・フック**（`export` されるものに必須）

```ts
/** [何をするかを端的に説明] */
export const / function ...
```

**ブロックコメント**（処理のまとまりが変わる箇所）

```ts
// [このブロックの処理を端的に説明]
```

**JSXコメント**

```tsx
{/* [説明] */}
```

### 省略してよいケース

- ファイル内部でのみ使用し，外部に公開されない型・関数・定数
- コード自体が自明な場合

詳細: `docs/01_GUIDE/GUIDE_04_コードコメント規則.txt`

---

## 5. プロトコル追加手順 (GUIDE_05)

`packages/shared/src/protocol` 配下のソケットイベントを追加・変更する際は，以下の順序で必ず全工程を実施する．

1. `socketEvents.ts` にイベント名を追加（kebab-case/snake_case を既存方針に合わせる）
2. `payloads/` 配下の適切なファイルにペイロード型を追加（重複定義を避ける）
3. `maps/` 配下の方向別マップ（C→S / S→C）に追記
4. `eventPayloads.ts` / `eventPayloadMaps.ts` / `events.ts` で外部利用する型のみ再公開
5. client/server の handler/bridge/useCase で on/off/emit と型参照を更新

### チェックポイント（PR前に確認）

- [ ] イベント名追加済みか
- [ ] payload 型追加済みか
- [ ] map への方向別登録済みか
- [ ] events.ts 再公開が過不足ないか
- [ ] client/server で型エラーがないか
- [ ] 既存イベントの型互換を壊していないか
- [ ] `UPDATE_PLAYERS` / `update-players` に `teamId` を含めていないか
- [ ] `CURRENT_PLAYERS` / `current-players`，`NEW_PLAYER` / `new-player` に `teamId` を含めているか

### 検証コマンド

```bash
$ pnpm --filter @repo/shared build
$ pnpm --filter server build
$ pnpm --filter client build
```

### 禁止事項

- `events.ts` に型本体を置かない（再公開専用を維持する）

詳細: `docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt`

---

## 6. ディレクトリ構造ドキュメントの更新 (ENV_02)

ファイル・ディレクトリの**追加・削除・移動**を行った場合は，`docs/02_ENV/ENV_02_ディレクトリ構造.txt` を合わせて更新すること．

- 対象: `apps/client/src`，`apps/server/src`，`packages/shared/src` 配下の変更
- 既存の記載粒度（代表的なファイル・フォルダのみ）に合わせて追記・修正する
- ファイル単体の追加でも，同階層に未記載のディレクトリが生じた場合は追記する

---

## 7. ゲーム定数変更時のSPEC更新

`packages/shared/src/config/gameConfig.ts` の定数値を変更した場合は，`docs/04_SPEC/` 配下の対応する仕様書を合わせて更新すること．

- 対象: `GAME_CONFIG` 内の時間・距離・回数などの数値定数
- 特に影響が大きいファイル:
  - `SPEC_03_ゲームプレイ仕様.txt`（制限時間，ボム・ハリケーン・被弾の各パラメータ）
  - `SPEC_04_HUD_UI仕様.txt`（表示切替のしきい値，クールダウン時間）

設定値（config）の配置ルールと定数一覧は `packages/shared/src/config/README.md` を参照すること．