dev-agent-teamシリーズの3本目。 設計思想、 実運用で出た失敗と対処に続いて、 今回は「案件固有の失敗から、一般化できる学びだけを抜き出して本体に取り込んだ話」。
この記事の要点
  • 振り返りの学びには「その案件限定」と「どの案件でも効く」の2種類がある
  • 一般化できるものだけ本体へ、案件固有のものは固有の場所に閉じる
  • 視覚仕様ゲート・受け入れ基準の明示承認・Known Risks蓄積を本体に取り込んだ

前回、Migration/UI Replicaタスクで出た失敗をもとに、Migration専用のサブフローを追加した。 その後も振り返りを続けると、「これ、Migrationに限った話じゃないよな」という学びが いくつか出てきた。

今回の改善（PR #15）の本題は、 その学びを「一般化」してワークフロー本体に取り込むか、固有の場所に閉じておくかの線引きだ。 機能を追加した話というより、判断の話に近い。

1. なぜ「一般化」を意識するのか

振り返りで出てくる学びには2種類ある。

前者を本体に入れると、関係ない案件にノイズとして降ってくる。 後者を固有の場所に閉じ込めると、次の案件でまた同じ学びをゼロから踏み直す。 だから振り返りのたびに「これはどっちだ?」を判定して、置き場所を分ける必要がある。

今回のフィードバックは AngularJS → React の書き換え案件から出たものだが、 その依存部分は意図的に切り離して、UI変更・開発プロセス全般に効く形に直してから取り込んだ。

2. 一般化して本体に取り込んだもの

(1) 視覚仕様レビューゲート（Phase 4 → 5）

UI（画面・コンポーネント・レイアウト・見た目）を伴う変更では、 実装に入る前に視覚仕様スケッチを作り、人間の合意を得てから次に進む—— というゲートをPhase 4と5の間に新設した。

手段は問わない。ASCIIワイヤーフレームでも、mockでも、既存画面に注釈をつけたスクショでもいい。 「何をどう見せるか」を実装前に視覚的にすり合わせられればよい。 

┌─────────────────────────────┐
│ [検索ボックス]        [絞込] │
├─────────────────────────────┤
│ 行1                         │
│ 行2                         │
└─────────────────────────────┘
実装前に合意する「視覚仕様スケッチ」の一例（配置だけでも十分）

表現するのは配置だけでなく、状態（通常 / hover / 空 / エラー / ローディング）や レスポンシブ時の振る舞いまで含める。 「コードを書いてから見た目をすり合わせると手戻りが大きい」—— これはMigrationに限らずUI変更全般に当てはまるので、本体のPhaseに組み込んだ。

(2) 受け入れ基準の「明示承認」をStop Conditionに

Phase 1で受け入れ基準（完了条件）を整理しても、それを列挙しただけでは次に進まない ようにした。人間が「これで進めてよい」と明示的に承認するまで停止する。

「確認事項がない」＝「承認済み」ではない。

ここが今回の地味だが効く変更だ。AIは「質問がないから合意できている」と解釈しがちだが、 実際には「まだ誰も読んでいないだけ」のことが多い。 明示承認を要求することで、認識ズレを実装前に炙り出せる。

(3) Known Risksの蓄積運用（Phase 8）

リリースチェックのPhase 8に振り返りステップを追加した。 「次回また踏みそうな罠」を1行ずつ抽出し、対象リポジトリのProject Rulesの Known Risks への追記を人間に提案する。

ポイントは蓄積する対象を絞ること。環境固有のビルド/キャッシュ挙動や、 見落としやすい前提・依存のように「次の別案件でも踏みそうなもの」だけを残す。 その案件限りで再発しない事象は書かない（ノイズになる）。

そしてこの追記は あくまで「提案」止まりにしてある。 Project Rulesは対象リポジトリの所有物なので、AIが勝手に書き換えない。 追記するかどうかは人間が判断する。同じ罠を毎回踏むのを止めるための仕組みであって、 AIが勝手にルールを増やすための仕組みではない。

(4) タスク粒度の指針

タスク追跡の粒度はPhase単位までとし、Phase内の細かい実装ステップは 個別タスク化せず、計画書（Phase 4）と実装ログ（Phase 5）で管理する方針を明文化した。

sub-taskを作りすぎると、追跡コストが本質的な作業を上回る。 「全部タスクにすれば管理できている気になる」という罠への対策だ。

3. Migration側で補強したもの

一般化はできないが、前回のMigrationサブフローに足りなかった点も2つ補強した。

全画面スクショ＋可視要素インベントリを必須化

source側を計測するとき、個別要素の計測に入る前に まず画面全体を実機スクショで撮り、見えている要素を棚卸しするようにした。

前回、コードや要件から拾った要素「だけ」を計測していたため、 画面には存在するのにコードから辿れない要素（一覧の補助グラフ、状態バッジ、フッタなど）を 丸ごと見落とすリスクがあった。「コードに無かったから作らなかった」を防ぐには、 実機の見た目から要素を洗い出すしかない。

キャッシュバイパスを no-cache → no-store に

browser-verification の検証ループで注入するヘッダを Cache-Control: no-cache から no-store に強化した。

no-cache は「再検証してから使う」だが、no-store は 「そもそもキャッシュに保存させない」。古いbundleを掴む事故をより確実に防げる。 「コードを直したのに反映されない」の体感の多くはキャッシュ起因なので、 目視で悩む前に定型手順として通す。

4. 意図的に「入れなかった」もの

今回いちばん大事な判断はここだ。同じ振り返りから出たのに、 本体には取り込まなかったものがある。

これらは AngularJS → React というその案件にしか効かない。 汎用リポジトリに入れても他案件では使えず、ノイズになるだけだ。 だから本体には入れず、案件側のProject Rulesに閉じる。

「振り返りで出た学びを全部ルール化する」のは一見丁寧に見えるが、 実際には使えないルールでワークフローを太らせるだけになる。 一般化できるものとできないものを分けて、置き場所を変えるのが正しい。

5. まとめ

今回は新しい大きな仕組みを足したというより、 「失敗から得た学びを、どの粒度で、どこに置くか」を判断した記録だ。

特定案件の振り返りは、放っておくと「その案件専用のメモ」で終わる。 そこから一般化できる本質を抜き出して仕組みに還元できると、 次の別案件でも効くようになる。逆に何でも一般化しようとすると、 使えないルールで重くなる。この線引きのセンスが、型を育てるうえで効いてくると感じている。

リポジトリはこちら: fecot/dev-agent-team