staff-level-elixir

Staff-Level Elixir

BEAM 上の Elixir におけるスタッフエンジニアレベルの判断基準をまとめたものです。Elixir、OTP、Ecto、Phoenix で求められる設計上の判断と、経験豊富なエンジニアがそれらをどう決定するかを、エージェントがコードの作成やレビュー時に適用できるように記述しています。各ルールは、具体的な誤ったデフォルトを正します。モデルがすでに正しく扱えること（構文、基本的な慣用表現、標準ライブラリ）についてのルールはありません。

適用する場面

• OTP コードの作成やレビュー — プロセスが必要かどうか、必要な場合はどれを使うか（GenServer、Task、Agent、ETS、スーパーバイザー）を判断するとき
• 障害への対処 — タグ付きタプル、例外、with、プロセスのクラッシュのどれを使うかを選ぶとき
• Ecto の記述 — クエリ、関連付け、トランザクション、変更セット、大量の結果セットを扱うとき
• Phoenix コントローラーや LiveView の構築 — コンテキストの境界、ソケットの状態、マウントのライフサイクルを扱うとき
• 並行処理の実行 — 並列ファンアウト、結果を待たないタスク、信頼できない入力を扱うとき
• Elixir コードをより慣用的で、障害に強く、または「スタッフエンジニアレベル」にする依頼全般

ルールのカテゴリ

#	カテゴリ	プレフィックス	対象
1	プロセスと OTP の設計	otp-	問題にプロセスが必要かどうか、必要な場合はどれを使うか、スーパービジョン
2	エラー処理とクラッシュ許容	err-	障害の通知、raise・rescue・クラッシュを使う場面
3	慣用表現と設計上の選択	data-	パターンマッチ、Stream/Enum、iolist、パイプ、マクロ
4	並行処理とスケジューラー	conc-	上限付き・分離された並列処理、アトムテーブルの安全性
5	Ecto とデータアクセス	ecto-	N+1、アトミックな書き込み、制約をめぐる競合、大量のデータ
6	Phoenix と LiveView	phx-	コンテキストの境界、ソケットのメモリ、マウントのライフサイクル

クイックリファレンス

1. プロセスと OTP の設計

• otp-genserver-not-default — GenServer は直列化の要所であり、デフォルトの抽象化ではありません
• otp-ets-for-shared-reads — 読み取りが多い共有状態は、GenServer.get の背後ではなく ETS に置きます
• otp-supervise-over-manual-restart — 手書きの再起動ロジックではなく、子仕様と DynamicSupervisor/Registry を使います
• otp-handle-continue-init — 重い起動処理は handle_continue に遅らせます。init/1 はスーパーバイザーをブロックします

2. エラー処理とクラッシュ許容

• err-tagged-tuples-vs-raise — 想定内の失敗には {:ok/:error} を使い、raise は不変条件違反の場合に限ります
• err-let-it-crash — バグを隠すために rescue しないでください。スーパーバイザーにクリーンな状態で再起動させます
• err-with-happy-path — 失敗する可能性のある手順は with で連結し、エラー項をそのまま保持します

3. 慣用表現と設計上の選択

• data-pattern-match-over-conditionals — 引数の形状に対する if/cond ではなく、関数節とガードを使います
• data-stream-vs-enum — 大規模・遅延評価・早期終了には Stream を、具体的で小さなリストには Enum を使います
• data-iolists-over-concat — 大きな出力は iolist として構築します。ループ内の <> は O(n²) になります
• data-pipe-idioms — 変数を節約するためではなく、データを変換処理に通すためにパイプを使います
• data-functions-over-macros — マクロに頼る前に、関数で解決できないか検討します

4. 並行処理とスケジューラー

• conc-async-stream-bounded — max_concurrency と明示的な timeout を指定した Task.async_stream を使います
• conc-task-supervised-nolink — 結果を待たない処理には、スーパーバイズされ、リンクされていない Task を使います
• conc-atom-exhaustion — 外部入力からアトムを決して生成せず、to_existing_atom を使います

5. Ecto とデータアクセス

• ecto-preload-n-plus-one — 事前にプリロードし、Enum のループ内では決して行わないでください
• ecto-multi-for-transactions — 失敗箇所を特定できる、複数ステップのアトミックな書き込みには Ecto.Multi を使います
• ecto-db-constraints-over-validation — 競合の恐れがある検証クエリではなく、DB 制約と unique_constraint を使います
• ecto-stream-large-sets — 大規模なデータセットには Repo.stream とバッチ処理を使います。規模が大きくなると Repo.all はメモリ不足になります
• ecto-atomic-counters — カウンターには inc: を指定した update_all を使います。読み取り・変更・書き込みでは更新が失われます

6. Phoenix と LiveView

• phx-context-boundary — Web 層から呼び出すのはコンテキストであり、Repo やスキーマを直接呼び出してはいけません
• phx-liveview-streams — 大規模または増加するコレクションにはストリームを使い、assigns にリスト全体を保持しないでください
• phx-mount-twice-connected — connected?/1 で副作用の実行を制御します。mount は 2 回実行されます

使用方法

判断が必要になったら、該当するリファレンスファイルを読んでください。各ルールでは、まず修正対象となる誤ったデフォルトを示し、次に標準的な方法を紹介します（誤った方法が実際に陥りやすい罠である場合に限り、誤りと正しい方法を対比します）。

• セクション定義 — カテゴリーの構成と順序
• ルールのテンプレート — 新しいルールを追加する際に使用します
• AGENTS.md — すべてのルールをまとめた自動生成の目次

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとソースの参照情報