cross-refactoring を飛ばしてよい条件が、どの Skill にも書かれていない

[takemi-ohama]

何を見つけたか

cross-refactoring を飛ばしてよい条件が、どの Skill にも書かれていない。

development-workflow は「構造改善と実装レビューは、通す工程であって任意ではない」と定め、
standard と legacy-refactor の構造改善を cross-refactoring にしている。一方
references/parallel-work.md の下限 3 は「判定したモードの必須の工程を飛ばさない。飛ばすなら、
飛ばした工程と理由を Pull Request の本文へ残す」と書く。

飛ばしてよい場合があることは読み取れるが、どういうときに飛ばしてよいかは書かれていない。
判断が毎回その場の裁量になる。

どこで見つけたか

v10.8.0 の実装 Pull Request #489。standard だが、本番コードの差分は
plugins/ndf/skills/development-workflow/scripts/lib/workflow-common.sh の 1 行
（WF_STAGE_MATRIX の「設計」の行）だけで、残りは Skill 本文と参照の Markdown だった。

飛ばした理由は 2 つで、Pull Request の本文へ残した。

• 改善する構造が 1 行しかない
• --scope を広げると、この変更が触っていないファイルへの改善提案が入り、範囲外の変更になる

なぜこの変更の範囲外なのか

#375 / #376 / #463 の受け入れ条件は design と requirements-design の成果物の定義であり、
cross-refactoring の要否の判断を含まない。

同じ状態に当たった回数

4 回当たっている。 いずれも変更が Markdown と定数だけで、構造改善の対象になるコードが無かった。

Pull Request	扱い
#489（v10.8.0）	飛ばし、理由を Pull Request の本文へ残した（上記）
#520 / #521（v10.10.0）	--baseline-test に指定できるテストが範囲に無く（pytest が no tests ran、終了コード 5）、refactor.py init が「着手前のテストが失敗しています」で止まった。workflow-modes.md の「構造改善の退避先」に従い refactoring 単独へ退避し、Pull Request のコメントへ残した
#612（v10.11.0、#500 の文書の改名と手入れ）	standard のため起動したが、テスト整備ラウンド 1 の途中で中止した。中止までに、pytest が収集しない補助ファイルへテストを足す事象も起きた（#620）

退避の判断は規定どおりに通った。 ただし plugins/ndf/skills/development-workflow/references/workflow-modes.md
の「構造改善の退避先」の条件は、テストが無い・CLI が使えない・範囲を絞れないの 3 つで、Markdown
だけを変える standard の変更は条件に無い。 Skill を足す変更がこれに当たり、退避が例外ではなく
通常の経路になっている。

直さないと何が起きるか

同じ判断を毎回その場で行うことになる。 standard の変更のうち、Markdown だけを変える
ものはこのリポジトリでは珍しくない（v10.5.0 は 22 件中 19 件が light、残る 3 件も配布物の
記述だった）。

飛ばした記録が gate に残らない。 進行の記録に「構造改善」を書かないため、配布の時点で
「記録なし: 構造改善」と案内が出る。これは意図した挙動だが、飛ばしてよいと判断した場合と、
通し忘れた場合が同じ見え方になる。

所要時間への影響（2026-09-01〜09-15 の実測）

集計の方法と全体の値は #662 にある。

• 同じ Pull Request で両方を回した 19 件で、所要の中央値は cross-refactoring 75.9 分、cross-review 14.9 分だった。1 本の Pull Request では構造改善が工程の時間の大半を占める
• 同じ期間の合計は、cross-refactoring 33 件で 56.3 時間（上限なしに繰り返した 2 件を除くと 34.4 時間）、cross-review 143 件で 101.4 時間
• 飛ばしてよい変更で起動した実行が何件あったかは出していない（変更の種類で分けていないため未確認）

考えられる直し方

案	中身
飛ばしてよい条件を書く	「本番コードの差分が無い、または改善の対象になる構造を持たない」ときに飛ばしてよい。判断は --scope に入れる対象があるかで見る
記録に「飛ばした」を持たせる	通っていない状態と、飛ばすと判断した状態を分ける。工程の値は増やさない（盤面の単一選択に影響する）

どちらも「飛ばす」を既定にしない。 通す費用より、通さない判断が見えないことのほうが高い。

• 条件の判定は差分から決まるので、スクリプトに持たせる。 差分がコード以外だけか、--scope に入る対象があるかを development-workflow の scripts/（stage-check.sh と同じ置き場所）が返し、LLM はその結果を読んで判断する（Skill の主体をスクリプトへ移し、LLM は呼び出し・結果の解釈・判断だけを持つ（全 Skill の改善の親） #845 の判断の 3 段の段 1）
• 「飛ばした」の記録は progress-record.sh --note で残せる。 工程の値を増やさずに、飛ばした工程と理由を記録へ添える（plugins/ndf/scripts/progress-record.sh の usage に --note TEXT がある）

由来

issue #375

関連

• cross-refactoring: テスト整備ラウンドが pytest の収集しないファイルへテストを足し、実行されないまま検証を通る #620 — テスト整備ラウンドが pytest の収集しないファイルへテストを足す（Docs: README.md を規約の役割へ合わせ、Skill 執筆規約を AUTHORING.md へ改名する（#500） #612 の中止までに起きた）
• cross-refactoring の --scope がファイル単位のため、issue と関係の無い既存の関数まで整理し、変わった範囲が issue から読めない #622 — --scope がファイル単位のため、issue と関係の無い既存の関数まで整理する
• cross-refactoring: 受け入れ条件のテストが既にある文書中心の変更で、テスト整備ラウンドが文言を固定するテストを足し、後の構造改善を塞ぐ #723 — 受け入れ条件のテストが既にある文書中心の変更で、テスト整備ラウンドが文言を固定するテストを足し、後の構造改善を塞ぐ（同じ「構造改善の退避先」で直る）
• supervisor の分類・振り分けの判断を Jev へ移し、最小構成の claude -p より費用を下げる #841 — 判断点の一覧。「飛ばしてよいか」は段 2 の判断点の候補

リリース後テスト（10.17.5、本番）

対象の版: 10.17.5（2026-09-23 23:27（UTC）に main へマージ、c33fde11、タグ ndf--v10.17.5、GitHub Release https://github.com/devbasex/ai-plugins/releases/tag/ndf--v10.17.5 ）
導入経路: ref を指定しない登録（正式版のチャネル = main）から、$HOME 直下の隔離した設定ディレクトリで取得・導入した。Claude Code 2.1.281 は CLAUDE_CONFIG_DIR、Codex 0.156.0 は CODEX_HOME、Kiro は git archive c33fde11 の展開物の install.sh --project <一時> --yes（一時 HOME）。claude のセッションは起動していない。利用者の ~/.bashrc ~/.zshrc の sha256 は前後で一致、~/.local/share/ndf/ は前後とも無い。隔離先は確認後に削除した。

課題	受け入れ条件	実行したこと	実行時刻（UTC）	結果
#880 #883 #494 #723	取得元が出した版を指す	git ls-remote origin refs/heads/main 'refs/tags/ndf--v10.17.5^{}'	2026-09-23 23:28	合格 / exit=0、どちらも c33fde11
#880 #883 #494 #723	3 経路で 10.17.5 が入る	claude plugin marketplace add devbasex/ai-plugins → install ndf@ai-plugins → list / codex plugin marketplace add devbasex/ai-plugins → plugin add → list / Kiro の install.sh	2026-09-23 23:28	合格 / すべて exit=0。Claude・Codex とも Version 10.17.5、Kiro の ndf.json の説明が v10.17.5、.kiro/skills 43 個 + steering の ndf-policies.md（manifest の 44 と一致）
#880 #883 #494 #723	導入先の中身が出した版と同じ	Claude の導入先全体を c33fde11 の plugins/ndf と diff -rq。Codex と Kiro の導入先の skills/cross-refactoring と skills/development-workflow を同様に diff -rq	2026-09-23 23:29	合格 / 差は Claude Code が作る .in_use だけ。Codex・Kiro は 4 つとも exit=0
#880 #883 #494 #723	更新案内の「手元で確かめる」	4 コマンド（Claude Code の導入先の scripts を $SCRIPTS に）	2026-09-23 23:29	合格 / 4 つとも exit=0
#880 #883 #494 #723	AC1〜AC7・AC9〜AC14・AC17・AC18（検証手段は pytest）	導入先の skills/cross-refactoring/tests を uv run ... pytest -n 4	2026-09-23 23:29	合格 / exit=0、846 passed（10.6 秒）
#494	AC12〜AC14: assess の判定	一時リポジトリで導入先の refactor.py assess --base base を差分ごとに実行	2026-09-23 23:29	合格 / .md とテストだけ → exit=3（0 ファイル・0 行）、本番コード 5 行 → exit=3、11 行 → exit=0（通す）、存在しない ref → exit=2。理由と数えた値を 1 行ずつ出す
#494	AC15: 退避先の文書が飛ばす条件と退避の条件を分ける	導入先の workflow-modes.md の「構造改善の退避先」を読む	2026-09-23 23:30	合格 / assess の終了コード 3 の行と実行例がある

合否: 合格（実施した条件すべて）

記録: https://github.com/devbasex/ai-plugins/pull/935#issuecomment-5804675590（配布: PR #935 / #937、Release ndf--v10.17.5）

進行

モード: standard / 作業ツリー: /work/ai-plugins/.worktrees/feat/issue-880-883-494-723-cross-refactoring-fixes / 計画: issues/issue-880-883-494-723-plan.md

• 要求と受け入れ条件 — 2026-09-23 09:45
• 作業場所の用意 — 2026-09-23 09:49
• 設計 — 2026-09-23 09:54
• 素材の収集と出典の確定
• ドキュメント再構成 — 2026-09-23 09:58
• ドキュメントレビュー — 2026-09-23 09:59
• 計画 — 2026-09-23 12:56
• 実装 — 2026-09-23 12:57
• 構造改善 — 2026-09-23 14:26
• 実装レビュー — 2026-09-23 15:41
• 完了判定 — 2026-09-23 16:17
• Pull Request — 2026-09-23 13:13
• 確定仕様化 — 2026-09-23 21:22
• 後片付け — 2026-09-23 21:32
• 配布 — 2026-09-23 21:33
• 体裁レビュー
• リリース後テスト — 2026-09-23 23:28
• 振り返り

[takemi-ohama]

マイルストーン 10 で、この課題が指す状態に 2 回当たった（PR #520 / #521）。

どちらも変更が Markdown と定数だけで、--baseline-test に指定できるテストが対象範囲に
無かった。workflow-modes.md の「構造改善の退避先」に従い refactoring 単独へ退避し、
退避したことを Pull Request のコメントへ残した。

$ uv run --with pytest pytest plugins/ndf/skills/quality-gates plugins/ndf/skills/requirements-design -q
no tests ran in 0.01s          # 終了コード 5
$ refactor.py init 520 --scope ... --baseline-test ...
❌ 着手前のテストが失敗しています（...）。先に直してから開始してください

退避の判断そのものは規定どおりに通った。 ただし、standard で Markdown だけを変える
Pull Request は繰り返し出るため（Skill を足す変更がこれに当たる）、退避が例外ではなく
通常の経路になっている。この課題が扱う「飛ばしてよい条件」に、この形を含めるかどうかの
判断材料として残す。

[takemi-ohama]

同じ事象を PR #617（ndf v10.11.0）のまとまりで確認した。PR #612（issue #500、文書の改名と手入れ）は standard のため cross-refactoring を起動したが、構造改善の対象になるコードが無く、テスト整備ラウンド 1 の途中で中止した（改修計画: #612 (comment) ）。中止までに、pytest が収集しない補助ファイルへテストを足す事象も起きた（#620）。

[takemi-ohama]

「飛ばしてよい条件」を決める材料として、マイルストーン「04 worktree 運用の残課題」の 5 本の実測を置く。

PR	終わり方	適用 / 取り消し
#637	6 ラウンド、上限で終了	適用 9（現状固定 8 + 構造改善 1）/ 取り消し 8 組
#639	5 ラウンド、上限で終了	適用 8 / 取り消し 9
#640	5 ラウンド	適用 20 / 取り消し 3
#643	3 ラウンド、no_more_proposals で収束	適用 7 / 取り消し 3。構造改善の提案は 0 件
#646	打ち切り（同じ項目で 4 回連続 STALLED。#647）	テスト整備 適用 8 / 構造改善 適用 5

読めること。

• 5 本のうち 3 本が収束していない（上限 2 / 打ち切り 1）
• 取り消しが適用と同数に近く、Fix: 被演算子の走査がリダイレクトを読み飛ばして続く形にする（#313） #639 では取り消しが適用を上回る。原因の 1 つは cross-refactoring: test_coupled_to_internals の提案を受け付けるのに、検証が「テストの期待出力の変更」として必ず取り消し、同じ群の src 改善まで道連れにする #641
• Fix: 開始時の hook の追従を既定で止め、follow_branch: true で有効にする（#610） #643 は構造改善の提案が 0 件で、費用はテスト整備ラウンドだけに使われた。対象が 1 ファイルの小さな差分では、構造改善の提案そのものが出ないという条件の候補になる

由来: #652 (comment)

[takemi-ohama]

「飛ばしてよい条件」の材料を 1 件足す（devbasex/devbase#252、issue devbasex/devbase#249、ndf 10.17.0、standard）。

• 本番コードの差分は containers/base/Dockerfile の 2 か所（apt の一覧へ 1 語、版の確認の RUN へ && shellcheck --version）だけ。守る振る舞いは「イメージを建てると入る」ことで、CI はイメージを建てないため手元のテストが見られるのは Dockerfile の文字列だけだった
• cross-refactoring を起動したところ、テスト整備ラウンドが差分と関係しない既存の命令の現状固定テストを 4 コミット・約 350 行積み、ループを止めて e379a6c でまとめて戻した（--scope がファイル単位である点は cross-refactoring の --scope がファイル単位のため、issue と関係の無い既存の関数まで整理し、変わった範囲が issue から読めない #622 に記録済み）
• 結果として構造改善の工程が残したものは 0 件で、戻す手間と CI の 1 巡が増えた

条件の案: 差分の本番コードが、テストから文字列としてしか検査できない宣言（Dockerfile・CI の定義など）だけで、構造を変える余地が差分の中に無いときは refactoring 単独へ退避してよい。

[takemi-ohama]

棚卸（2026-09-25）: 実装は ndf 10.17.18 までに main へ配布済みのため閉じる。