rubocop-todo-fix

name	rubocop-todo-fix
description	.rubocop_todo.yml に残った違反を段階的に潰すスキル。safe autocorrect だけで完結する Cop はまとめてバッチで、unsafe autocorrect や手動修正が必要な Cop もリスクに応じた単位でバッチにまとめて潰す。
disable-model-invocation	true
license	MIT

rubocop-todo-fix

rubocop --auto-gen-config で生成された .rubocop_todo.yml には、既存コードの違反が「いったん許容」 として列挙されている。これを潰していくための運用支援スキル。safe autocorrect（-a）だけで完結する Cop はまとめてバッチ処理し、unsafe autocorrect や手動修正が必要な Cop も、挙動変更のリスクに応じた （safe バッチより狭い）単位でバッチにまとめて潰す。 sgcop-setup が .rubocop_todo.yml を生成するところで終わるのに対し、 本スキルはその続き——生成済みの todo を実際に消化する工程——を担う。

導入先の Rails/Ruby プロジェクトで実行する（sgcop gem 本体の開発スキルではない）。

このスキルがやること / やらないこと

• やる:
  1. .rubocop_todo.yml から 潰す対象を選ぶ。Tier（safe autocorrect / unsafe autocorrect / 手動修正）ごとに、そのリスクに見合ったしきい値・基準で複数 Cop をバッチにまとめる。
  2. 対象 Cop のエントリを todo から削除して 違反を再び検出される状態に戻す。
  3. 修正する: Tier 順（rubocop -a → rubocop -A〈unsafe・要テスト〉→ 手動修正）でバッチを 処理する。同じ Tier のバッチはまとめて一度に適用・確認する。
  4. アプリ仕様上やむを得ない違反だけ、理由コメント付きで最小範囲の Exclude / 無効化に倒す。
  5. 再 rubocop で 違反ゼロを確認（挙動を変えたら関連テストだけ実行）し、必要なら .rubocop_todo.yml を作り直して 停止する。
• やらない:
  • .rubocop_todo.yml の生成そのものはしない（sgcop-setup の担当。本スキルは「生成済みを潰す」）。
  • コミット / push / PR 作成はしない。 1 サイクル潰したら停止し、差分確認とコミットはユーザーに委ねる。
  • Tier をまたいでバッチにしない。 safe / unsafe / 手動修正はリスクの質が異なるので、 1 回のバッチは同じ Tier の Cop だけで構成する。

なぜこの形か: 既存違反を一度に全部直すと差分が巨大化してレビュー不能になる。「潰す → ユーザーが差分を確認してコミット → 次へ」というレビュー単位の運用にすると、変更の責任範囲が 把握しやすく、挙動が変わっても切り分けやすい。一方で 1 Cop ずつ処理すると、サイクル数 （起動〜レビュー〜コミットの往復）だけが無駄に増えてしまう。そこで Tier ごとに「レビューが 破綻しない範囲」を見極めてバッチ化する：safe autocorrect は挙動を変えないので件数ベースで 最も広く（目安100件）まとめられる。unsafe autocorrect は挙動が変わりうるので、それより 狭い件数（目安30件）に抑える。手動修正はさらに読み解きコストが件数に比例しないため、 件数ではなく「性質が近い少数の Cop（目安2〜3個）」という基準でまとめる。

引数

• --auto: 起動時にこの引数が渡されたら、1 サイクルをユーザー確認なしで回しきるモードに入る。 スキップするのは「進めてよいか」の確認ゲートだけで、それ以外の原則は一切変わらない:
  • **1 サイクル ＝ 選んだバッチ（Tier をまたがない）**の原則、コミット・push・PR をしない原則、 サイクル完了で停止する原則は --auto でも不変。複数サイクルの自動連続実行はしない。
  • 人間の判断が要る曖昧な分岐は --auto でも勝手に決めない（手順 5 参照）。触らず残して報告する。
  • 手順 6 の関連テスト検証は --auto でも省かない。 unsafe autocorrect を無確認で当てる分、 関連テストが挙動変更を検知する唯一の安全網になるため、むしろ飛ばしてはいけない。
  • WHY: 確認ゲートは「差分が想定外に大きくならないか」「挙動変更を許容するか」を人に確かめる ためのもの。--auto は呼び出し側がその判断を事前に委譲した状態、と位置づける。委譲できるのは 「自動で潰してよい」判断までで、曖昧な Exclude 判断や壊れたテストの承認までは委譲されない。
• 引数が無ければ（従来どおり）各確認ゲートでユーザーに確認する。

重要な前提

• 1 サイクル ＝ 選んだバッチ（1 つの Tier にまとめた Cop 群）を潰しきるまで。 潰し終えたら 自動で次へ進まず、そこで停止してユーザーに制御を返す。次を潰したいときはユーザーが改めて このスキルを起動する。
• safe autocorrect（-a）と unsafe autocorrect（-A）を区別する。 -A はコードの挙動を 変えうるので、適用後は変更箇所に関連するテストで検証する（手順 6。全テストは流さず CI に任せる）。 safe バッチはこの性質を利用して最も広い単位でまとめて処理する（切り離しルールは手順 4 参照）。
• テスト/lint の実行コマンド・コーディング規約・コミット記法は そのプロジェクトの流儀に従う （このスキルでは決め打ちしない）。Cop ごとの autocorrect 可否の見分け方・Tier の進め方・ 各 Tier のバッチの組み方・Exclude/無効化の書き方は references/cop-fix-guide.md にまとめてある。

---

手順

1. 前提を確認する

• プロジェクトルートに .rubocop_todo.yml があるか確認する。
• 無ければ ここで止め、先に生成するよう案内する（生成は本スキルの役割ではない）:
  • sgcop を使っているプロジェクトなら sgcop-setup スキル、または直接 bundle exec rubocop --auto-gen-config で .rubocop_todo.yml を作ってから戻ってくるよう促す。
  • WHY: 本スキルは「列挙済みの違反を消化する」のが役割。潰す対象（todo）が無ければ仕事が始まらない。
• .rubocop.yml の先頭に inherit_from: .rubocop_todo.yml があることも確認する （--auto-gen-config が自動追記する。これが無いと todo が読まれない）。

2. 潰す対象を選ぶ

• .rubocop_todo.yml の各 Cop 見出しコメントにある # Offense count: N と autocorrect 対応状況を読み、 候補を提示する。
• ユーザーが特定 Cop / 特定モードを指定していればそれを優先する。 指定が無ければ以下の方針で選ぶ （見分け方・打ち切り基準は references/cop-fix-guide.md 参照）。

経路A: safe バッチ（safe autocorrect のみで完結する Cop）— しきい値内（目安100件）で複数 Cop を まとめる。候補一覧と合計件数をユーザーに提示し、対象範囲を確認する。--auto 時、または実行環境が 非対話でユーザーの応答を待てない場合は、提示（ログ出力）だけ行い、確認を待たずにしきい値内の バッチをそのまま対象にする。（安全側の理由: safe autocorrect は挙動を変えないため、確認なしで 進めても手順6の検証で違反ゼロを確認できれば取り消し可能な範囲に留まる。）

経路B: unsafe/手動修正のバッチ（unsafe autocorrect対応、または autocorrect 非対応の Cop）— Tier ごとに、そのリスクに見合った基準で複数 Cop をバッチにまとめる（Tier をまたいでは まとめない。組み方・打ち切り基準は references/cop-fix-guide.md 参照）。

• Tier 2 バッチ（unsafe autocorrect）: 件数ベース。経路Aより狭いしきい値（目安30件）に収まる 範囲で複数 Cop をまとめる。挙動が変わりうる修正なので、経路Aと同じ件数まで許容すると 手順6のテストで問題が起きたときの切り分けが大変になるため、上限を絞る。
• Tier 3 バッチ（手動修正）: 件数ではなく 性質が近い少数の Cop（目安2〜3個。例: Metrics/MethodLength と Metrics/AbcSize のように同じ箇所に重なって出る Cop）でまとめる。 手動修正は1件ごとの読み解きコストが件数に比例しないため、件数上限より「レビュアーが 1つの意図として読める Cop の組み合わせか」を基準にする。

3. 対象 Cop のエントリを .rubocop_todo.yml から削除する

• 選んだ Cop（バッチ対象すべて）の見出しコメントと設定ブロックを まるごと削除 する。
• WHY: todo に残したままだと違反は「許容」され続け、修正すべき対象として浮かんでこない。 削除して縛りを復活させることで、rubocop が再びその違反を報告する状態になる。

4. 修正する

経路A（safe バッチ）

• バッチ対象の Cop 全体に --only を付けずに一括で rubocop -a を当てる: bundle exec rubocop -a。 --only を外すのは、ある Cop の修正が引き金で新規発生する別 Cop の違反（連鎖違反）まで 一括で自動修正するため（詳細は references/cop-fix-guide.md 参照）。 --only なしのこの1回の実行結果（残った offense の一覧）が、そのまま残違反判定と手順6 最終検証を兼ねる（連鎖違反まで含めて検証される）。
• 結果に違反が残った Cop があれば、その Cop だけバッチから切り離し、経路Bの手順 （Tier 2 → Tier 3）に回す。バッチ側は safe で完結した Cop だけでこのサイクルを完了させる。 切り離した Cop は別サイクルとして扱う（このサイクル内では深追いしない）。残った Cop が todo に載っていた対象 Cop なのか、autocorrect の連鎖で新規発生した別 Cop なのかを区別する: 前者は切り離して別サイクルに回すが、後者は切り離さず手順6の副作用処理としてこのサイクル内で 扱う。
  • 切り離した Cop のエントリは手順 3 で削除済みなので、bundle exec rubocop --auto-gen-config で todo に戻しておく。 戻さずに放置すると、todo に載らない生の違反として残り、 手順 6 のプロジェクト全体検証が通らなくなる。

経路B（unsafe/手動修正のバッチ、Tier 順）

references/cop-fix-guide.md に従い、上から順に試す。各 Tier で違反が 残ったら次の Tier へ進む。Tier 2・Tier 3 ともバッチ全体に一括で適用し、一部の Cop だけ残った・ テストで問題が出た場合はその Cop だけバッチから切り離す（経路Aの切り離しルールと同じ考え方。 切り離した Cop は --auto-gen-config で todo に戻し、別サイクルとして扱う）。

• Tier 1: rubocop -a（safe autocorrect） — 挙動を変えない安全な自動修正。まずこれを試す。 autocorrect は絞らない: bundle exec rubocop -a（--only は付けない。連鎖違反を 取りこぼさないため）。
• Tier 2: rubocop -A（unsafe autocorrect） — safe で残った分に、バッチ対象の Cop 全体へ 一括で 当てる: bundle exec rubocop -A（--only は付けない）。挙動が変わりうるので、 当てる前にユーザーに一言断り、適用後は手順 6 で必ずテストする。--auto 時、または実行環境が 非対話でユーザーの応答を待てない場合は、断りを省いて適用してよい（手順 2 の経路Aと同じ扱い）。 ただし手順 6 の関連テスト検証は省かない（無確認で当てる分、テストが唯一の安全網）。 テストが落ちたら、原因になった Cop だけバッチから切り離す。切り離しは次の2点がそろって 初めて完了とみなす: ① その Cop が -A で書き換えた箇所を取り消す（対象ファイルが他の Cop の変更と混在していなければ git checkout -- <file> で丸ごと戻せる。混在している場合は 該当 Cop 由来の変更箇所だけを手動で戻す）。② --auto-gen-config で .rubocop_todo.yml に 戻す。①を忘れると、todo で「許容」に戻したはずの Cop の書き換えがコードに残ったまま次工程に 進んでしまう。切り離した Cop は別サイクルとして扱い、残りの Cop でこのサイクルを完了させる。 原因の切り分けが付かない場合のみ、そのサイクルを停止してどの Cop に -A を当ててどのテストが 落ちたかを報告する。
• Tier 3: 手動修正 — autocorrect 非対応の Cop、または自動修正後に残った違反を、意味を変えない 範囲で 個別に直す。バッチにまとめた Cop（目安2〜3個）を続けて直してよいが、どの修正がどの Cop 由来かコミットメッセージや差分から追えるように、Cop ごとに一区切りつけながら進める。 書き方はプロジェクトのコーディング規約に従う。
  • メソッド抽出ではコメントの対応先も見直す。 ガード節・処理のまとまりを別メソッドへ切り出すと、 直前にあった説明コメントがテキスト上「たまたま近い」別メソッドの直前に取り残されることがある。 抽出後は各コメントを「テキスト上の直前行」ではなく「意味的に何を説明しているか」で読み直し、 対応するメソッドの直前に付け直す。

5. 仕様上やむを得ない違反は Exclude / 無効化する

修正がアプリ仕様上不適切な違反だけ、.rubocop.yml での Exclude / 無効化、またはコード側の インライン # rubocop:disable で対応する。修正できるものは Tier 1〜3 で直し、ここに倒すのは 「直すと仕様が壊れる / その箇所には Cop の指摘が当てはまらない」ものに限る。

• できるだけ狭い範囲に限定する。特定ファイル/ディレクトリだけの Exclude か、該当行だけの インライン # rubocop:disable を第一候補にし、Cop 全体の Enabled: false はそのプロジェクトに 合わないと判断したときだけ。
• 必ず理由コメントを残す（記法はプロジェクトの規約に従う）。
  • WHY: 「あえてチェックを外した」判断はコードにも差分にも現れにくい。理由が無いと、後から別の人 （や別の AI）が対応漏れと誤認して蒸し返したり、漫然と放置されたりする。
• 自明に直せるか無効化が妥当か 判断が割れるものはユーザーに相談 してから決める。 --auto 時は相談で止まる代わりに、その違反には手を付けず残し、最終報告に「要判断」として 列挙する（手順 7）。Tier 1〜3 で自明に直せるもの・明確に Exclude/インライン disable 相当の ものは従来どおり自動で処理してよい。曖昧なものだけ人に残す。
  • WHY: Exclude / 無効化は「あえてチェックを外す」判断でコードにも差分にも現れにくく、誤ると後で 対応漏れと誤認されて蒸し返される。自動で倒すと責任の所在が曖昧になるため、--auto でも ここだけは人に委ねる。
  • 人に残した「要判断」の違反は、その Cop のエントリを削除したままにせず、手順 7 で --auto-gen-config を実行して todo に拾わせ、見出しコメントに「要判断: <理由>」を一言 添える。 これにより違反が todo 上で「許容」され CI を壊さず、かつ次に見た人（や別の AI）が その Cop を素通りせず要判断状態だと気づける。
    • WHY: 手順 3 でエントリを削除した Cop に判断保留の違反が残ると、そのままでは todo にも 载っていない生の違反として CI で検出され続けてしまう。かといって黙って todo に戻すと 「もう解決済み」と誤認されて蒸し返されない。要判断である旨をコメントで残すことで、 両方の問題を同時に避けられる。

6. 検証する

• 経路A（safe バッチ）は手順 4 の実行結果をそのまま使う。 再実行不要。挙動を変えない前提なので 関連テストの実行も不要。
• 経路Bはバッチ対象の Cop に絞って再実行し、違反ゼロを確認する: bundle exec rubocop --only <Cop1>,<Cop2>,...。
• サイクルの最後に、必ずプロジェクト全体で bundle exec rubocop（--only 無し、対象ファイル 指定も無し）を実行し、違反ゼロを確認する。 これがこのサイクルの完了条件であり、経路A・経路B 共通の最終ゲート。まだ todo に残っている（今回のサイクル対象外の）他 Cop の違反は inherit_from: .rubocop_todo.yml で抑制されるため出てこない想定で、ここで検出される違反は todo に載っていない新規のものだけのはず。
  • WHY: --only <Cop> や変更ファイルだけの実行では見えない副作用がある（例: autocorrect で不要な代入を消したらメソッド本体が空になり Lint/Void 等が新規発生する、 手順 5 の Exclude/無効化の書き方が構文として誤っている、など）。プロジェクト全体を通すことで 初めて「このサイクルで CI を壊していない」と言い切れる。
  • 手順 5 で「要判断」の違反を残した場合は、その Cop をこの時点ではまだ todo に戻していない （todo に戻すのは手順 7）。 そのままでは全体検証がその違反で失敗してしまうので、 要判断の Cop だけ手順 7 を先に済ませてから全体検証する（--auto-gen-config で todo に 戻し「要判断」コメントを添えたあと、あらためて全体実行する）。
  • それでも全体実行で違反が残っていたら、このサイクルは未完了として扱い、原因を調査してから 解消する。 想定される原因ごとの対応:
    • autocorrect の副作用でスコープ外の Cop が新規違反を出した → その違反を Tier 1〜3 の要領でこのサイクル内に含めて直す（バッチの選定基準は、あくまで 選定時にどの Cop を まとめて着手するかを縛るものであり、副作用の後始末まで対象を広げるかどうかを 縛るものではない）。手順4の autocorrect から --only を外したことで、safe に直せる 連鎖違反はこの時点（autocorrect 実行時）で既に解消されている。ここで残るのは、safe に 直せなかった連鎖違反や、Exclude/無効化の設定ミスなど autocorrect では対応できない ものだけという役割分担になる。
      • ただし新規違反の発生箇所が適用済みマイグレーション等の「書き換えてはいけないファイル」 の場合は、コード修正ではなく Exclude / インライン disable に倒す（Tier 1〜3 の対象に 含めない）。適用済みマイグレーションはロールバック定義も含めて過去のスキーマ操作の記録 そのものであり、rubocop 違反の解消目的であっても書き換えると履歴と実際のDBスキーマが 乖離する。判断基準は references/cop-fix-guide.md の「Exclude のパス指定」参照。
    • バッチから切り離した Cop のエントリを todo に戻し忘れている → 手順 4 の とおり --auto-gen-config で戻す。
    • 手順 5 で Exclude / 無効化した設定が誤っている（YAML の書き方・対象範囲のミスなど）→ 設定を直す。
  • --auto 時も原因調査と解消は省略しない。 確認ゲートを省くのは「進めてよいか」の 合意だけで、全体成功というゴール自体は --auto の有無に関係なく変わらない。
• Tier 2（unsafe）または手動修正でコードの挙動に触れた場合は、変更箇所に関連するテストだけを そのプロジェクトの流儀で実行し、壊れていないことを確認する。バッチ内の複数 Cop をまとめて 1 回のテスト実行で検証してよい（Cop ごとに個別実行する必要はない。バッチは全 Cop が同じ Tier ＝同程度のリスクという前提でまとめているので、変更ファイル全体に対して一度テストを 通せば十分）。
  • 関連テストの絞り方: git diff --name-only で変更ファイルを出し、対応する spec/test、修正した クラス/メソッドを使う箇所など、今回の差分が影響しうる範囲に限定して走らせる。全テストは 流さない（重いので CI に任せる）。
  • 影響範囲が差分から自明でないほど広い場合のみ（例: Metrics/* 系をメソッド分割・クラス抽出して 呼び出し側が散る、1 Cop でも大量ファイルにまたがる修正）、変更したシンボルの利用箇所と対応する spec の洗い出しを 探索エージェントに委ねてよい。差分から関連 spec がすぐ辿れる通常ケースでは 不要（手間の方が勝つので、デフォルトは上記の git diff 起点の手動絞り込み）。
  • WHY: rubocop の pass はスタイルの整合しか見ない。unsafe autocorrect や手動修正は挙動を 変えうるので、関連テストを通して初めて「この変更で壊していない」と言える。全体の網羅は CI の 役割で、ここで毎回フルスイートを回すと 1 サイクルが重くなりレビュー単位の軽快さが失われる。

7. todo を再生成して停止する

• 注意: ここでの再生成は「todo からエントリが消えて空いた分を綺麗にする」ためだけの操作。 手順 5 で決めた Exclude / 無効化の設定内容そのものは .rubocop.yml に書くのであって、 --auto-gen-config の出力（.rubocop_todo.yml）に理由コメントを足して着地させるものではない。 --auto-gen-config は実行のたびに Exclude/無効化していない残存違反を全部拾い直して .rubocop_todo.yml を丸ごと作り直すため、.rubocop.yml 側に書いた恒久設定と混同しないこと。
• 手順 5 で Exclude / 無効化した場合、その Cop の項目が .rubocop_todo.yml に残って紛らわしいので bundle exec rubocop --auto-gen-config で作り直す。
  • 違反を全部修正しきった（Exclude/無効化していない）場合は、その Cop のエントリは手順 3 で既に 削除済みなので、再生成は必須ではない。todo の他項目の件数を更新したいときだけ実行する。
  • バッチ（経路A・経路Bいずれも）から Cop を切り離した場合も、その Cop の項目は手順 3 で 削除済みなので再生成不要。切り離した Cop は改めて別サイクルで扱う。
• 手順 5 で「要判断」の違反を手を付けずに残した場合は、再生成が必須。 bundle exec rubocop --auto-gen-config を実行してその Cop を todo に戻したあと、生成された .rubocop_todo.yml を自分で開いて（--auto-gen-config はコメントを自動で足してくれないので 手動編集する）、見出しコメントの直後に「要判断: <理由を一言>」を追記する。 （この todo 反映自体は手順 6 の全体検証より前に行う必要がある。手順 6 の該当箇所を参照。）
  • WHY: 手順 3 で todo エントリを削除済みのまま要判断の違反を放置すると、todo にも载らない生の 違反として CI を壊し続ける。再生成して todo に戻し、かつ「要判断」と分かるコメントを添える ことで、CI を壊さずに「解決済みではない」ことも伝わる。
• 1 サイクルが完了したらここで停止し、ユーザーに制御を返す。 差分確認・コミットはユーザーが行う。
  • WHY: レビュー単位で運用するため。バッチはあくまで「1サイクルで扱える Cop 数を、Tier ごとの リスクに見合う範囲で増やす」ものであり、複数サイクルを自動連続実行するものではない。 次を潰したいときは、ユーザーが改めてこのスキルを起動する。--auto でもこの停止原則は 不変（--auto は「1サイクルを確認なしで回しきる」だけで「複数サイクル連続」ではない）。
• --auto 時の最終報告には次を含める（差分確認・コミット判断の材料になる）:
  • 潰した Cop / バッチと結果（違反ゼロを確認した旨）。
  • -A（unsafe）を当てた場合はどの Cop に当てたか＋手順 6 の関連テスト結果。
  • 手順 6 で見つかったスコープ外の新規違反（既存の「次回 --auto-gen-config で拾う todo 候補」報告に含める）。
  • 手順 5 で残した「要判断」の違反一覧（自動で倒さず人に残したもの）。

8. 全 Cop を潰しきったら .rubocop_todo.yml 自体を削除する

• 手順 7 の結果、.rubocop_todo.yml に Cop のエントリが1つも残っていない（「要判断」で 戻した項目も無い）状態になったら、todo 運用そのものが不要になったとみなし、以下を行う。
  • .rubocop_todo.yml を削除する。
  • .rubocop.yml の inherit_from から .rubocop_todo.yml への参照を削除する （他ファイルへの参照と併記されていた場合は、その1行だけを取り除き残りは維持する。 inherit_from が .rubocop_todo.yml 単体だった場合は inherit_from キー自体を削除する）。
  • bundle exec rubocop を実行し、削除後も違反ゼロであることを確認する。
  • WHY: .rubocop_todo.yml は「未対応の違反を一時的に許容する」ための仕組み。中身が空になった まま放置すると、空ファイルと不要な inherit_from参照がプロジェクトに残り続け、次に見た人 （や別の AI）が「まだ何か許容されている違反があるのでは」と誤解する余地を残す。空になった 時点で撤去してしまえば、todo 運用が完了したことがファイル構成からも一目で分かる。
• 1つでも Cop エントリが残っている場合はこのステップを行わない。 手順 7 までで停止する （まだ消化中の todo を早まって消すと、残りの違反が生の違反として CI を壊す）。
• このステップも手順 7 までと同じサイクルの終端として扱い、削除できたらここで停止して ユーザーに制御を返す（コミットはユーザーが行う）。--auto 時も削除の実行自体は他の safe な 自動処理と同様に確認なしで行ってよいが、削除した旨は最終報告に必ず含める。

---

注意点・つまずきやすいところ

• Tier をまたいでバッチにしない。 safe / unsafe / 手動修正は挙動変更のリスクが異なるので、 1 回のバッチは同じ Tier の Cop だけで構成する。
• バッチのしきい値・打ち切り基準は references/cop-fix-guide.md 参照。 経路A（safe）は件数ベースで最も広く、Tier 2（unsafe）はそれより狭い件数、Tier 3（手動修正）は 件数ではなく性質が近い少数の Cop、という基準の違いに注意する。
• safe と unsafe を区別する。 -a（safe）は基本そのまま信頼してよいが、-A（unsafe）は挙動が 変わりうる。-A を当てたら手順 6 の関連テストを飛ばさない。逆に、ここで全テストを流す必要はない （重いので CI に任せ、手元では差分に関連するテストだけ確認する）。
• 検出は絞る／autocorrect は絞らない。 残違反の確認・検証（autocorrect を伴わない実行）は --only <Cop> を付ける——まだ todo に残した他 Cop の違反が出力に混ざらず、潰したい Cop の 進捗が見やすくなる。一方 autocorrect（-a/-A）には --only を付けない——付けると 対象 Cop の修正が引き金で新規発生する別 Cop の違反（連鎖違反）が自動修正されずに残ってしまう。 todo が対象外 Cop の違反をマスクしてくれるので、絞らなくても安全（詳細は references/cop-fix-guide.md 参照）。さらに手順 6 最後の 全体検証は --only を付けず対象ファイル指定も無しで実行する（この検証の目的そのものが 「絞り込みでは見えない副作用が無いか」の確認なので、絞ってしまうと意味がない）。まとめると 3区分: 検出・検証＝絞る／autocorrect＝絞らない／全体検証＝絞らない。
• サイクルの終端条件は「プロジェクト全体で bundle exec rubocop が違反ゼロ」。 対象 Cop だけ潰して停止するのではなく、手順 6 の全体検証まで含めて初めてサイクル完了とみなす。
• 無効化は最小範囲＋理由コメント。 Cop 全体を無効に戻すのは最後の手段。まず Exclude で ファイル/ディレクトリ単位に絞れないか考える。
• コミットしない。 このスキルの責務は「選んだバッチを違反ゼロにして停止」まで。 コミット・PR はユーザーの手で。
• todo が空になったら消す。 .rubocop_todo.yml の中身を全部潰しても、ファイル自体と .rubocop.yml の inherit_from 参照は自動では消えない。手順 8 で明示的に削除・参照解除まで 行う。