AI と協業して開発していると、「何を、どこに記録すべきか」を、改めて考えるようになりました。issue、PR、ADR、仕様書、コメント── 記録の置き場所はいろいろあります。今回は、AI 時代に、記録をどう残すか、考えてみます。
- コードと PR を見れば、たいてい分かる
- 残らないのは「なぜ」
- 時間軸で、記録を分ける
- issue は更新しない、追加情報は PR やコメント
- 一時的な Spec は、PR に書く
- SDD や AI-DLC のドキュメントは、どうするか
- 重厚な手法の、規模とのミスマッチ
- 概要は、オンデマンドで生成する
- 「なぜ」も、起点を渡せば AI が書く
- PR テンプレート
- 設計してから作るか、しながら作るか
- まとめ
コードと PR を見れば、たいてい分かる
まず、当たり前のことから。「今どうなっているか」は、コードを見れば分かります。「今回何を変えたか」は、PR を見れば分かる。
だから、別途、仕様書を作って「現在の状態」を書いても、それはコードと重複します。そして、仕様書は、メンテされなくなりがちです。コードは変わったのに、仕様書は古いまま。メンテされない仕様書は、コードと乖離して、かえって誤解を生む。「ないより悪い」状態になることもあります。
「現在の状態」を知りたいなら、コードを読む。「変更の内容」を知りたいなら、PR を読む。これが、一番確実です。記録を別に作るより、コードと PR を、信頼できる状態に保つ。
残らないのは「なぜ」
ただ、コードにも PR の差分にも、残らないものがあります。「なぜ、そうしたか」です。
「なぜ、この技術を選んだのか」「なぜ、この設計にしたのか」「検討したけれど、却下した案は何か」── これらは、コードを見ても分かりません。コードは「どうなっているか」を示しますが、「なぜそうなのか」は語らない。
「なぜ」を知らない AI は、勝手に「もっと良い方法がある」と、変えてしまうことがあります。「なぜ、この技術を選んだか」を知らなければ、別の技術に変える PR を出すかもしれない。「なぜ」が記録されていれば、それを踏まえて動ける。
この「なぜ」を残すのが、ADR(Architecture Decision Record)です。アーキテクチャの決定について、背景、理由、却下した代替案を記録する。一度書いたら、原則として書き換えず、決定が変わったら新しい記録を追加する。
時間軸で、記録を分ける
ここで、一つの整理が見えてきます。記録は、時間軸で分ける。
- コード: 現在の状態
- issue: 起点(課題が発生したときの前提)
- PR: 変更の記録(変更したときの内容・理由)
- ADR: 大きな決定の記録(決定したときの理由・却下案)
そして、コード以外は、すべて「その時点の記録」で、後から書き換えない。issue は、課題が発生したときの前提。PR は、変更したときの記録。ADR は、決定したときの記録。それぞれが、時系列に並ぶ。
後から書き換えないのが、ポイントです。書き換えると、「いつの時点の情報か」が、分からなくなる。書き換えずに積み重ねるから、時間軸がきれいに残る。
issue は更新しない、追加情報は PR やコメント
この「時間軸」の考え方は、実践的な判断につながります。
例えば、自分や PM、他の人が昔に作った issue を、更新するか。雑に書かれた issue だと、後から「もっと詳しく書こう」と、更新したくなります。
でも、時間軸で考えると、本体は更新しない方がいい。issue は、作成したときの前提です。後から本体を書き換えると、「作成時の前提」と「今の補足」が混ざって、いつの情報か分からなくなる。
代わりに、追加情報は、PR か、issue のコメントに書く。issue の本体は、作成時のまま。でも、コメントなら、時系列で積まれるので、時間軸は保たれます。PR も、変更時点の記録として残る。
これは、ADR の考え方と同じです。ADR も、元を書き換えず、新しい記録を追加する。本体は書き換えず、追記で積み重ねる。記録を「その時点のもの」として残し、時系列を保存する。
一時的な Spec は、PR に書く
AI のワークフローに流すには、「何を作るか」を伝える必要があります。仕様(Spec)です。「これを作って」と、AI に渡す設計図。
でも、この Spec を、別ファイルで残すと、メンテされなくなります。実装が終われば、Spec は役目を終える。残しても、コードと乖離していく。
一つの落としどころは、一時的な Spec は、PR に書くことです。「何を、なぜ、こう作ったか」を、PR の説明に書く。レビューで使えるし、マージ後も記録として残る。別途メンテする必要もない。経緯を知らないメンバーが見ても、PR を読めば、何をしたか分かる。
別ファイルの仕様書を作って維持するより、PR に書いて、コードと一緒に残す。これが、メンテの手間を増やさず、記録を残す方法です。
SDD や AI-DLC のドキュメントは、どうするか
ここで、spec-driven development(SDD)や、AI-DLC のような手法に触れておきます。cc-sdd や GitHub Spec Kit は、仕様(spec)や設計(plan)、タスク分解(tasks)のドキュメントを生成します。AWS の AI-DLC に至っては、要件、ユーザーストーリー、アーキテクチャ、テストまで、開発ライフサイクル全体の成果物を、大量に生成します。「ドキュメントは残さない」という、ここまでの話と、矛盾するように見えるかもしれません。
でも、これらのドキュメントは、実装するための、一時的な設計図と捉えられます。実装の前に「何を作るか」を AI に伝えるために使う。そして、レビューにも役立ちます。「何を作ろうとして、どう作ったか、なぜそうしたか」が分かると、レビュワーの認知負荷が下がる。
だとすれば、これらの要点── 「なぜ」「何を」、そして「どう」の概要── を、PR か ADR に残すのが良さそうです。「どう」は、詳細な実装はコードにあるので、方針の概要だけで十分。概要があると、レビュワーが全体像を掴んでから、コードを読める。全部を確認するより、認知負荷が減ります。PR に書けば、レビューで使えるし、変更時点の記録として残る。別ファイルでメンテする必要もありません。
ただ、AI-DLC のように大量に生成されると、扱いに注意が要ります。全部を、最後にまとめてレビューするのは、しんどい。そして、実装後も全部を維持すると、コードと乖離した、大量の「メンテされない仕様書」が残ります。
ここで、時間軸の考え方が効きます。膨大なドキュメントは、生成されたその時点で、段階ごとに確認する。AI-DLC が、各ステージで人間の承認を挟む(Human-in-the-Loop)のは、この考え方に近い。要件ができたら要件を、設計ができたら設計を、その時点で見る。最後にまとめて見るのではない。そして、実装後に残すのは、「なぜ」と要点を、PR か ADR に抽出したものだけ。大量のドキュメント本体は、コードに真実を譲る。
重厚な手法の、規模とのミスマッチ
ただし、AI-DLC のような重厚な手法には、規模とのミスマッチもあります。
小さい改修には、重すぎる。typo、アラート対応、バグ修正、軽い改修に、要件・設計・承認のステップを踏むのは、オーバーヘッドが大きい。確認の手間が、改修の規模に、見合わない。
大きい改修だと、別の問題が出ます。確認するドキュメントが膨大になるうえ、流れがウォーターフォール的(要件 → 設計 → 実装、と順に進む)なので、後から問題に気付くと、前の工程に戻ることになる。ウォーターフォールでも、タスクは分割しますが、工程をまたいで戻るときの、確認のやり直しが、しんどい。差分だけ見直せれば、まだ良い方で、全体を見直すとなると、相当しんどい。これは、ウォーターフォールが昔から抱える問題が、そのまま出ているとも言えます。
自分は、AI 開発は、アジャイルの方が向いていると思います。まず作ってみる。動かして、判断する。ダメなら、捨てて作り直す。
AI で、作るコストが下がりました。だから、「まず作ってみる」のが、安い。そして、捨てるのも、安い(また作ればいい)。設計を完璧に固めてから作るより、作りながら固める方が、AI とは相性が良い。ウォーターフォール的に設計を全部固めてから進めると、後から問題に気付いたときの手戻りが大きい。特に AI は大量に生成するので、手戻りの量も大きくなる。それより、小さく作って、動かして、ダメなら捨てる。この回転を速くする方が、AI の「作るのが速い」という強みを、活かせます。
もちろん、複雑で、意図がずれると困るものは、ある程度設計を固めてから。でも、基本は、まず作ってみる、ダメなら捨てる。手法の重さは、タスクの規模に合わせる。AI で「作る・捨てる」が安くなったぶん、アジャイルの回転が、より回しやすくなりました。
概要は、オンデマンドで生成する
「システム全体の概要を、把握したい」というときもあります。大きなコードベースだと、全部を読むのは大変です。
ここで、別途「概要ドキュメント」を作って維持すると、また、メンテの問題が出ます。コードが変わるたびに、概要を更新するのは、現実的ではありません。
AI 時代らしい方法は、必要なときに、AI に生成させることです。「このコードの概要を、まとめて」と頼めば、その場で生成してくれる。コードが唯一の真実で、概要はオンデマンド。これなら、メンテされないドキュメントが、残りません。
ただし、AI が生成できるのは「何を、どうしているか」までです。「なぜ」は、コードにないので、生成できない。だから、「なぜ」だけは、ADR や PR に、残しておく。
「なぜ」も、起点を渡せば AI が書く
「なぜは、コードにないから、人間が書く」と思うかもしれません。でも、実際には、もっと楽になっています。
タスクを始めるとき、「なぜ」を、すでに AI に渡していることが多い。「こういう背景で、これを作りたい」と会話で伝える。あるいは、issue の URL を渡す。すると、AI はその文脈を踏まえて動くし、PR の「なぜ」も、AI が書いてくれます。
特に、PM が作った issue は、背景(なぜ)や受け入れ条件が、しっかり書かれていることが多い。その issue の URL を渡せば、AI が読んで、PR の Why に反映してくれる。Why には、issue 番号だけ書けば十分です。背景は issue にあるので、二重に書かない。
これは、調査でも同じです。例えば、Sentry のエラーの URL を渡せば、AI がそれを調べて、原因を探ってくれる。人間が、エラーの内容を説明する必要すら、ないことがあります。
つまり、人間の役割は、「なぜ」をゼロから書くことより、正しい起点(issue や Sentry の URL)を渡すこと、そして、AI が書いた「なぜ」が正しいか、確認することに移っています。書くのは AI、起点を選ぶ・確認するのは人間。ここでも、機械的な作業は AI、判断は人間、という分担です。
PR テンプレート
PR に「なぜ・何を・動作確認」を書く、と言いましたが、毎回ゼロから書くのは大変です。AI に下書きさせるにも、書く項目が定まっていた方がいい。正直、PR テンプレートは、これまで形骸化しがちでした。でも、AI と向き合う中で、その重要性を再認識しました。そこで、AI が書きやすく、レビューの負荷が減るように、見直しました。
# Why(なぜ) ★必須
<!-- issue番号(例: #1234)。issueが薄い/ない/前提が変わった場合は、背景・課題を補足 -->
# What(何を) ★必須
<!-- 変更の概要 -->
<!-- 下記は残してください -->
@coderabbitai summary
# 動作確認 ★必須
<!-- 確認したシナリオ、エビデンス -->
* [ ]
# How(どう) ◎推奨
<!-- 実装方針。変更が大きいとき -->
# 影響範囲 ◎推奨
<!-- 影響するモジュール、注意点 -->
# レビューで見てほしい点 ◎推奨
<!-- 自信のない箇所 -->
# 検討した代替案
<!-- 却下した案。大きな決定は ADR へ -->
# 残課題・TODO
<!-- 別タスクに積んだもの -->
Why を、先頭に置いています。レビュワーは、「なぜこの変更が必要か」を理解してから、「何を変えたか」を読む方が、判断しやすい。課題 → 解決、の流れです。Why は、issue 番号だけで十分なことが多いですが、issue が薄い・ない・前提が変わった場合は、背景を補足する。
What には、@coderabbitai summary を置いています。AI レビューツールが、変更の要約を自動で挿入してくれる。「何を変えたか」の概要は、AI に任せる。
How は、実装方針(概要)。詳細な実装は、コードにあります。概要があると、レビュワーが全体像を掴んでから、コードを読める。
必須・推奨で、変更の規模に応じて使い分けます。小さな修正なら、必須だけ。大きな変更なら、推奨も埋める。一律に全部埋めさせると、小さな PR で負担になります。「検討した代替案」「残課題・TODO」は、あれば書く程度で、強調はしていません。
これらの項目も、起点(issue の URL など)を渡しておけば、ほとんど AI が下書きしてくれます。人間は、書かれた内容を確認する。AI と協業するようになって、テンプレートの価値が、上がった気がします。
設計してから作るか、しながら作るか
ここまでの話を、開発の進め方として整理すると、二つのスタイルになります。
設計してから作る: 仕様を固めてから、実装する。ウォーターフォール的。SDD や AI-DLC は、この支援。
設計しながら作る: 作りながら、設計を固める。アジャイル的。まず作って、見ながら調整する。
先に書いた通り、AI 開発は、基本はアジャイル寄りが向いていると思いますが、複雑で意図がずれると困るものは、設計を固めてから。タスクの性質で、使い分けることになります。
どちらにしても、決まったこと(なぜ・何を)は、PR や ADR に残す。設計の進め方は選べますが、記録の残し方は、変わりません。
まとめ
AI 時代の記録の残し方を、考えてみました。
- 「今どうなっているか」はコード、「何を変えたか」は PR を見れば分かる
- 別ファイルの仕様書は、メンテされず、コードと乖離する
- 残らないのは「なぜ」。これを ADR や PR に残す
- 記録は、時間軸で分ける。すべて「その時点の記録」で、後から書き換えない
- issue の本体は更新せず、追加情報は PR か、issue のコメントに書く
- 一時的な Spec は、PR に書く(メンテ不要、レビューで使える)
- SDD や AI-DLC のドキュメントは、実装前の設計図。生成時点で段階ごとに確認し、なぜ・何を・どうの概要を PR/ADR に残す
- 重厚な手法は、小さい改修に重すぎ、大きい改修に手戻りが大きい。AI 開発はアジャイルが向く(まず作る、ダメなら捨てる)
- 概要は、AI にオンデマンドで生成させる
- 「なぜ」も、起点(issue や Sentry の URL)を渡せば、AI が書く。人間は、正しい起点を渡し、確認する
- PR テンプレートは、AI と向き合う中で、重要性を再認識した
記録を、あちこちに二重に持たない。コードが唯一の真実で、変更の経緯は PR、大きな決定は ADR。「なぜ」は、起点を渡せば AI が書き、人間が確認する。情報を、適切な場所に一つ、時系列で。これも、いつものエンジニアリングの延長です。AI で記録を生成・参照しやすくなったぶん、「何を残し、何を渡し、何を確認するか」の判断が、より大事になります。
