Elixir向け「CLAUDE.md」：AIがイディオムに沿いOTPを意識したElixirを書くための13のルール

これはOTPアプリケーションです。並行動作を次でモデル化します：
- 状態を持つプロセスにはGenServer
- 障害許容と再起動戦略にはSupervisor
- 一度限りの並行作業にはTask
- 簡単な共有状態にはAgent（非自明なものはGenServerを優先すること）

共有ミュータブル状態、ミューテックス、グローバル変数で並行性をモデル化しないでください。
並行性と隔離の単位はプロセスです。

分岐には関数ヘッドでのパターンマッチを使います：

  def process(%{status: :active} = user), do: ...
  def process(%{status: :inactive} = user), do: ...
  def process(%{status: status}), do: {:error, "unknown status: #{status}"}

ダメな例:
  def process(user) do
    cond do
      user.status == :active -> ...
      user.status == :inactive -> ...
    end
  end

`case`は関数内でのローカルな分岐にだけ使ってください。`cond`は一致する値がない（マッチングせず） boolean 式のために使ってください。

パイプのルール：
- 3ステップ以上でデータを変換するときは`|>`を使う
- 各パイプのステップは1つの操作にする（必要がない限りパイプ内に匿名関数を入れない）
- パイプされた関数の最初の引数は、変換されているデータである必要がある
- 本番コードで`IO.inspect/2`にパイプしない — Loggerを使う
- 可読性が落ちるなら、長いパイプを名前付きの中間変数に分解する

避ける：
  result = transform(filter(validate(data)))  # ネスト形式

優先する：
  result = data
    |> validate()
    |> filter()
    |> transform()

どのステップでも失敗しうる、連続した操作には`with`を使います：

  with {:ok, user} <- fetch_user(id),
       {:ok, account} <- fetch_account(user),
       {:ok, _} <- charge(account, amount) do
    {:ok, "charged"}
  else
    {:error, :not_found} -> {:error, "user not found"}
    {:error, reason} -> {:error, reason}
  end

ネストしたcase/ifチェーンはダメ。
失敗しうるすべての関数から`{:ok, value}`と`{:error, reason}`のタプルを返してください。

スーパビジョン戦略：
- 独立したワーカーには`:one_for_one`
- クラッシュ時に状態が不整合になる共有状態を持つワーカーには`:one_for_all`
- ワーカーに順序依存がある場合は`:rest_for_one`
- supervised（監督下）プロセスはapplication.ex、または専用のSupervisorモジュールで起動する
- クラッシュを避けるためにGenServerのコールバックで例外をrescueしないでください — クラッシュさせてください。スーパー バイザが再起動します

スーパーバイザこそがエラーハンドラです。ワーカープロセスで防御的なrescue句を書くのは設計に反します。

DBアクセス：Ectoのみ。
- すべてのデータ検証はchangesetsで行う：`cast`、`validate_required`、`validate_format`
- クエリはEcto.Query DSLで構築する — 複雑なクエリで`fragment/1`を使う場合を除き、生SQLは使わない
- ビジネスロジックで`Repo.get!`を使わない — `Repo.get`を使い、nilは明示的に扱う
- アソシエーションのプリロードを明示的に行う：`Repo.preload(user, [:posts])` — 遅延ロードをしない
- 原子的である必要がある操作には`Repo.transaction`を使う
- スキーマchangesetsは唯一の検証ポイント — コントローラやcontext関数ではない

Phoenixのcontextsで整理する（Phoenixの外でも）：
- ドメインごとに1つのcontextモジュール：`Accounts`、`Payments`、`Inventory`
- context関数が公開API：`Accounts.get_user(id)`、`Accounts.create_user(attrs)`
- スキーマモジュールはcontextの内部に閉じ込める — コントローラや他のcontextから直接呼び出さない
- context間での直接的なスキーマアクセスはしない — 所有するcontextのAPI経由でのみ行う

これはPhoenix 1.3+のアーキテクチャです。古い「1スキーマ1コントローラ」パターンは使わないでください。

Atom discipline:
- ユーザーが提供した文字列を、`String.to_atom/1` でアトムに変換しない
  （アトムはガー
tbage collected されない — 無制限の生成はメモリリーク / DoS のベクター）
- 既知の文字列をアトムに変換するときは、`String.to_existing_atom/1` を使う
- モジュール名、関数名、自分のコード内でのマップキー：アトムで問題ない
- JSON のパース：基本は文字列キーを使う。アトムキーにしない（Jason のデフォルトは正しい）

プロセス間通信：
- 同期リクエストには `GenServer.call/3` を使う（値を返す）
- 非同期の fire-and-forget には `GenServer.cast/2` を使う（戻り値なし）
- OTP によって管理されない、アドホックなメッセージ受け渡しに限り `send/2` + `receive` を使う
- `call` には常にタイムアウトを設定する：`GenServer.call(pid, msg, 5_000)`
- `handle_info/2` で想定外のメッセージを扱う — 受信ボックスに溜め込ませない

調整（coordination）のために `Process.sleep/1` を使うことは決してしない — `GenServer.call` か `Task.async/await` を使う。

テスト：
- 全テスト：グローバル状態を共有しない限り `use ExUnit.Case, async: true`（データベース）
- データベースのテスト：トランザクションによるアイソレーションのために `Ecto.Adapters.SQL.Sandbox` を使う
- テストのセットアップ：モジュール属性ではなく `setup` ブロックを使う
- `assert {:ok, _} = MyModule.function(args)` を使う — 構造にマッチさせる
- ファクトリ：テストデータには ExMachina を使う。手作りのマップではない
- テスト内で `Process.sleep` を使わない — async なアサーションにはタイムアウト付きの `assert_receive` を使う
- 外部サービスは `Mox` でモックする — 振る舞いを定義し、期待を検証する

可観測性（Observability）：
- ライブラリ/アプリケーションコードからメトリクスを発行するには `:telemetry` を使う
- ログエントリにコンテキストを付与するには `Logger.metadata/1` を使う：`Logger.metadata(user_id: id, request_id: req_id)`
- ログレベル：debug（開発で冗長に）、info（通常の運用）、warning（劣化）、error（失敗）
- 本番コードで `IO.puts` や `IO.inspect` をむき出しで使わない — Logger を使う
- Telemetry のハンドラはアプリケーションの起動時にアタッチする。インラインではなく

ドメインデータ：
- すべてのドメインエンティティに対して struct を定義する：`defstruct [:id, :name, :email]`
- 必須フィールドには `@enforce_keys` を使う：`@enforce_keys [:id, :name]`
- Struct はコンパイル時のキー検査を提供する — 裸のマップにはそれがない
- 形（shape）が分かっているときは `%User{}` を使う。`%{id: ..., name: ...}` ではない
- パブリック関数すべてに typespec を書く：`@spec create_user(attrs :: map()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}`

デプロイ：
- 本番デプロイには `mix release` を使う — `mix run` ではない
- 設定：ランタイム設定には `config/runtime.exs` を使う（起動時に読み取る env vars）
  コンパイル時のみは `config/config.exs`
- 秘密情報をハードコードしない — `config/runtime.exs` では `System.fetch_env!/1` を使う
- ヘルスチェック：Mix タスクのシェルアウトではなく、シンプルな HTTP エンドポイントを実装する
- 移行（ミグレーション）：CI では常に `--no-start` を付けて実行する：`mix ecto.migrate --no-start`

# Elixir Project — AI Coding Rules

## アーキテクチャ
OTP アプリケーション。並行性のために GenServer + Supervisor を使う。落ちさせよ — supervisor が復旧を扱う。
ドメイン境界のためのコンテキスト。スキーマモジュールはそれぞれのコンテキストに private にする。

## パターン
関数レベルで cond/case よりも関数ヘッドディスパッチを使う。
with は逐次のフォールible 操作のために使う — どこでも {:ok, val} / {:error, reason} のタプル。
3 ステップ以上のデータ変換には pipe 演算子を使う。

## Ecto
すべてのバリデーションに Changeset を使う。明示的な preloads。Repo.get は Repo.get! ではない。
生 SQL は fragment/1 経由のみ。原子的な操作にはトランザクションを使う。

## アトム
ユーザー入力で String.to_atom/1 を使わない。既知の文字列に限り String.to_existing_atom/1 を使う。

## テスティング
可能な限り async: true。DB テストには Ecto.Adapters.SQL.Sandbox を使う。
外部サービスのモックには Mox を使う。async の検証には assert_receive を使う。テスト内で Process.sleep を使わない。

## 可観測性
メタデータ付きの Logger。メトリクスには Telemetry。本番環境で IO.puts/IO.inspect を使わない。

## デプロイ
mix release。env vars には runtime.exs。秘密情報には System.fetch_env!/1。