世界を動かす技術を、日本語で。

人間が保守するようにコードを書く

2026年7月10日原文(unstack.io)

概要

  • LLM によるコード生成の利便性と落とし穴の指摘。
  • DRY原則 や保守性の軽視がもたらす悪影響の説明。
  • コードベース内の 悪いパターンの連鎖 について解説。
  • LLMが 既存のスタイル を学習し再生産するリスクの強調。
  • 良いコードスタイル を維持する重要性の提言。

LLM活用時のコーディング習慣がもたらす影響

  • LLM は一日中コードを書いてくれる存在。
  • 手作業で長大な条件分岐を各所で更新する必要性の消失。
  • 例として、同じアクセスチェックを複数箇所で必要とするプロジェクトの開発体験。
    • route handlerbackground jobAPI endpointwebhook などで同様の条件式を利用。
  • 毎回要件を伝えるだけで、 モデルが動作するコード を生成してくれる現状。
  • 生成される条件式はほぼ同じ内容で、変数名や細部が若干異なるだけの コピペロジック
  • 本来なら 共通ヘルパー などで抽出・整理するべき箇所でも、AI任せにしてしまう傾向。
  • コードが動作し、テストも通るため、 保守性やベストプラクティス を軽視しがち。
  • 「あとでAIが直してくれるから」と、 面倒な保守を先送り する心理。

コードベースへの悪影響とLLMの学習プロセス

  • LLM は真空状態でコードを書くわけではない点に注意。
  • 既存のコードベース、開いているファイル、過去の変更履歴を参照しながら生成を行う仕組み。
  • 悪いショートカットや コピペパターン をマージするたび、それが 「このプロジェクトの流儀」 として学習される。
  • 新たなエンドポイント追加のたびに、過去のコピーを参照し 同じ悪いパターン を再生産。
  • リファクタ依頼をしても、 既存のスタイル を維持する形でしか修正されない傾向。
  • 一時的な妥協 が積み重なり、やがてプロジェクト全体の品質低下に直結。

保守性とスタイル維持の重要性

  • LLMは 人間の保守作業を肩代わり してくれるようで、実は 悪習慣の再生産装置 にもなり得る。
  • 悪いパターンが一度根付くと、 プロンプトだけでの修正が困難 になる現実。
  • コードスメル や「後で直す」マージが積み重なり、技術的負債の温床に。
  • 最終的には 自分の手で泥臭く直す しかなくなるリスク。
  • 良いコードスタイル を常に意識し、LLMにも 良いお手本 を与える姿勢が大切。

まとめ:LLMと向き合う心構え

  • LLMはあなたの行動を模倣 するスポンジのような存在。
  • だからこそ、 人間が保守しやすいコード を書く意識が不可欠。
  • 良い習慣 を根付かせることで、LLMもそれを学び、再生産してくれる。
  • 短期的な楽さ に流されず、長期的な品質維持を優先する姿勢が成功の鍵。

Hackerたちの意見

古い名言があるよね。「次にこのコードをメンテナンスする人は、君の住所を知っている殺人鬼だと思って、コードにコメントを追加しなさい。」

一番殺人鬼的な行動を引き起こすのは、コメントがないことじゃなくて、古いコメントや不正確なコメントなんだよね。

今、一番イラッとくるコメントは、特定の関数の現在の呼び出しについて、関数定義のすぐ上で話すLLM TMIスタイルのコメントだね。最近、PRレビューで何度目かの遭遇で怒りを感じちゃった…それには驚いたよ。自分がそんな反応するなんて思ってもみなかった。

昔、一緒に働いてた人が「コメントは謝罪だ」ってよく言ってたんだよね。つまり、コードが明確じゃないからコメントが必要ってこと。確かにそういうこともあるけど、個人的にはコメントが多い方がいいと思う。特に、コードが実際のビジネスや機能要件に関連してる場合はね。昔は、よくコメントを最初に書いてたんだ。全体の目標を説明してから、ルーチンや操作の順序を分けて、全部普通の英語で書いてた。満足したら、コメントをコードのブロックで分けてたんだ。これって「リテラルプログラミング」みたいだけど、その言葉を聞くずっと前からやってたし、実際にそれについてあまり読んだこともない。どちらかというと、自分を最終目標に向かわせてた感じかな。このアプローチの欠点は、結局コメントがコードが何をしているかを英語で説明するだけになっちゃうから、将来のメンテナンスにはあんまり役立たないかもしれないね。

コメントが多すぎるレシピみたいだね。コードは自己文書化されるべきだよ。コメントはドラゴンがいるところのためのもの。

コードベースをいろんなモデルでチェックして、繰り返しのコードみたいな悪臭を探してるんだ。それが結構効果的なんだよね。時間が経つにつれてメンテナンスしないと、だんだんとごちゃごちゃになっちゃうのは想像できる。

それが別のモデルだってことは重要だと思う?それとも、レビューのプロセスやコンテキストのリセットの方が大事なのかな?

自分用の /review コマンドを作ってみて。.claude/commands/review.md に空のマークダウンファイルを作って、エージェントが確認すべき項目のチェックリストを入れておくんだ。コードをレビューしてもらう準備ができたら、/review と打つと、そのチェックリストが確認されて、修正したいことを計画して聞いてくれるよ。私のは「プランモードに入る。このブランチとメインの違いを調べる。考慮すべき点: ...」から始まって、箇条書きのリストが続くんだ。コードレビューで何か気づいたら、エージェントに直してもらうためにリストに追加するよ!今はリストが200項目くらいになってる。エージェントは、ただの一般的なフィードバックの壁をもらったって気にしないから、喜んで箇条書きを見てくれるんだ。「新しいものが他の場所にあるコードを重複していないか確認する」って追加したら、驚いたことに、ほんとにクリーンアップの計画を立て始めた!まだまだ始まったばかりだね。ツールにツールを与えて、私たちのためにもっと良いツールになれるようにしないと。

論理的にまとめられた複数のレビューに分ける実験をしてみるといいよ。私の仮説では、期待されるテキスト量のせいで信号が失われてるかもしれない。

いいね!フォーマットを含むコードサンプルのファイルがあって、それを参照として使うように頼んだんだ。君のアプローチを試して、コードを箇条書きにまとめてみるよ。

リストを共有してくれる?何が入ってるのか気になるな。私の場合、エージェントとのやり取りが多いけど、「自分の目と好みに合う」までやってる。でも、まだそんなリストは作ってないんだ。プロジェクトによって文脈が違うから、ちょっとした問題は許したり、魔法の数字を使ったりするけど、他のプロジェクトではエージェントに意味のある名前の定数を使わせるようにしてる。SECONDS_IN_A_DAY = 24 * 60 * 60

open-code-reviewを使った経験は良いよ: * https://github.com/alibaba/open-code-review https://layandreas.github.io/personal-blog/posts/beyond-vide...

Hacker Newsで議論の続きを見る