docs(issue139): PLAN49 devbase build <image> の要求仕様と設計

[takemi-ohama]

概要

devbase build <image> が位置引数を docker buildx build へそのまま渡して失敗する不具合 (#139) について、受け入れ条件と設計だけを確定させる PR です。実装は含めません。設計の誤りを実装後に直す費用を避けるため、設計を先にレビューへ通します。

関連 Issue

• fix: devbase build <image> が docker へ image 引数をそのまま渡して失敗する #139（この PR では閉じません。実装 PR で閉じます）
• fix: 新規アカウントグループの .claude.json が 0 バイトで作られ Claude Code が起動しない #136（ベースイメージ再ビルドが必要になり本不具合を踏んだ経緯）
• chore: CI が tests/ の pytest を実行していない #141 / fix: devbase build <image> が実在プロジェクト名と衝突して黙って別のイメージをビルドする #142（設計中に見つけた範囲外の課題として起票）

変更点

• issues/PLAN49_build-image-argument.md を追加（要求仕様 + 設計）
• .ndf/worktree.json を追加、.gitignore に .worktrees/ を登録（作業ツリー運用の宣言）

調査で確定したこと

issue #139 が「確認が要る」としていた 2 点を先に潰しました。

確認事項	結果
containers/ 配下が devbase-<name> 規約に従うか	10 件すべて従う。例外なし（compose.yml の image:、他 Dockerfile の FROM devbase-base:latest、snapshot/manager.py:34 の SNAPSHOT_IMAGE で確認）
Python 側 cmd_build(image=...) が到達不能か	到達可能。 devbase project build <image> / devbase container build <image> から届く。到達不能なのはトップレベル devbase build からの経路だけ

主な設計判断

単体ビルドの実装は Python 側へ寄せ、shell (bin/devbase) は振り分けだけを行う。

逆向き（Python が bash bin/devbase build <image> を呼ぶ）にすると、bin/devbase 先頭の name 解決を通ってしまい、devbase project build bi-tools が projects/bi-tools の compose ビルドへ黙って化けます（projects/bi-tools と containers/bi-tools が両方実在）。現在 project build の位置引数が name 解決の対象外であることで守られている挙動を、実装を寄せただけで壊すことになるため採りません。

タグは devbase-<image>:latest に統一し、docker buildx build --load へ揃える。

devbase project build base は現状 base:latest を作りますが、これは FROM devbase-base:latest から解決できず、ビルドした意味が失われます。リポジトリ内のどこからも参照されていない旧タグのため、移行措置は設けません。

動作確認

設計だけの PR のためコード変更はありません。設計の裏付けとして次を実行しています。

• docker / compose_with_secrets をスタブ化して bin/devbase build base --no-cache を実行し、docker buildx build --load -t devbase-base:latest <ROOT>/containers/base base --no-cache と PATH が 2 つになることを再現
• 同じ方法で devbase build bi-tools が name 解決に吸われ containers/bi-tools を一度もビルドしないことを確認（fix: devbase build <image> が実在プロジェクト名と衝突して黙って別のイメージをビルドする #142 として起票）
• containers/*/compose.yml と Dockerfile を走査し devbase- 以外のタグ参照が無いことを確認
• ローカルで ./bin/devbase --help が正常に動作する（コード変更なしのため未実施）
• CI が green である

スクリーンショット・ログ（任意）

$ devbase build base --no-cache   # docker / compose をスタブ化
DOCKER:buildx build --load -t devbase-base:latest <ROOT>/containers/base base --no-cache
                                                  ^^^^^^^^^^^^^^^^^^^^^^ ^^^^  PATH が 2 つ
COMPOSE:docker compose build dev base --no-cache
                                 ^^^^  compose にもサービス名として漏れる

$ devbase build bi-tools --no-cache
DOCKER:buildx build --load -t devbase-base:latest <ROOT>/containers/base --no-cache
COMPOSE:docker compose build dev --no-cache
Shell cwd was reset to <ROOT>      # projects/bi-tools へ cd し image 指定が消えている

補足

レビューでは特に次を見ていただきたいです。

1. 単体ビルドを Python へ寄せる判断（決定 1）。shell へ寄せる案を退けた理由が妥当か
2. devbase project build <image> のタグが <image>:latest → devbase-<image>:latest に変わることを、互換の断絶として扱わなくてよいか
3. 受け入れ条件 AC1〜AC11 で、この不具合の再発を止めるのに足りているか

[takemi-ohama]

🤖 cross-review | round 1 | codex | APPROVE

修正が必要な指摘はありません。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | APPROVE

PLAN49 の要求仕様と設計を確認しました。現状のコードベースの実態（maybe_cd_project による name 解決の優先ルールや、Python 側の cmd_build が抱えるタグ規約・ビルダの不一致）と完全に整合しており、提案されている解決策や受け入れ条件は妥当です。懸念点はなく、この設計のまま実装へ進んで問題ありません。