Claude Codeの運用知見
公式ドキュメントからは分からず、検証して初めて分かったClaude Codeの挙動と、それを踏まえた運用の判断を残します。仕様は更新で変わるため、実測にもとづく記述には調査時期を付し、価値がなくなった記述は削除します。機能の一般的な使い方は公式ドキュメントを正本とします。
CLAUDE.mdの管理
CLAUDE.mdはリポジトリの構成やコマンドが変わるたびに古くなります。依存関係の追加やディレクトリ構成の変更など、大きな変更を加えた後に/initで更新します。古いままにすると、誤った前提で動作する原因になります。
コードから読み取れない制約や既知の問題もCLAUDE.mdに書きます。特定のページが外部APIに依存していてローカルでデバッグできない、といった事情を残すことで、AIが不要な修正へ着手するのを防ぎます。
コンテキストの構造
CLAUDE.mdと.claude/rules/配下のファイルは、毎ターンシステムプロンプトへ全文展開されます（2026年3月調べ）。ファイルが増えた分だけ毎ターンのトークンを消費するため、指示ファイルは簡潔に保ち、価値のない記述を残しません。
ファイル変更通知やスキル一覧は、会話の途中で<system-reminder>としてオンデマンドに注入されます。システムプロンプトに常駐させる指示と、必要な時だけ届く情報が分かれていることを前提に、指示ファイルの分量を判断します。
スキル内の環境変数
スキルファイル内で$VARと書いても展開されません。!`echo $VAR`構文を使うと、スキル展開時に1回だけ実行されて値へ置き換わります。インラインコードマーカーで囲んだ$VARも展開されません。
リポジトリ: !`echo $CUSTOM_REPOSITORY_ID`
環境変数は、トークンや個人IDをグローバル設定（~/.claude/settings.json）へ、リポジトリ固有の値をプロジェクト設定（.claude/settings.json）へ置きます。スキルへ値をハードコードせず環境変数から読むことで、同じスキルを複数のプロジェクトで使い回せます。
ターミナル出力のMarkdown
CLAUDE.mdやoutput styleで出力形式を指示するときは、ターミナルで装飾される要素を前提にします（2026年3月調べ）。
- 装飾が効く: 太字、斜体、インラインコード、引用、箇条書き、テーブル、コードブロック
- 装飾されない: 見出し、水平線、チェックリスト
- 色が付くのはコードブロックのシンタックスハイライトのみで、HTMLタグやLaTeXによる色指定は効かない
変更点の提示にはdiffブロックを使います。追加行が緑、削除行が赤で表示されます。補足や注意は引用ブロックにすると薄い色で表示されます。
Agent Teams
.claude/agents/のカスタムエージェントは、subagent_typeへ名前を渡すことでチームメイトとして起動できます。frontmatterの設定も反映されることを確認済みです（2026年2月調べ）。
チームメンバーとして起動された場合だけSendMessageツールが追加されます。単独起動と兼用するエージェントは、この差分を使ってプロンプト内で動作を分岐できます。
TeamDeleteを呼ばずにセッションが終了すると~/.claude/teams/<name>/と~/.claude/tasks/<name>/が残り、同名のチームを作成できません。名前を再利用する場合は、残ったディレクトリを手動で削除します。