claude-code

Claude Code — Hermes オーケストレーションガイド

Hermes ターミナル経由で Claude Code（Anthropic の自律型コーディングエージェント CLI）にコーディングタスクを委任できます。Claude Code v2.x は、ファイルの読み取り、コードの作成、シェルコマンドの実行、サブエージェントの起動、Git ワークフローの自律的な管理ができます。

前提条件

• インストール： npm install -g @anthropic-ai/claude-code
• 認証： claude を一度実行してログインします（Pro/Max の場合はブラウザー OAuth、または ANTHROPIC_API_KEY を設定）
• Console 認証： API キーによる課金には claude auth login --console を実行します
• SSO 認証： Enterprise の場合は claude auth login --sso を実行します
• ステータス確認： claude auth status（JSON）または claude auth status --text（人間が読みやすい形式）
• ヘルスチェック： claude doctor — 自動アップデーターとインストールの状態を確認します
• バージョン確認： claude --version（v2.x 以降が必要です）
• 更新： claude update または claude upgrade

2 つのオーケストレーションモード

Hermes は、Claude Code と根本的に異なる 2 つの方法で連携します。タスクに応じて選択してください。

モード 1：プリントモード（-p）— 非インタラクティブ（ほとんどのタスクで推奨）

プリントモードは、単発のタスクを実行して結果を返し、終了します。PTY は不要です。対話型のプロンプトも表示されません。最もシンプルな連携方法です。

terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)

プリントモードを使う場面：

• 単発のコーディングタスク（バグ修正、機能追加、リファクタリング）
• CI/CD の自動化とスクリプト作成
• --json-schema を使った構造化データの抽出
• パイプ入力の処理（cat file | claude -p "analyze this"）
• 複数ターンの会話が不要なすべてのタスク

プリントモードでは、すべての対話型ダイアログがスキップされます — ワークスペースの信頼確認も、権限の確認もありません。そのため、自動化に最適です。

モード 2：tmux 経由のインタラクティブ PTY — 複数ターンのセッション

インタラクティブモードでは、追加のプロンプトを送信したり、スラッシュコマンドを使ったり、Claude の作業をリアルタイムで確認したりできる、完全な対話型 REPL を利用できます。tmux によるオーケストレーションが必要です。

# Start a tmux session
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")

# Launch Claude Code inside it
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")

# Wait for startup, then send your task
# (after ~3-5 seconds for the welcome screen)
terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")

# Monitor progress by capturing the pane
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")

# Send follow-up tasks
terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")

# Exit when done
terminal(command="tmux send-keys -t claude-work '/exit' Enter")

インタラクティブモードを使う場面：

• 複数ターンの反復作業（リファクタリング → レビュー → 修正 → テストのサイクル）
• 人間が介在して判断する必要があるタスク
• 探索的なコーディングセッション
• Claude のスラッシュコマンド（/compact、/review、/model）を使う必要がある場合

PTY ダイアログの処理（インタラクティブモードでは重要）

Claude Code は初回起動時に、最大 2 つの確認ダイアログを表示します。tmux send-keys を使って必ず処理してください。

ダイアログ 1：ワークスペースの信頼確認（ディレクトリへの初回アクセス時）

❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
  2. No, exit

処理方法： tmux send-keys -t <session> Enter — デフォルトの選択肢で問題ありません。

ダイアログ 2：個別の権限プロンプト（通常のフロー）

承認が必要なツールの使用（ファイル書き込み、シェルコマンド、ネットワーク）ごとに、プロンプトが表示されます。実行全体のプロンプトを無効化するのではなく、その都度表示されたプロンプトに回答してください。

# Read the prompt before answering it
terminal(command="tmux capture-pane -t <session> -p -S -30")
# Allow this one action (Enter = default "Yes"); Esc declines it
terminal(command="tmux send-keys -t <session> Enter")

内容を確認していないプロンプトを承認するために、タイマーで無条件に Enter を送信してはいけません。これはバイパスフラグを回りくどく使うのと同じです。

完全なバイパスよりも制限されたオプトインとして、--permission-mode acceptEdits があります。作業ディレクトリ内のファイル編集は承認されますが、シェルやその他のツール呼び出しでは引き続きプロンプトが表示されます。タスクを確認したうえで、専用の worktree 内でのみ使用してください。

堅牢なダイアログ処理パターン

# Default launch — keep permission prompts enabled
terminal(command="tmux send-keys -t claude-work 'claude \"your task\"' Enter")

# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")

# Now wait for Claude to work
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")

注： ディレクトリに対する信頼を一度承認すると、以降は信頼確認ダイアログが表示されません。

オプトイン：--dangerously-skip-permissions（隔離環境のみ）

これを使うと、実行全体の権限プロンプトが無効になります。ファイルシステム、シェル、ネットワークへのアクセスが、プロンプトなしで許可されます。使ってもよいのは、使い捨ての worktree または隔離コンテナ内に限られます。

❯ 1. No, exit                    ← DEFAULT (safe choice)
  2. Yes, I accept

承認するには、tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter を実行します。

CLI サブコマンド

サブコマンド	用途
claude	対話型 REPL を開始します
claude "query"	初期プロンプトを指定して REPL を開始します
claude -p "query"	印刷モード（非対話型。処理完了後に終了します）
cat file | claude -p "query"	標準入力の内容をコンテキストとしてパイプします
claude -c	このディレクトリで直近の会話を続行します
claude -r "id"	ID または名前を指定して特定のセッションを再開します
claude auth login	サインインします（API 課金には --console、Enterprise には --sso を追加します）
claude auth status	ログイン状態を確認します（JSON を返します。人が読みやすい形式にするには --text を指定します）
claude mcp add <name> -- <cmd>	MCP サーバーを追加します
claude mcp list	設定済みの MCP サーバーを一覧表示します
claude mcp remove <name>	MCP サーバーを削除します
claude agents	設定済みのエージェントを一覧表示します
claude doctor	インストールと自動アップデーターのヘルスチェックを実行します
claude update / claude upgrade	Claude Code を最新バージョンに更新します
claude remote-control	claude.ai またはモバイルアプリから Claude を操作するサーバーを起動します
claude install [target]	ネイティブビルドをインストールします（stable、latest、または特定のバージョン）
claude setup-token	長期間有効な認証トークンを設定します（サブスクリプションが必要です）
claude plugin / claude plugins	Claude Code プラグインを管理します
claude auto-mode	自動モードの分類器設定を確認します

印刷モードの詳細

構造化 JSON 出力

terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)

次のフィールドを含む JSON オブジェクトを返します：

{
  "type": "result",
  "subtype": "success",
  "result": "The analysis text...",
  "session_id": "75e2167f-...",
  "num_turns": 3,
  "total_cost_usd": 0.0787,
  "duration_ms": 10276,
  "stop_reason": "end_turn",
  "terminal_reason": "completed",
  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
  "modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
}

主なフィールド： 再開用の session_id、エージェントループの回数を示す num_turns、使用量の追跡に使う total_cost_usd、成功／エラーの判定に使う subtype（success、error_max_turns、error_budget）。

ストリーミング JSON 出力

トークンをリアルタイムでストリーミングするには、--verbose とともに stream-json を使用します：

terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)

改行区切りの JSON イベントを返します。jq でフィルタリングして、テキストをリアルタイムで表示できます：

claude -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

ストリームイベントには、attempt、max_retries、error フィールド（例：rate_limit、billing_error）を含む system/api_retry が含まれます。

双方向ストリーミング

入力と出力の両方をリアルタイムでストリーミングするには：

claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages を指定すると、確認用にユーザーメッセージを標準出力に再出力します。

パイプ入力

# Pipe a file for analysis
terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)

# Pipe multiple files
terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)

# Pipe command output
terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)

構造化抽出用 JSON スキーマ

terminal(command="claude -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)

JSON 結果から structured_output を解析します。Claude は返す前に、スキーマに照らして出力を検証します。

セッションの続行

# Start a task
terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > ~/.hermes/cache/scratch/session.json", workdir="/project", timeout=180)

# Resume with session ID
terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat ~/.hermes/cache/scratch/session.json | python -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)

# Or resume the most recent session in the same directory
terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)

# Fork a session (new ID, keeps history)
terminal(command="claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)

CI／スクリプト向けのベアモード

terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

--bare はフック、プラグイン、MCP の検出、CLAUDE.md の読み込みを省略します。最速で起動できます。ANTHROPIC_API_KEY が必要です（OAuth はスキップされます）。

ベアモードでコンテキストを選択的に読み込むには：

読み込む対象	フラグ
システムプロンプトへの追加内容	--append-system-prompt "text" または --append-system-prompt-file path
設定	--settings <file-or-json>
MCP サーバー	--mcp-config <file-or-json>
カスタムエージェント	--agents '<json>'

過負荷時のフォールバックモデル

terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)

デフォルトのモデルが過負荷の場合、指定したモデルに自動的にフォールバックします（印刷モードのみ）。

CLI フラグの完全なリファレンス

セッションと環境

フラグ	効果
-p, --print	非対話型の単発モード（完了すると終了）
-c, --continue	現在のディレクトリで直近の会話を再開します
-r, --resume <id>	ID または名前を指定してセッションを再開します（ID を指定しない場合は対話型ピッカーを表示）
--fork-session	再開時に元の ID を再利用せず、新しいセッション ID を作成します
--session-id <uuid>	会話に特定の UUID を使用します
--no-session-persistence	セッションをディスクに保存しません（プリントモードのみ）
--add-dir <paths...>	Claude に追加の作業ディレクトリへのアクセスを許可します
-w, --worktree [name]	.claude/worktrees/<name> に分離された Git ワークツリーを作成して実行します
--tmux	ワークツリー用の tmux セッションを作成します（--worktree が必要です）
--ide	起動時に有効な IDE に自動接続します
--chrome / --no-chrome	ウェブテスト用の Chrome ブラウザー連携を有効／無効にします
--from-pr [number]	特定の GitHub PR に関連付けられたセッションを再開します
--file <specs...>	起動時にダウンロードするファイルリソース（形式：file_id:relative_path）

モデルとパフォーマンス

フラグ	効果
--model <alias>	モデルの選択：sonnet、opus、haiku、または claude-sonnet-4-6 のような正式名称
--effort <level>	推論の深さ：low、medium、high、xhigh、max
--max-turns <n>	エージェントのループ回数を制限します（プリントモードのみ。無制限の実行を防止します）
--max-budget-usd <n>	API の利用額をドル単位で制限します（プリントモードのみ）
--fallback-model <model>	デフォルトのモデルが過負荷の場合に自動で切り替えるモデル（プリントモードのみ）
--betas <betas...>	API リクエストに含めるベータヘッダー（API キー利用者のみ）

権限と安全性

フラグ	効果
--dangerously-skip-permissions	オプトイン専用：すべての権限確認（ファイル書き込み、bash、ネットワーク）を無効にします。使い捨てのワークツリーまたは分離されたコンテナーでのみ使用してください。上記の「オプトイン」を参照してください
--allow-dangerously-skip-permissions	デフォルトでは有効にせず、バイパスをオプションとして有効にします
--permission-mode <mode>	default、acceptEdits、plan、auto、dontAsk、bypassPermissions
--allowedTools <tools...>	特定のツールを許可リストに登録します（コンマまたはスペース区切り）
--disallowedTools <tools...>	特定のツールを拒否リストに登録します
--tools <tools...>	組み込みツールセットを上書きします（"" = なし、"default" = すべて、またはツール名）

出力と入力の形式

フラグ	効果
--output-format <fmt>	text（デフォルト）、json（単一の結果オブジェクト）、stream-json（改行区切り）
--input-format <fmt>	text（デフォルト）または stream-json（リアルタイムのストリーミング入力）
--json-schema <schema>	スキーマに適合する構造化 JSON 出力を強制します
--verbose	ターンごとの出力をすべて表示します
--include-partial-messages	受信時に部分的なメッセージのチャンクを含めます（stream-json + print）
--replay-user-messages	ユーザーメッセージを標準出力に再出力します（stream-json 双方向）

システムプロンプトとコンテキスト

フラグ	効果
--append-system-prompt <text>	デフォルトのシステムプロンプトに追加します（組み込み機能を維持します）
--append-system-prompt-file <path>	ファイルの内容をデフォルトのシステムプロンプトに追加します
--system-prompt <text>	システムプロンプト全体を置き換えます（通常は代わりに --append を使用してください）
--system-prompt-file <path>	システムプロンプトをファイルの内容で置き換えます
--bare	フック、プラグイン、MCP の検出、CLAUDE.md、OAuth をスキップします（起動が最速になります）
--agents '<json>'	JSON でカスタムサブエージェントを動的に定義します
--mcp-config <path>	JSON ファイルから MCP サーバーを読み込みます（繰り返し指定可能）
--strict-mcp-config	--mcp-config の MCP サーバーのみを使用し、他のすべての MCP 設定を無視します
--settings <file-or-json>	JSON ファイルまたはインライン JSON から追加の設定を読み込みます
--setting-sources <sources>	読み込むソースをコンマ区切りで指定します：user、project、local
--plugin-dir <paths...>	このセッションでのみ、ディレクトリからプラグインを読み込みます
--disable-slash-commands	すべてのスキル／スラッシュコマンドを無効にします

デバッグ

フラグ	効果
-d, --debug [filter]	オプションのカテゴリーフィルター（例："api,hooks"、"!1p,!file"）を指定してデバッグログを有効にします
--debug-file <path>	デバッグログをファイルに書き込みます（デバッグモードも暗黙的に有効になります）

エージェントチーム

フラグ	効果
--teammate-mode <mode>	エージェントチームの表示方法：auto、in-process、または tmux
--brief	エージェントからユーザーへの通信に SendUserMessage ツールを有効にします

--allowedTools / --disallowedTools のツール名構文

Read                    # All file reading
Edit                    # File editing (existing files)
Write                   # File creation (new files)
Bash                    # All shell commands
Bash(git *)             # Only git commands
Bash(git commit *)      # Only git commit commands
Bash(npm run lint:*)    # Pattern matching with wildcards
WebSearch               # Web search capability
WebFetch                # Web page fetching
mcp__<server>__{tool}   # Specific MCP tool

設定と構成

設定の優先順位（高い順）

1. CLI フラグ — すべてを上書きします
2. ローカルプロジェクト： .claude/settings.local.json（個人用、Git で無視されます）
3. プロジェクト： .claude/settings.json（共有、Git で追跡されます）
4. ユーザー： ~/.claude/settings.json（グローバル）

設定での権限

{
  "permissions": {
    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
    "ask": ["Write(*.ts)", "Bash(git push*)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  }
}

メモリファイル（CLAUDE.md）の階層

1. グローバル： ~/.claude/CLAUDE.md — すべてのプロジェクトに適用されます
2. プロジェクト： ./CLAUDE.md — プロジェクト固有のコンテキスト（Git で追跡されます）
3. ローカル： .claude/CLAUDE.local.md — 個人用のプロジェクト上書き設定（Git で無視されます）

対話モードで # を先頭に付けると、メモリにすばやく追加できます：# Always use 2-space indentation。

対話セッション：スラッシュコマンド

セッションとコンテキスト

コマンド	目的
/help	カスタムコマンドや MCP コマンドを含む、すべてのコマンドを表示します
/compact [focus]	トークンを節約するためにコンテキストを圧縮します。圧縮後も CLAUDE.md は保持されます。例：/compact focus on auth logic
/clear	会話履歴を消去して、新しいセッションを開始します
/context	コンテキストの使用状況を、最適化のヒント付きの色分けされたグリッドで可視化します
/cost	モデル別およびキャッシュヒット別の内訳とともに、トークン使用量を表示します
/resume	別のセッションに切り替えるか、再開します
/rewind	会話またはコードの以前のチェックポイントに戻します
/btw <question>	コンテキストコストを増やさずに、補足的な質問をします
/status	バージョン、接続状況、セッション情報を表示します
/todos	会話から追跡されたアクション項目を一覧表示します
/exit or Ctrl+D	セッションを終了します

開発とレビュー

コマンド	目的
/review	現在の変更のコードレビューを依頼します
/security-review	現在の変更のセキュリティ分析を実行します
/plan [description]	タスク計画用の自動開始機能を使って、Plan モードに入ります
/loop [interval]	セッション内で繰り返しタスクをスケジュールします
/batch	大規模な並行変更用の作業ツリーを自動作成します（5～30 個）

設定とツール

コマンド	目的
/model [model]	セッション中にモデルを切り替えます（矢印キーで推論の労力を調整します）
/effort [level]	推論の労力を設定します：low、medium、high、xhigh、または max
/init	プロジェクトのメモリ用に CLAUDE.md ファイルを作成します
/memory	編集用に CLAUDE.md を開きます
/config	対話型の設定画面を開きます
/permissions	ツールの権限を表示／更新します
/agents	専門のサブエージェントを管理します
/mcp	MCP サーバーを管理する対話型 UI
/add-dir	作業ディレクトリを追加します（モノレポで便利です）
/usage	プランの上限とレート制限の状態を表示します
/voice	プッシュ・トゥ・トークの音声モードを有効にします（20 言語対応。Space を押し続けて録音し、離すと送信します）
/release-notes	バージョンのリリースノートを対話形式で選択します

カスタムスラッシュコマンド

.claude/commands/<name>.md（プロジェクト内で共有）または ~/.claude/commands/<name>.md（個人用）を作成します：

# .claude/commands/deploy.md
Run the deploy pipeline:
1. Run all tests
2. Build the Docker image
3. Push to registry
4. Update the $ARGUMENTS environment (default: staging)

使用例：/deploy production — $ARGUMENTS はユーザーの入力に置き換えられます。

スキル（自然言語での呼び出し）

手動で呼び出すスラッシュコマンドとは異なり、.claude/skills/ 内のスキルは Markdown 形式のガイドで、タスクが一致すると Claude が自然言語を介して自動的に呼び出します：

# .claude/skills/database-migration.md
When asked to create or modify database migrations:
1. Use Alembic for migration generation
2. Always create a rollback function
3. Test migrations against a local database copy

対話型セッション：キーボードショートカット

一般的な操作

キー	操作
Ctrl+C	現在の入力または生成をキャンセルします
Ctrl+D	セッションを終了します
Ctrl+R	コマンド履歴を逆方向に検索します
Ctrl+B	実行中のタスクをバックグラウンドに移します
Ctrl+V	画像を会話に貼り付けます
Ctrl+O	トランスクリプトモード — Claude の思考プロセスを表示します
Ctrl+G or Ctrl+X Ctrl+E	外部エディターでプロンプトを開きます
Esc Esc	会話またはコードの状態を巻き戻す／要約します

モードの切り替え

キー	操作
Shift+Tab	権限モードを切り替えます（Normal → Auto-Accept → Plan）
Alt+P	モデルを切り替えます
Alt+T	思考モードを切り替えます
Alt+O	Fast Mode を切り替えます

複数行入力

キー	操作
\ + Enter	素早く改行します
Shift+Enter	改行します（代替方法）
Ctrl+J	改行します（代替方法）

入力プレフィックス

プレフィックス	操作
!	AI を介さず bash を直接実行します（例：!npm test）。! のみを入力するとシェルモードを切り替えます。
@	自動補完を使ってファイル／ディレクトリを参照します（例：@./src/api/）
#	CLAUDE.md のメモリにすばやく追加します（例：# Use 2-space indentation）
/	スラッシュコマンド

プロのヒント：「ultrathink」

特定のターンで推論の労力を最大にするには、プロンプトにキーワード「ultrathink」を使用します。現在の /effort 設定にかかわらず、最も深い思考モードが起動します。

PR レビューのパターン

クイックレビュー（印刷モード）

terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)

詳細レビュー（対話型＋ワークツリー）

terminal(command="tmux new-session -d -s review -x 140 -y 40")
terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
terminal(command="sleep 5 && tmux send-keys -t review Enter")  # Trust dialog
terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")

番号を指定した PR レビュー

terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

tmux を使った Claude ワークツリー

terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")

.claude/worktrees/feature-x に分離された git ワークツリーを作成し、そこに tmux セッションも作成します。利用可能な場合は iTerm2 のネイティブペインを使用します。従来の tmux を使うには --tmux=classic を追加します。

Claude の並列インスタンス

複数の独立した Claude タスクを同時に実行します：

# Task 1: Fix backend
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")

# Task 2: Write tests
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")

# Task 3: Update docs
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")

# Monitor all
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")

CLAUDE.md — プロジェクトコンテキストファイル

Claude Code はプロジェクトルートの CLAUDE.md を自動的に読み込みます。プロジェクトのコンテキストを保持するために使用します：

# Project: My API

## Architecture
- FastAPI backend with SQLAlchemy ORM
- PostgreSQL database, Redis cache
- pytest for testing with 90% coverage target

## Key Commands
- `make test` — run full test suite
- `make lint` — ruff + mypy
- `make dev` — start dev server on :8000

## Code Standards
- Type hints on all public functions
- Docstrings in Google style
- 2-space indentation for YAML, 4-space for Python
- No wildcard imports

具体的に記述してください。「良いコードを書く」の代わりに、「JS は 2 スペースでインデントする」や「テストファイルの末尾に .test.ts を付ける」のように記述します。具体的な指示により、修正のやり取りを減らせます。

ルールディレクトリ（モジュール式 CLAUDE.md）

ルールが多いプロジェクトでは、1 つの巨大な CLAUDE.md の代わりにルールディレクトリを使用します：

• プロジェクトルール： .claude/rules/*.md — チームで共有し、Git で追跡します
• ユーザールール： ~/.claude/rules/*.md — 個人用、グローバル

ルールディレクトリ内の各 .md ファイルは、追加のコンテキストとして読み込まれます。すべてを 1 つの CLAUDE.md に詰め込むよりもすっきりします。

自動メモリ

Claude は、学習したプロジェクトのコンテキストを ~/.claude/projects/<project>/memory/ に自動的に保存します。

• 上限： プロジェクトごとに 25KB または 200 行
• これは CLAUDE.md とは別のもので、セッションをまたいで蓄積される、Claude 自身によるプロジェクトのメモです

カスタムサブエージェント

.claude/agents/（プロジェクト）、~/.claude/agents/（個人）、または --agents CLI フラグ（セッション）を使って、特化型エージェントを定義します。

エージェントの場所の優先順位

1. .claude/agents/ — プロジェクトレベル、チームで共有
2. --agents CLI フラグ — セッション固有、動的
3. ~/.claude/agents/ — ユーザーレベル、個人用

エージェントの作成

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Security-focused code review
model: opus
tools: [Read, Bash]
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization flaws
- Secrets in code
- Unsafe deserialization

次のように呼び出します：@security-reviewer review the auth module

CLI による動的なエージェント

terminal(command="claude --agents '{\"reviewer\": {\"description\": \"Reviews code\", \"prompt\": \"You are a code reviewer focused on performance\"}}' -p 'Use @reviewer to check auth.py'", timeout=120)

Claude は複数のエージェントを統括できます：「@db-expert を使ってクエリを最適化し、その後 @security を使って変更を監査してください。」

フック — イベントに応じた自動化

.claude/settings.json（プロジェクト）または ~/.claude/settings.json（グローバル）で設定します。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
    }],
    "Stop": [{
      "hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> ~/.hermes/cache/scratch/claude-activity.log"}]
    }]
  }
}

8 種類すべてのフック

フック	実行されるタイミング	一般的な用途
UserPromptSubmit	Claude がユーザープロンプトを処理する前	入力の検証、ログ記録
PreToolUse	ツールの実行前	セキュリティゲート、危険なコマンドのブロック（終了コード 2 = ブロック）
PostToolUse	ツールの終了後	コードの自動フォーマット、リンターの実行
Notification	権限のリクエスト時、または入力待ち時	デスクトップ通知、アラート
Stop	Claude が応答を完了したとき	完了のログ記録、ステータスの更新
SubagentStop	サブエージェントの完了時	エージェントの統括
PreCompact	コンテキストメモリが消去される前	セッションのトランスクリプトのバックアップ
SessionStart	セッションの開始時	開発コンテキストの読み込み（例：git status）

フックの環境変数

変数	内容
CLAUDE_PROJECT_DIR	現在のプロジェクトのパス
CLAUDE_FILE_PATHS	変更中のファイル
CLAUDE_TOOL_INPUT	JSON 形式のツールパラメーター

セキュリティフックの例

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
  }]
}

MCP 統合

データベース、API、サービス向けの外部ツールサーバーを追加します。

# GitHub integration
terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)

# PostgreSQL queries
terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)

# Puppeteer for web testing
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)

MCP スコープ

フラグ	スコープ	保存先
-s user	グローバル（すべてのプロジェクト）	~/.claude.json
-s local	このプロジェクト（個人用）	.claude/settings.local.json（gitignore 対象）
-s project	このプロジェクト（チームで共有）	.claude/settings.json（Git で追跡）

Print/CI モードでの MCP

terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

--strict-mcp-config は、--mcp-config で指定されたものを除くすべての MCP サーバーを無視します。

チャットで MCP リソースを参照します：@github:issue://123

MCP の制限と調整

• ツールの説明： ツールの説明とサーバーの指示は、サーバーごとに 2KB が上限です
• 結果サイズ： デフォルトでは上限が設定されています。大きな出力に対して最大 500K 文字を許可するには、maxResultSizeChars アノテーションを使用します
• 出力トークン： export MAX_MCP_OUTPUT_TOKENS=50000 — コンテキストの過剰な消費を防ぐため、MCP サーバーからの出力を制限します
• トランスポート： stdio（ローカルプロセス）、http（リモート）、sse（サーバー送信イベント）

対話型セッションの監視

TUI ステータスの確認

# Periodic capture to check if Claude is still working or waiting for input
terminal(command="tmux capture-pane -t dev -p -S -10")

以下のインジケーターを確認してください。

• 画面下部の ❯ = 入力待ち（Claude の処理が完了したか、質問をしています）
• ● の行 = Claude がツールを使用中（読み取り、書き込み、コマンドの実行など）
• ⏵⏵ bypass permissions on = ステータスバーに権限モードが表示されています
• ◐ medium · /effort = ステータスバーに現在の作業レベルが表示されています
• ctrl+o to expand = ツールの出力が省略されています（対話形式で展開できます）

コンテキストウィンドウの状態

対話型モードで /context を使うと、コンテキストの使用状況が色付きのグリッドで表示されます。主な閾値は次のとおりです。

• < 70% — 通常の動作、精度は最大
• 70-85% — 精度が低下し始めます。/compact の使用を検討してください
• > 85% — 幻覚のリスクが大幅に高まります。/compact または /clear を使用してください

環境変数

変数	効果
ANTHROPIC_API_KEY	認証用 API キー（OAuth の代替）
CLAUDE_CODE_EFFORT_LEVEL	デフォルトの推論レベル：low、medium、high、max、または auto
MAX_THINKING_TOKENS	思考トークンの上限（思考を完全に無効にするには 0 に設定）
MAX_MCP_OUTPUT_TOKENS	MCP サーバーからの出力の上限（デフォルトは状況によって異なります。例：50000 に設定）
CLAUDE_CODE_NO_FLICKER=1	ターミナルのちらつきをなくすため、代替画面表示を有効化
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB	セキュリティのため、サブプロセスから認証情報を削除

コストとパフォーマンスに関するヒント

1. プリントモードでは --max-turns を使用して、ループが暴走するのを防ぎます。ほとんどのタスクでは、まず 5～10 に設定してください。
2. コストの上限には --max-budget-usd を使用します。注：システムプロンプトのキャッシュ作成には、最低でも約 $0.05 かかります。
3. シンプルなタスクには --effort low を使用します（より高速で低コストです）。複雑な推論には high または max を使用します。
4. CI／スクリプトでは --bare を使用して、プラグイン／フックの検出にかかるオーバーヘッドを省きます。
5. 必要なものだけに制限するには --allowedTools を使用します（例：レビューでは Read のみ）。
6. インタラクティブセッションでコンテキストが大きくなったら、/compact を使用します。
7. 既知の内容を分析するだけの場合は、Claude にファイルを読ませる代わりに、入力をパイプで渡します。
8. シンプルなタスクには（低コストの）--model haiku を使用し、複雑な複数ステップの作業には --model opus を使用します。
9. プリントモードでは --fallback-model haiku を使用して、モデルの過負荷に適切に対処します。
10. 別のタスクには 新しいセッションを開始します — セッションは 5 時間続きます。新しいコンテキストのほうが効率的です。
11. CI では --no-session-persistence を使用して、保存済みセッションがディスク上に蓄積されるのを防ぎます。

注意点と落とし穴

1. インタラクティブモードには tmux が必須です — Claude Code は本格的な TUI アプリです。Hermes のターミナルでは pty=true だけでも動作しますが、tmux を使うと監視用の capture-pane と入力用の send-keys が利用でき、オーケストレーションに欠かせません。
2. --dangerously-skip-permissions の警告ダイアログでは、デフォルトで「No, exit」が選択されています — これは安全な選択肢です。隔離された環境で意図的にバイパスを選んだ場合に限り、Down の後に Enter を送信してください。プリントモード（-p）ではダイアログ全体が省略されます。
3. --max-budget-usd の最小値は約 $0.05 です — システムプロンプトのキャッシュ作成だけでこの金額がかかります。これより低く設定すると、即座にエラーになります。
4. --max-turns はプリントモード専用です — インタラクティブセッションでは無視されます。
5. Claude は python の代わりに python を使用する場合があります — python のシンボリックリンクがないシステムでは、Claude の bash コマンドは最初の試行で失敗しますが、自動的に修正されます。
6. セッションを再開するには同じディレクトリが必要です — --continue は、現在の作業ディレクトリにある最新のセッションを見つけます。
7. --json-schema には十分な --max-turns が必要です — 構造化出力を生成する前に Claude がファイルを読む必要があり、そのために複数のターンが必要です。
8. 信頼ダイアログはディレクトリごとに一度だけ表示されます — 初回のみ表示され、その後はキャッシュされます。
9. バックグラウンドの tmux セッションは残り続けます — 終了時には必ず tmux kill-session -t <name> でクリーンアップしてください。
10. スラッシュコマンド（/commit など）はインタラクティブモードでのみ動作します — -p モードでは、代わりに自然言語でタスクを説明してください。
11. --bare は OAuth を省略します — ANTHROPIC_API_KEY 環境変数、または設定内の apiKeyHelper が必要です。
12. コンテキストの劣化は実際に起こります — コンテキストウィンドウの使用率が 70% を超えると、AI の出力品質は測定可能なほど低下します。/context で監視し、先回りして /compact を実行してください。

Hermes エージェント向けルール

1. 単一のタスクではプリントモード（-p）を優先してください — ダイアログへの対応が不要で、出力も整った構造になります
2. 複数ターンにわたる対話型の作業には tmux を使用してください — TUI を制御する唯一の信頼できる方法です
3. 必ず workdir を設定してください — Claude が適切なプロジェクトディレクトリに集中できるようにします
4. プリントモードでは --max-turns を設定してください — 無限ループや予想外のコストを防げます
5. tmux セッションを監視してください — tmux capture-pane -t <session> -p -S -50 を使用して進捗を確認します
6. ❯ プロンプトを確認してください — Claude が入力待ち（完了または質問中）であることを示します
7. tmux セッションを後片付けしてください — リソースのリークを防ぐため、作業完了後に終了させます
8. ユーザーに結果を報告してください — 完了後、Claude が行った作業と変更点を要約します
9. 時間のかかるセッションを終了させないでください — Claude は複数の手順を実行中かもしれません。代わりに進捗を確認してください
10. --allowedTools を使用してください — 実際に必要な機能だけに制限します