design: 入出力の契約を、既存のコマンドの引数定義と呼び出し経路に突き合わせる対を足す

[takemi-ohama]

何が起きたか

devbasex/devbase#183（設計 PR、2026-09-15）はクロスレビューが収束するまで 7 ラウンドかかり、指摘は 31 件だった。そのうち少なくとも 9 件は、設計文書の契約が既存のコードの形と食い違っているという指摘で、どれも設計を書く時点でコードを読めば分かった。

指摘の中身	読めば分かった場所
env get には -p が無い / env list の -p は意味が違う	cli.py の引数定義
案内したオプション名が --exclude-projects（実際は単数形）	cli.py の引数定義
子プロセスの env init は cwd=$DEVBASE_ROOT で起動する	_ensure_env_files
scale は _run_deploy_pipeline を通らない	cmd_scale
cmd_up は _run_pre_up_checks → スナップショット → 起動の順で、検査の位置によって副作用が先に起きる	cmd_up
dispatch 前の注入が実行時のディレクトリで行われ、切替元のグループへ要求が出る	cli._load_secret_env
同期済みハッシュの控えが 1 ファイルでグループをまたぐ	SourcesManager
ラッパーがプロジェクトの env を source するため、例に挙げた食い違いが起きない	bin/devbase
export / import は既定で全プロジェクトを扱う	cmd_env_export / import_bundle

design の「進む前に突き合わせる対」は同じ文書の中だけで確かめられるものに限っており、外部を要するものはレビューが拾う前提になっている。その結果、レビューのラウンドがコードの読み合わせに使われた。

提案

「呼び出される約束を変える」領域に当たるときは、入出力の契約の表を書いた後に、次の 2 つを突き合わせる手順を足す。

1. 表に書いたコマンド・オプションを、引数を定義している場所と 1 行ずつ照合する（実在するか、名前と意味が同じか）
2. 振る舞いを変える入口ごとに、そこへ至る呼び出し経路（別のコマンドからの経路、子プロセス、実行時のディレクトリ）を列挙し、処理の流れの図に現れているかを見る

関連

• 機密ストアのチーム共通と個人単位の置き場を、アカウントグループ（nyle / with / kkg）ごとに分ける devbase#182（振り返りのコメント）
• 根本原因の親 issue: design の突き合わせを文書の中に限る前提をやめ、実物へ当てる対を設計の段に置く #733（design の突き合わせを文書の中に限る前提をやめ、実物へ当てる対を設計の段に置く）
• implementation-plan / plan-to-spec / requirements-design / design: 雛形と構造の検査を doc-check の呼び出しにする #872（閉じている）— 文書の検査をスクリプトの呼び出しにした課題。design-check.py pairs は入っておらず、突き合わせる対は design/references/design-template.md の「進む前に突き合わせる対」に本文の規約として残る。この課題は design の突き合わせを文書の中に限る前提をやめ、実物へ当てる対を設計の段に置く #733 と一緒に直す