PR #450 の構造改善で時間の枠を超えて見送った提案の残り 15 件（_aws_plan の重複・補完の分岐の連なり・テストの補助の重複など） #452

何を見つけたか

PR #450（スプリント m10b）の構造改善（cross-refactoring rf450）は、提案のうち 5 件を適用し、16 件を PR に入れなかった。内訳は、時間の枠（budget）を超えた見送りが 15 件、ほかの採用と同じ変更（duplicate）が 1 件である。main = 04f7228（2026-10-15）で、次の 15 件が残っている。

提案ごとの理由と見積りは改修計画の「見送った提案」の節にある: #450 (comment)

どこで見つけたか

スプリント m10b の振り返りで、PR #450 の改修計画のコメントを起票済みの課題と突き合わせたとき。見送った提案は改修計画にだけあり、課題になっていなかった（m10a の同じ見送りは #444 として起票され、m10b で片付けた）。

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

PR #450 の構造改善は時間の枠の中で入る件だけを適用する工程で、枠を超えた件はその PR の範囲に入らない。#444・#435 の受け入れ条件にも含まれない。根拠: Vision（MVV 版 1）

直さないと何が起きるか

利用者から見える振る舞いは変わらない。次に env sync の AWS の経路・補完・偽の OpenBao などを触る開発者と AI エージェントが、同じ重なりや長い関数を読み解く手間を負う。課題にしないと、改修計画のコメントが埋もれて次のスプリントの候補に上がらない。

由来

PR #450

依頼（原文）

#452。人へ問わずに進め、決められない点は前提か未決として課題の本文へ書く。本文を書いたら spec-copy.py write 452 issues/issue-452-requirements.md で写しを作り、コミットする（push しない）。 #452 は PR #450 の構造改善で時間の枠を超えて見送った提案の残り 15 件である。前例は #444（要求と設計は #445・#446 の形、実装 #448）で、件ごとに直すか直さないか（理由を書く）を決め、兆候が消えたと見なす基準（行数・認知的複雑度など）と、振る舞いを変えないことの確かめ方（既存のテストが手を入れずに通るか、直すならその理由）を決める。提案ごとの理由と見積りは PR #450 のコメント 6056505102 の「見送った提案」の節にある。#365 と #490 は同じスプリントだが本文の受け入れ条件で進めるため、この設計に含めない（#490 と同じ lib/devbase/volume/manager.py を触る件は、ぶつからない分け方を書く）。作業用のプロジェクトを含め devbase up を打たない（AGENTS.md の落とし穴。実のボリュームが付く）。base イメージを建て直さない。

（書き手: AI の起動指示、日付: 2026-10-15。利用者の指示の原文ではない）

課題の題と、上の「何を見つけたか」〜「由来」の節は、書き手が起票者（スプリント m10b の振り返り、2026-10-15）である。利用者の指示の原文は、この課題には無い。

起票者の推定

題・本文のうち、利用者の指示の原文に無く起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• PR スプリント m10b #450 の構造改善で時間の枠に入らなかった 15 件を、直すか直さないかに分けて片付ける。env sync の AWS の経路・補完のスクリプト・偽の OpenBao（tests/conftest.py）などを次に触る開発者と AI エージェントが、重なりや長い関数を読み解く手間を減らす
• 改修計画のコメントにだけある見送りを、判断と理由の付いた記録にする

前提

• 前提 1: 「15 件」は改修計画（PR スプリント m10b #450 のコメント 6056505102）の「見送った提案」の行のうち、duplicate の 1 行を除いた 15 行で、1 件は「対象 × 兆候」の組である。下の「提案の一覧」の R1〜R15 がその 15 件で、1 本の実装の Pull Request で扱う
• 前提 2: 改修計画には提案ごとの兆候の名前と見積りしか残っておらず、提案の本文（どこが重なりの相手か・何が死んだコードか）は残っていない（提案の作業ディレクトリ rf450/work/.cross_refactoring には指標のキャッシュしか無いことを 2026-10-15 に確かめた）。下の「現状」の列の重なりの相手と死んだコードは、要求の時点でコード（main = 04f7228）から特定したものである
• 前提 3: 行数は def（シェルは関数名の行）から関数の最後の行までを数える（docstring・コメントを含む）。認知的複雑度は complexipy、循環的複雑度は ruff の C901（McCabe）の値を使う。シェルの関数には認知的複雑度を測る道具が無いため、行数と分岐の置き場で判定する
• 前提 4: 兆候の基準の数値は PR #442 の構造改善で時間の枠を超えて見送った提案の残り 13 件（_aws_sync_plan の _SyncContext 化・env list / keygen の長い関数・テストの補助の重複） #444 の基準（long_method は 50 行以下かつ認知的複雑度 15 以下）を引き継ぐ。長い関数から抜き出した関数も同じ基準を満たす。抜き出した先へ長さを移しただけのものは、兆候が消えたと見なさない
• 前提 5: 「直す / 直さない」の列は要求の時点の見立てである。設計で変えるときは、変えた事実と理由を設計文書の決定の記録に残す。理由の無い「直さない」は受け入れない
• 前提 6: 表に無い同じ形のもの（env.py のほかの関数の from devbase.errors import DevbaseError の取り込み直し、env/collectors/google.py の /home/ubuntu の文字列など）は扱わない
• 前提 7: PR #488 の構造改善で取り消し・見送った 2 件（使われない project_name の引数・VS Code Server の片付けの関数の分割） #490（VolumeManager.__init__・ensure_volumes から使われない project_name を外す）と テストの例に作成者のプロジェクト名が残り、置き換えの表にも固有の語の一覧にも無い #365 は、この課題に含めない。PR #450 の構造改善で時間の枠を超えて見送った提案の残り 15 件（_aws_plan の重複・補完の分岐の連なり・テストの補助の重複など） #452 が lib/devbase/volume/manager.py で変えるのは、モジュールの先頭の定数（VSCODE_SERVER_TARGET・VSCODE_BIN_TARGET とその近く）だけで、VolumeManager.__init__・ensure_volumes・その呼び出し元（lib/devbase/commands/container.py）と、PR #488 の構造改善で取り消し・見送った 2 件（使われない project_name の引数・VS Code Server の片付けの関数の分割） #490 が期待を直すテスト（tests/commands/test_container_scale_order.py・tests/volume/test_manager_vscode.py・tests/volume/test_manager_ensure_volumes.py）を変えない。後からマージする方が main を取り込む（main は strict）

提案の一覧

現状の値は main = 04f7228 で測った。

「直さない」の理由:

1. R4: この関数の役目は、名前の検査の誤りを --group のオプションの誤り（「--group に使えない名前です: …」・終了コード 2）へ変えることで、文言と終了コードはコマンドの層の知識である。呼ぶ先（volume.manager・OpenBao の設定）へ移すと、コマンドの文言が設定の層へ入る。PR #442 の構造改善で時間の枠を超えて見送った提案の残り 13 件（_aws_sync_plan の _SyncContext 化・env list / keygen の長い関数・テストの補助の重複） #444 の R2（#444 を実装する（スプリント m10b） #448）で CLI と TUI の両方が呼ぶ 1 か所として置いた形で、移す先の候補がこの形より良くならない
2. R6: 名前は _ENV_MASKERS のキー（_env_shape の返す 'none'）に合わせた _mask_env_<形> の規則どおりで、使わない引数は表から同じ形で呼ぶために要る。名前や引数を変えると、4 つの関数の揃いが崩れる
3. R7: すでに long_method の基準（50 行以下・認知的複雑度 15 以下、前提 4）を満たしている

兆候が消えたと見なす基準

ドメインイベント

E3 を E4 より先に置くのは、本番のコードと補完の変更を「既存のテストが手を入れずに通る」ことで確かめるためである（R11 の補助を先に動かすと、R8〜R10 の確かめに使うテストが変わった後になる）。

受け入れ条件

• R1〜R15 の 15 件のそれぞれが「直す」か「直さない」に分かれ、「直さない」の件には理由が本文（Pull Request か、この課題）に書かれている
• 「直す」とした件は、「兆候が消えたと見なす基準」の該当の行を満たす。基準の値を測ったコマンドと、変更の前後の値が Pull Request の本文にある
• 直した関数から抜き出した関数も、long_method の基準（50 行以下・認知的複雑度 15 以下。シェルの関数は 60 行以下）を満たす
• env keygen・env sync（AWS の経路）・env の --group の検査（CLI と TUI）・compose のスケールで作るファイル（.docker-compose.scale.yml）・snapshot list の、標準出力・標準エラー・終了コード・ファイルへの書き込みが変更の前と同じである。R1〜R10 を入れたコミットで tests/ を変えず、既存のテストが手を入れずに通ることで確かめる
• bash と zsh の補完の候補が変更の前と同じである。tests/cli/test_completion.py・test_name_context_consistency.py・test_zsh_completion_run.py・test_post_start_command.py が、R8〜R10 を入れたコミットで手を入れずに通ることで確かめる
• R11〜R15 の補助の移動を除き、tests/ の既存のテストを変えていない。補助の移動でも assert の中身を変えていない。変えたときは、変えたテストと理由が Pull Request の本文にある
• R15 の後も、Docker かイメージが無い端末で 4 つのファイルのテストが飛ばされ、飛ばす理由の文が変更の前と同じである
• lib/devbase/volume/manager.py の変更がモジュールの先頭の定数に限られ、VolumeManager.__init__・ensure_volumes と前提 7 に挙げたテストを変えていない
• 表に無い関数と、前提 6 に挙げた同じ形のものを変えていない
• 全体のテスト（env -u DEVBASE_ROOT uv run --locked pytest tests/ -q）が通る
• CI と同じ lint（uvx ruff check --select=E9,F63,F7,F82 lib）と固有の語の検査（python3 .github/scripts/proper_term_check.py）が通る。固有の語の検査が「語の一覧が無いため飛ばした」と出たときは、通ったと扱わず Pull Request の本文にそう書く
• bash -n etc/devbase-completion.bash と zsh -n etc/_devbase が通り、devbase-base:latest の shellcheck（-s bash）の etc/devbase-completion.bash への指摘が変更の前より増えない
• 実装の中で devbase up を打たず（作業用のプロジェクトを含む）、base イメージを建て直していない

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

進行

モード: —

• 要求と受け入れ条件 — 2026-10-15 13:24
• 作業場所の用意 — 2026-10-15 17:48
• 設計 — 2026-10-15 13:29
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-15 17:48
• 実装 — 2026-10-15 18:07
• 構造改善 — 2026-10-15 18:28
• 実装レビュー — 2026-10-15 18:46
• 完了判定 — 2026-10-15 18:21
• Pull Request — 2026-10-15 18:24
• 確定仕様化 — 2026-10-15 22:22
• 後片付け
• 配布 — 2026-10-15 23:34
• 体裁レビュー
• リリース後テスト — 2026-10-15 22:24
• 振り返り — 2026-10-15 22:33
• 棚卸し — 2026-10-15 22:35

振り返り: #495 (comment)