はじめに

ここ半年ほど、Claude CodeでのAI駆動開発を業務で実際に運用してきました。

その中で変更管理の仕組みを導入してしてみたところ、思った以上によかったので記事にまとめてみました。
「なぜこの実装になったのか」「何を確認してからマージしたのか」が後から追えるようになりましたし、修正方針を考える際の判断基準も可視化されたのが特によかったと感じています。

具体的にどういう仕組みで実働しているか、やってみてどうだったかを書いていきます。

整備した仕組み：3 ファイルによる変更台帳

チケット（Issue）単位でディレクトリを切り、3 つのファイルをセットで置く運用に落ち着きました。

tickets/{issue-key}/
├── impact.md    # 着手前の影響マップ
├── decisions.md # 実装中の判断記録
└── closure.md   # レビュー依頼前のクローズ前チェック

ファイル数は最小限にしました。「書くものが多すぎると誰も書かなくなる」というのは身をもって知っていたので、それぞれ役割を 1 つに絞るようにしています。

impact.md — 着手前の影響マップ

コードに触る前に書くファイルです。「何を変えるか・どこに波及するか」を表形式で列挙するだけのシンプルな構成にしました。

解消した行もそのまま残して右端に状態列（解消 / 見送り）を置きます。
削除すると「一度は考えた」という事実が消えてしまうので。

役割は 2 つあって、1 つは着手前のスコープ合意の証跡、もう 1 つは後述するクローズ前チェックのベースラインになることです。

decisions.md — 実装中の判断記録

実装を進めていると、必ずどこかで「A か B か」という判断分岐が出てきます。
そこで選んだ判断・論点・根拠を残すのがこのファイルです。

各論点に「決着 / 持ち越し」の状態欄を付けておくと、クローズ前チェックで「全件決着しているか」を機械的に確認できます。

closure.md — レビュー依頼前のクローズ前チェック

レビューを依頼する直前に作るファイルです。影響マップの全行が「解消」か「見送り（後続 Issue 番号付き）」のどちらかになっていることを確認します（順方向チェック）。

ここでもう一手間かけるのが逆方向検査です。

git diff --name-only $(git merge-base <マージ先ブランチ> HEAD)..HEAD

で実際に変更したファイル一覧を取り出し、影響マップと突き合わせます。マップに載っていない変更ファイルがあれば、「着手前に書いていなかった変更が混じっている」と判定し、マップに追記してスコープを再確認します。

順方向だけでは「書き忘れた変更」を検出できません。逆方向検査がその穴を塞ぎます。

AI 駆動開発との組み合わせ

この 3 ファイルは、AI エージェントが書く運用にしています。
フォーマットが決まっているので、担当者によるばらつきなく記録が残ります。

ただしスコープの合意と各フェーズの承認は人間が行います。
AI に着手させる前に impact.md を見てスコープを確認し、レビュー依頼前に closure.md を確認することで人間が行う作業とAIが行う作業を分別しています。

このプロセスの背景

開発フロー全体の骨格は、Amazon が 2024〜2025 年に公開した AI 駆動開発 IDE「Kiro」の仕様駆動開発（SDD: Spec-Driven Development）をベースにしています。
仕様を先に確定してから実装するというアプローチで、「後から仕様が変わる」「実装が先行して設計がついてこない」という状況を防ぐことを目指しています。

ただ、Kiro SDD は「仕様 → 実装」のフロー管理が核心で、変更の追跡・決着確認まで体系化しているわけではありません。
今回整備した 3 ファイルの変更台帳フローは、実際にプロジェクトで運用するなかで出てきた課題に合わせて独自に考えた拡張になっています。

運用してみて

実際に使い続けてみると、最初に想定していた以上の効果がありました。

設計判断の理由が decisions.md に残るため、「なぜこの実装になったか」が後から追えるようになりました
修正方針を考える際も、判断基準や選択肢が台帳に可視化されているため、根拠を持って議論できるようになりました
レビュアーも closure.md を見れば「何を確認してレビュー依頼しているか」が一目でわかります
変更の経緯・判断・確認結果がチケット単位でリポジトリ内に残り続けるようになり、「なんでこうなったんだっけ」が調べればわかる状態になりました

直近で出てきた課題

実際にチーム内で議論していく中で、変更管理を実施する前に会議などで決めた仕様がどこにも残っておらず、変更管理を実施する際のインプットとして投げることができなければ反映されないという課題も出てきました。

その点は別途会議の議事録などから必要な部分は都度記載するなどの運用をすることで改善をしていく予定です。

おわりに

アウトプットやフローを定型化することで、担当者依存を減らしながら変更の追跡可能性を確保できたのは、とても意味のある事だったと思います。
もちろん完璧ではないので、これからも実際に運用しながら改善していくことになると思います。

「記録が残らないから後で困る」という経験をした人には、何かしら参考になる部分があれば嬉しいです。

最後まで読んでいただきありがとうございました。