Claude codeのコマンド類からみる設計思想の理解

はじめに

Claude Code の設計思想は、Anthropic 社内のエンジニアやインタビューで何度も語られていて、いくつかの軸で整理できます。

1. 出発点が「ハック」だった

そもそも Claude Code は、エンジニアの Boris Cherny さんが Claude 3.6 で遊んでいたときの個人プロトタイプから始まっています。最初のバージョンはファイルも読めずbashも使えない、AppleScriptで再生中の音楽を答えるだけのデモでした。それにファイルシステムへのアクセスを与えたら社内で爆発的に広まった、という経緯です。「マスタープランはなかった」「クレイジーな研究プロジェクトみたいなもの」と本人たちが言っています。 The Pragmatic EngineerSubstack

つまり「ターミナルから始まった」のは思想というより、最も摩擦の少ない実験場がターミナルだったから、というのが本当のところです。

2. “Unix utility であって product ではない”

これが一番象徴的なフレーズです。Boris さん曰く「Claude Code はプロダクトというより Unix ユーティリティ」。Anthropic の製品原則は”do the simple thing first”——記憶はマークダウンファイルを自動ロードするだけ、要約は Claude にそのまま頼むだけ、と「役に立って、理解可能で、拡張可能な最小のビルディングブロック」を選ぶという方針です。 SubstackSubstack

3. ターミナルは「composability」の言語

公式ドキュメントは「Unix 哲学に従い composable」（コマンドを組み合わせられるイメージか）と明言しています。たとえば:

tail -200 app.log | claude -p "Slack me if you see any anomalies"
git diff main --name-only | claude -p "review these changed files for security issues"

パイプで繋ぐ、CI で動かす、他ツールとチェーンする——これは GUI ラッパーでは絶対に成立しない設計です。エディタの中に閉じ込めた瞬間、| も && も cron も使えなくなる。ターミナルから始めることで、既存の Unix エコシステム全部が無料の依存関係になるわけです。 Claude

4. モデル自身が CLI に強い

これは見落とされがちな点ですが、LLM は学習データの構造上、bash・git・grep・curl みたいな CLI ツールの使い方を膨大に知っています。新しいカスタムツールを大量に発明するより、モデルが既に得意な道具をそのまま使わせるほうが性能が出る。技術スタック（TypeScript, React, Ink, Yoga, Bun）も “on distribution”——モデルの強みに合わせて選ばれたと明言されています。 The Pragmatic Engineer

代表的なコマンドの使い方

/initコマンド

1. /init は最初に1回でOK?

基本的には最初の1回で十分です。/init は「プロジェクトをスキャンして CLAUDE.md の土台を作る」というブートストラップ用コマンドなので、一度走らせれば役目は果たせます。/init は Claude Code のインタラクティブモード内でのみ動作し、コマンドラインから直接 claude /init のようには呼べません。 Vincent’s Blog

ただし「1回きり」というより「節目で再利用してもいい」という性格のコマンドです。

2. 「プロジェクト」=GitHub リポジトリ / VS Code のルートフォルダ?

Claude Code にとってのプロジェクトとは、claude を起動したディレクトリ(=cwd)　のこと。通常はそれが Git リポジトリのルートだったり、VS Code で開いているワークスペースだったりします。

その配下に作られるものが、

• CLAUDE.md — プロジェクトメモリ(これが /init で生成される)
• .claude/commands/, .claude/skills/, .claude/settings.json — プロジェクト固有の設定・拡張

なので 、それぞれのリポジトリルートで、別個に /init する形になります。例えば、Turborepo のような monorepo の場合はルート1つで運用するのが基本ですが、パッケージごとに サブディレクトリ配下に.claude/skills/ を置くと、サブディレクトリで作業しているときに自動で拾ってくれる仕組みもあります。

3. 同じプロジェクトで2回実行するとどうなる?

完全上書きにはなりません。CLAUDE.md が既に存在する場合、/init は上書きではなく現在のコードベースを基に既存ファイルを更新します。実装的には「もし既に CLAUDE.md があれば改善案を提案する」という指示が /init のプロンプトに含まれているためです。 Vincent’s BlogKau

なので、こういう場面で再実行する価値があります:

• 新しいフレームワーク・主要な依存を入れたとき
• ディレクトリ構造を大きく変えたとき
• ビルド・テスト・lint コマンドが変わったとき

ただし、手動で書き加えたカスタムルール(チームの暗黙ルール、過去のハマりどころなど)が薄まる可能性はあるので、実行前にコミットしておくのが安全策です。差分は git diff で確認 → 不要な変更は revert、という運用がおすすめです。

補足として、/init で生成されたものは「叩き台」と捉えて、コードからは読み取れない情報(ビジネスロジックの注意点、DBのスキーマ規約など) は手動で追記するのが効果的です。

@ファイル, @フォルダ

作業セッションを始めるとき

タスクが明確な場合: 直接プロンプトを書く。範囲を絞るために @ファイル名 や @フォルダ/ を使う。

@src/auth/login.ts のトークン検証ロジックに
リフレッシュトークンのハンドリングを追加して

タスクが大きい・曖昧な場合: まず方針を聞く。Claudeに整理させてから実装に入る。

RBAC機能を設計したい。
必要なモデル、エンドポイント、権限チェックのパターンを提案して

@ファイルはコンテキストにファイルがまるまる入るので、注意が必要

＠フォルダはコンテキストにファイルリストが入るだけなので、それほど圧迫はしない

/context — コンテキストの中身を見る

「コンテキスト」とは何か

Claude が1ターン（１会話）中に「見えている」テキストの総量のこと。LLM は状態を持たない(=前のターンを覚えていない)ので、毎ターン、過去の会話履歴を丸ごと再送する 必要がある。

❯ /context                                                                                                       
  ⎿  Context Usage                                                                                          
     ⛁ ⛁ ⛁ ⛁ ⛀ ⛁ ⛶ ⛶ ⛶ ⛶   Opus 4.7 (1M context)                                                                 
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-opus-4-7[1m]                                                                   
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   33.2k/600k tokens (6%)                                                   
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶                                                                                         
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   Estimated usage by category                                                           
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 8.7k tokens (1.5%)                                                   
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 11.4k tokens (1.9%)                                                   
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 6k tokens (1.0%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Skills: 724 tokens (0.1%)
     ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛁ Messages: 6.6k tokens (1.1%)
                           ⛶ Free space: 533.6k (88.9%)
                           ⛝ Autocompact buffer: 33k tokens (5.5%)

中身は:

• システムプロンプト(Claude Code 本体の指示)
• 利用できるツールの定義
• CLAUDE.md(プロジェクトメモリ)
• 読み込まれた Skills
• これまでの会話履歴(自分のメッセージ + Claude の返答 + ツール実行ログ + 読み込んだファイルの中身)

ポイント:

• ハードリミットあり (モデル/プランで 200K〜1M トークン)
• 毎ターン、これらすべてが再送される
• 大きくなるほど料金もレスポンス品質も悪化する

つまりコンテキスト管理 = 速度・品質・コストの管理。

コンテキストが、60〜70% くらい:体感での品質劣化が始まる。これが俗に言う “context rot”(コンテキストの腐り)。ハードリミットの問題というより、長い文脈を持つほど LLM の注意が分散するという性質

85〜95% 前後:自動 compact が発動する。Claude Code が勝手に会話履歴を要約 → 圧縮版に置き換える。要約は「Claude のお任せ」なので、何が残って何が消えるかコントロールできない。自分で先回りして /compact 〇〇を残して で打った方が品質がいい。

100% に達したら:そもそも送信できなくなる。API レベルで「コンテキスト超過」エラー。自動 compact が発動するので普通はここまではいかない。

ちなみにコンテキストは、~/.claude/projects/<project name>/配下にjsonlファイルとして保存されているので、目視確認が可能

% ls -t ~/.claude/projects/{project name}/*.jsonl | head -1 | xargs cat | jq > a

/compact — 会話履歴を要約する

何をするか

• これまでの会話を Claude が要約 → 全文を要約版に置き換える
• 要約後の状態でセッションを継続
• 引数で要約方針を指定できる:

  /compact エラーハンドリングのパターンと現在のテスト失敗を優先して残して
  /compact 次の作業に入るので、雑談を圧縮して

影響するファイル

• ディスク上のファイルには触らない。CLAUDE.md もコードも変更しない
• 変わるのは 現在のセッションのインメモリ会話状態のみ

使いどき

• 体感では 60% 前後で先回り実行が一番きれい(要約対象が少ないほど要約品質が高い)
• 自動 compact は 80%超〜95% で発動するが、それを待つと既に応答品質の劣化が始まっている
• 大きなサブタスクの切れ目で意識的に挟む
• /clear とは別物。/clear は全消去、/compact は要約して継続

/usage — レート制限の残量を見る

何をするか

• 5時間ローリングウィンドウの使用率(現在のセッション枠)
• 週次上限の使用率(全モデル合算)

❯ /usage                                                                                                         
         
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   Status   Config   Usage   Stats                                                                               
                                                                                       
  Session                                                                                                   
  Total cost:            $1.01                                                                                 
  Total duration (API):  3m 22s                                                                                
  Total duration (wall): 2h 41m 45s                                                                            
  Total code changes:    0 lines added, 0 lines removed   
  Usage by model:                                         
       claude-opus-4-7:  5.1k input, 9.7k output, 694.8k cache read, 63.2k cache write ($1.01)
      claude-haiku-4-5:  356 input, 13 output, 0 cache read, 0 cache write ($0.0004)

これは 「今の会話のコンテキスト」ではなく「サブスクリプションの残量」 を見るコマンド。/context とは見ているものが完全に別物。

使いどき

• 重めの作業に入る前に残量チェック
• 急に応答がブロックされた、遅くなったとき
• 締切前に「あと何時間 Opus を使えるか」を確認

「プロジェクト」と「セッション」

ここを誤解していると /clear を打つのが怖くなる。Claude Code には2つのスコープがある:

/clear も /resume も セッション側を操作するだけ で、プロジェクト側は一切触らない。CLAUDE.md は無事だし、.claude/skills/ も生きている。安心して使っていい。

/clear — セッションを完全リセット

何をするか

• 会話履歴を全消去
• 読み込まれていたファイル内容も忘れる
• CLAUDE.md と Skills は次のメッセージで再ロード(プロジェクト側だから無傷)
• 「初対面の Claude」と同じ状態に戻る

影響するファイル

• ディスク上のファイルには触らない
• セッションのインメモリ状態のみリセット

注意:Claude が修正したコード変更は残るが、「なぜそう修正したか」のロジックは消える。重要な決定はコミットメッセージか CLAUDE.md に残してから /clear するのが安全。

使いどき

• 別チケット・別タスクに移るとき(これが圧倒的に多い)
• 失敗アプローチを2回以上繰り返したあと(コンテキスト汚染のリセット)
• 長時間セッションで品質が落ちてきたとき
• /compact でも復活しないほど混乱したとき

「同じプロジェクト内なら /clear するな」というのは誤解。プロジェクトはディレクトリ、セッションは会話。同じプロジェクトでもセッションは何度でも切っていい。

/resume — 過去のセッションに戻る

何をするか

• ローカルに保存されているセッション履歴から1つ選んで再開
• 引数なしでセッションピッカーが開く
• 引数指定で直接そのセッションに戻れる

バリエーション

/resume                   # セッションピッカーを開く
claude -c                 # 直近のセッションを CLI から継続
claude --resume <名前>    # 名前付きセッションを直接再開

影響するファイル

• なし。保存済みセッションを呼び戻すだけ。

使いどき

• /clear した後に「やっぱり戻したい」と思ったとき
• 昨日の続きから始めたいとき
• 複数チケットを並行していて、別タスクのセッションに切り替えたいとき
• 中断した検証・PoC の続きを書くとき

大事なセッションは /rename で名前をつけておくと後で探しやすい。タイムスタンプだけだと自分でもどれか分からなくなる。

次のチケットにはいるときの標準ルーチン

新しいチケットに入る瞬間が、一番コンテキストを汚しやすいタイミングです。基本ルーチンはこれ。

1. 前のタスクの成果をコミット(git commit)
2. /clear            ← ここが一番大事
3. /context          ← 出発点のサイズ確認(任意)
4. Shift+Tab で Plan Mode
5. 新しいタスクを @関連ファイル と一緒に渡す

なぜ /clear なのか

/compact ではなく /clear を選ぶ理由:

• 前のチケットで Claude が試した失敗アプローチがコンテキストに残っている → 新しいタスクの判断を歪める
• 関係ないファイルの中身が乗っている → 無駄にトークンを食う
• 要約しても「別タスクの記憶」は新タスクには邪魔

要約して残す価値があるのは「同じタスクの長丁場」のときだけ。タスクが変わるなら、未練なく /clear。

コミット忘れ防止

/clear すると会話履歴は消えるけど、ファイルへの変更は残る(Claude Code はディスクに直接書いている)。それでも、

• まだコミットしてない変更を確認するクセをつける(!git status)
• 「あの修正、なぜそうしたか」のロジックは Claude の頭の中にしかなかった → /clear で消失

なので /clear の前に コミット + 必要ならコミットメッセージや CLAUDE.md に決定事項を残す のが安全です。

Plan Mode を挟む価値

新タスクで Plan Mode に入る理由:

• いきなり実装に走られるのを防ぐ
• Claude が「何をやろうとしているか」を読み取れる → 認識ズレに早く気づける
• ファイルを読みすぎる前に止められる(コンテキスト節約)

特に、チケットの内容が複雑だったり影響範囲が広い場合 は Plan Mode の効果が大きい。逆にtypo修正レベルならスキップしてOK。

実運用パターン

複数チケットを回す1日の流れ:

朝
└ claude -c で直近セッション復元
  └ 朝イチのチケット作業

チケット切替時
├ git commit(変更を永続化)
├ /clear            ← 必ず挟む
└ 次のタスク開始

緊急の脇道タスクが入ったとき
├ /rename "main-feature-work"   ← 戻ってこられるように名付け
├ 別タブで claude を開く、または /clear で脇道タスクへ
└ 脇道完了後、/resume で main-feature-work に戻る

夜
└ 続きをやりたいセッションは /rename で命名しておく

Plan Mode とは

Claude が実装する前に、計画だけを立てる読み取り専用モード。

通常モードだと、頼んだ瞬間からファイルを編集したり、コマンドを実行したりが始まる。Plan Mode に入ると、Claude は:

• ファイルは 読める(Read、Grep、Glob)
• ファイルの 編集はできない
• 状態を変えるコマンドは 実行できない(git commit、npm install など)
• 代わりに「こうやって実装します」という 計画を文章で提示する

ユーザーが計画にOKを出すと、Plan Mode を抜けて実行に入る。

入り方

Shift+Tab           # normal → auto-accept → plan の3モードを循環
/plan               # コマンドでも入れる(Windowsで Shift+Tab が効かないとき)

入っている間はプロンプトの下に「Plan Mode」と表示される。

何が嬉しいか

1. 認識ズレを早期検出できる

Claude が「6ファイル読んで、3ファイル修正します」と言ってきたとき、実際は2ファイルで済むなら、コードを触る前に修正できる。手戻りが激減する。

2. コンテキストの節約になる

通常モードだと Claude は探索で大量のファイルを読み込んでコンテキストを食う。Plan Mode で計画を確認してから実行に入れば、無駄なファイル読みを避けられる。

3. 大きな変更の安全弁

リファクタや影響範囲の広い変更は、いきなり走らせると事故る。Plan Mode で「どこに手を入れるつもりか」を可視化することで、レビューポイントを作れる。

使うべき場面

計画への介入方法

計画を見て修正したいとき:

• Esc を押して計画を却下 → フィードバックを返す → Claude が計画を作り直す
• 「データベースは PostgreSQL じゃなくて SQLite を使って」「テストは vitest で」など、具体的に方針を指示
• 何度でもやり直せる

計画でOK出すまではコードに何も影響しないので、納得するまで往復していい。

チケット入りのフローに組み込む

前回の話とつなげると、新チケットの理想的な始まり方は:

1. git commit(前のタスクを締める)
2. /clear(セッションリセット)
3. Shift+Tab → Plan Mode
4. @関連ファイル と一緒にチケット内容を投げる
5. 計画をレビュー → OKなら実行 / NGなら指示し直す
6. 実装が始まる

これがいまのところ最も事故率が低い始め方。「Claude にまず喋らせて、それから動かす」 の発想ですね。

計画依頼のテンプレ

チケット #xx:ダーク/ライトモード切り替え

目的:
全画面で dark / light モードを切り替えられるようにする。

受け入れ条件:
- 左下のユーザー設定で全画面が切り替わる
- 選択は localStorage に保存され、再訪問時に復元される
- 初回アクセス時は OS の prefers-color-scheme を尊重する
- 既存xxxxxページの見た目が崩れない
- テーマ切替時に画面の白フラッシュ(FOUC)が起きない

参考資料:
- UI規約:@docs/xxxxx.md
- 既存ダーク実装の参考:@app/xxxxx/

現状:
- xxxxxページのみ dark スタイルが実装済み
- 他画面は light スタイルのみ
- 既存のダーク用色値を再利用してテーマトークン化したい

技術前提:
- Tailwind v4 + CSS変数
- グローバルテーマは app/globals.css

スコープ外:
- ユーザー設定ページの新規追加(トグルのみで良い)
- 言語による初期テーマ自動判定(やらない)

まず Plan Mode で計画を立てて。
影響ファイル一覧とテーマトークンの命名案も出して。

ポイントまとめ