Claude Codeは3回、私を悪いアーキテクチャの決定から救ってくれた。
「エージェントが私より賢かった」ということではなく、むしろ「計画を説明しなければならない状況が、欠陥を見つけさせてくれた」という感じだ。
N+1 クエリ
私はユーザーデータを読み込むダッシュボードを作っていました。私の計画は、ユーザーを取得してから、各ユーザーの最近の活動を取得する、というものでした。
これをエージェントに説明して実装を依頼したところ、『ユーザーデータと活動を1つのクエリで取得するためにJOINを追加しますか、それとも別々のクエリにしますか？』と聞かれました。
私は『とりあえず別々のクエリで、後で最適化できる』と答えました。エージェントは私の要望を実装しました。
しかし、その質問は引っかかった。ダッシュボードが1,000人のユーザーを抱える環境では、'今のところ'とはページの読み込みごとに1,001回のデータベース呼び出しを意味します。私は機能をリリースする前にJOINを指定しました。
エージェントは問題を見抜けませんでした。計画を文字通り実装する相手に説明する必要があると、私自身が問題を見ることになりました。
設定アプローチ
いくつかのハードコードされた値を含む機能を作っていました：レートリミット、リトライ回数、キャッシュのTTL。私の計画はそれらをハードコーディングして『後で設定可能にする』というものでした。
これをエージェントに説明すると、彼は『これらの値は環境変数、設定ファイル、または定数から取得するべきですか？』と尋ねました。
正解は設定ファイルだった—これらは環境間で変更する必要がある値でした。しかし私はそこまで考えていませんでした。『今は定数で』と答え、エージェントは定数を実装しました。 それから本番環境のデプロイを見て、そこの値が異なる必要があることに気づきました。
再び：有用な部分は答えではなく、質問そのものでした。
欠落していたエラーパス
私はサードパーティのAPI統合を追加していました。私の計画は、成功応答とネットワーク障害の両方を想定していました。これをエージェントに説明しました。
それは『APIが429のレート制限を返した場合、どうすべきですか？指数バックオフを実装するか、それとも失敗させて呼び出し元に対処させるか？』と尋ねました。
429については全く考えていませんでした。統合していたAPIは本番環境で過度なレート制限を課していました。この質問がなければ、レート制限に達したときに本番環境で黙って失敗する統合を出荷していたでしょう。
パターン
私は Claude Code が私よりアーキテクチャについて賢いとは言いません。私が主張したいのは、他者（あるいは別の存在）が実装できるだけの詳細を持つ計画を説明することが、普段見落としがちなギャップを自分で埋めるよう促す、ということです。
これらの3つの発見は、エージェントが考えた結果ではなく、私自身が自問していなかった明確化の質問をエージェントが投げかけたことから生じたのです。
それは『私の代わりにコードを書いてくれる』という価値とは別の性質のものです。むしろ『私が計画を説明する相手になること』です。
builtbyzac.comでClaude Codeを動かした経験から。
