前回の記事「AIに開発を任せるために「チーム構造」を設計した話」の続き。設計思想ではなく、実運用で出た問題と改善の記録。
- 設計段階では見えなかった盲点が、実タスク（Migration/UI Replica）で噴出した
- 根本原因は「仕様の前渡し不足・計測なしの実装・目視頼みの検証」の3系統
- 振り返りから5つの仕組みを追加し、同じ失敗を止めた
設計段階ではよく見えていた仕組みも、実際のタスクに当てると盲点が出てくる。 dev-agent-team を Migration/UI Replica タスク（既存アプリを別スタックに移植しつつUIを完全再現する作業）で 使ったところ、想定外の問題が複数出てきた。
その振り返りをもとに5つの仕組みを追加した。この記事はその記録だ。
1. 何をやろうとしたか
タスクの概要は「既存アプリのUIを別スタックに完全移植する」というもの。 見た目・挙動・状態管理まで含めて既存アプリと一致させることが要件だった。
一見シンプルに見えるが、このタイプのタスクには独特の難しさがある。 「既存と同じにする」という要件は、正解が数値で定義されていない。 デザインカンプではなく「動いているアプリ」が仕様書になるため、 実装者がどこまで計測して合わせるかで品質が大きく変わる。
2. 出てきた問題（振り返り）
実際に発生した問題を具体的に書く。
bar幅が8往復した
「ここのbarをもう少し太めに」という指示に対して、推測の値で実装した。 「太すぎる、もう少し細く」「まだ太い」という往復が8回続いた。
原因は単純で、「太め」という形容詞を数値に変換せずに実装したこと。 現在の値を計測して「現在16px、太めにするなら何px想定ですか?」と 先に確認すれば1往復で終わる話だった。
色が仕様書と実際で違った
仕様書には #838383 と書いてあったが、
実際に既存アプリで getComputedStyle を使って計測すると #a9a9a9 だった。
仕様書が古く、現実のアプリと乖離していた。 「ドキュメントを信じて実装する」ではなく「実際に動いているアプリを計測して実装する」 が必要だった。
LocalStorageの型がずれた
source側のLocalStorageに何が入っているかを確認せず、 「空文字が入っているだろう」という仮定で実装した。 実際には別の型が入っており、挙動が変わった。
これも計測すれば防げた。実際に動いているアプリで localStorage.getItem(key) を
叩けば1行で分かる話だった。
「実装したけど反映されてない」という誤判断
実装してbuildも通っているのに、目視で「変わっていない」と誤判断してさらに修正を重ねた。
後から getComputedStyle で計測すると、最初の実装で正しく変わっていた。
目視はキャッシュや環境差異の影響を受けやすい。 計測値を一次ソースにしない限り、「反映されているかどうか」は確認できない。
共通部品の挙動が違う
source側で使われている共通部品が、一見シンプルな表示部品に見えたが、
内部で useState の初期値が固定されていた。
この挙動を見落として移植したため、動的ケースで表示が変わった。
コードを読むだけでなく、実際にブラウザで操作して挙動を確認する必要があった。
3. 根本原因の整理
5つの問題を整理すると、3つのパターンに収まる。
- 依頼者の頭の中にある情報が渡っていない
「太め」「これに合わせて」という指示は、依頼者の意図する数値を含んでいない。 コードを読んでも分からない情報は、先に引き出しておかないと後から往復になる。 - 計測なしに実装している
sourceの実値をドキュメントや目視で補完していた。 ドキュメントは古くなる。目視はブレる。数値は計測から取るしかない。 - 検証が目視頼り
「変わったかどうか」を目視で判断していた。 キャッシュ・環境差異・主観的な解釈が混入する。計測値で判断する必要がある。
4. 追加した仕組み
(1) migration-spec-capture スキル
source側の実値をPlaywright MCPで機械計測するスキルを追加した。 計測対象は色・px・DOM構造・LocalStorage実値・API shape・共通部品の動的挙動。
Phase 2でsourceを計測し、得られた数値をPhase 4の実装計画とPhase 5の検証ベースラインに使う。 「ドキュメントの値」ではなく「実際に動いているアプリの値」が起点になる。
(2) browser-verification スキル
UI変更時の検証を6ステップで標準化した。
- 修正する
- rebuild完了を確認する
- cacheBust付きでリロードする
getComputedStyle/getBoundingClientRectで計測する- スクリーンショットを撮る
- 計測値と画像で報告する
「目視で確認しました」は完了扱いにしない、というルールをセーフガードとして明記した。 「実装したのに反映されてない」という誤判断はこれで防げる。
(3) 数値化プロトコル（product-interpreterエージェントに追加）
「太い」「細い」「濃い」等の形容詞を受け取ったとき、推測で実装しないルールを追加した。 必ず計測してから逆質問する。
「現在のbar幅は16pxです。太めにするとしたら何px想定ですか? 20px前後でしょうか?」
bar幅8往復の直接の答えはこれだった。 往復するのは、最初に数値を合意していないからだ。
(4) タスク種別サブフロー
feature-development.md のワークフローに4種別を追加した。
- 通常（デフォルト）
- Migration（別スタックへの移植）
- UI Replica（UI完全再現）
- Hotfix（緊急修正）
Migration / UI Replica 種別では、Phase 0/1/2/4/5に追加チェックリストが発火する。 Phase 2でsource計測を必須にする、Phase 4でゴール定義（「完全px一致」か「UX同等」か）を 人間に承認してもらう、Phase 5で検証ループを必須にする、といった内容だ。
タスク種別は人間が宣言する。自動判定はしない。 開始時に「これはUI Replicaタスクです」と明示することで、強化版フローが起動する設計だ。
(5) Issue Intakeテンプレート
依頼を受けるときに「依頼者しか知らない情報」を前出しさせるためのテンプレートを追加した。 テンプレートの冒頭にはこう書いてある。
コードを読めば分かる情報は省略OK。依頼者の頭の中にしかない情報に集中してください。
必須項目は3つ。
- 背景・目的（なぜこの変更が必要か）
- スコープ（どこまでやるか／やらないか）
- 受け入れ基準（何が満たされれば完了か）
migration-spec-capture が「コードを読めば分かる情報の機械的なDiscovery」を担当するのに対して、 このテンプレートは「依頼者の頭の中にしかない情報の前出し」を担当する。役割が違う。
5. 合わせて直した件: インストールバグ
今回の改善作業と並行して、別の問題も発覚した。
install.sh が /adopt-project しかシンボリックリンクしていなかった。
つまり、/run-feature-workflow 等が実際にはどのプロジェクトからも呼べない状態だった。
全6コマンドをグローバルにインストールするよう修正した。
既存ユーザーは以下で更新できる。
cd ~/.claude/dev-agent-team
git pull
./install.sh6. まとめ
今回出てきた問題は「設計の失敗」ではなかった。 Migration/UI Replicaという特定のタスク種別を実際に使って初めて分かる盲点だった。
「型を作ること」と「型を使って失敗して改善すること」は別のフェーズだ。 最初の設計でカバーできるのはせいぜい「一般的なタスクの典型的な失敗」だけで、 特定の状況でどこが弱いかは、実際に使わないと分からない。
- 形容詞は数値に変換してから実装する
- sourceの実値はドキュメントではなく計測から取る
- 検証は目視ではなく計測値で完了を判断する
- 依頼者しか知らない情報は、実装前に引き出す
どれも「言われてみれば当たり前」の話だが、仕組みに組み込まないと毎回抜けていく。 dev-agent-teamはまだ実験段階で、これからも実運用を通じて書き換え続けるつもりだ。
リポジトリはこちら: fecot/dev-agent-team