AIコーディングが「余計なことをする」のには理由がある——CLAUDE.mdが19万スターを集めた話

AIが書くコードが「なんか違う」と感じる理由

AIコーディングアシスタントを使ったことがある人なら、一度はこんな経験をしているはずです。「ボタンの色を変えてほしいだけなのに、なぜかファイルが3つ増えた」「シンプルな処理を頼んだら、見たこともないライブラリが追加されていた」。これは腕の問題でも、プロンプトの書き方が悪いわけでもありません。AIが構造的に持っている傾向が原因です。

AIの研究者として知られるAndrej Karpathyは、LLM（大規模言語モデル）がコードを書くときに起こしやすいミスに一定のパターンがあると指摘しています。過剰な設計を好む、既存のコードスタイルを無視する、頼んでいない依存関係を追加する——この3つが代表的なものです。偶発的なバグではなく、モデルの学習データの構造から来る「癖」に近いものです。だとすれば、ミスが予測できるなら、あらかじめ防ぐことができるはずです。

その発想から生まれたのが、GitHubで19万スターを超えたCLAUDE.mdという1枚のファイルです。

CLAUDE.mdとは何か

CLAUDE.mdは、Claudeに対してプロジェクトのルールや制約を事前に伝えるための設定ファイルです。技術的な仕組みとしては、プロジェクトのルートディレクトリに置いておくと、Claudeがコードを生成する前にその内容を読み込みます。いわば「このプロジェクトでは、こういうコードを書いてください」という事前の申し送りです。

注目すべきは、その内容がKarpathyの観察から直接導かれている点です。「余計なライブラリを追加しない」「既存のパターンに従う」「シンプルな解決策を優先する」といった指示が、具体的な言葉で書かれています。これは「AIに気合いを入れさせる」ような曖昧な指示ではなく、AIが起こしやすいミスを一つひとつ潰していく設計です。

GitHubのスター数は、そのファイルを見た開発者たちが「これは使える」と判断した数を反映しています。19万という数字は、同じ悩みを抱えていた人がそれだけいたことを意味します。

「過剰設計」「パターン無視」「余計な依存」——3つの癖を理解する

Karpathyが指摘した3つの傾向を、非エンジニアにも伝わる形で整理しておきます。

過剰設計（Over-engineering）とは、シンプルに解決できる問題に対して、AIが複雑な構造を作ってしまうことです。たとえば「売上を合計する関数を書いて」と頼んだとき、将来の拡張性を考慮した抽象クラスやインターフェースを自動的に追加してくる、という状況です。プロとして「将来に備えた設計」を学習しているため、頼んでもいない先回りをしてしまいます。

既存パターンの無視は、プロジェクトにすでに存在するコードスタイルやファイル構成を参照せず、AIが独自のスタイルで書いてしまうことです。チームで使っているコードに、突然見慣れない書き方が混入します。

余計な依存関係の追加は、すでに標準機能で対応できる処理に対して、外部ライブラリを引っ張ってくるパターンです。「日付を整形したいだけ」なのに、moment.jsのような重いライブラリが追加されるようなケースがこれに当たります。

これら3つは、AIが「良いコードを書こうとした結果」起きていることです。悪意ではなく、過剰な善意が原因です。

非エンジニアの会社員にも関係する話

ここで「自分はエンジニアじゃないから関係ない」と思った方に、少し立ち止まって考えてほしいことがあります。

たとえば、企画部門の30代マネージャーがChatGPTやClaudeにExcelのマクロを書いてもらうケースを想像してください。「売上データをシートごとに集計するマクロを作って」と頼んだとき、返ってきたコードが想定より長く、見慣れないモジュールが含まれていたとします。動くかどうかも分からないまま、上司に「これどういうこと？」と聞かれる場面は、エンジニアでなくても十分起こりえます。

あるいは、人事部でPythonを少し使い始めた社員が、採用データの集計スクリプトをAIに書いてもらう場面。「簡単にお願いしたのに、なんか複雑なものが返ってきた」という経験は、コードを本業にしていない人ほど対処に困ります。AIが余計なことをする傾向を知っておくだけで、「シンプルに書いて」「既存のコードに合わせて」という一言を追加できるようになります。

この一言が、プロンプトの書き方ガイドで解説している「制約の明示」に当たります。AIへの指示は、何をしてほしいかだけでなく、何をしてほしくないかを書くことで精度が上がります。

CLAUDE.mdの発想を自分のAI活用に転用する

CLAUDE.mdの本質は「AIの癖を知った上で、事前に制約を渡す」という考え方です。これはコーディング以外の場面でも使えます。

以下は、CLAUDE.mdの代表的な指示内容と、コード以外の業務への転用例を並べたものです。

この表が示しているのは、「AIに指示を渡すときに制約を書く」という習慣の有効性です。「議事録を作って」ではなく「議事録を作って。既存のフォーマットを崩さず、追加の見出しは作らないで」と書くだけで、返ってくる結果は変わります。

ChatGPTの使い方を体系的に整理したChatGPTガイドでも触れているように、AIへの指示は「何をするか」と「何をしないか」の両方を書くことで完成します。CLAUDE.mdはその考え方をファイルとして形にしたものです。

19万スターが示すもの

GitHubのスター数は、技術コミュニティの「これは使える」という投票です。19万という数字を単純に「人気がある」と読むだけでは不十分で、その背景にある意味を考えると別の景色が見えます。

AIコーディングツールが急速に普及した結果、「使ってみたけど思ったより使いにくい」という経験をした人が急増しました。ツールの問題ではなく、AIの癖を知らずに使っていたことが原因です。CLAUDE.mdが広まったのは、その「なんか違う」という感覚に、具体的な言葉で答えを出したからです。

AI活用の次のフェーズは、ツールを使い始めることではなく、ツールの傾向を理解した上でうまく制御することに移りつつあります。CLAUDE.mdの普及は、そのフェーズへの移行を象徴する出来事の一つです。

まとめ

AIが余計なことをするのは、悪い道具だからではなく、「良くしようとする癖」を持っているからです。その癖が予測可能である以上、事前に制約を渡せば防げます。CLAUDE.mdはその考え方をシンプルな形で実装したファイルであり、19万スターはその発想への共感の数です。

エンジニアでなくても、AIへの指示に「やってほしくないこと」を一文加える習慣は、今日から試せます。あなたが毎日使っているAIツールで、最後に「余計なことをされた」場面はどこにあったでしょうか。