Claude Code 実戦運用ガイド ― エージェントを2年回して分かった8つの勘所

「Claude Code の使い方」記事の多くは、npm install とファイルを編集するスクリーンショットで終わります。それは最初の5分の話です。この記事は、その後の2年の話です。

私は Claude Code を主力の開発エージェントとして、数百件のマージ済み PR で回してきました。比較のために Codex と Cursor も併走させ、対象は1ファイルの CLI から、もう単一のコンテキストウィンドウに収まらないリポジトリまで。どこかの時点でこれは物珍しさではなく、インフラになりました。ちょうどその頃から、鋭利な角が問題になり始めます。本ガイドはその地図です。8つの章、それぞれが「いま私が信頼している数字」を生んだ検証記事へのリンクで構成されています。90秒で見出しだけ追うことも、半日かけて全リンクを巡ることもできます。

1. どのエージェントを選ぶか

正直な答えは「1つに絞らない」で、その根拠は手元にあります。

Claude Code・Cursor・Codex を1日並列で走らせて判断回数を数えたら412回でした。複数エージェントを同時に回すコストは、サブスク料金ではありません。あなたの注意力です。その412回を、ハーネスの設計で400回から40回まで削った実測が、この章の核心です。どのツールが「勝つ」かはタスク次第で、だからこそ1つに絞る判断そのものがコストになります。

なお、Claude Code と Codex を正面から比べた47 PRのベンチマーク(3.4倍のコスト差)は英語版に詳しくまとめてあります。日本語ではまず「併用したうえで、いつどちらに振るか」を軸に読むのが実用的です。

2. 実際いくらかかるのか

表示価格と実コストは別の生き物で、その差で人はつまずきます。

サブスク・API従量・ローカルモデルのどれを選ぶかは、損益分岐点として計算しました。短く言えば、ある token 閾値を越えるまではサブスクが勝ち、多くの人はその閾値を思っているより後で越えます。例外は並列化です。エージェントをファンアウトさせると token 消費は線形でなくなり、損益分岐点が大きくずれます。3ヶ月後に自分が実際に持つワークフローを基準に予算を組むのがいいでしょう。

3. CLAUDE.md とコンテキスト設計

Claude Code はコンテキストウィンドウの中身で生き死にが決まり、その調整の大半は1つのファイルで起きます。

まず直感に反する発見から。コンテキストを足すほど速く賢くなるわけではありません。/clear せず9時間動かした日、コンテキストがどこで腐り始めたかを追いかけると、劣化の起点が見えます。長時間セッションの腐りに対してはcompact-ops というプラグインを作って自分に67%警告を鳴らさせたのが実務的な対処でした。

設計の分岐としては、AGENTS.md と CLAUDE.md の違いは「専用機か汎用機か」ではないという3ヶ月使い分けた実感が土台になります。そして CLAUDE.md の書き方自体が事件で変わることもある。Shai-Hulud 事件で CLAUDE.md の書き方が変わった話は、セキュリティ観点からの見直しの記録です。

4. Skills ― 腐らない再利用ワークフロー

Skills は、Claude Code を「賢い補完」から「運用者の道具」に引き上げた機能です。ただし、実運用で生き残るものを見分けてから、の話です。

回るパターンはSkills を10個書いたら4個に統合されたに整理しました。回り始める瞬間と回らない瞬間がある。そして書いた skill の多くは発火しません。発火しなくてもトークンを食うという計測は、成功例より多くを教えてくれました。出す前に skill の良し悪しを測る話は、107本の SKILL.md を lint したら稼働中の21本が「壊れてる」と言われたに続きます。

5. サブエージェントとマルチエージェント・ハーネス

ここで Claude Code はチャットであることをやめ、システムになります。そして面白い失敗が住んでいるのもここです。

最初に作ったのはレビューの合議でした。3人のサブエージェントに同じ PR を見せたら4割の指摘で意見が割れた。その食い違いこそが機能でした。本番のハーネスはObserver / Strategist / Marketer の3役分離に落ち着き、それぞれに狭い仕事を割りました。

そこから良い方向に変になります。他のエージェントを監査する4層目を足したら、Strategist が3週間サボっていたことが発覚しました。さらに7本のエージェントを cron で回したら2本が18日間沈黙していて、observability では拾えず exit-code 契約で拾えた。これは「艦隊を作る前に監査役を作れ」という私の最良の論拠です。

6. 演技ではないAIコードレビュー

エージェントにコードをレビューさせるのは簡単です。「ちゃんと」レビューさせるのは、トークンとコンテキストの問題です。

素朴なやり方は予算の大半を無駄にします。AIレビューがトークンを80%焼く問題を Tree-sitter + MCP で8〜49倍削減したのが最初の突破口でした。変更の blast radius だけをレビュアーに渡す発想です。同じ考え方で、ナレッジグラフでレビュー範囲を9割削るを実PR30件でトークンと時間を測って確かめました。

7. MCP と物理世界

MCP は Claude Code がリポジトリの外に手を伸ばす方法で、外に手を伸ばすところこそ安全柵が最も要ります。

いちばんタクタイルな例から。Claude Code MCP でハードウェアを制御し、UART/I2C/SPI/RS-485/CAN の5プロトコルを実測しました。作った中でいちばん綺麗だったのはOpenCut classic を fork して MCP サーバーを入れた一件で、踏んだ4つの罠付き。いちばん怖かったのは逆で、Claude をカオスエンジニアリングの MCP に繋いだらステージングを4回殺したものの、6ヶ月見逃していた本番バグを見つけました。

8. デバッグ・TDD・誰も読まない安全設定

最後の章は、あなたが午前2時に必要になるやつです。

Claude Code は、放っておくと自分のミスを堂々と隠します。3回連続でバグを「隠す修正」を出してきたので、デバッグ10の技法をプロンプトに翻訳して止めました。そして、あなたを実際に守る設定の話。「とりあえず全部許可」は便利ですが、.env の秘密がそのまま Anthropic に渡る経路があります。auto mode を本番に触れる何かで有効にする前に、これは読んでおいてください。認証まわりでは複数アカウントで気づいた2ファイル認証の構造を押さえておくと事故が減ります。

次に読むもの

多くの人は次の3つのどれかで来ます。安上がりなルーティングを置いておきます。

• まだツールを選んでいる。 1章 → 2章。銘柄で選ばず、タスクで選び、コストの計算で裏を取る。
• 毎日使っているが、なんだか不安定。 ほぼ確実に3章がボトルネックです。プロンプトいじりより、コンテキスト調整のほうが効きます。
• チャットではなくシステムを組む段階。 5章と8章を一緒に。ハーネスを組み、それを監視する監査役を組んでから、無人で信頼する。

長編版が欲しければ、2行から100行までの CLAUDE.md パターン、Plan Mode ワークフロー、チーム運用、そして意外だった非コーディング用途まで、すべて 実践 Claude Code に入れてあります。地図ではなく、実際のプレイブックのほうです。

このピラーは検証記事を書くたびに更新します。下にぶら下がる記事は元の日付のまま。地図は改訂され、地形は動き続けます。