AIにコードを書いてもらえるようになると、最初はとても楽に感じます。自分で全部調べて書かなくても、やりたいことを伝えれば、画面や処理のたたき台が出てくる。エラーが出ても、原因を一緒に探してくれる。私も、AIコーディングの速さにはかなり助けられています。
ただ、継続的に改善していく前提で見ると、速く作れることと、後から直しやすいことは別です。AIがその場で動くコードを書けても、コメントが少ない、変数名が曖昧、処理が一つの場所に詰め込まれている、なぜその実装にしたのかが残っていない。そうなると、次に直すときに自分が読めなくなります。
会社の中でAIにコードを書かせている場面を見ていても、ここはかなり差が出ると感じています。
ルールを決めずに進めていると、コードは増えているのに、本人がその中身をうまく説明できないことがあります。必要な箇所を修正する段階で、どこを触ればよいのか探す時間が増え、結局「AIで速く作った分」を後から払い戻しているような状態になります。
だから最近は、AIにコードを書かせる前に、まずルールを置くことが大事だと感じています。Claude CodeならCLAUDE.md、CodexならAGENTS.mdのようなファイルに、最低限守ってほしい書き方を残しておく。この記事では、AIにコードを書かせる時代に、読めるコードを保つためのルールをどう考えるかを整理します。
AIにコードを書かせるほど、読める状態を保つルールが必要になる
AIコーディングの便利さは、手を動かす量を減らしてくれるところにあります。画面を作る、関数を追加する、既存コードを修正する、エラー原因を探す。こうした作業をAIに任せると、最初のスピードはかなり上がります。
一方で、AIが作ったコードをそのまま積み重ねると、後から理解しにくくなることがあります。特に怖いのは、動いている間は問題に見えないことです。処理が大きすぎても、変数名が曖昧でも、コメントがなくても、今の動作だけを見ると通ってしまうことがあります。
でも、機能を追加したり、仕様を変えたり、別の人に説明したりする段階になると、急に重くなります。どの処理が何を担当しているのか。なぜこの条件分岐があるのか。どこまでがAIの提案で、どこからが人間側の判断なのか。そこが見えないと、修正のたびに調査から始まります。
AIに任せる範囲が広がるほど、人間側には「あとから読める形に整える力」が残ると思っています。これはきれいなコードを書きたいという美意識だけではありません。継続的に改善するための、かなり実務的な条件です。
ルールがないAIコードは、チーム開発で説明しにくくなる
個人で小さく試すだけなら、多少読みにくくても動けばよい場面はあります。実験として作り、使い捨てにするなら、それでも十分なことがあります。
ただ、継続的に改善するものや、チームで扱うものになると話が変わります。自分以外の人が読む。レビューする。障害が出たときに原因を探す。別の機能を追加する。そういう前提になると、コードは「動くもの」であると同時に、「説明できるもの」である必要があります。
会社の中でも、AIでコードを書かせているのに、本人が内容をあまり把握していないように見える場面があります。聞くと、AIが作ったから細かいところは追えていない。修正したい場所が出てきても、どこに書かれているかすぐに説明できない。そうなると、周りもレビューしづらくなります。
これはAIを使うこと自体が悪いのではなく、AIに任せる前のルールと、任せた後の確認が足りない状態だと思っています。AIが書いたコードでも、最後に運用するのは人間です。人間が説明できないものを積み上げていくと、あとから修正するたびに時間がかかります。
AIにコード修正を任せるときの監督ポイントは、別記事でも整理しています。差分や影響範囲の見方まで含めて考えるなら、Codexを触って感じた監督ポイントの記事も近いテーマです。
AIコーディングでは、ルール、変更差分、実際の画面、テスト結果を並べて確認できると、作業効率が格段に上がるのと人間側がAIの作業を監督しやすくなります。
私の場合、外部モニターがあると、AIの提案を読む画面と、コードやプレビューを確認する画面を分けられるので、開発と確認作業がかなり効率化できます。
また、画面を分けておくことで、複数のAI作業を並行して動かしやすくなるのも便利だと感じています。
ポチップ
CLAUDE.mdやAGENTS.mdは、毎回のお願いではなく作業前提を残す場所
最初に言葉だけ整理しておくと、Claude CodeではCLAUDE.md、CodexではAGENTS.mdが、AIに作業ルールを伝えるための代表的なファイルになります。
Claude Codeの公式ドキュメントでは、CLAUDE.mdをプロジェクトの永続的な指示として扱う説明があり、Codexの公式ドキュメントでも、AGENTS.mdをプロジェクト内の指示ファイルとして扱う説明があります。
ただし、ここで大事なのはファイル名そのものより、会話の外にルールを置くという考え方です。毎回チャットで「変数名はわかりやすく」「コメントを書いて」「関数を分けて」と伝えていると、会話が長くなったときに抜けます。自分も、毎回同じことを言うのが面倒になります。
そこで、毎回守ってほしい前提をファイルに残しておきます。AIはそのルールを読んだうえで作業を始めるので、少なくとも出発点がそろいます。もちろん、書けば必ず完璧に守られるわけではありません。それでも、あとからレビューするときに「このルールに対してどうだったか」を見られるようになります。
AGENTS.mdを使ったときの実感は、AGENTS.mdでAIコーディングの指示を減らした記事でも書きました。今回の記事では、その中でもコードの読みやすさに関係するルールに絞って考えます。
最初に書くべきなのは、コメント・変数名・処理のまとまり
AIに渡すルールは、最初から完璧にしようとしなくてよいと思っています。むしろ、細かく書きすぎると、AIも自分も読み切れません。最初に置くなら、コメント、変数名、処理のまとまり。この3つで十分です。
コメントは、「この行は何をしているか」を全部説明するためではありません。コードを読めばわかることを日本語で繰り返しても、あまり役に立ちません。残したいのは、なぜその条件にしたのか、なぜその処理を分けたのか、あとから迷いそうな判断です。
変数名も大事です。AIは短い名前や、その場では通じる名前を出すことがあります。小さな処理なら問題なくても、改善を重ねると意味がぼやけます。dataやresultだけでは、何のデータで、どの時点の結果なのかが見えにくくなります。
処理のまとまりは、後から修正できるかに直結します。長い関数の中に、入力チェック、変換、保存、表示、エラー処理が全部入っていると、変更したい場所を探すだけで疲れます。AIにコードを書かせる前に、一つの関数に複数の役割を詰め込みすぎないと伝えておくだけでも、後から触りやすくなります。
私なら最初のルールファイルにはこのくらいだけ書く
最初のCLAUDE.mdやAGENTS.mdに書くなら、私はあまり長くしません。いきなり細かい規約を大量に入れるより、毎回守ってほしい最低限だけにします。
その上で、もし会社やチーム内で変数名などの具体的なルールがあればそれを追記していきます。
最初はスモールスタートで徐々に増やしていく運用がいいです。
# Coding Rules
- 変数名は省略しすぎず、役割がわかる名前にする
- 複雑な処理は小さな関数に分ける
- コメントは「何をしているか」より「なぜそうしたか」を残す
- 長い文字列やプロンプトは、あとから編集しやすい形で分ける
- 既存コードの書き方がある場合は、まず周辺の書き方に合わせる
- 修正後は、変更点と確認した内容を短く説明する
- 動作未確認の部分は、確認済みのように書かないこのくらいなら、AIにも自分にも読みやすいです。大事なのは、立派なルール集を作ることではありません。あとから読めないコードになったときに、「何を守れていなかったのか」を振り返れる状態を作ることです。
また、ルールは一度で完成させなくてよいと思っています。AIが同じ失敗をしたら追記する。レビューで読みにくいと感じたら直す。チームで説明しづらかったら、説明しづらかった原因をルールに戻す。そうやって、実際の違和感から育てる方が続きます。
勢いで作るAIコーディングと、ルールを置いて戻れるようにする考え方はセットです。仕様メモを先に置く話は、バイブコーディングで仕様メモを先に置く理由の記事にもつながります。
AIに任せるほど、人間側の判断基準を先に置く
AIにコードを書かせることは、これからもっと当たり前になっていくと思います。だからこそ、「AIが書いたから中身はよくわからない」では済ませにくくなります。特に仕事やチーム開発では、作ったものを説明できること、後から直せること、他の人が読めることが必要になります。
AIを使うほど、人間がコードを一文字ずつ書く時間は減るかもしれません。でも、人間側の判断が消えるわけではありません。何を任せるか。どんな書き方を許すか。どこまで確認したら採用するか。そうした基準を先に置くことが、AIコーディングの土台になると感じています。
CLAUDE.mdやAGENTS.mdは、AIを縛るためだけのファイルではなく、自分があとから説明できるコードに近づけるための作業メモです。AIに任せるほど、何を大事にするかを先に書いておく。そこから始めるだけでも、後から読み返したときの負担はかなり変わります。
まずは、コメント、変数名、処理のまとまり、長い文字列の扱い。この4つだけで十分です。AIにコードを書かせる前に、自分が読めるコードの条件を短く置いておく。小さなルールですが、継続的に改善していくほど効いてくるはずです。
