AIコーディングツールの進化により、コードを書くハードルは大幅に下がりました。
Claude CodeやCursorなどのツールを使えば、数時間でNextJSアプリケーションを構築できます。
しかし、新たな問題が浮上しています。
AIが書いたコードを、自分で保守できないのです。
海外のエンジニアコミュニティで、この問題が活発に議論されていました。
その内容が非常に示唆に富んでいます。
本記事では、議論から得られる教訓と実践的な対策を整理しました。
問題の本質：コードが「自分のもの」ではない感覚
ある開発者がコミュニティに悩みを投げかけました。
曰く、「AIで素晴らしいアプリを作れるようになった。でも、コードベースが頭の中にない。だから保守が悪夢になる」と。
この感覚、AIコーディングを試した人なら身に覚えがあるのではないでしょうか。
コードは動く。
テストも通る。
でも、どのサービスが何をしているのか把握できていない。
新機能を追加しようとしても、どこを触ればいいのかわからない。
バグが出たとき、原因の特定に異常な時間がかかる。
実際のところ、これはAI特有の問題ではありません。
大規模なコードベースに後から参加した開発者も、同じ問題に直面します。
ただし、AIの場合は状況が異なります。
コードの生成速度が速すぎるため、理解が追いつかないまま規模が膨らんでしまうのです。
コミュニティの圧倒的な見解
海外のエンジニアコミュニティで、この問題に対する議論が白熱しました。
圧倒的多数の意見は厳しいものでした。
「自分のコードベースを理解することに近道はない」
これが結論です。
ダッシュボードやGUIで魔法のように解決できるツールは、現時点では存在しません。
AIにコードを書かせるなら、そのコードを理解する責任も負う必要があります。
特に、クライアント向けの仕事をしている場合は深刻です。
コミュニティでは厳しい意見が多く見られました。
「コードに基づいたサービスを売るなら、何を売っているのか理解する倫理的義務がある」と。
レストランのシェフに例える人もいました。
「構造も計画も関係ない、料理が出ればいい」とは言えないでしょう。
短期的にはうまくいっても、長期的には必ずツケが回ってきます。
実践的な解決策
批判だけでなく、建設的なアドバイスも数多く寄せられていました。
その中から、特に有用なものを紹介します。
「システムの地図」を人間が所有する
最も支持を集めたアドバイスは、「ARCHITECTURE.md」というファイルの作成でした。
これはシステム全体の構造を高レベルで記述したドキュメントです。
AIにこのファイルを書いてもらうことはできます。
しかし、その内容を「所有」するのは人間でなければなりません。
構造的な変更があるたびに、必ず更新するルールを設けましょう。
あるエンジニアは語っていました。
「地図があれば、保守がずっと落ち着いたものになる」と。
コードベース全体を頭に入れる必要はありません。
でも、俯瞰できる地図は必要なのです。
AIを「アーキテクチャアシスタント」として使う
AIをコード生成器としてだけ使うのは、能力の一部しか活用していません。
依存関係のマッピング。
隠れた結合の特定。
モジュール化の提案。
こうした作業にこそ、AIは力を発揮します。
コードベース全体を分析して推論するのが得意だからです。
「アーキテクチャや設計のアシスタントとして使ってみたことはありますか？」という質問に対し、多くの人が目から鱗が落ちたようでした。
アーキテクチャを「先に」定義する
経験豊富なエンジニアからのアドバイスで印象的だったのは、順序の問題でした。
「コードを書く前にアーキテクチャを決める」のです。
まず、フォルダ構造、デザインパターン、データフローをレイアウトする。
その後、AIに個々のコンポーネントを実装させる。
この順序を守れば、コードベースは自分の設計に沿ったものになります。
結果として、把握しやすい構造が維持されます。
「ヘリコプタービュー」ファイルを生成する
ユニークなアプローチを紹介していた開発者もいました。
コードベース全体を1つのマークダウンファイルに連結するスクリプトを作成する。
そのファイルをAIチャットに渡して「プロジェクト全体についての構造的な会話」をする。
こういうやり方です。
コーディングエージェントは通常、ファイルを1つずつ行き来しながら読みます。
しかし、この方法なら全体を俯瞰した議論が可能になります。
大規模なモノレポの場合は、1つのファイルでは不十分という指摘もありました。
その場合、各パッケージやアプリごとにREADMEファイルを用意するとよいでしょう。
ファイル単位の説明を書いておくと効果的です。
テストの重要性
「テスト駆動開発（TDD）と統合テストが鍵だ」という意見も多く見られました。
ユニットテストとE2Eテストを充実させておけば、コードの詳細を把握していなくても安心できます。
変更による影響を検出できるからです。
あるエンジニアは語っていました。
「AIが何をしたか分からなくても、テストが通れば安心できる」と。
ただし、これは「コードを理解しなくていい」という意味ではありません。
テストは安全網です。
理解の代替ではないのです。
小さく刻む
「コードベースが大きくなればなるほど、一度の変更は小さくする」
このシンプルな原則も、繰り返し強調されていました。
AIに一度に大量の作業をさせると、変更の追跡が困難になります。
1つのタスクが30分以上かかりそうなら、サブタスクに分割すべきです。
各タスクの完了後には、要約を作らせる習慣も有効です。
何が変わったのか。
どう実装されたのか。
どこに問題がありそうか。
これらを毎回確認するのです。
ドキュメントも同様です。
コミットごとに更新する習慣をつけましょう。
単一責任原則を守らせる
「常にSingle Responsibility Principleを使うようAIに指示している」という開発者のコメントも目を引きました。
モックしやすく、テストしやすいコードを書かせる。
そうすれば、AIのコードも保守しやすくなります。
関数やモジュールの責務が明確なら、理解も容易になるでしょう。
視覚化ツールの現状
投稿者は「コードベースを俯瞰できるGUIが欲しい」と述べていました。
フローチャートや図表でシステムを可視化できるダッシュボードです。
残念ながら、このニーズを完全に満たすツールはまだ存在しないようです。
ただし、状況は急速に変化しています。
一部のツールは、コードベースの自動ドキュメント生成や依存関係グラフの可視化機能を提供し始めています。
当面の代替策として、AIにASCIIダイアグラムでリポジトリ構造を図示させる方法が紹介されていました。
Mermaid記法を使えば、READMEにダイアグラムを埋め込むことも可能です。
「理解」を避けられない理由
議論の中で最も印象的だったのは、経験豊富なソフトウェアアーキテクトの発言でした。
専門家は、自分の決定の二次的・三次的な影響を理解している。 狭いユースケースでは『動く』設計はできる。 でも、それらの影響までは見えていない
これは「ダニング・クルーガー効果」に関連しています。
知識が浅いと、自分の無知に気づきにくい。
LLMはこの効果を悪化させる傾向があります。
AIが自信満々で回答してくるため、問題の複雑さを過小評価しがちだからです。
まとめ
AIコーディングツールは強力です。
しかし、コードを書くことは、ソフトウェア開発のほんの一部に過ぎません。
コミュニティの議論から得られる教訓は明確でした。
- コードベースを理解することに近道はない
- ARCHITECTURE.mdのような「地図」を作成し、人間が所有する
- AIはコード生成だけでなく、アーキテクチャ分析にも活用する
- 設計を先に決め、その後でAIに実装させる
- テストを充実させ、変更は小さく刻む
「コードを書くことが解決された今、次の課題はAIにスケールでコードを書かせる方法だ」と投稿者は語っていました。
しかし、多くの人が反論しました。
彼らの反論は正しいと思います。
ソフトウェア開発の大部分は、コードを書くことではないのです。
設計し、理解し、保守し、改善すること。
その本質は、AIの時代になっても変わりません。
AIは優秀なアシスタントになります。
しかし、運転席に座るのは人間でなければなりません。
