目次
- この記事の立ち位置
- 導入と最初の一手
- 使い方の基本：4つの操作単位
- 本番運用で分かった落とし穴
- 完了を確かめる4つの方法
- 1日の作業記録：何を直し、何を間違えたか
- 任せる作業と任せない作業の線引き
- 記憶と文脈の扱い
- 他のAIツールとの併用
- コストと速度の実際
- チームで使うときの取り決め
- 委任の費用は測らないと見えない
- まとめ
この記事の立ち位置
Claude Code の入門記事は多い。インストール手順とコマンド一覧は公式ドキュメントにすでに十分に書かれている。一方で、実際の本番環境で継続して使うと、入門記事が扱っていない種類の問題に当たる。
編集部は自社で9つのサイトを運用しており、その保守と改善に Claude Code を日常的に使っている。本記事はその運用から得た記録である。基本操作は簡潔に触れ、分量は「動いているように見えて動いていない」場面の見分け方に割く。
本文中の数値はすべて2026年9月20日時点の自社実測で、測定方法を各節に併記した。手順そのものは提供元の更新で変わるため、実行前に公式ドキュメントを確認してほしい。なお本記事は、うまくいった話より、うまくいったように見えて実際には動いていなかった話に重心を置いている。運用で時間を奪われるのは後者だからである。
導入と最初の一手
インストールと認証
Claude Code はクイックスタートの手順に沿って Node.js 環境にインストールして使う。認証はブラウザ経由で行われ、成功するとローカルに資格情報が保存される。
導入直後に確認しておくとよいのは、どの権限が有効になっているかである。編集部の環境では、クラウドサービスの操作権限が想定より狭く、後の作業で権限不足に当たったことがあった。具体的には、DNS レコードの編集はできるのに、リダイレクト規則の編集ができない、という状態だった。
権限は「できるはず」で進めず、最初に一度だけ確かめておくと、後の手戻りが減る。有効な権限や動作の設定は設定ファイルのリファレンスで確認できる。
作業ディレクトリの決め方
Claude Code は起動したディレクトリを基準に文脈を組み立てる。リポジトリの直下で起動するのが基本だが、複数のリポジトリにまたがる作業では、親ディレクトリで起動したほうが扱いやすい場面がある。
編集部の運用では、単一プロダクトの改修はそのリポジトリ内で、横断的な調査はホームディレクトリで起動している。
最初に用意すると効くもの
作業を始める前に、リポジトリに次の3つを置いておくと、指示の往復が目に見えて減る。
- プロジェクトの規約を書いたファイル。命名規則、禁止事項、デプロイ手順を書く
- 過去に踏んだ失敗の記録。同じ失敗を繰り返さないための材料になる
- 検証コマンドの一覧。何をもって完了とするかを明示する
3つ目が特に効く。完了の定義が書かれていないと、作業は「それらしいところ」で止まる。
使い方の基本：4つの操作単位
日常の使い方は、おおむね次の4つに整理できる。
1. 調べる
コードベースの構造を把握する、特定の実装箇所を探す、過去の変更履歴を追う、といった読み取り中心の作業である。
このとき効くのは、探す対象を具体名で指定することである。「認証まわりを調べて」より「auth.ts のトークン検証がどこで呼ばれているか」のほうが速い。抽象的な指示は探索範囲を広げ、時間とコストの両方を増やす。
2. 直す
バグ修正、リファクタリング、設定変更である。変更の範囲が明確なほど精度が上がる。
編集部の運用で効果が大きかったのは、修正の前に「何が壊れているかを再現する手順」を先に確定させることだった。再現手順がないまま修正に入ると、直ったかどうかが確かめられない。
3. 作る
新規のファイル、スクリプト、ページを作る作業である。既存の似たファイルを参照先として示すと、規約に沿ったものが出てくる。
4. 確かめる
テストの実行、実環境での検証、ログの確認である。本記事で最も分量を割く部分でもある。この4つ目を省くと、1から3の成果が本当に成果なのかが分からないまま積み上がる。
本番運用で分かった落とし穴
ここからが本題である。編集部が2026年9月20日の1日の作業で実際に踏んだものを挙げる。いずれも「エラーが出ない」ため、気づかないまま進む種類の問題である。
落とし穴1：検査が対象に届いていないのに合格が出る
ページの重複を検出する検査を、コンテナ内のパスに向けてホスト側から実行したことがあった。そのパスはホストには存在しない。検査は「0群 / 0ページ / 問題なし」と表示し、終了コード0で正常終了した。
存在しないディレクトリを検査していただけである。
対策は単純で、検査対象が0件のときは失敗として扱うようにした。合格の条件に「対象が1件以上あること」を含める。
落とし穴2：観測の窓が短くて、正常を異常と判定する
計測タグが発火しているかをブラウザで確認する際、ページ読み込み完了から2.5秒で判定していた。3つのサイトが「発火していない」と出た。
窓を9秒に広げたところ、3つとも正常に発火していた。2.5秒では送信リクエストが間に合っていなかっただけである。
0件を「無い」と読む前に、窓や範囲を変えてもう一度測る。これは計測全般に言える。
落とし穴3：検査は存在するのに、走っていない
自社サイトの1つで、アクセス解析が一度も発火していないことが分かった。HTTPの応答はすべて200で、監視も鳴っていなかった。
調べると、「解析タグが実際に発火するか」を確認する自動テストは以前から存在していた。走らせていなかっただけである。さらに、監視スクリプトの説明文には「解析が発火しない場合も200が返る」という例が書かれていた。例は書かれていたが、検査そのものは実装されていなかった。
検査を足すだけでは足りない。走る場所に埋める必要がある。
落とし穴4：一覧を取得したつもりで、途中で切れている
クラウドサービスの管理対象を一覧で取得し、10件と数えた。実際は26件あった。API の既定のページサイズで打ち切られていたのに、総件数と突き合わせていなかった。
見落とした中に自動デプロイが有効な設定が含まれており、後の操作で予期しないビルドが走る原因になった。
一覧を返す API は、総件数と突き合わせる。
落とし穴5：デプロイの成功を、動作の確認と取り違える
監視の仕組みに新しい検査を追加し、デプロイが成功したことを確認した。しかしその検査が実行時に例外で落ちていた場合、問題ゼロの記録と区別が付かない。記録には「問題なし」としか残らないためである。
実行ログを直接確認して、処理が完走し例外が発生していないことを見て、初めて確定した。
デプロイしたことと、動いていることは別の量である。
落とし穴6：テスト用のデータが原因で、存在しない不具合を見つける
配信される説明文にHTMLが混入していないかを検査したところ、94件が該当した。
原因を追うと、検査用に取得したデータをデータベースから取り出す際に文字数で切り詰めており、その切り口がHTMLタグの途中に当たっていた。完全なタグしか除去しない処理を通しても、切れたタグは残る。切り詰めていない全文で測り直すと、該当は0件だった。
不具合は検査対象ではなく、検査のためのデータ側にあった。
完了を確かめる4つの方法
上の6つに共通するのは、「終わったように見えるが終わっていない」という形である。編集部が実際に使っている確認手段を挙げる。
方法1：成果物の実在を見る
作業が完了したという報告ではなく、ファイルが存在するか、変更が記録されているか、コマンドが成功を返すかを見る。
具体的には ls でファイルの有無、git status で変更の有無、実行結果の終了コードを確認する。報告と実在は別の量である。
方法2：壊れた実物を対照に使う
検査が本当に欠陥を見つけられるかは、欠陥のある対象に当ててみないと分からない。
編集部の例では、過去に配信された壊れたバージョンが記録として残っていたため、それを対照に使った。新しい検査をそのバージョンに当てると4件が失敗し、正常なバージョンでは15件すべてが成功した。検査が両者を区別できていることが確認できた。
壊れた実物が残っていない場合は、意図的に壊したものを作る。設定ファイルに不正な値を入れて、検査が落ちることを確かめる。
方法3：ログで実行を確定させる
デプロイや設定変更の成功だけでは、処理が意図どおり動いたことにならない。
クラウドの実行環境であれば、実行ログを取得して、処理が完了したこと、例外が発生していないことを確認する。編集部では wrangler tail に相当するログ取得で、処理結果と例外の有無を見て確定させている。
方法4：基準値を先に知っておく
ある数値が異常かどうかは、正常値を知らなければ判断できない。
アクセス解析の例では、データ層に積まれる要素が2件なら外部スクリプトが読み込めていない状態、4件から5件が正常だった。この基準を知らないと、2件を見ても異常と気づけない。
数値を見る前に、正常ならいくつになるかを確かめておく。
1日の作業記録：何を直し、何を間違えたか
抽象的な注意点より、実際の1日の記録のほうが伝わることがある。2026年9月20日に編集部が Claude Code で行った作業から、性質の異なるものを抜き出す。
直したもの
全パスが404を返すサブドメイン。 独自ドメインの www 側が別のホスティングを向いたまま放置されており、トップページも記事URLもすべて404を返していた。転送の設定ファイルには www から本体への転送規則が書かれていたが、そのサブドメインが配信側のカスタムドメインとして登録されていなかったため、リクエストが配信側に届かず、規則は一度も評価されていなかった。設定は存在していたが、経路が繋がっていなかった。
一度も発火していなかったアクセス解析。 配信されているHTMLに、解析タグの識別子が置換されないまま残っていた。コード側には「置換されていなければ実行しない」という安全装置があったため、タグが暴発することはなく、代わりに計測が完全に止まっていた。HTTPはすべて200で、監視も鳴らない。実ブラウザで確認するまで、誰も気づいていなかった。
検索結果の説明文が全ページで同じだった問題。 1,007ページの説明文の先頭40文字が、すべて同一の定型文だった。しかもその後ろに元データの本文を継ぎ足していたため、区切り記号が連続して並んだだけの説明文になっているページがあった。検索順位の中央値は9位で1ページ目に入っていたのに、クリック率は0.7%だった。順位ではなく、表示される文面で負けていた。
間違えたもの
同じ日に、編集部自身が9件の測定ミスを出している。前節で挙げた6つに加えて、次の3つがあった。
ドメインの生存確認で、リダイレクト先を見ていなかった。 検索エンジンの結果ページから外部リンクを取り出す際、リンク先のURLを見ていたが、そのURLは検索エンジン側の中継URLだった。実際の遷移先を追わないと、どのサイトが表示されているか分からない。
多バイト文字を区切り文字に使ったスクリプトが、静かに空文字を返した。 検査対象のURLが空になり、すべての項目が「取得失敗」と出た。検査対象の欠陥ではなく、検査スクリプトの欠陥だった。
正規表現の非貪欲マッチが、挿入したブロックを途中で切断した。 HTMLに解析タグを挿入したあと、位置を調整しようとして、ブロック全体を1つの正規表現で扱わなかった。最初の終了タグまでしか一致せず、ブロックが2つに割れてHTMLが壊れた。24ファイルの妥当性を機械で検査するまで気づかなかった。
この記録から言えること
9件のうち、エラーメッセージが出たものは1つもない。すべて「それらしい結果」が返ってきて、確かめるまで正しく見えた。
確かめる手段を持たずに作業を増やすと、間違いは蓄積するが表面には出ない。作業の速度が上がるほど、確かめる仕組みの重要性が上がる。
任せる作業と任せない作業の線引き
Claude Code はサブエージェントを起動して作業を分担できる。ただし何を任せるかで結果が大きく変わる。
任せて機能する作業
仕様が閉じた機械作業である。具体的には次のようなものが該当する。
- 大量のファイルの読み込みと要約
- 同じ規則にもとづく反復的な編集
- 公開データの収集
- 検証コマンドの実行と結果の集約
いずれも「何をもって完了とするか」が事前に書ける作業である。
任せると壊れる作業
判断を伴う作業である。編集部の記録では、47都道府県の公的制度を調べる作業を並列のエージェントに任せたところ、成果がゼロで終わった事例がある。指示に不足があり、各エージェントがさらに別のエージェントを起動して、結果を返さないまま終了していた。
作り直した際は、エージェントに任せず、機械的に検証できるスクリプトに置き換えた。出典のURLが実際に200を返すか、本文にその制度名が含まれるか、公的ドメインかを機械で確かめる形にしたところ、9件の誤りを事前に弾いた。
判断が必要な部分は自分で解き、閉じた作業だけを任せる。この線引きが最も効いた。
任せた結果の確かめ方
任せた作業が完了したという報告は、完了の証拠にならない。方法1で挙げたとおり、成果物の実在で確認する。
記憶と文脈の扱い
Claude Code は作業の文脈を保持するが、長い作業では文脈が上限に達する。ここで効くのが、メモリと CLAUDE.mdによる外部に記録を持つ設計である。
編集部の運用では、記録を3つの層に分けている。
- リポジトリ内のドキュメント。これが正典であり、最も詳しい
- 失敗の記録。同じ種類の問題を繰り返さないための索引
- 横断的な教訓。どのリポジトリにも属さない規律
分けている理由は、毎回すべてを読み込むと文脈を圧迫するためである。作業に関係するものだけを開く運用にしている。
記録には上限を設けている。1件が長くなりすぎると読まれなくなるためで、上限を超えたものはリポジトリ側のドキュメントに移し、記録はそこへのポインタだけを持つ形にしている。
実務上の注意として、記録は増やせば増やすほど効くわけではない。規則を8つ目に足した時点で、1つ目から7つ目までが読まれる確率も下がる。書く前に、それが本当に行動を変える記録かを考える価値がある。
コストと速度の実際
料金表は公式の料金プランページが更新するため本記事では扱わないが、運用で効いた「どこに費用がかかるか」の構造は書ける。
費用の大半は出力ではなく読み直しにある
編集部が自社の利用状況を集計したところ、消費の大半は新しく生成する文章ではなく、すでにある文脈を読み直す分だった。長い作業を続けるほど、毎回の応答で過去のやり取り全体を読み直す量が増えるためである。
この構造が分かると、削るべき場所が変わる。出力を短くするより、文脈を短く保つほうが効く。
文脈を短く保つ3つの運用
1つ目は、作業の切れ目で文脈を整理することである。ひとつのまとまった作業が終わったら、そこまでの経緯を要約して、以降はその要約を土台にする。
2つ目は、巨大な出力を文脈に入れないことである。画像や長いログをそのまま貼ると、以降のすべての応答でそれを読み直すことになる。ファイルに書き出して、必要な行だけを読む形にする。
3つ目は、読み込みを伴う作業を別の文脈に逃がすことである。大量のファイルを読む調査は、結果の要約だけを受け取る形にすれば、元の文脈は汚れない。
速度で効くのは指示の具体性
体感の速度差は、利用できるモデルの性能より指示の具体性で決まる場面が多い。探す対象をファイル名や関数名で示せば数秒で終わる作業が、抽象的な指示だと探索に数十秒かかる。
編集部の運用では、作業を頼む前に「対象のファイルはどれか」「完了の条件は何か」の2つを書けるかを自問している。書けない場合は、まず自分で調べたほうが速い。
チームで使うときの取り決め
個人で使う場合と、複数人が同じリポジトリで使う場合では、必要な取り決めが変わる。
何を人の確認にかけるか
編集部では、確認を必要とする操作を有限の一覧で定めている。共有ブランチへの反映、本番環境への適用、第三者に届く送信、再生成できないデータの削除、費用と鍵に関わる操作、対外的な文面の変更の6つである。
重要なのは、一覧を有限にしたことである。「重要な操作は確認する」という書き方だと、何が重要かの判断が毎回発生して止まる。一覧に載っているかどうかだけで判定できる形にすると、載っていないものは進めてよいと決まる。
他の作業者の変更を壊さない
同じリポジトリで複数の作業が並行すると、未コミットの変更を巻き込む事故が起きる。編集部でも、自分の変更をコミットする際に、別の作業者が編集中のファイルを一緒に含めてしまった例があった。
対策として、変更をコミットする前に対象を明示的に指定し、一括で全部を含めない運用にしている。また、ファイルが読み込み後に変更されていた場合に警告が出る仕組みは、意図しない上書きを実際に防いだ。こうしたイベント駆動の自動チェックはHooksの仕組みで組める。
記録の置き場を決めておく
誰がどこに記録を書くかを決めていないと、同じ内容が複数の場所に分散する。編集部では、製品固有の知見はそのリポジトリの中に、どのリポジトリにも属さない横断的な規律だけを共通の置き場に、と分けている。
分け方の基準は「その記録を必要とする人が、どこを見に来るか」である。製品を触る人はそのリポジトリを見る。だからそこに置く。
他のAIツールとの併用
Claude Code だけで完結するわけではない。編集部では作業の性質に応じて使い分けている。
使い分けの基準
コードベースの操作と、コマンドを伴う検証には Claude Code を使う。ファイルの読み書きとコマンド実行が同じ文脈の中で完結するためである。
資料の読み込みと整理には別のツールを使うことがある。外部のデータソースやツールと接続する構成にはMCPサーバー連携の仕組みを使う設計もある。大量の資料から要点を取り出し、出典を保ったまま参照する用途では、資料を中心に据えた設計のツールのほうが扱いやすい。
表計算やドキュメントの作成が主目的の場合は、その環境に統合されたアシスタントのほうが往復が少ない。
併用で注意する点
同じ作業を複数のツールで並行して進めると、どちらの結果が最新か分からなくなる。編集部では、変更を加える作業は1つのツールに集約し、他は読み取りと下調べに限定している。
もう1点、ツールを導入したこと自体は成果ではない。使われているか、効果が測れているかは別に確かめる必要がある。編集部の横断調査では、9サイトのうち3サイトで解析タグが設置されておらず、1サイトでは設置されていても一度も発火していなかった。導入と稼働は別の量である。
委任の費用は測らないと見えない
作業を別のセッションへ委任する使い方は便利だが、費用の構造が見えにくい。
編集部で30日分の利用を集計したところ、委任先からの要求が38,546件あり、そのうち36%が自動化した処理の連鎖から発生していた。個々の委任は小さく見えても、連鎖すると量が積み上がる。
消費の94%は読み直しだった
同じ集計で分かったもうひとつのことは、消費の内訳である。
出力の生成に使われたのは全体の6%で、残りの94%は文脈の読み直しだった。 費用を下げたければ、出力を短くするより、同じ文脈を何度も読み直さない構成にするほうが効く。
これは直感に反する。「長い回答をさせると高くつく」と考えがちだが、実際には同じ会話を延々と続けることのほうが高くつく。会話が長くなるほど、次の一手のたびに過去のすべてを読み直すためである。
実務的な対処は3つ
作業の切れ目で文脈を圧縮する。 1つの課題が終わったら、次の課題を同じ会話で始めない。
巨大な出力や画像を主たるセッションに入れない。 一度入ると、その会話が終わるまで読み直され続ける。大量の読み込みが必要な作業は、別のセッションに切り出して要約だけ受け取る。
模型の選択を作業の性質に合わせる。 機械的な作業に高価な模型を使うと、差は量で効いてくる。委任時に模型を明示していなかったために、上位の模型が機械作業を処理していた、という記録がある。
離席する前に圧縮する
もうひとつ、測って分かったことがある。時間を置いてから会話を再開すると、費用が跳ねる。
一定時間が経過すると、それまでの会話を保持していた仕組みが解放される。再開時には全文を再度読み込むことになる。60分以上あけて再開した714件で、3億8000万トークンの再書き込みが発生していた。
席を立つ前に、作業の区切りをつけて文脈を圧縮しておく。それだけで避けられる。
まとめ
Claude Code の基本操作は、調べる・直す・作る・確かめるの4つに整理できる。このうち4つ目を省くと、成果が成果かどうか分からないまま積み上がる。
本記事で挙げた6つの落とし穴は、いずれもエラーを出さない。検査が対象に届いていない、観測の窓が短い、検査は存在するが走っていない、一覧が途中で切れている、デプロイ成功を動作と取り違える、テストデータ側に原因がある。共通するのは、確かめずに結果を意味へ翻訳していることである。
確かめる手段は4つ挙げた。成果物の実在を見る、壊れた実物を対照に使う、ログで実行を確定させる、正常値を先に知っておく。いずれも特別な道具を必要としない。
任せる作業は、完了の定義が事前に書けるものに限る。判断を伴う部分は自分で解く。この線引きが、運用上いちばん効いた。
明日から試せる3つ
本記事の内容を一度に取り入れる必要はない。効果が出やすい順に3つ挙げる。
1つ目は、完了の条件をリポジトリに書くことである。どのコマンドが成功したら完了かを1行で書いておく。これだけで、作業が「それらしいところ」で止まるのを防げる。
2つ目は、検査が0件を返したときに失敗として扱うことである。対象が見つからないまま合格するのが、最も気づきにくい壊れ方である。
3つ目は、壊れた状態を1つ手元に残しておくことである。新しい検査を書いたとき、それに当てて落ちることを確かめる。落ちなければ、その検査は何も見ていない。
検証の記録を残す
最後に、確かめた結果を残すことを勧めたい。編集部では、失敗の記録をリポジトリ内に蓄積し、同種の作業を始める前に検索する運用にしている。同じ失敗を2回踏むコストは、記録を書くコストより大きい。
記録に書く内容は、何が起きたかと、なぜ最初に気づけなかったかの2つである。後者が抜けると、次に同じ状況に置かれたときに再現できない。
編集部では、AI導入の相談や、導入後に効果が測れているかの点検も行っている。本記事で挙げたような「動いているように見えて動いていない」箇所の洗い出しについては、サービス案内を参照してほしい。
参考にした一次資料
- スラッシュコマンドの公式ドキュメント — コマンドによる操作の仕様
- Claude Code の GitHub リポジトリ — ソースコードとリリース情報
- Model Context Protocol 公式サイト — MCP の仕様とエコシステム
- Anthropic「効果的なエージェントの作り方」 — エージェント設計に関する一次資料
- ツール利用の仕組み — Claude のツール呼び出しに関する公式仕様
よくある質問
Claude Codeは無料で使えますか。料金はどうなっていますか。
Claude の有料プラン（Pro・Max）に含まれる形と、API の従量課金を使う形があります。編集部の運用ではサブスクリプション側で日常の作業を回し、長い文脈を一度に扱う必要がある場面だけ別枠を使い分けています。プランの詳細と価格は提供元の公式ページで最新の条件を確認してください。本記事では価格そのものではなく、どの作業をどちらで回すかの判断基準を扱います。
Claude Codeが「完了しました」と言ったら、作業は終わっていますか。
終わっているとは限りません。編集部の実測では、デプロイが成功してもコードが実行時に例外で落ちていれば記録に残らず、成功と区別が付かない事例がありました。確定させるにはログを直接見る必要があります。本記事の「完了を確かめる4つの方法」で、実際に使っている確認手順を挙げています。
エージェントに作業を任せると品質が落ちませんか。
作業の種類によります。編集部の運用では、仕様が閉じた機械作業（大量の読み込み、反復的な編集、データ収集、検証の実行）は任せ、設計判断や根本原因の特定は任せない、という線を引いています。実際に判断を伴う調査を並列のエージェント6体に任せて全滅した記録があり、その後は委任の範囲を狭めました。
この記事の内容はどこまで検証されていますか。
本文中の数値は、編集部が自社で運用する9サイト（AIコンパス、カンタン補助金、弁護士みつかるほか）での実測です。2026年9月20日時点の測定値で、測定方法は各節に併記しています。ツールの仕様は更新されるため、手順は実行前に公式ドキュメントで確認してください。