Claude Codeの運用知見
Claude Codeの挙動を踏まえた弊社の運用判断を残します。公式ドキュメントに説明がない挙動を実測した場合は調査時期を付し、後から公式の説明が整ったものや、仕様の更新で価値がなくなった記述は置き換えます。機能の一般的な使い方は公式ドキュメントを正本とします。
CLAUDE.mdの管理
記載する製品の前提は、CLAUDE.mdに残す前提の一覧を正本にします。開発者は、記載された公開範囲、環境、許可された操作がGitHubや実行環境の設定と一致するかを確認します。設定から分かる現在の状態と、人が合意した方針を混同しません。
/initで得られる構成やコマンドの案は、対象リポジトリと照合して更新します。依存関係やディレクトリ構成を変更したときに加え、本番運用の開始、公開範囲や担当者の変更時にも見直します。実行できる検査、外部APIに依存してローカルでは確認できない箇所など、検証条件を併記します（Claude Code: Set up a project CLAUDE.md）。
コンテキストの構造
一つの修正で広い範囲のモデルやユースケースを読み込む必要があるなら、業務の境界から構造を見直します。境界づけられたコンテキストでは、対象の業務と外との契約から調査を始められる配置を扱います。
弊社では、毎回必要な約束をCLAUDE.mdへ、特定のファイルを扱うときだけ必要な約束を.claude/rules/の条件付きルールへ分けます。条件付きルールは、paths（対象ファイルのパスを指定する項目）が一致するファイルを読んだときに読み込まれます。すべてを常時読み込む前提で指示を削るのではなく、必要になる場面に合わせて配置し、それぞれを簡潔に保ちます（Claude Code: Path-specific rules）。
CLAUDE.mdはシステムプロンプトの一部ではなく、その後のユーザーメッセージとして渡されます。指示ファイルに禁止を書くだけで操作を強制的に止められるとは考えず、権限設定と組み合わせます。読み込まれる条件などの仕様は公式ドキュメントを正本とし、設定変更後は/contextで実際に読み込まれたファイルを確認します。
スキル内の環境変数
スキルファイル内で$VARと書いても展開されません。!`echo $VAR`構文を使うと、スキル展開時に1回だけ実行されて値へ置き換わります。インラインコードマーカーで囲んだ$VARも展開されません。この構文は現在、公式ドキュメントにdynamic context injectionとして説明があり、仕様の正本はそちらです。
リポジトリ: !`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>/が残り、同名のチームを作成できません。名前を再利用する場合は、残ったディレクトリを手動で削除します。