はじめに
AI を使ったチーム開発をしていると、ときどき不思議なコードがレビューに上がってきます。
既存の構造を無視した実装、責務を跨いだ処理、なぜここに書いたのか説明できないコード。おかしいのは、バイブコーディングでもこうはならない点です。AI は既存コードを読めます。丸投げでも、それなりに整合性のとれたものを出してきます。
ドキュメントはもちろん、ルールやスキルといったハーネスも整備してあります。それでも品質が崩れます。実際にペアプログラミングしながらプロンプトや会話の流れを横で見ていると、問題の本質はAIの性能不足、プロンプトの技術というより、話し手と聞き手の間で設計に関する前提、つまり共通基盤が共有されていないまま、人間が実装に介入してしまっている点にあるように見えます。
AIとのやりとりは共通基盤に依存する
コミュニケーションは、話し手と聞き手の間に共有された知識や前提、つまり共通基盤があって初めて成立します。相手が何を知っていて何を知らないかを把握しないと、話は噛み合いません。
AI は人間のように相互理解を確認しながら会話するわけではありません。それでも、出力の品質は与えられたコンテキストに強く依存します。どこまでコンテキストを共有できているかが成果を左右する以上、AI への指示も共通基盤の多寡に影響を受けるコミュニケーションだといえます。
AI は既存コードからかなり多くの文脈を拾えます。少なくとも、設計を理解していない人間が雑に実装を指示するより、一貫した判断をすることは珍しくありません。設計を理解しているエンジニアとは共通基盤を作りやすいですが、理解していない人間が AI に指示を投げると、その共通基盤は薄くなり、判断の整合性も崩れやすいです。
理解なき中途半端な介入が、品質を壊す
具体的に見てみましょう。
「OrderUseCase の execute メソッドで注文処理が完了したとき、
そのままメール通知も送るように追加してください」
AI はこの指示を受けとります。既存コードや周辺のルールを読めば、「UseCase はドメインロジックの調整役であり、メール送信などのインフラ層の処理を直接持つべきではない。通知はドメインイベントを発行して別レイヤーが担う」といった設計パターンを推測できることもあります。ハーネスが止めてくれることもあります。しかし「execute に追加してほしい」のような局所的で強い指示は、その文脈より優先されやすいです。すべての「理解なき介入」を検知できるほど、現時点のハーネスも AI も万能ではありません。
結果として、UseCaseがインフラ層の具体実装に依存するコードが生まれます。動作はしますが、外部I/Oを伴うためユースケース単体のテストが書きにくくなり、通知手段を変更したときにUseCase自体の修正が必要になってしまいます。
AI が悪いわけじゃない。AI の理解を壊す、具体的すぎる中途半端な介入が問題です。
設計を理解しているエンジニアなら設計上の違和感を返してきますが、AI はユーザーの意図への追従を優先しやすいです。設計破壊的な指示でも静かに実装してしまうことがあります。
あまりに具体的な実装指示を出すより、「この設計どう思う？」「ここに置くのはおかしくない？」と問いかける方が、AI の理解を活かせることが多いです。
AIに任せるべき粒度、人間が担うべき判断
まず自分が共通基盤を持つことが理想です。既存コードの「なぜ」を読みます。動いているかどうかじゃなくて、なぜその構造になっているのか。どこが何を担っているのか。それを理解してから「今回の要件をどこに置くべきか」を考えます。
それができていないなら、実装方法を決め打ちで指示するより、まず AI に設計上の置き場所や実装方針を提案させた方がいいです。理解が浅い人間が細かい実装指示まで決めてしまうと、コードベースやルールから拾える文脈を自分で上書きしてしまいやすいからです。委ねた後は、AI が出してきたプランや提案がおかしくないか、矛盾していないかを判断します。それができれば十分です。
ただし、目的だけを雑に投げればいいわけではありません。目的、要件、守るべき制約、評価観点は渡した上で、実装の置き場所や詳細手順を決め打ちしすぎないことが重要です。
- 「
OrderUseCaseのexecuteにメール送信を追加して」ではなく、「注文完了後にメールを送りたい。既存の設計に照らしてどこに置くべきか考えてほしい」 - 既存のレイヤリングや責務分離は崩さないことを制約として渡す
- 実装前にコードベースを探索させる
- 提案された方針に対して、人間が設計上の違和感を確認する
Claude Code のベストプラクティスでも Explore -> Plan -> Implement というフローが推奨されており、GitHub Copilot など他の AI コーディングツールでも、似た考え方は有効です。
まとめ
AI とのやりとりは、相手が何を知っているかを踏まえたコミュニケーションです。共通基盤を持たないまま介入することは、品質を壊す大きな原因のひとつです。
AI が想定と違うものを出してきたとき、AI のせいにする前に自分の指示を疑ってみてください。AI に任せるべき粒度と、人間が担うべき判断を切り分けるだけで、出力の質はかなり変わります。