CODE IN TOKYO

Claude Codeをアホにしないためのリポジトリ設計

最近、Claude Codeを使っていて改めて思うことがある。

AIは賢い。

本当に賢い。

だが同時に、驚くほど騙されやすい。

そして騙されたことに気付かない。

人間なら、

「このコード古そうだな」

「このドキュメント更新されてないな」

と疑う場面でも、AIはわりと素直に信じてしまう。

その結果、

「なんでそんな実装した？」

というコードを書き始める。

最初はモデルの性能を疑った。

Opusが劣化したのか。

プロンプトが悪いのか。

そうゆうこともあるが、多くの原因はプロジェクト側だった。

AIはコンテキストの生き物

Claude Codeを長く使っていると分かる。

AIの性能はモデル性能だけでは決まらない。

むしろ、

与えられるコンテキストの品質

に強く依存する。

綺麗なプロジェクトでは驚くほど賢い。

散らかったプロジェクトでは驚くほどアホになる。

だから最近は、

「どうやってAIにコードを書かせるか」

よりも、

「どうやってAIが迷わない環境を作るか」

の方が重要だと思っている。

ADRを真実のソースにする

以前は会話だけで設計を進めていた。

Claudeと相談しながら実装していけば何とかなる。

実際、何とかなる。

問題は一か月後だ。

なぜそう設計したのか。

なぜこのライブラリを選んだのか。

なぜ別案を捨てたのか。

誰も覚えていない。

当然AIも覚えていない。

そこでADR（Architecture Decision Records）を残すようにしている。

大事なのは作ることではない。

更新することだ。

ADRと実装がズレた瞬間に、AIは過去の嘘を学習し始める。

そして全力で間違った方向へ走り出す。

AIにも地図が必要

ドキュメントを大量に作る人は多い。

私もそうだ。

だがドキュメントが増えると今度は探せなくなる。

人間ですら迷う。

AIが迷わないはずがない。

そこで最近はルートにインデックスファイルを置いている。

READMEでもいい。

INDEX.mdでもいい。

とにかく、

「何がどこにあるのか」

を最初に説明する。

Claude Codeにはまずそこを読ませる。

すると無駄な探索が激減する。

AIも人間と同じで、初見の巨大プロジェクトに放り込まれると迷子になるらしい。

古いコードは毒になる

これが一番痛い目を見た。

以前、ローカル環境用のモックコードを残していた。

もう使っていない。

ただ消すのが面倒だった。

するとClaudeがそれを発見した。

そして自信満々に言った。

「現在はこちらの仕組みで動いています」

動いてない。

半年以上前に捨てた仕組みだ。

だがAIから見れば、

リポジトリに存在する以上、それは現役選手なのだ。

このとき学んだ。

AIは存在しているコードを過大評価する。

だから不要なコードは残してはいけない。

人間向けの可読性だけではない。

AI向けの衛生管理でもある。

巨大なファイルは人間もAIも嫌い

最近はマイクロサービスまで行かなくても、

責任分解点

をかなり意識している。

一万行の巨大ファイルをAIに読ませても精度は落ちる。

人間でも嫌になる。

だから、

ここからここまでは認証。

ここからここまでは決済。

ここからここまでは通知。

という境界をなるべく明確にする。

するとAIが読む量が減る。

読む量が減ると精度が上がる。

結局、人間が理解しやすい設計はAIにとっても理解しやすい。

Slackやメールも知識になる

仕様変更はSlackで起きる。

重要な決定はメールで流れる。

会議の結論は議事録に埋もれる。

ところがAIはそれを知らない。

だから自動で収集してドキュメント化する。

重要な決定だけを集める。

そしてインデックスに登録する。

そうするとAIもプロジェクトの歴史を追えるようになる。

最近やっていること

とはいえ、いま書いていたことを毎回のログインで指示するのも面倒だ。

なのでClaude CodeのSkill機能を使って自動化する。

プロジェクトに入ったら自動的に実行されるようにして、

を最初に行わせている。

要するにAI向けのオンボーディングだ。

新しいメンバーがプロジェクトに参加したら、まず設計資料や運用ルールを読む。

それと同じことをAIにもやらせている。

面白いのは、この仕組みを導入してからAIの回答品質がかなり安定したことだ。

AIが突然おかしな実装を始める原因の多くは、能力不足ではなくコンテキスト不足だったりする。

さらに最近は、

「自分を賢く保つための改善案を出せ」

というSkillまで作っている。

するとAI自身が、

といった問題を見つけてくれる。

AIを使っているようで、半分はAIに管理してもらっている感覚だ。

結局、仕事が変わった

重要なのはプロンプト職人になることではない。

AIが迷わない環境を作ることだ。

ADRを整備する。

不要なコードを捨てる。

インデックスを作る。

知識を集約する。

そしてSkillを使って、その知識へ自動的に到達させる。

考えてみれば、優秀な新人が入社したときにやることと大差ない。

違うのは、その新人が人間ではなくAIだということくらいだ。

AI駆動開発の本質は、AIにコードを書かせることではない。

AIが正しい判断を下せる環境を整備することだ。

そして、その環境整備がうまくいくほど、AIは驚くほど優秀な同僚になる。

逆に言えば、散らかったリポジトリの中では、どんな高性能モデルでも迷子になる。

最近はコードレビューよりも、Claude Codeの職場環境改善をやっている時間の方が長い気がする。

案外、それが一番コストパフォーマンスの良い開発なのかもしれない。