Claude Codeを使っていて詰まった5つのこと

「Claude Codeを使えばなんでも作れる」という話をよく見る。

半分本当だと思う。でも残り半分は、「Claude Codeと格闘する時間」だった。

使い始めて1週間で詰まったことを、そのまま書いておく。同じところで詰まっている人の参考になればと思って。

1. 「何を指示すればいいか」がわからない

最初の一番大きな壁はここだった。

Claude Codeは高機能だけど、「何をお願いできるか」を知らないと使いこなせない。「サイトを作って」という指示は漠然としすぎて、意図と違うものが出てきやすい。

だんだん「Next.jsのApp Routerで、/about ページを追加して。スタイルは既存のホームページに合わせて」という形で具体的に指示できるようになった。最初の数日は「なんか違う」→「修正して」のループが多かった。

解決策: 指示は「技術スタック・ページ名・参照すべき既存ファイル」を含めると精度が上がる。

エラーが出たとき、「Claude Codeが間違えたのか」「自分の指示が悪かったのか」「そもそも環境の問題なのか」が最初はわからなかった。

X APIで403が出たときがそうで、キーが間違っているのか、権限設定の問題なのか、APIプランの問題なのか、3回くらい別の原因を疑った（結局は権限設定を変えた後にTokenを再生成していなかっただけだった）。

解決策: Claude Codeに「エラーの原因の候補を3つ挙げて、それぞれの確認方法を教えて」と聞くのが一番早かった。

Stopフック（Claude Codeが返答するたびに自動でgit pushする仕組み）を設定したとき、設定したのにしばらく動いていなかった。

Hooksはセッション開始時に読み込まれる。設定中のセッションでは有効にならない。これを知らずに「なんで動かないんだろう」と15分くらい悩んだ。

解決策: Hooks設定後は必ずClaude Codeを再起動する。

ブログ記事の表やコードブロックが崩れて表示された。本文は読めるのに表だけ壊れる、という中途半端な状態で、原因の特定に時間がかかった。

原因は2つ重なっていた。remark-gfm プラグインが入っていないことと、Tailwind v4のtypographyプラグインのスタイルが一部グローバルCSSに書かないと効かないこと。どちらも「設定ファイルを見れば一目瞭然」なことだったけど、何を見ればいいかわからないうちは迷った。

解決策: スタイルが効かないときは「Tailwindのバージョン・プラグインの設定・globals.cssの中身」の3点を確認する。

これが一番困った。

Claude Codeは自信を持って「はい、できます」と言うことがある。でも実際にやってみると途中でエラーになったり、別の方法を提案してきたりする。

嘘をついているわけじゃなくて、「やってみないとわからない部分がある」ということだと理解した。人間のエンジニアに頼むときと同じで、「見積もりより難しかった」はある。

解決策: 重要な機能は「まず小さく試す」。いきなり本番に組み込まない。

「Claude Codeがあれば簡単にできる」は、ある程度使い慣れた後の話だと思う。

最初の1週間は、「どうすればうまく使えるか」を学ぶ期間だった。その時間が無駄だったとは思わないし、むしろ「どう使うか」を考える力がついた気がする。

詰まり方にも個人差があると思うので、参考程度に。