PR は問題なさそうなのに、どこか違和感があるとき
AI と一緒に数週間でもリリースを回していれば、この感覚にはもう覚えがあるはずです。
PR を開く。コードは十分きれいだ。命名も悪くない。テストもある。見た目には明らかな破綻はない。なのに、どこかがおかしい。
境界が少し曖昧なのかもしれない。contract が明文化されず、暗黙の了解のままなのかもしれない。正常系は押さえていても、肝心の業務ルールはまだ誰かの頭の中にしかないのかもしれない。致命的な 1 行を指させなくても、危うさだけははっきり伝わってくる。
それが、新しいレビューの問題です。
大半のチームは今も、AI 支援コーディングを古いワークフローに流し込んでいます。プロンプトを書き、diff を生成し、PR を開き、壊れた invariants や取りこぼした境界ケース、アーキテクチャの逸脱、見えないリスクをシニアエンジニアがコードを精査して拾う、という流れです。
そのモデルは、実装のほぼすべてを人間が自分で書いていた時代には筋が通っていました。けれど、モデルが 1 回で実装、最初のテストスイート、スキーマ、さらには contract のフレームワークまで生成できるなら、このやり方は一気に筋が悪くなります。
その時点で、シニアの注意力を注ぐ先として、1 行ずつのコードレビューはもう最もレバレッジの高い場所ではありません。
本当に問うべきことは、もはや「この関数はもっともらしく見えるか？」ではありません。
本当に問うべきは、「この関数が存在する前に、正しい振る舞いと境界、そして invariant を定義できていたか？」です。
これが、AI が引き起こすワークフローの反転です。コードレビューが消えるわけではありません。けれど重心は上流へ移る。AI 時代、コードレビューは仕様レビューになります。
なぜこの変化はこれほど別物に感じるのか
長いあいだ、多くのエンジニアリングチームは仕様を補助資料として扱ってきました。
本体はコードだった。doc comment はヒント。ADR は時間があれば読む補足コンテキスト。スキーマは「ただのバリデーション」。Gherkin ファイルは、誰かが更新を続けていれば便利、という程度の存在でした。
その序列が、いま崩れ始めています。
LLM が仕様から実装成果物をすばやく何度でも生成できるなら、仕様はもはや脇役ではありません。システムの残りすべてがそこから導かれる、起点そのものになります。
そうなると、ミスを最も安く捕まえられる場所も変わります。
仕様が曖昧なら、モデルは間違ったものを見事な構造で実装してしまいます。きれいなコードも、もっともらしいテストも、誤った安心感もまとめて渡してくる。どれだけ強いコードレビューでも、本当の問題を見落としえます。バグが構文にあるのではなく、意図にあるからです。
この瞬間が厄介で、しかも重要なのはそこです。AI は説得力のある出力を作ることを簡単にする。同時に、何を求めたのかを雑に定義することを、はるかに危険にします。
仕様が正確で、境界が明確で、テスト可能なら、すべてが楽になります。実装は楽になる。検証は楽になる。レビューは楽になる。CI は強くなる。
だから、人間のレビュー労力の最適な置き場所は、すべての分岐を手で監査することではなく、その分岐の振る舞いを最初に定める成果物を引き締めることへ移っているのです。
仕様は巨大な要件文書ではない
「仕様」と聞くと、多くの人は、誰も書きたがらず、6 週間後には誰も信用しない膨れ上がった文書を思い浮かべます。
ここで重要なのは、そんなものではありません。
実務的な AI 支援ワークフローにおいて、仕様とは、生成と enforcement に十分使える精度で意図した振る舞いを定義する、あらゆる成果物のことです。
たとえば、こういうものです。
- boundary rule を記述した Markdown ADR
- 外部入力の形を定義する Zod schema
- 切れ味のある doc comment を添えた関数シグネチャ
- 観測可能な振る舞いを捉える Gherkin シナリオ
- 事前条件と事後条件を持つ contract ブロック
- reducer モデルや状態遷移表
どれも大げさである必要はありません。ツールがそこから何か有用なことをできるだけの明瞭さがあれば十分です。
そこが大事な閾値です。有用な仕様は、人間に読めるだけでは足りない。codebase の周りにあるシステムが実際に使えるものでなければなりません。
優れたレビューは、こういう姿になっていく
古いモデルでは、シニアエンジニアは次のような問いに力を使っていました。
- この実装はクリーンか？
- 作者は境界ケースを見落としていないか？
- このテストは十分に強いか？
- この import は境界を破っていないか？
こうした問いは今でも重要です。ただ、もう最初に投げるべき最もレバレッジの高い問いではありません。
仕様先行のワークフローでは、より価値が高いのは次の問いです。
- contract はそもそも正しいか？
- スキーマは本当の境界を定義しているか？
- 業務ルールは出そろっているか？
- ADR は enforcement できるほど精密か？
- 列挙した性質は、実際の意味を表せているか？
こちらのほうが良いレビュー問いです。ひとつ良い答えを出せば、複数の成果物が一度に改善されるからです。
曖昧な ADR を締めれば、アーキテクチャルール、実装ガイダンス、CI の enforcement を一手で改善できます。
弱いスキーマを直せば、実行時バリデーション、型推論、コード生成の質を一度に引き上げられます。
contract を研ぎ澄ませば、実装、テスト、mutation 耐性を一手で強くできます。
これがレバレッジの差です。もう出力を 1 つずつ点検しているのではない。出力の形を決める側をレビューしているのです。
なぜ従来のコードレビューはひび割れ始めるのか
従来のコードレビューは、人間が主要な作者であり、レビューアは完成したコードから人間の思考プロセスの質を確かめる、という前提に立っています。
AI の登場で、その前提は週ごとに弱くなっています。
モデルはもっともらしい 50 行を数秒で出せます。その次の 50 行もすぐ出せる。そのまた次も同じです。もしプロセス全体が、その流れに埋もれた意味のずれをレビューアが手作業で見つけることに依存しているなら、レビュー対象の面積は人間の注意力より速く膨らんでいきます。
すると、悪い均衡が生まれます。
- コード生成は速くなる
- diff は大きくなるか、頻度が上がる
- レビュアーの疲労は増える
- 意味に対する確信は下がる
- チームは雰囲気と勘、それに「まあ良さそうです」で埋め合わせ始める
それはスケール戦略ではありません。見た目が整っているだけの、積み上がったリスクです。
もっと良い手は、そもそも主観的レビューを必要とする量を減らすことです。意味をもっと決定論的でレビュー可能な仕様に押し込み、その意味にコードがまだ沿っているかを機械に確かめさせるのです。
これを現実にするのは CI だ
このワークフローの反転が機能するのは、仕様が enforcement と結びついている場合だけです。
そうでなければ、文書に別の名前を付けて、前より尊重されることを期待しているだけになります。
要点は、仕様を運用可能なものにすることです。
つまり、こういうことです。
- アーキテクチャ判断が依存ルールにコンパイルされる
- スキーマが実行時にも型の上でも安全な境界を定義する
- contracts が実行可能なチェックを生成する
- 性質のリストがテスト生成を駆動する
- 重要な意味がマージゲートになる
そうなった瞬間、CI は受け身のビルドシステムではなくなり、実装を意図に揃え続ける仕組みになります。
だからこそ、生きた仕様がようやく普通のチームでも現実味を持ちます。これまでは、文書とコードを手作業で同期し続ける時間が誰にもなく、文書は腐っていきました。
AI は、その成果物を書くコストと更新するコストの経済性を変えます。CI は、それを enforcement するコストの経済性を変えます。
両方が必要です。enforcement のない AI は、磨き上げられた逸脱を生む。良い仕様のない enforcement は、硬直した混乱を生みます。
Hard Guards、Soft Reviews
ここは、Autotomy の哲学の中でも、いまますます正しいと感じている部分です。
考え方は単純です。譲れないルールは hard guards に入れる。そのうえで、人間のレビューは本当に判断が必要な部分に集中させます。
つまり、型、スキーマ、contracts、依存ルール、deterministic checks が、既知の壊れ方を受け持つということです。毎回走る。疲れない。見栄えのいい diff に気を取られない。コードがスタッフエンジニア由来か言語モデル由来かも気にしません。
するとレビュー層は小さくなり、質が上がります。
システムが自動で弾けたはずのことにシニアの注意力を使うのではなく、トレードオフ、意味、interface、アーキテクチャに使える。境界は正しいか。contract は正直か。差し替えた実装は本当に interface を満たしているか。システムは変えやすくなっているか、変えにくくなっているか。
その最後の点はとても重要です。
仕様先行の仕事がもたらす最も健全な副作用のひとつは、切れ目のきれいな設計へ押し出してくれることです。ある module が contract を満たし、チェックを通る限り差し替え可能なら、あらゆる実装を神聖視するのをやめられる。苦しい延命のためではなく、安全に置き換えるために設計し始めます。
これは微妙な変化ですが、チームの成長への向き合い方を変えます。codebase は、内側から慎重に継ぎ足すしかないもの、という感触を失う。代わりに、継ぎ目が明示されたシステムとして感じられるようになります。
これはシニアエンジニアにとって、むしろ朗報だ
この変化は、シニアエンジニアの判断を価値の低いものにしません。むしろ焦点を鋭くし、重要性を高めます。
シニアエンジニアが最も価値を出す場所は、もはや構文差分をなぞる人間の比較機としてではありません。曖昧さが解消され、invariants が選ばれ、interface が形づくられ、トレードオフが明示される場所こそが本領です。
つまり、より多くの時間を次に使うということです。
- 精密な ADR を書くこと
- contracts とスキーマを定義すること
- スタイルではなく意味の変更をレビューすること
- どの性質を enforcement すべきか決めること
- アーキテクチャをマージ可能なルールに変えること
そのほうが、高価な注意力の使い道としてはるかにましです。
機械は実装の細部を埋めるのが非常にうまい。けれど、システムに負荷がかかり、変更され、スケールするときに、何を変えてはならないかを決める力は、いまもシニアエンジニアのほうがずっと上です。
巨大なプロセス改革は要らない
話が実際以上に大きく聞こえるかもしれません。
形式手法の取り組みを立ち上げる必要はない。出荷を止める必要もない。チームをプロセスで埋め尽くす必要もありません。
まずは狭い変更を 1 つで十分です。ある 1 種類の仕様を、第一級のレビュー対象として扱うことから始める。
現実的な順序は、こんな感じです。
- 重要な境界には、精密な doc comments とスキーマを必須にする
- ADR の変更はシニアレビュー項目として扱う
- その成果物からテストと contracts を生成する
- アーキテクチャと contract のずれを CI で enforcement する
- スタイルだけのレビューコメントは格下げし、意味を問うレビューを優先する
それだけで、文化は変わり始めます。
より良い仕様が下流のレビューの消耗を減らすとチームが実感すれば、そのモデルは自己強化を始めます。レビューは鋭くなる。diff は怖くなくなる。信頼は増していきます。
本当の戦略的転換
AI で勝つチームは、ただコードを速く生成するチームではありません。
人間の注意力を、ワークフローの中で最も狭く、最もレバレッジの高い部分へ移せるチームです。
その部分とは、仕様です。
仕様が主要な成果物になると、コードはもはや 1 行ずつレビューすべき唯一の対象ではなくなります。より規律あるシステムが生み出す出力のひとつになる。
それが本当の転換です。
実装は今でも重要です。とても重要です。けれど、最も重要なレビュー判断は、ますます実装が存在する前に行われるようになる。
だから AI 時代、コードレビューは仕様レビューになります。