token-discipline

トークンの節約

コンテキストウィンドウには上限があります。ユーザーはトークンの料金を直接（API）または間接的に（プランの上限やレート制限）支払っています。あなたの仕事は、作業を完全にやり遂げると同時に、会話のコストを抑えることです。コンテキストの大半は、ファイル内容をそのまま繰り返したり、同じファイルを読み直したり、計画を文章として保持したり、フィルターしていないツール出力を大量に表示したりすることで無駄になります。これらは作業そのものではなく、ただの浪費です。

コンテキストは予算として扱ってください。思考や判断、差分に使いましょう。ノイズに使ってはいけません。

7つの習慣（「トークンが足りなくなりそうなとき」だけでなく、常に適用）

1. offset と limit を使って読み込む — ファイル全体を一気に読み込まない

Read ツールは、デフォルトで約2000行を読み込みます。ほとんどのファイルでそこまで必要ありません。大半のタスクで扱うのは10～50行です。

• 100行未満のファイル：全体を読み込みます。
• 100～500行のファイル：まず構造を確認し（シンボルに対して grep -n を実行）、次に offset と limit を使って必要な範囲だけを読み込みます。
• 500行を超えるファイル：全体を読み込んではいけません。まず場所を特定してから、必要な範囲を読み込みます。

編集したばかりのファイルを読み直すのは、ほとんどの場合誤りです。ハーネスがすでに変更を追跡しています。

2. 調査をサブエージェントに委任する — メインコンテキストを守る

回答するのに3回以上ファイルを読む必要がある作業は、サブエージェントに任せてください（読み取り専用の調査には Explore、複数ステップの調査には general-purpose）。サブエージェントは自身のコンテキストを使い、段落1つ分の報告を返します。

直接読み込まず、サブエージェントに任せるべき例：

• 「Xはどこで定義され、何から呼び出されていますか？」
• 「Yを処理するすべての箇所を見つけてください」
• 「Z用の既存ヘルパーはありますか？」
• コードベースでの「どこで／どのように実装されているか」を尋ねる、オープンエンドな質問全般。

その後、同じ検索を自分でも繰り返してはいけません。サブエージェントの報告を信頼してください。

3. 長い出力はパイプで絞り込む — 生の bash 出力をそのままコンテキストに入れない

長くなりそうな出力は、デフォルトで tail や head を使ってください。

• ビルドとテスト：... | tail -50
• 検索（find、ls -R、grep -r）：... | head -50
• 長いログ：... | tail -200、または最初に grep <pattern> を実行
• JSON 全体を整形表示しないでください。必要な値を抽出するには、jq '.field' にパイプします。

実際に必要な情報が画面を流れてしまうなら、出力全体は役に立ちません。出力元で絞り込んでください。

4. TodoWrite（または同等のタスクトラッカー）を使う — 計画を文章で保持しない

会話の中に複数ステップの計画を書くと、その後のすべてのターンで再び含められます。同じ計画を TodoWrite で管理すれば、コンパクトな構造1つに保持し、その場で更新できます。

ルール：「AをしてからB、その後Cをします」という番号付きリストを書くなら、代わりに TodoWrite に記録し、ステータスで参照してください。情報源は1つにします。

5. ツールを3～4回使うごとに、チェックポイントの要約を残す

1文で書きます。「auth.go:142 にバグが見つかりました。ガード節の条件が逆です。次に修正します。」こうすることで、コンテキストが圧縮されても状況を把握でき、後から参加した人も最初から調べ直さずに作業を再開できます。

これは作業予定の実況ではありません。判明した事実を明確に残すためのものです。

6. ファイル内容を繰り返さない — そのまま分析に進む

ファイルを読み込んだ直後に、その内容を言い直してはいけません。ユーザーはそれを見ることができる（または Read ツールの結果ですでに確認しています）。「ファイルの内容は次のとおりです：」のような前置きは省き、「問題は42行目にあります。x がシャドーイングされています」と分析から始めてください。

grep の結果、git log、find の出力についても同じです。要約を繰り返さず、作業に取りかかってください。

7. スキルシステム自体を活用する

スキルは説明をコンテキストに読み込みますが、本文は呼び出されたときにだけ読み込みます。そのため、200行のスキルドキュメントは、実際に呼び出されるまでは約30トークンしか消費しません。references/ 内のファイルも同様です。必要になったときだけ読み込んでください。詳しい手順は、SKILL.md 本文ではなく、参照ファイルに記載してください。

見つけ次第、すぐにやめるべきアンチパターン

• 編集後に再読み込みする。 変更に失敗した場合、Edit ツールはエラーになります。再読み込みは余計な心配です。
• 値を1つ確認するために設定ファイル全体を cat する。 grep -E '^KEY=' file を使ってください。シークレットをコンテキストに含めることも避けましょう。
• 同じファイルを3回のターンにわたって読む。 何度も戻ってくるなら、最初に適切な範囲を一度だけ読み、関連する行番号を書き留めてください。
• 元に戻せる作業の許可を求める。 編集、読み込み、テストは元に戻せます。そのまま実行してください。確認を求めるのは、破壊的な操作や共有状態に影響する操作に限ります。
• ターンの最後に複数段落の要約を書く。 2文までにしてください。差分がすべてを語ります。
• まとめて読めるのに、ファイルを順番に読む。 独立した読み込みは、ターンごとに1回ずつではなく、1つのメッセージ内で並列にツールを呼び出してください。
• 不要になったコンテキストを引きずる。 古い計画や、もう関係のない古いツール結果などです。会話が明らかに先に進んだら、古い話題に触れ続けないでください。

ユーザーが明示的に上限に達したと伝えたとき

「コンテキストが足りなくなってきた」「上限が近い」「動作が遅くなってきた」と言われたら：

1. 要点を絞ったチェックポイント要約（現在の状態、決定事項、次のステップ）を作成します。最初から読み直して再開できるだけの情報を盛り込んでください。
2. 作業中の詳細は、会話の文章ではなく TodoWrite やメモリファイルに移します。
3. 次の調査・探索ステップは積極的にサブエージェントに委任し、結果を会話の記録ではなく1段落の要約として受け取ります。
4. /compact（Claude Code）を使うか、チェックポイントを最初のメッセージとして新しいセッションを開始するよう提案します。

心構え

ツール呼び出しには、呼び出しそのもの、返される出力、セッションの残りの間コンテキストを占める分のコストがかかります。不要な400行の読み込みは、その後50ターンにわたってついて回ります。サブエージェントの1段落の要約も、その後50ターンにわたってついて回ります。

トークンあたりの シグナル密度 を高めましょう。重要なのは差分と決定事項です。それ以外はすべて余計な負担です。