ドキュメント駆動で手戻りを減らす — 実装と同時にmapping/logを更新する

なぜ書いたか

レガシー移行では、コードそのものよりも「どこまで同等性を確認したか」が迷子になりやすいです。

画面の一部を移し、ビルドも通り、見た目もそれらしくなる。そこだけを見ると完了に見えます。でも実際には、後続のレビューで確認する差分、今回は見送った導線、次のスライスで戻ってくるべき処理が残っています。ここを曖昧にしたまま翌日に進むと、「これは意図的に残したのか、単に忘れたのか」をもう一度掘り返すことになります。

私も最初は、実装が終わってから移行マッピングや作業ログを整えればよいと思っていました。けれど実装後にまとめて書こうとすると、判断した瞬間の温度が落ちます。なぜその分岐を残したのか、なぜそのボタンを未対応表示にしたのか、レビュー未完了なのにどこまで進めてよいのか。そういう小さな判断が抜けていきます。

そこで運用を変えました。実装が終わってから書くのではなく、実装と同じセッションの中で書く。今回は、その切り替えで手戻りが減った話です。

やったこと

ルールはシンプルにしました。

1. 着手前に、今回触る範囲を移行マッピングへ置く
2. 実装中に判断したことを、作業ログへその場で書く
3. スライスを閉じる前に、完了分と残差分を更新する

移行マッピングは全体地図です。画面単位、導線単位、未移行のまとまり単位で、「今どこにいるか」を見るためのものです。

作業ログは、その日の判断の証跡です。どの根拠を見たか、何を実装対象に入れたか、何を対象外にしたか、レビューで何が残ったかを書く場所です。

この2つを混ぜないようにしたのが効きました。全体地図に細かい実装判断を書きすぎると読みにくくなります。一方で、作業ログだけに残すと、次に全体を眺めたときに未完了の場所が見えません。なので、全体地図には「状態」を残し、作業ログには「理由」を残す、という分担にしました。

たとえば、ある画面でフッター導線だけを先に実装した日がありました。登録系の導線はつなぐ。一方で、帳票や一括処理のように影響範囲が広いものは、無理に作り込まず未対応表示へ寄せる。さらにレビュー担当AIが利用上限で止まり、その時点ではレビュー完了と呼べない状態でした。

このとき、コードだけを見ると「ボタンが増えた」「ビルドが通った」で終わりに見えます。でも作業ログには、次のような粒度で残しました。

- 今回完了したこと:
  - 主要な登録導線を接続した
  - 未移行の操作は未対応表示にそろえた
- 今回あえて残したこと:
  - 帳票系と一括処理の本実装
  - レビュー担当AIによる再確認
- クローズ判断:
  - レビュー未完了のため、完了扱いにはしない

これはコードの説明ではなく、次に作業する人への引き継ぎです。翌日見るべきなのは「どのボタンを押すと何が起きるか」だけではなく、「このスライスを閉じてよいのか」です。そこをログに残すようにしました。

何が変わったか

一番変わったのは、翌日の再開です。

以前は、再開するときにまず差分を読み直していました。どのファイルが変わったか、どの処理が増えたか、なぜこの分岐になっているのかをコードから逆算する時間がありました。これが地味に重いです。特にAIに実装させていると、変更量は速く増えるので、翌日には自分でも文脈を忘れています。

実装と同時にmapping/logを更新するようにしてからは、再開時の入口が変わりました。

• まず移行マッピングで、対象画面の状態を見る
• 次に作業ログで、その状態になった理由を見る
• 最後にコード差分で、実装がその判断と一致しているかを見る

この順番にすると、「コードを読んでから意図を推測する」時間が減ります。先に意図を読んで、その意図どおりにコードが変わっているかを見る。レビューの負荷もこちらの方が軽いです。

もう1つ効いたのは、未完了を未完了として残せるようになったことです。

移行作業では、部分的に正しい状態がよくあります。画面の主要導線は動いた。でもレビューは終わっていない。検索結果の表示は近づいた。でも名称解決の細部は後続確認が必要。こういう状態を「ほぼ完了」と呼ぶと、後で必ず痛みます。

そこで、作業ログの最後にクローズ判断を置きました。完了なら完了。レビュー未完了なら未完了。後続スライスへ送るなら、残差分として書く。単に進捗を書くのではなく、次に閉じてよいかを判断できる形で書くのがポイントでした。

わかったこと

ドキュメントは、あとで清書するものではなく、実装中の判断を固定するためのものだと考えるようになりました。

特にAI駆動開発では、実装速度が上がるぶん、判断の揮発も速くなります。AIは広い範囲を一気に触れますが、何を根拠に採用したか、何を後回しにしたかを毎回自然に残してくれるわけではありません。そこを人間があとで思い出して書く運用にすると、人間側がボトルネックになります。

なので、私はエージェントへの依頼に「実装して」だけではなく、「移行マッピングと作業ログも更新して」を含めるようにしました。AIAgentを使う開発Tipsとしては、Orchestrator側でドキュメント更新をスライスのDoD（Definition of Done）に含めるのがかなり効きます。ビルドが通ったか、レビューが終わったか、mapping/logに残差分が出ているか。この3つを並べると、作業の閉じ方がかなり安定します。

注意点もあります。ログを詳しく書きすぎると、今度は読むのがつらくなります。実装メモをすべて貼るのではなく、次回の判断に必要な粒度に絞る必要があります。

今のところ、残す価値が高いのはこの4つです。

• 今回の対象範囲
• 採用した判断と、その理由
• あえて残した差分
• 次回最初に確認する場所

逆に、単なる作業実況はあまり役に立ちません。「ファイルを開いた」「ビルドした」だけでは再開の助けになりにくい。読み返した人が、次に何を判断すればよいか分かる形にしておくのが大事でした。

次にやること / 未解決の問題

• 移行マッピングと作業ログの重複をどう扱うか
• スライス完了 / 一部完了 / 未決 / レビュー待ちの状態をテンプレート化すること

まだ難しいのは、移行マッピングと作業ログの重複です。同じことを2箇所に書くと、どちらが正なのか分からなくなります。ただ、片方だけに寄せると別の問題が出ます。移行マッピングだけでは判断理由が薄くなり、作業ログだけでは全体の残り具合が見えません。

今は、移行マッピングを「現在地」、作業ログを「そこに至った理由」として使い分けています。次はこの使い分けを、もう少し機械的に運用できる形へ寄せたいです。スライス完了、一部完了、未決、レビュー待ち、のような状態をテンプレート化しておくと、AIAgentが毎回同じ粒度で更新しやすくなります。