かつて固定するしかなかったルールが、いまは削れる

実物のルールを1本見てみます。Claude Code 初期のシステムプロンプトでは、コメントについてこう書かれていました。

In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.

当時、このルールは必要でした。Claude Code が出たばかりの頃、いちばん大事だったのはモデルにやらかさせないこと — たとえばファイルを消させないことです。だからかなり強い指針を出す。その指針が常に正しいわけではないとしても。コメントの件はまさに「常に正しくない」側でした。自分でドキュメントを書く習慣のあるユーザーもいるし、とても複雑なコードには複数行のコメントブロックを付けるべきです。ただ当時のモデルは、こう止めておかないと、書くコメントの大半が間違っていた。一部の人を巻き込むと分かっていても、そう決めるしかなかったのです。

新世代モデルの判断力は足りるようになったので、もう巻き込む必要はありません。同じことが、いまのシステムプロンプトでは一文だけです。

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

当時のガードレールは、最悪のケースを避けるために立てたものです。最悪のケースが起きなくなったら、ガードレールは外し、周囲の文脈とモデル自身の判断に任せるべきです。

互いに矛盾する3つの指示が、同じリクエストに同時に現れる

ルールを削るには、もっと実務的な理由もあります。自社チームが Claude Code を使った会話ログを読んで、1回のリクエストにケンカする文がいくつも同時に出てくると気づいたのです。

3つの文が同じコンテキストに詰められて送られます。この3つは Anthropic が作った例示で、実際の原文ではありません。画像出典：Thariq / X

Claude はふつう、あなたが本当は何を求めているか当てられます。ただし、この矛盾する数文をまず調停しないと、何をするか決められません。スキルに制約を1本足すのはタダだと思っているかもしれませんが、実際は1本足すたびに、どこか別の場所で別の1本とぶつかる可能性があります。そして調停には手間がかかります。

8割削っても点が落ちなかった理由もここにあります。削られたのは場所を取る文字だけでなく、それらが生み出していた矛盾もだからです。

時代遅れになった6つの旧作法と、その置き換え

Thariq は、長く語り継がれてきたが今は成り立たない作法を6つ挙げ、1本ずつ置き換えを示しました。

1つ目は前で片付きました。残り3つはそれぞれ1節を取るので、まず軽い2つを済ませます。

繰り返し念を押す → シンプルなツール説明

以前の Claude モデルは、同じことを何度か言わないと覚えられないことがありました。しかもコンテキストの末尾の話は耳に入りやすく、冒頭は入りにくかった。だから昔はシステムプロンプトでツールの使い方を一度書き、ツール説明にもう一度書いていました。いまはこの重複を削り、使い方はツール説明にだけ書きます。

記憶は CLAUDE.md に書く → 自動記憶

以前は # のショートカットで、覚えてほしいことを自動的に CLAUDE.md に書き込む使い方でした。いまは Claude 自身が、今回の作業やあなた自身に関する記憶を保存します。手でファイルに詰め込む必要はありません。

サンプルはもういい、ツール自体の設計を明快に

これまでモデルにツールを教えるとき、鉄則の1つ目はサンプルを多く見せることでした。ところが最新世代のモデルでは、サンプルがかえって探索空間を狭く縛ってしまうと分かった。いくつか使い方を挙げると、その周辺だけを回るのです。

同じ TodoWrite ツールの説明で、左が改修前、右が改修後。右の文末は省略記号で、いまの説明には続きがあり、図は冒頭だけを示しています。画像出典：Thariq / X

サンプルに代わるのはインターフェース設計 — ツール、スクリプト、ファイルそのものを明快に設計することです。鍵はパラメータで、どんな値を取れるかが、それ自体で使い方を語るべきです。

TodoWrite がその例です。status フィールドの値は3つだけ：pending、in_progress、completed。この列挙型があるだけで、モデルに使い方が伝わります — タスクにはこの3状態があり、それ以上でも以下でもない。要件もサンプルは不要で、「同時に in_progress のタスクは1つだけ」の一文で足ります。

この立場は1年前とは変わりました。Anthropic の2025年のコンテキストエンジニアリング記事では、サンプルについて「サンプルの提供、すなわち少数ショットプロンプティングは、我々が一貫して強く推奨する定番のベストプラクティスである」と述べていました。当時反対されていたのは、プロンプトに長いエッジケースの列を積むことだけです。モデルが1世代進んで、サンプル自体が推奨項目から制約項目に変わりました。

全部を冒頭に書く必要はない、使うときに読み込む

Claude Code は初期はコーディング専業だったので、システムプロンプトにコードレビューのやり方や検証のやり方の詳しい説明が詰め込まれていました。大半の場面では使いませんが、本当に必要なときは決定的な情報なので、ずっと場所を取り続けていた。

いまの解き方は、必要なときに出てくるようにすること。コードレビューと検証はそれぞれ独立したスキルに移され、Claude が必要なときに呼びに行きます。この作法を段階的開示（progressive disclosure）と呼びます。必要な部分だけを、そのときに読み込む。

同じやり方はツールにも使われています。Claude Code が今つないでいるツールは以前よりずっと多く、一部は遅延読み込みです。ふだんコンテキストには名前が1つあるだけで、モデルはまず ToolSearch で完全な定義を検索しないと呼び出せません。検索しない間、そのツールが占めるのは名前1行分で、数千文字におよぶ完全な説明は入ってこない。入ってこないからこそ、より多くつなげるのです。

あなた自身の CLAUDE.md やスキルファイルも、こう組み立てるべきです。Thariq はよくある誤解を1つ挙げました — 使いうる作法を全部1つのファイルに積む人が多い、書かないと Claude が見つけられないから、という理由で。正しいやり方は、必要時に読み込めるファイルのツリーに分けることです。

仕様はドキュメントでなくてもいい、コードやテスト一式でもいい

まずここでの「仕様」をはっきりさせます。Claude に書いて渡す「私が欲しいものはこういう形」です。これまでは markdown のドキュメントに書くのが習慣で、プランモードの Claude Code はこの種のファイルにずっと依存してきました。仕様をコードベースに置いて長期プロジェクトの参照にするのも同類です。これらはいまも有効ですが、もう一歩進めます — Claude はいま、はるかに複雑な参照物を扱えます。

コード系の参照物がなぜ効くのか。彼は『Fable フィールドガイド』（同じ人が書いた別の記事で、Anthropic が Fable 5 向けに出した公式手引き）でもっと率直に書いています — 描写できないものがある。その語彙を持っていないのかもしれないし、はっきり描写するのに時間がかかりすぎるのかもしれない。そういうときは参照物を渡すのがいちばんで、あらゆる参照物の中で最良はソースコードだ、と。この記事に戻ると、彼が挙げた例はこうです。同じデザインなら、HTML の下書きを渡すほうが、文章の説明やスクリーンショット1枚よりずっと効く。

@ でファイルを持ち込んで参照物にできます……一般にはコードの中のものを優先してください。Claude に対して明快で高忠実度の指示になり、しかも Claude がとても慣れている言語だからです。 — Thariq Shihipar『The new rules of context engineering for Claude 5 generation models』（省略記号の箇所は原文の別段落）

コンテキストは6層でできている、各層に何を置くか

ここまでの数カ条を合わせると、階層ごとの配置指針になります。まず1回のリクエストで Claude が実際に読むものが、どう組み立てられているかを見ます。

あなたが打った一言が最上段、その下は順に参照物（@ で持ち込んだファイル、仕様、デザイン案、コードベース、artifacts）、システムプロンプト、CLAUDE.md、スキル、記憶。画像出典：Thariq / X

この6層のうち、最上段の一言はあなたがその場で打つもの、最下段の記憶は Claude 自身が保存するもので、どちらも並べる必要はありません。ほんとうに手を入れるのは真ん中の4層です。

整理に取りかかるなら、まず健診コマンドを実行

Anthropic はこの一連の作法を1つのコマンドに入れました。あなたのスキルと CLAUDE.md を軽量化するためのものです。使い方について原文はこう書いています — 「これらのベストプラクティスを claude doctor に入れました。Claude Code では /doctor コマンドです」。

この2つの入口は完全に同じではありません。本サイトが Claude Code 2.1.220 で実測したところ、コマンドラインの claude doctor のヘルプには「Claude Code のインストールが健全か確認する。カレントディレクトリの設定ファイルを読み、信頼プロンプトを出さない」とあり、末尾に一文が添えられていました — 問題をその場で直せる完全な健診をするには、セッション内で /doctor を実行してください。ですからスキルと CLAUDE.md を整理してほしいなら、セッションに入ってスラッシュコマンドのほうを使います。

この6カ条が成り立つには前提があります。「新世代モデルの判断力が上がった」ことで、原文が挙げているのは Opus 5 と Fable 5 です。あなたのワークフローがより古いモデルや他社のモデルで動いているなら、当時のガードレールが防いでいた問題はまだ残っている可能性があります。真似して削る前に、小さな範囲で試してください。この層は原文では展開されていません。

Claude Code が出たばかりの頃、最優先はやらかさせないことでした。だからルールはかなり固く書かれた。一部の人が巻き込まれると分かっていても、です。コメントの件がまさにそれ。自分でドキュメントを書く習慣の人もいるし、複雑なコードには本来複数行のコメントを付けるべきですが、当時のモデルは止めておかないと間違ったコメントを大量に書いた。一律にするしかなかったのです。

新しい一文は、参照先を周囲のコードに委ねました。コメント密度、命名、書き方は隣に合わせる。参照先はプロジェクトごとに変わるので、このルールをプロジェクトごとに書き直す必要はありません。

ルールを削るもっと実務的な理由もあります。自社チームが Claude Code を使った会話ログを見て、1回のリクエストにケンカする文が同時に何本も出ることに気づいたのです。

Thariq は、長く語り継がれてきたが今は成り立たない作法を6つ挙げ、1本ずつ置き換えを示しました。

ここまでを合わせると、配置の指針になります。6層のうち最上段の一言はその場で打つもの、最下段の記憶は Claude が自分で保存するもの。ほんとうに手を入れるのは真ん中です。

取りかかるならまず健診を。Claude Code のセッションで /doctor と入力すると、この一連の基準であなたのスキルと CLAUDE.md の整理案を出してくれます。本サイトは 2.1.220 版で試しました。コマンドラインの claude doctor はインストールの確認だけで、完全な健診はセッション内で実行します。