先に結論
AIを導入すると、実装スピードは確実に上がります。
ただ、チーム開発で本当に問題になるのは、コードを書く速さではなくコードを理解し、判断を共有する速さです。
今回読んだ2本の記事から得た学びを一言でまとめると、次の3つでした。
- 仕様書は「ずっと保守する正本」ではなく、「認識を揃えるための起点」として使う
- AI時代のレビューは、「細かい指摘」より「なぜその実装なのか」を確認する場になる
- AIが書いたコードをチームの資産にするには、「説明できる状態」を作ることが必要
「AIで実装は速くなったのに、レビューや設計はむしろしんどくなった」と感じている人には、かなり刺さる内容でした。
参考にした記事
なぜAI導入後の開発は、逆に難しく感じるのか
AIを使うと、定型的なコードはかなり速く作れます。
CRUD、マイグレーション、補助的な処理などは、以前よりずっと短時間で前に進められるようになりました。
でも、チーム開発では別の問題が出てきます。
それは、コード生成の速度に人間の理解速度が追いつかないことです。
その結果、こんなことが起きやすくなります。
- PRが大きくなってレビューが重くなる
- 仕様書が更新されず、すぐに古くなる
- コードは動くが、設計判断の根拠が弱い
- 実装者自身も「なぜこうしたのか」を説明しづらい
つまり、AIが増やしているのはコード量だけではなく、理解負債でもあるのだと思います。
学び1: 仕様書は「長く守るもの」より「正しく始めるもの」
1本目の記事で印象的だったのは、要求仕様書や実装計画書をAIに渡すことで、実装のズレを減らしていた点です。
要求仕様、QA項目、API仕様、イベント仕様、参考情報。
こうした情報を整理しておくと、AIにも人にも前提を共有しやすくなります。
特に、既存実装を参考として渡すと精度が上がる、という話にはかなり納得感がありました。
ただし、その運用を続けると別の課題も出てきます。
仕様変更のたびにドキュメント更新が必要になり、コードとの二重管理が発生する。
さらに、仕様書内のコード例が検索ノイズになることもある。
そこで記事では、仕様書を「ずっと正であり続けるもの」としてではなく、
開発前に認識を揃えるためのものとして捉え直していました。
これはかなり本質的だと思います。
AI時代の仕様書で大事なのは、完璧に残すことではなく、AIと人間が同じ前提でスタートできる状態を作ることです。
学び2: AI時代のレビューで大事なのは「正しさ」より「説明可能性」
2本目の記事では、「理解負債」という言葉がとても印象に残りました。
AIはそれっぽいコードをかなり上手に書いてくれます。
でも、そのコードがチームとして本当に理解されているかは別問題です。
記事では、ポイント消費と特典付与をまたぐ処理で、AIが補償トランザクションを含むそれらしい実装を出した一方、
「片方だけ成功した場合にどう扱うのか」という設計判断の根拠が曖昧だった、という例が紹介されていました。
また、FIFOキューを何となく採用していたところ、レビューで「本当に順序保証が必要なのか」と問い直された例もありました。
ここから見えてくるのは、AI時代のレビューで本当に見るべきものです。
それは、
- なぜこの設計なのか
- 何を優先してその判断をしたのか
- 障害時にどう振る舞うのか
- 代替案と比べて、なぜこれを選んだのか
といった、判断の根拠です。
命名、規約、明らかな抜け漏れのような一次チェックは、AIにもかなり任せられます。
そのぶん人間は、「この実装は説明できるか」を見る側に寄った方が強いと感じました。
2本の記事から得た、今すぐやるべき action
1. 設計書には「コードから自然には読めないこと」を書く
AIに渡す設計情報として価値が高いのは、クラス図や疑似コードそのものよりも、次のような情報です。
- エラー時の扱い
- rollback の優先順位
- リトライ方針
- 順序保証の必要性
- 運用・監視で見たいポイント
- 参考にしたい既存実装
こうした情報は、コードからは自動で復元しづらい。
だからこそ、設計書に残す意味があります。
2. 仕様書は「使い切る前提」で考える
全部の仕様を長寿命ドキュメントとして維持しようとすると、かなり苦しくなります。
それよりも、認識合わせのために作って、必要に応じてIssueやPR説明に役割を分散した方が現実的です。
「立派な文書を残す」より、更新し続けられる運用にすることの方が大事です。
3. AIには大きく作らせず、小さく出させる
AIを使うと、気づいたらPRが巨大化しがちです。
だからこそ、PRは一言で説明できる粒度まで小さく分けるべきです。
小さいPRは、レビューしやすい。
差し戻ししやすい。
AIへの追加指示もしやすい。
結果として、チーム全体の理解コストが下がります。
4. レビューの役割を分ける
AIに任せやすいものと、人間が見るべきものを分けた方が良いと思います。
AIに任せやすいのは、規約、命名、抜け漏れ、定型チェック。
人間が見るべきなのは、設計意図、障害時のふるまい、技術選定の妥当性です。
この切り分けをしないと、AI時代のレビューはどんどん重くなります。
5. マージ前に「自分の言葉で説明できるか」を確認する
個人的に、一番大事なのはこれです。
AIが書いたコードでも、自分で書いたコードでも、最終的にマージするなら、実装者が
- なぜこの方式を選んだのか
- どんな失敗ケースを想定したのか
- 何を優先し、何を捨てたのか
を説明できるべきです。
説明できないなら、そのコードはまだチームのコードになっていないのだと思います。
まとめ
AIで実装は速くなります。
でも、チーム開発で本当に差が出るのはその先です。
- 仕様書をどう作るか
- どこまで保守するか
- PRをどの粒度で出すか
- レビューで何を見るか
- 実装者がどこまで説明責任を持つか
このあたりを見直さない限り、AIは便利なはずなのに、現場のしんどさを増やすこともあります。
今回の2本の記事を読んで、自分の中で一番大きかった学びはこれでした。
AI時代に守るべきなのは、コード量ではなく「理解が回る状態」だ。
同じ違和感を持っている人は、ぜひ元記事も読んでみてください。
かなり解像度が上がると思います。