Claude Codeのベストプラクティス：実運用から得た知見

[オペレーターの視点] 私はコンサルティングブランドと、テキサス州プフルガービルにあるピックルボール施設Picklelandという2つの事業で、平日は毎日Claude Codeを使っている。このブログの公開パイプラインから、本番Worker上のコードレビューまで用途は様々だ。これはClaude Codeとは何かという入門記事ではない。数か月間、実際に使い続けた末に残った習慣と、コストの方が見返りより大きいとわかって手放した習慣についての話だ。

目次

目次を開く

• CLAUDE.mdはドキュメントではなくルールとして書く
• サブエージェントに委任するものと、自分のスレッドに残すもの
• コンテキスト管理は一度きりの設定ではなく日々の規律だ
• 一人でやらせてはいけないと学んだこと
• 出す前に検証する——Claudeの「完了」は主張であって事実ではない
• オペレーターとしての結論
• FAQ
  • CLAUDE.mdファイルには実際何を書くべきか?
  • Claude Codeの出力を再チェックせずに信用するタイミングはどう決めるのか?
  • Claude Codeに自分でコミットやプッシュをさせているか?
  • 最も時間を節約した習慣は一つ挙げるとすれば何か?

CLAUDE.mdはドキュメントではなくルールとして書く

私が書いたどのCLAUDE.mdも、最初のバージョンは長すぎた。そしてどれも時間とともに短くなっていき、長くなったことは一度もない。よくある間違いは、それをWikiページのように扱うことだ——背景、方針、「なぜこうしているのか」。Claudeはそのタスクに必要かどうかにかかわらず、セッションごとにファイル全体を読む。つまり指示でない段落はすべて、指示である段落と注意を奪い合うことになる。

編集を重ねて生き残るのは、もっと狭い範囲のものだ。厳格なルール——理想を言えばテストが強制するもので、静かに後退することがないもの——に加えて、本当に詳細が必要なケースのために、より長いドキュメントへのリンクを添える。「タイトルは60文字未満」は一行の価値がある。その上限がなぜ存在するのかという経緯は、ドキュメントへのリンクに値するのであって、Claudeが毎セッション読み返すファイル内の一段落に値するわけではない。

二つ目に追加したもの、そしてこれほど重要になるとは思っていなかったものは、すでに決着がついた事実の短いリストを一度だけ書き、それを再調査しないよう明示的に指示することだ。初期のClaude Codeは、数セッションごとに同じ誤検知——不安定なチェック、ビルド手順に潜む既知の癖——を再診断し、すでに私がたどり着いた結論を再導出するのにコンテキストを浪費していた。検証済みの事実を一行で記し、調査を再度開くのではなく先に進むようエージェントに指示することで、その空転時間はほぼゼロになった。私が使うルールはこうだ——同じ「実はそれは想定内だ」を二度説明したなら、それはチャットで三度目に打ち直すものではなく、事実としてCLAUDE.mdに記すべきだ。

サブエージェントに委任するものと、自分のスレッドに残すもの

スキル、スラッシュコマンド、サブエージェントについての決定フレームワークはすでに別記事で書いたので、ここでは繰り返さない。付け加える価値があるのは、実際にサブエージェントを起動する前に使っているオペレーターレベルのフィルターだ——「完了」がどんな状態かを一文で言えるか、そして中間ステップが自分のメインスレッドに残ったとして、本当にそれを読むだろうか?

両方の答えがノーなら——タスクの範囲が明確で、結果だけが欲しいなら——それはサブエージェント向きだ。この記事を12言語に翻訳するのが最もわかりやすい例だ。各翻訳は独立して検証でき、この並列化こそがコンテンツパイプラインが言語ごとに1つのサブエージェントを走らせる理由そのものだ。英語版の記事がこれで正しいかまだ判断している最中のスレッドに、12言語分の中間的なやり取りが散らかるのは絶対に避けたい。

タスクが進行中の推論を私自身が見届ける必要がある場合——第三の判断が第二の判断で明らかになったことに依存しているようなスキーマ変更——それは自分のメインスレッドに残す。実際に遭遇した失敗パターンは、それでもそういうタスクにサブエージェントを起動してしまい、きれいな要約を受け取り、その要約が肝心な唯一の詳細を落としていたせいで「待って、正確には何を見つけたの」と三回聞き直すことだった。同じ種類のタスクで二度それが起きたら、そのタスクの委任はやめる。

コンテキスト管理は一度きりの設定ではなく日々の規律だ

CLAUDE.mdは一度書いて忘れられがちな部分だ。コンテキストウィンドウは私が毎セッション管理している部分であり、実際に結果の良し悪しを決めているのはこちらだ。

• 編集させる前に読ませる。 Claude Codeは、完全な現在の状態を見ていないファイルに対してでも喜んで変更を提案してくる。中身をよく分かっている自信があるときでも、必ず先にファイルを読ませている——その「自信」が外れたことが十分にあったので、もう省略できるステップではない。
• 1つのセッションに無関係な仕事を2つやらせない。 デプロイ問題のデバッグに1時間費やした後にマーケティングコピーの執筆へ切り替えるスレッドは、その1時間分の無関係なツール出力を以降のすべての応答に引きずり込む。Claudeに「デプロイの件は忘れて」と頼む代わりに新しいセッションを始めている——その指示はトークンを取り除くわけではなく、モデルにそれを無視するよう頼んでいるだけで、しかも不完全にしか実行されない。
• 実行させる前に計画させる。 2、3ステップを超えるものについては、まず計画を求め、実行を承認する前にそれを読む。5行の計画を読むのは15秒で済む。5番目のステップがすでに走った後で3番目のステップが間違っていたと気づくのは、その日の午後全部を持っていかれる。
• 大量の貼り付けはコストであって便利さではない。 ログファイル全体やAPIレスポンス全体を会話に投げ込むと、実際に必要な3行以外の97%分のコンテキストを無駄に燃やすことになる。私はまずgrepしてから、一致した部分だけを貼り付ける。

これはAIエージェントのためのコンテキストエンジニアリング全般の背後にあるのと同じ原則だ——Claude Codeはただそのコストをより早い段階で可視化するだけだ。あとでWorkerのログをデバッグして気づくのではなく、コンテキストがリアルタイムで埋まっていくのを自分の目で見ることになるからだ。

一人でやらせてはいけないと学んだこと

コミット、プッシュ、公開、送信、支出といった取り消せない行動は、すべて私自身が実行する明示的な承認ステップの向こうに置かれる——Claude Codeがタスクを完了だと判断して勝手に踏み出すことは決してない。これは、エージェントが実際の結果に触れる場所ならどこでも使っているヒューマン・イン・ザ・ループのパターンと同じであり、Claude Codeがクラウドではなく自分のマシン上で動いているからといって例外にはならない。

もう一つやめたこと——破壊的なコマンドに対して幅広く恒久的な許可を与えることだ。rm -rf、強制プッシュ、テストフックのスキップ——どれも一括でイエスにはしない。それぞれ、その都度、その文脈の中で確認を求める。なぜなら「時間の節約のため」に幅広い許可を一度だけ事前承認したときこそ、まさにタスクがきちんとレビューしていなかった範囲にまで逸れていった唯一の例だったからだ。許可プロンプトにかかる5秒は、その代償に対する安い保険だ。

出す前に検証する——Claudeの「完了」は主張であって事実ではない

これが最も元を取った習慣であり、最も地味なものでもある。完了報告を信用しない。実際のチェックを自分で走らせる。

Claude Codeはビルドが通った、テストスイートが緑だ、リンクが機能すると言うだろう。その報告が本物の出力から生成されていることもある。半分しか走らなかったコマンドや、中に役立つものが何もないまま早期に返ったチェックについての、自信たっぷりな要約であることもある。この二つはチャットの記録の中では見分けがつかない。区別する唯一の方法は、自分自身で実際の出力を見ることだ——エージェントを出荷するために使っているエバル・ハーネスの背後にあるのと同じ規律だ。タスクはエージェントがそう言うから完了とみなされるのではなく、定義されたチェックが実際に通ったときに完了とみなされる。

実務上これが意味するのは——ビルドコマンドを自分で走らせて、Claudeの言い換えではなくその出力を読むこと。編集したと言っているファイルを開くこと。機能すると言っているリンクをクリックすること。コンテンツに関しては特に、Claudeが一回目で正しく適用したはずだと信じるのではなく、強制されているとわかっているルール——文字数制限、禁止パターン、壊れた内部リンク——に照らして敵対的に草稿を読み直している。なぜならたいていは正しく適用しているが、たまにそうでないこともあり、その稀なミスが実際のサイトに公開される代償は、読み直しにかかる90秒よりもはるかに高くつくからだ。

オペレーターとしての結論

これはすべて、時間とともにClaude Codeへの信頼を減らすという話ではない——その信頼が実際に稼がれるべき場所を正確に見定める話だ。長いドキュメントより、短くて強制力のあるCLAUDE.md。境界が明確で検証可能な作業はサブエージェントへ、推論そのものが結果と同じくらい重要な作業は自分のスレッドへ。引き延ばされたセッションより新鮮なコンテキスト。取り消せないものすべてに承認ゲートを。そして、委任した何かが本番に出る前に、自分自身が読んだ実際のチェックを。それが全リストであり、実際に私が実行しているものだ。

FAQ

CLAUDE.mdファイルには実際何を書くべきか?

エージェントが毎セッション従うべきルールを、指示として書く——コードベースがなぜそうなったのかという背景ではない。あるルールがテストによって強制されているなら、そう明記してテストを真実の源にする。より長い背景情報は、CLAUDE.mdがリンクするドキュメントに属し、タスクが実際にその領域に触れるときだけ読まれるべきで、毎セッション既定で再読み込みされるべきではない。

Claude Codeの出力を再チェックせずに信用するタイミングはどう決めるのか?

チェックを省略するかどうかを決めているのではなく、そのコストがどれくらいかを決めている。ビルドコマンドを自分で走らせるのはほぼ無料に近いので、常にそうしている。長いドキュメントの完全な敵対的読み直しはより時間がかかるので、実際の読者の前に出るものだけに取っておく。決して省略しないのは、取り消せないものすべて——公開、コミット、支出だ。

Claude Codeに自分でコミットやプッシュをさせているか?

いいえ。すべてのコミットとプッシュは、差分を自分の目で見た後で、自分自身が実行する。Claude Codeは変更を提案する側であり、草稿状態を離れるすべてのものについて、私が承認ゲートを務める。これは私が運用している他のどのエージェントにも適用しているのと同じルールだ。

最も時間を節約した習慣は一つ挙げるとすれば何か?

完了報告を事実ではなく主張として扱い、自分自身で実際のチェックを走らせることだ。一見すべてを遅くするように聞こえる。実際には逆だ——偽の「完了」を30秒で見つけるほうが、3日後に本番で見つけるより速い。

---

関連記事： Claudeのスキル・スラッシュコマンド・サブエージェント比較 · 30以上の本番エージェントを運用する私のエージェントスタック · ヒューマン・イン・ザ・ループAIエージェント：承認ゲートを設けるべきとき · Claudeのスケジュールタスクの使い方

自分のビジネスでもこんな風にClaude Codeを運用したいなら? 私のAI Agents for Beginnersコースは、このプレイブックが前提とするビルドの基礎をカバーしている。コワークプログラムは、こうした運用習慣を構造化されたグループで教える場だ。まずセットアップを代わりにやってほしいなら、30分のセッションを予約してほしい。