agentleFS
s977043s977043/river-review/skills/midstream/laravel-eloquent-nplus1/SKILL.md

Laravel Eloquent N+1 and Query Efficiency Review

Skill7 starsChanged 5 months agoMITView on GitHub

Detects N+1 query patterns (relation access inside loops without eager loading), full-table get()/all() loads, and unsafe chunk()/cursor() usage in Laravel Eloquent code.

The file

Files
SKILL.md

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Inversion Why: Eloquent のクエリ効率規約への適合をチェックリスト型で検査する

Goal / 目的

  • ループ内 relation アクセスによる N+1 クエリ(公式例: 25 件で 26 クエリ)を検出する。
  • 巨大テーブルの全件ロード(all() / get())と、chunk() / cursor() の誤用を検出する。

Non-goals / 扱わないこと

  • mass assignment / 認可(laravel-mass-assignment のスコープ)。
  • migration の安全性(laravel-migration-safety のスコープ)。
  • SQL チューニング一般・index 設計。

Pre-execution Gate / 実行前ゲート

このスキルは以下の条件がすべて満たされない限りNO_REVIEWを返す。

  • 差分に Eloquent モデルのクエリ・relation アクセスの追加変更が含まれている
  • diff コンテキストが利用可能である

ゲート不成立時の出力: NO_REVIEW: laravel-eloquent-nplus1 — Eloquent クエリの変更なし

False-positive guards / 抑制条件

  • ループ前に with() / load() 済みの relation へのアクセスは指摘しない(diff 外で eager load されている可能性があるため、確証がなければ質問に留める)。
  • ループ対象が少数固定(config 由来等)の場合の relation アクセスは指摘しない。
  • chaperone() を使った親逆参照は正当。
  • preventLazyLoading が有効なプロジェクトでは N+1 がテストで落ちるため、重複指摘を避ける。

Rule / ルール

  • ループ内で relation を参照する場合は with('relation')(取得後なら load() / loadCount())で eager load する。
  • 巨大テーブルの反復は chunkById / lazyById / cursor を使う。
  • chunk() でフィルタ対象カラムを更新しない(公式: inconsistent results。chunkById を使う)。
  • cursor() と eager loading を併用しない(cursor は relation を eager load できない。lazy を使う)。
  • chunkById / lazyById で orWhere を含む条件は closure で論理グループ化する。

Evidence / 根拠の取り方

  • 指摘は <file>:<line> で差分に紐づけ、公式規約(laravel.com/docs/12.x/eloquent-relationships#eager-loading 等)を 1 行で添える。
  • eager load の有無が diff から確定できない場合は断定せず questions で返す。

Output / 出力(短文版の推奨)

コメントは日本語で返す。

  • Finding: N+1 / 全件ロード / chunk 誤用のどれか(1文)
  • Impact: クエリ数 / メモリ / 一貫性への影響
  • Fix: with() / chunkById / lazy 等の最小修正案

Sources / 出典

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.