引き継いだコードの指摘リストを前に、どこから手をつけるか考えている開発者
設計・レビューでのAI活用約15分

AIにコードの複雑さ・設計の臭いを指摘させる｜直す順番の決め方

引き継いだばかりのコードを開いて、正直なところ少し途方に暮れて、AIに全部貼って「設計上の問題を指摘してください」と頼んでみる。——この流れは、たぶん今日もどこかで起きています。

返ってくる指摘は、四十いくつ。責務が多すぎる関数、深すぎるネスト、重複したロジック、意味の伝わらない変数名、マジックナンバー、長すぎる引数リスト。どれも、読めば「たしかに」と思う内容です。

そして手が止まります。全部直す時間はないし、どれが「直す価値のある問題」なのかは書いていないからです。

これは、聞き方が悪かったから起きることではありません。AIは「教科書的な理想形との差」なら答えられますが、「そこを直すと今後の仕事が楽になるかどうか」は知らない——ただそれだけです。知らないことを聞かれたから、理想形との差分がそのまま並んだ。この記事では、その足りない材料をどう補うかを整理します。

結論：AIに複雑さや設計の臭いを洗わせるときの要点は3つです。①AIに出させるのは「直すべき順番」ではなく「気になる箇所の一覧」。順番を決める材料——そのコードを今後も触るのか、壊れたら何が止まるのか、テストがあるのか——は、こちらしか持っていません。②「事実」と「意見」を分けて出させる。行数・ネストの深さ・分岐の数は数えれば決まる事実で、「責務が多すぎる」は意見です。混ぜて並べると重みが分からなくなります。③直すのは「次に触る予定のある場所」だけ。この先1年誰も開かないファイルの臭いは、臭いのまま置いておいて構いません。

AIに足りないのは腕ではなく、そのコードの変更履歴とこれからの予定です。そこだけ渡せば、指摘の並びは急に使えるものに変わります。

全部を今日やる必要はありません。まずは①の「一覧として受け取る」という構えだけで大丈夫です。

何が起きているのか——AIは「理想形との差」を出している

よく手に取る箱を手入れする場面、棚の奥の箱に触らず通り過ぎる場面、受け皿を敷いてから手を入れる場面を並べた図
複雑さの大きさより先に、次に触る場所かどうかで選ぶ。触ると決めたら、受け皿を先に置いてから手を入れます

まず、なぜここだけ勝手が違うのかを共有させてください。理由は3つあります。

1つ目は、AIが変更履歴を知らないこと。図の左と中央の違いが、AIには見えていません。同じくらい入り組んだ関数でも、毎月のように修正が入っている場所と、3年間一度も変わっていない場所では、直す価値がまるで違います。前者は直せば今後ずっと楽になりますが、後者は「動いているものを触ってリスクだけ取る」になりかねません。AIはコードの現在の姿だけを見て話しているので、どちらにも同じ強さで指摘を出します。

2つ目は、指摘の粒度が揃わないこと。変数名の付け方と、責務の混在と、モジュール分割の是非が、同じ箇条書きの中に並びます。片方は5分で直る話、もう片方は設計の作り直しです。箇条書きは、並べた瞬間にどれも同じ重さに見える——これが厄介なところで、四十いくつを前にして途方に暮れる原因の半分はここにあります。

3つ目は、「臭い」は欠陥ではなく仮説だということ。コードの臭い（code smell）というのは、もともと「ここ、あとで問題になるかもしれないので見ておいたら」という気づきの目印であって、バグの報告ではありません。長い関数が必ず悪いわけでも、重複が必ず間違いなわけでもない。業務要件がそう決まっているから分岐が多い、似ているけれど別物なので、あえて共通化していない——現場にはそういう事情がありますが、AIはその事情を渡されていません。

この3つが重なると、「AIの指摘を上から順に潰していったのに、コードは別の形で読みにくくなり、時間だけが溶けた」という、いちばん報われない状態になります。逆に言えば、渡す材料を足すだけで、同じAIの同じ指摘が使えるものに変わるということでもあります。

具体例——AIの指摘が、こう外れる

現場で見かけやすいのは、次のような形です。どれも「AIが嘘をついた」わけではなく、判断材料がなかったというだけの話です。

並べてみると、外れ方のほとんどが「今後そこを触るのか」「壊れたら何が止まるのか」「テストがあるのか」を渡していないことに由来します。裏を返せば、どれも渡せる情報です。

影響——一番の損失は、時間より「信用が減ること」

指摘を上から順に潰そうとすると、しんどさは工数以外のところにも出ます。

ただ、ここは強調しておきたいのですが、指摘の一覧そのものは、捨てなくて構いません。今日直さない指摘も、次にそのファイルを触る日の下調べになります。並べ替えて、上から1〜2件だけ拾う。残りは、そのままメモとして置いておけば十分です。

明日からやること（3ステップ）

大がかりな静的解析基盤は要りません。この順番で、今日から小さく始められます。

1. 対象を「次に触る場所」に絞ってから貼る

コードベース全体を貼るのをやめて、次のひと月で触る予定のあるファイルに絞ります。予定がはっきりしないときは、変更履歴が教えてくれます。

Gitを使っていれば、直近1年でよく変更されたファイルは、次の1行で出せます。

git log --since="1 year ago" --name-only --pretty=format: -- '*.py' \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -20

拡張子の部分は、扱っている言語に読み替えてください。この上位に来たファイルが、手を入れると効きやすい場所です。変更が多いということは、これからも変わるということで、読みにくさのコストを毎回払っている場所でもあります。

逆に、この一覧に出てこないファイルは、今日の対象から外して大丈夫です。図の中央、埃をかぶった箱です。臭いは残りますが、臭いを残す判断も、立派な判断です。

なお、ここでAIに渡すのが社外のサービスなら、貼る前に社内規程と機密の線引きを確認してください。判断の目安は社内データをAIに渡す前の線引き｜情報漏えいを防ぐ型に整理してあります。

2. 「事実」と「意見」を分けて出させる

対象が絞れたら、指摘の形を指定します。ここを指定するかどうかで、受け取りやすさがまるで変わります。

そのまま使える頼み方の例：

以下のコードについて、修正コードはまだ出さなくて結構です。 気になる箇所を洗い出して、次の2つに分けて書いてください。

【A】数えれば決まる事実：関数ごとの行数／ネストの最大の深さ／分岐（if・switch・ループ）の数／引数の数。数えられた根拠になる箇所を必ず示してください。数えていない数字は書かないでください。

【B】あなたの見立て（意見）：責務の混在、命名、重複、抽象化のずれなど。1件ごとに、次の3点をセットで書いてください。

1. どこが、どう気になるか（ファイル・関数名まで具体的に）
2. 直さないと今後どういう場面で困るか（起きうる具体的な場面で）
3. 直す規模の目安（数分／半日／設計の作り直し、のどれか）

あわせて、「これは意図的にそうしている可能性がある」と思う箇所には、その旨を添えてください。

前提：（言語・フレームワーク／このファイルの役割／今後予定している変更）

ポイントは3つあります。

事実と意見を分けること。行数やネストの深さは、誰が数えても同じになる情報です。ここが分かれていると、「意見のほうは、あくまで見立てとして読む」という構えができます。数えていない数字は書かないでと一言足しておくのは、前掲のとおり、それらしい数値が混ざるのを防ぐためです。可能なら、言語ごとの静的解析ツールで実際に測った値を渡してしまうのがいちばん確実です。

「直す規模の目安」を書かせること。5分の話と、設計の作り直しが同じ行に並ばなくなります。四十いくつの指摘も、数分でできる分だけ拾えば、今日のうちに片づきます。

「意図的かもしれない箇所」を自己申告させること。これを足すと、AIの言い方が少し慎重になります。「重複していますが、用途が別なら意図的な可能性があります」と書かれていれば、こちらも判断しやすい。前提の渡し方そのものはAIにコードを書かせる前に渡す前提と制約｜伝え方の型、既存コードの文脈の載せ方は既存コードにAIを馴染ませる文脈の渡し方｜実務の型と同じ考え方です。

3. 3つの問いで並べ替えて、上位1〜2件だけ直す

返ってきた一覧を、次の3つの問いで並べ替えます。ここが、AIには代われない仕事です。

①この先3か月、そこを触る予定があるか（ないなら、今日は見送り）
②壊れたときに何が止まるか（決済・在庫・請求まわりは慎重に、社内の集計画面は軽めに）
③テストがあるか（ないなら、直す前にテストを先に置く。図の右です）

この3つを通すと、四十いくつは、たいてい2〜3件まで減ります。減ったことに、後ろめたさを感じなくて大丈夫です。残りを捨てたのではなく、順番を後ろにしただけです。

そのうえで、直し方の作法をいくつか。

3つとも今日やる必要はありません。ステップ1の「対象を絞る」だけでも、返ってくる指摘の量は現実的なところに落ちます。

複雑さの指摘を扱うときのチェックリスト

全部に○が要るわけではありません。気になった行だけで十分です。

① AIに見せる前に

② 指摘を受け取るとき

③ 直すと決めたあと

この記事のまとめ

AIは、理想形との差を驚くほど速く並べてくれます。得意なのは気になる箇所を洗い出すことと、数えて決まる事実を整理すること。苦手なのは、そのコードをこれから誰が、どれくらい触るのかを知ることです。それは、渡していない情報だからです。

やることは3つだけです。①対象を「次に触る場所」に絞る／②事実と意見を分けて出させる／③3つの問いで並べ替えて、上位1〜2件だけ直す。この3つがあると、複雑さの整理は「終わりのない掃除」から、「今日ぶんだけ片づける作業」に近づきます。

長い指摘リストから今日やる1件を選び切って、落ち着いて手を動かし始めた開発者

引き継いだコードが読みにくいのは、あなたが書いたからではありません。それでも、開いて、指摘を受け止めて、どこから直すか考えている。その時点で、このコードはもう、昨日より少しだけ良くなる方向に動いています。 四十いくつを全部やらなくて大丈夫です。ひとつ選んで、ひとつ直す。それで十分、前に進んでいます。

よければ、こちらも

関連用語