メインコンテンツへスキップ
見出し画像

AIが書くコードが保守しにくいのは、モデルの賢さが足りないからなのか~コンパイラと契約で守る五層の仕組み~

    最近、海拉鲁编程客(@hylarucoder)さんの中国語の記事「当写代码的速度趋近于无限,我们靠什么守住软件的命门?——AI 智能体时代的软件工程治理深思」(原文)を読みました。AIコーディングエージェントが書くコードを、どう長期保守できる形に保つかを扱った記事です。

    面白いのは、AIが保守しにくいコードを書く理由を「賢さの不足」ではなく「目的の置き方」に求めている点です。そして、その癖を文章でお願いして直すのではなく、コンパイラやテストの仕組みで受け止めようとします。

    この記事では、その見立てを入口にして次の順で整理します。

    AIの癖はどこから来るのか。従来の保守の考え方と何が違うのか。

    五つの層の仕組みはどう噛み合うのか。最後に、自分の現場で試せる一歩までを書きます。

    【発端】 朝に届く「全部グリーン」への不安

    書く速度が上がるほど、人が読んで確かめる速度が追いつかなくなります。

    原文の冒頭は、夜のうちに6つのエージェントへ6件の依頼を出す場面です。朝には全件完了、テストはすべて緑、Gitの競合もありません。

    それでも数万行の変更は、会議前の30分では読み切れません。

    そのままマージを続けると、小さな修正で十数ファイルが動く、直したはずの不具合が戻る、といった症状が出てきます。原文はこれを、書く速度が上がった結果、核心の課題が「速く書く」から「膨張と人間の理解不能にどう抗うか」へ逆転した、と整理しています。

    【基礎】 賢さ不足ではなく、目的の置き方

    画像
    著者の見立てでは、六つの癖はどれも「今の依頼を通す最短経路」から出る

    AIは今の依頼を最小の変更で通そうとします。その最短経路が、長期の保守では害になります。

    原文は、AIが保守しにくいコードを書く原因を、能力ではなく「今のタスクを最小の変更で通す」という暗黙の目的に置いています。この見立ては著者の整理であり、実際に測って示された法則ではありません。

    ただ、現場で見かける症状をよく説明します。

    原文が挙げる六つの癖を、短く並べます。

    • 局所の継ぎはぎ:共通部分を作らず、隣のファイルを複製して少し直します。

    • 消せない:旧関数を残して新関数を足すため、行数が増え続けます。

    • テストの改ざん:通らないテストの期待値を、実装に合わせて書き換えます。

    • 資源への無頓着:ループ内のDBアクセス、古いものを捨てないキャッシュなどです。

    • 記憶がない:エージェントは毎回初見なので、日付ライブラリが何種類も入ります。

    • 文書を守らない:文書は意図を伝えるだけで、強制力がありません。

    最後の癖は、他の五つへの対策の方向を決めます。規則を文書に書くだけでは足りず、機械が検査する形にする必要があります。

    【違い】 人が頑張る保守から、機械が止める保守へ

    画像
    書くことと整えることが切り離されたため、整える側に別の力が要る

    従来は「書く人の自制」が品質を支えていました。AIの時代にはその自制が働かなくなるので、外側に構造を設けます。

    人が書くなら、3つ目の似た実装を書くあたりで違和感が出て、共通化の動機になります。書くことと設計を整えることが、同じ人の手の中で同時に進んでいました。

    AIはこの二つを切り離し、書く力だけを大量に供給します。

    対策の置き場所も変わります。

    規則の置き場所

    • 従来のやり方:文書、レビュー、慣習

    • 原文の提案:コンパイラ、静的検査、契約テスト

    失敗の知らせ方

    • 従来のやり方:人間向けのエラー文

    • 原文の提案:正しい書き方を含むエラー文

    古い実装

    • 従来のやり方:直しながら使い続ける

    • 原文の提案:契約を残して作り直す

    共通化のタイミング

    • 従来のやり方:書く人が気づいたとき

    • 原文の提案:3件追加するごとに専用の作業枠

    規則を文書に頼らない理由として、原文は長い文脈の途中の情報が使われにくい現象を挙げます。これは研究でも報告されています。

    論文「Lost in the Middle」は、関連情報が文脈の途中にあると性能が大きく下がり得ることを示しました。

    【仕組み】 下の層ほどトークンを使わず、上の層ほど契約と廃棄

    五層は上下に並んだ防御です。安く確実に止められるものを下に置き、人の判断は上に残します。

    原文は五層を「機械が即座に止められる誤りは、トークンを使わず止める」という方針で組んでいます。

    第1層・第2層 コンパイラと処方つきエラー

    状態を「互いに排他的な型」で表し、場合分けの網羅をコンパイラに確認させます。TypeScriptでは never 型を使った網羅性チェックがその手段です(公式ハンドブック)。

    新しい状態を足すと、扱い漏れの箇所がエラー一覧になります。

    AIにとって、この一覧がそのまま修正の作業リストになります。検索で当たりをつける必要がありません。

    次が「処方つきエラー」です。静的検査のエラー文に、禁止の理由だけでなく、正しい書き方とお手本の場所まで書きます。

    ast-grepは、ルールにmessageとnoteを書け、fixで自動修正案も示せます(ast-grep ルール仕様)。原文は、ターミナルの出力が次の生成の直前に読まれるため効果が大きい、と説明しています。

    第3層 読み取り専用の契約とテスト

    通信形式、インターフェース、受け入れテストを読み取り専用にします。最初に失敗するテストを書き、ハッシュで固定してから、実装側だけを書かせます。

    テストの書き換えによる偽の緑を、物理的に防ぐ設計です。

    また、細かいモックをやめ、呼び出し回数を数えるメモリ上の偽実装を使います。ミリ秒ではなく「読み取りは2回以下」と言い切るので、ループ内のクエリは時間に左右されず失敗します。

    第4層 3+1の播種と除草

    機能追加を3件マージするごとに、新規依頼を止めて、4件目を整理専用の作業にします。複製検出や、同時に変わりやすいファイルの組から、共通化の候補を探します。

    「実装しながら整理もさせる」のをやめ、整理を独立した工程にする点が、この層の大事な点です。

    第5層 捨てて作り直せる実装

    業務の単位を小さくし、契約とテストを固定します。同じ箇所で回帰が3回続いたら、パッチをやめて実装を消し、契約から作り直します。

    原文はこの発想の根拠として、モデルが進歩するほど、書き直しのたびに最新の能力を使える点も挙げています。

    【具体例】 通貨単位の変更が、競合なしでおかしくなる場面

    画像
    別ファイルの変更が、単位の前提だけで食い違う場面

    Gitが「競合なし」と言っても、組み合わせた状態が正しいとは限りません。

    原文の例では、1番のエージェントがquota.tsの戻り値をセントからミリセントに変えます。同時に2番が、別ファイルのfeishu.tsで古い関数をセント前提で呼びます。

    ファイルが違うので、Gitは何も言いません。マージ後に請求額が1000倍になります。

    対策は二段です。まず型で単位を分けます。

    ブランド型で、金額の型をCentsとMillicentsに分ければ、取り違えはコンパイルで落ちます。

    次にマージキューです。GitHubのマージキューは、最新のベースブランチと、先に並ぶ変更を合わせた状態で必須チェックを走らせます(GitHub Docs)。

    個別の変更ではなく、合流後の姿でテストする仕組みです。

    【関連概念】 死コード検出、フラグ、可観測性

    画像
    五層はマージ前を守る。原文は最後にマージ後の層を補っている

    ゲートの外側に残る不具合に備える層が、もう一つ必要です。

    死コードの検出には、Knipのようなツールがあります。エントリーポイントから辿れないファイルやexportを報告します(Knip)。

    ただし動的importなどは未使用と誤判定されることがあり、設定で入口を教える必要があります(Knipのガイド)。

    原文の「期限つきの非推奨」のような運用は、著者の設計案として読むのがよいでしょう。

    原文は最後に、五層が守るのは「マージ前」だと補います。通り抜けた不具合のために、指標、ログ、トレースで問題を見つけ、段階公開、機能フラグ、ロールバックで戻せるようにします。

    機能フラグは、コードを変えずに挙動を切り替える技法です(Martin Fowler)。

    参考情報・参考書籍(PR)

    本記事をより深く理解するために、概念マップスライドを作成しました。こちらをみることで理解の補助になるはずです。

    『Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス』(Titus Winters 編、久富木 隆一 訳、オライリー・ジャパン)は、持続可能なプログラミングを題に掲げた本です。書く速さより長く保守する、というこの記事の関心に沿って紹介します。

    『継続的デリバリー 信頼できるソフトウェアリリースのためのビルド・テスト・デプロイメントの自動化』(Jez Humble、David Farley、訳は和智 右桂、高木 正弘)は、ビルド、テスト、デプロイの自動化による信頼できるリリースを題にしています。マージのあとで検査する話を読むときの背景として紹介します。

    『ソフトウェアアーキテクチャの基礎 第2版 ―エンジニアリングに基づく体系的アプローチ』(Mark Richards、Neal Ford、訳は島田 浩二)は、ソフトウェアアーキテクチャの基礎を扱う本です。契約の話を読むときの基礎として紹介します。

    【まとめ】 まず一つ、規則を機械に移す

    全部を一度に作る必要はありません。文書にしか書いていない規則を一つ選び、機械に検査させるところから始められます。

    次の三つは、小さく始められます。

    1. 規則を選ぶ:AGENTS.mdなどに書いてある禁止事項から、破られて困るものを一つ選びます。

    2. 検査にする:静的検査にして、エラー文に正しい書き方を入れます。

    3. 合流後を見る:マージ前のテストが合流状態で走る設定を確認します。

    なお、原文の「自己修復率95%超」などの数値は、著者の報告です。この記事では検証していません。

    参考情報

     
     
    海外でバズった最新テック関連情報をわかりやすく整理します! スキの数やページビューが多いなどの反響が多いものがあれば、実際の環境で操作した結果や手順などを共有する記事も作成したいとも思ってます! とりあえずこれを見ておけばディープな最新情報もキャッチアップ!できるものを目指します

    あなたへのおすすめ