Claude Codeの話題は、どうしても環境構築に寄りがちです。
CLAUDE.mdをどう書くか、Skillsをどう切るか、subagentをどう定義するか。私自身も複数リポジトリにCLAUDE.mdとSkillsを整備して、それなりの型を作ってきました。
ただ、しばらく使い込んで分かったことがあります。
成果物の質を一番大きく動かしているのは、環境ではなく毎回打ち込むプロンプトそのものでした。
環境整備は「下限を上げる」作業で、プロンプトは「その日の上限を決める」作業なんですね。
この記事では、私が実際に使っていて効果が明確だった打ち方を6つに絞って共有します。
1.「目的・場所・完了条件」の3点セットで書く
結果が安定するプロンプトには、だいたいこの3つが揃っています。
【目的】
セッションタイムアウト後にログインが失敗する問題を直したい
【場所】
src/auth/ のトークンリフレッシュあたりが怪しい
【完了条件】
再現する失敗テストを書いてから修正し、npm test が通ること
対して、うまくいかないときの自分のプロンプトを見返すと、たいてい「ログインのバグ直して」だけです。
これだと、Claudeはまず問題箇所を探すところから始めることになり、探索でコンテキストを消費した末に見当違いの場所を触ることがあります。
3点セットは長く書く必要はありません。上の例も3行です。
2.完了条件だけは、絶対に省かない
3つのうちどれか1つを選ぶなら、迷わず「完了条件」です。
・テストが通ること
・ビルドがエラーなく終わること
・スクリーンショットが指定の画面と一致すること
こうした「機械的に検証できる条件」を渡すと、Claudeは自分でテストを回し、失敗を読んで直し、また回す、というループを回してくれます。
ここが人間の手離れの分岐点です。
逆に完了条件がないと、Claudeは「もっともらしいコード」を書いた時点で完了を宣言します。
3.探させずに、参照先を指定する
Claudeに探索させるのは、コンテキストという有限な資源を消費する行為です。
行き先が分かっているなら、最初から指してあげたほうが速くて正確です。
・ファイルを直接渡す
「@src/auth.js」と書けば内容が読み込まれます。
・既存パターンを指す
「HotDogWidget.phpを参考に、同じパターンでカレンダーウィジェットを実装して」
・履歴を指す
「ExecutionFactoryのgit履歴を見て、このAPIがどう変遷したか要約して」
3つ目は意外に使えます。
「なぜこの実装になっているのか」は、コードだけ読んでも分からず、コミットログに答えがあることが多いからです。
あわせて、指示は否定形より肯定形にします。
「モックを使うな」より「実際のDBに接続する統合テストで」。
何を避けるかより、何をしてほしいかを書いたほうが、出力のブレが小さくなります。
4.「一度に一つ」と「修正2回でリセット」
Claude Codeで一番効く運用ルールが、この2つです。
まず、「一度に一つ」。
1つのセッションでタスクAをやり、途中で別件Bを聞き、またAに戻る。
これをやると、無関係な情報がコンテキストに溜まって、肝心の指示が埋もれていきます。話題が変わったら「/clear」する。
それだけで精度が戻ります。
そして、もう一つが「修正2回でリセット」。
同じ箇所を2回直させても直らないとき、原因はたいていClaudeの能力ではなく、そのセッションが失敗例で汚染されていることです。
「さっきの間違い」の記憶が積み重なって、正しい方向に進みにくくなっている。
3回目の修正指示を打つ手を止めて、「/clear」してから、その2回で分かったことを盛り込んだプロンプトを新規に書く。
遠回りに見えて、体感では圧倒的にこちらが速いです。
5.重さに応じて、モードを使い分ける
すべてのタスクにPlan Modeを使う必要はありません。
私は次のように切り分けています。
1文で説明できる変更
→ typo修正、ログ追加など。Plan Modeを飛ばして直接依頼。
複数ファイルにまたがる、方針が固まっていない
→ Plan Mode → Ctrl+Gでプランを直接編集。
「〜がどうなっているか調査して」系
→ subagentに委譲。
設計判断・トレードオフの検討
→ プロンプトに「ultrathink」を明記。
subagentへの委譲は、慣れると手放せません。
調査で読み込んだ大量のファイルが本体のコンテキストに乗らず、要約だけが返ってくる。大きなリポジトリほど効きます。
Plan Modeで生成されたプランは、そのまま承認せず、Ctrl+Gでエディタを開いて手を入れるのがおすすめです。
ここで方針を1行直すコストと、間違った実装が終わってから直すコストは、桁が違います。
6.細かいけれど効く、2つのこと
「/compact」はフォーカス指示付きで。
素の「/compact」だと、残しておきたかった設計判断が落ちることがあります。
「/compact API周りの変更と実行したテストコマンドに絞って」
のように、何を残すかを毎回書く。
これだけでも、コンテキスト整理後の精度が変わります。
もう一つは、画像を惜しまないこと。
エラー画面、崩れたUI、参考にしたい図。
スクリーンショットを貼るだけで済むものを、言葉で説明しようとして時間を溶かしていた時期がありました。
貼ったほうが速いし、正確です。
まとめ
改めて並べると、こうなります。
1.目的・場所・完了条件の3点セットで書く
2.完了条件だけは絶対に省かない
3.探させずに参照先を指定する
4.一度に一つ、修正2回でリセット
5.重さに応じてPlan Mode・subagent・ultrathinkを使い分ける
6.「/compact」はフォーカス指示付きで、画像は惜しまない
どれも仕組みを作る話ではなく、「次の1回から変えられる打ち方」です。
CLAUDE.mdの整備は一度やれば効き続けますが、こちらは毎回の積み重ねで効いてきます。
個人的には、2の「完了条件」とを意識し始めてから、Claude Codeとの付き合い方がはっきり変わりました。
参考
Best practices for Claude Code
https://code.claude.com/docs/en/best-practices
Common workflows
https://code.claude.com/docs/en/common-workflows
Context management
https://code.claude.com/docs/en/context-window