CLAUDE.md で触れておきたい事メモ

# コーディング規律

コーディングエージェントが陥りやすい悪癖を防ぐためのガイドライン。

---

## 実装プロセス（最重要）

**即座にコードを書き始めない。**

コーディングエージェントの最大の悪癖は、依頼を受けた瞬間に実装を始めてしまうことである。これが近視眼的なコーディング、コード重複、設計破綻の根本原因となる。

### 実装前：全体俯瞰

1. **影響範囲の把握**: 変更が及ぶファイル、モジュール、機能を特定する
2. **既存コードの調査**: 再利用できるもの、影響を受けるものを確認する
3. **設計方針の確認**: 既存のアーキテクチャ、パターン、規約を理解する
4. **ブランチの分離**: 開発ブランチは feature/<name_of_topic> ブランチに切り出し、その中で作業する。
5. **TodoWriteの活用**: 開発ステップは手順漏れが無いよう TodoWrite ツールを使って進捗管理を行う事。

### 計画：戦略的アプローチ

1. **実装計画を言語化する**: 何を、どの順序で、どう実装するか明示する
2. **分割統治**: 大きな変更は小さなステップに分解する
3. **不明点は確認**: 仕様上、不確かな点は既存コードの調査を行うとともに、ユーザーと対話的に仕様を確定させていくこと
4. **依存関係の整理**: 先に作るべきもの、後から作るものを明確にする
5. **ドキュメント化**: docs/work/yyyy-mm-dd_<name_of_topic>.md ファイルに以下を記載する
   - 背景: なぜこの変更が必要か
   - 課題: 解決すべき具体的な問題
   - 対応方針: どのようなアプローチで解決するか
   - 変更対象ファイル: 影響を受けるファイル一覧
   - 確認方法: どのように動作確認するか
6. **セルフレビュー**: 下記「レビュー観点」に基づき、自身で計画の妥当性を検証する
7. **Codex MCPレビュー**: セルフレビュー完了後、Codex MCPのレビューを受ける。Codexの指摘事項は鵜呑みにせず、自身でも妥当性を検証すること。レビュー指摘点がなくなるまで繰り返しドキュメントをブラッシュアップする

### 実装中：段階的リファクタリング

1. **動く最小単位を作る**: まず動くものを作り、そこから改善する
2. **こまめに見直す**: 一気に完成させず、各ステップで立ち止まる
3. **継続的な整理**: 重複に気づいたらその場で共通化を検討する

### 実装後：振り返り

1. **全体との整合性確認**: 局所最適が全体を壊していないか
2. **不要な変更の除去**: スコープ外の変更が紛れ込んでいないか
3. **次の作業者への配慮**: 意図が伝わるコードになっているか
4. **Codex MCPの事後レビュー**: 実装完了後に実装内容やドキュメント内容が適切なものであったか、再度Codex MCPのレビューを受ける事。指摘点があればこれまでの進捗を一度コミットしてから（コミット前に、かならず feature/<name_of_topic> ブランチに分離されている事を確認）改めてCodexからの指摘点・改善点をドキュメントに反映、計画： 戦略的アプローチ、からやりなおし
5. **ドキュメントへの振り返り追記**: 実装完了後、ドキュメントに以下を追記する
   - 計画との差分: 計画通りに実装できたか、変更点があれば理由とともに記載
   - 学び: 実装で得た知見、今後に活かせるポイント
   - 残課題: 発見した課題、将来の改善点（あれば）

```
❌ 依頼 → 即実装 → 完成
✅ 依頼 → 調査 → 計画 → 実装 → 見直し → 改善 → 完成
```

---

## レビュー観点

セルフレビューおよびCodex MCPレビュー時に確認すべき観点。上位概念から順に検証する。

### 1. 課題の理解は正しいか

- 課題の本質を正しく捉えているか
- 課題の範囲に漏れはないか
- 前提条件・制約を見落としていないか

### 2. 対応策は課題を解決するか

- 対応策を実行した結果、課題が解決された状態に到達するか
- 対応策の前提は正しいか（検証されているか、推測に過ぎないか）
- 対応策に漏れている経路・ケースはないか
- データの流れを端から端まで追跡したか（特に境界を跨ぐ箇所）

### 3. 対応策はCLAUDE.mdのコーディングルールに準拠しているか

- スコープ外の変更を含んでいないか
- 既存のアーキテクチャ・パターンと整合しているか
- フォールバックに頼らず、エラーを適切に処理しているか
- 不要な抽象化・過剰な設計をしていないか
- KISS、YAGNI、Fail Fast原則に反していないか

### 4. 対応策の設計は妥当か

- 対応策を実現する設計に論理的な欠陥はないか
- 変更ファイル一覧に漏れはないか（特にDTO、型定義、バリデーション）
- 各コンポーネント間のインターフェースは正しく定義されているか

### 5. 実装は設計通りか

- コードが設計を正しく反映しているか
- エラーハンドリング、型定義等に問題はないか
- テストケースは網羅的か

---

## 基本原則

- **KISS (Keep It Simple, Stupid)**: 最も単純な解決策を選ぶ。「将来のため」の抽象化は不要
- **YAGNI (You Aren't Gonna Need It)**: 要求されていない機能は実装しない
- **スコープ厳守**: 依頼された範囲のみを実装する。「ついでに」は禁止
- **Fail Fast, Fail Loud**: 問題は早期に、明確に失敗させる

---

## 実装前の確認事項

1. 既存コードに再利用できるものはないか？
2. 新規ファイル/クラス/関数は本当に必要か？
3. 依存関係を増やす必要があるか？より軽量な代替手段は？
4. 既存の定数・設定ファイルに追加すべきか？

---

## 禁止事項

### スコープ・設計

- 要求されていないバリデーション、ログ、設定ファイル化の追加
- 1ファイルで済むものの不要な分割
- 動作未確認のコードを「これで動きます」と断言すること
- 既存の命名規則・コードスタイルを無視した実装
- 修正依頼時に関係ない部分を書き換えること

### フォールバックの乱用

- 安易なデフォルト値 (`?? []`, `|| 0`, `|| {}`) で問題を握りつぶさない
- try-catch で黙ってデフォルト値を返さない。エラーは適切に伝播させる
- Optional chaining (`?.`) の連鎖で「とりあえず安全」にしない
- フォールバックが必要な場合は、なぜそれが適切か明示的に説明できること
- フォールバックが必要なら、その手前で明示的にガードする（`if (x == null) { ... }`）。暗黙のフォールバックではなく、意図が見える分岐にする

### 定数・マジックナンバー

- 同じリテラル値を複数箇所に書かない
- 数値・文字列は意味のある名前の定数として定義する
- 定数は適切な場所（設定ファイル、constants ファイル等）に集約する
- URL、パス、APIエンドポイントの直書き禁止

```typescript
// ❌ Bad
if (status === 1) { ... }
if (role === 'admin') { ... }
const url = 'https://api.example.com/v1/users'

// ✅ Good
if (status === STATUS.ACTIVE) { ... }
if (role === ROLES.ADMIN) { ... }
const url = `${API_BASE_URL}${ENDPOINTS.USERS}`
```

### ロジックと表現の分離

- ビジネスロジック内にUIテキスト・メッセージを直書きしない
- 表示文字列はリソースファイルまたは専用モジュールに分離
- フォーマット処理（日付、通貨、数値）は表示層で行う
- 計算・判定ロジックと表示ロジックを同じ関数に混ぜない

```typescript
// ❌ Bad
function processOrder(order) {
  if (order.total > 10000) {
    return { message: 'ご注文ありがとうございます！送料無料です！', ... }
  }
}

// ✅ Good
function calculateShipping(order): ShippingResult {
  return { freeShipping: order.total > SHIPPING_THRESHOLD, ... }
}
// 表示層で結果を解釈してメッセージを生成
```

---

## 構造・可読性

### 関数設計

- 1つの関数は1つの責務のみ
- 早期リターンを活用し、ネストを浅く保つ
- 引数は最小限に。3つを超える場合はオブジェクト化を検討
- 副作用のある処理は明示的に分離する

```typescript
// ❌ Bad: 深いネスト
function process(data) {
  if (data) {
    if (data.items) {
      if (data.items.length > 0) {
        // 処理
      }
    }
  }
}

// ✅ Good: 早期リターン
function process(data) {
  if (!data?.items?.length) return
  // 処理
}
```

### 型定義

- `any` 型の使用は原則禁止
- 外部データ（API レスポンス等）には明示的な型定義を与える
- Union型で取りうる値を明確にする

### エラーハンドリング

- エラーは握りつぶさず、適切な層で処理する
- エラーメッセージは具体的に。何が、なぜ失敗したか分かるように
- リカバリ可能なエラーと致命的エラーを区別する

---

## コード重複・抽象化

### 重複の排除

- 同じコードを2回書いたら共通化を検討
- 3回以上出現するパターンはなるべく抽象化する
- ただし、無理な共通化は禁止（偶然の一致は共通化しない）

### 適切な抽象化レベル

- 抽象化は「現在の重複」に対して行う。「将来の可能性」に対して行わない
- 過度な汎用化より、具体的で読みやすいコードを優先
- レイヤー・階層は必要最小限に

---

## 出力形式

- コードに対して過剰なコメントを書かない
- 実装の背景説明は聞かれた場合のみ
- 定型的な締めの挨拶・確認フレーズは不要

---

## 変更時のチェックリスト

### 実装前
- [ ] 既存コードを調査したか
- [ ] 実装計画を言語化したか
- [ ] 影響範囲を把握したか
- [ ] ブランチを切ったか
- [ ] 実装計画をドキュメント化したか
- [ ] Codex MCPレビューを通したか

### 実装中
- [ ] スコープ外の変更をしていないか
- [ ] 既存のアーキテクチャ・パターンと整合しているか
- [ ] 同様の処理が他にないか確認したか
- [ ] 追加した依存関係は最小限か
- [ ] 新しい定数はハードコードではなく適切な場所に定義したか
- [ ] ロジックと表現が分離されているか
- [ ] フォールバックに頼らず、エラーを適切に処理しているか
- [ ] 型定義は明確か（any を使っていないか）

### 実装後
- [ ] 実際に動作確認したか（「動くはず」ではなく）
- [ ] 新しい環境でも再現するか
- [ ] セキュリティ上の問題はないか
- [ ] 不確実な部分を正直に報告したか
- [ ] Codex MCPレビューを通したか
- [ ] ドキュメントに振り返りを追記したか（計画との差分、学び、残課題）