サマリ： Claude Code でエージェントを定義して使うとき、他からも利用する可能性がある説明・ルールは、エージェント定義に書くのではなくスキルに分離し、エージェント定義には役割・スコープのみを書くと管理性がよいです (エージェントの利用目的によります)。
手元の Claude Code 運用体制
私は色々なタスクを Claude Code に手伝ってもらっていますが、互いのタスクの成果物を参照する必要があるため、Claude Code は親ディレクトリで起動しています (下記構成)。
ただし、それぞれのタスクを手伝ってもらうのに伝える説明・ルールは異なるため、タスクごとにエージェントを定義して定義ファイルに個別に説明・ルールを記述し、常にいずれかのエージェントを指定してセッションを起動しています。
ディレクトリ構成
workspace/ # 親ディレクトリ (ここで Claude Code を起動)
├─ library/ # サブディレクトリ：参考文献とそのメモの置き場
├─ tex-factory/ # サブディレクトリ：LaTeX 文書置き場
├─ lab0/ # サブディレクトリ：実験室0
├─ lab1/ # サブディレクトリ：実験室1
└─ .claude/ # Claude Code 向け
├─ agents/ # エージェントたちの定義ファイル
│ ├─ agent0.md
│ ├─ agent1.md
│ └─ agent2.md
└─ agent-memory/ # エージェントが作成する永続的記憶・引継ぎファイル置き場
生じた課題
上記の体制を長期にわたって運用していると、以下の課題が生じてきました。
- 「エージェント 0 だけに内容物を説明して参照させていたサブディレクトリ 0 を、エージェント 1 にも参照させたい」となることがありますが、エージェント 1 の定義ファイルにも「サブディレクトリ 0 の内容物の説明」を書くと、多重管理になります。
- 「エージェント 0 だけにルールを伝えていた作業 0 を、エージェント 1 にもさせたい」となることがありますが、エージェント 1 の定義ファイルにも「作業 0 のルール」を書くと、多重管理になります。
- 自分 (ユーザ) だけに向けた説明・ルールも必要になることがあります。が、それはエージェント向けの説明・ルールとは分けて、エージェントに「あなた向けではない」旨を伝えなければなりません。
解決方法
以下のように解決しました。
- 各サブディレクトリの内容物の説明は、エージェント定義ではなくスキルで管理します。
- 各作業のルールも、エージェント定義ではなくスキルで管理します。
-
README.mdをユーザ向けのドキュメントとして運用し、全エージェントに注入される.claude/CLAUDE.mdに「README.mdはエージェント向けではない」旨を明記します。
詳細
| ファイル | 説明 | |
|---|---|---|
| 1 | README.md | ユーザ向けのプロジェクト説明・ルール。 |
| 2 | .claude/CLAUDE.md | 全エージェントに共通の説明・ルール。 1 がユーザ向けの記述である旨をここに明記。 |
| 3 | .claude/skills/about-subdir0/ | エージェントが subdir0 を参照する時に必要な説明。 |
| 4 | .claude/skills/doing-work0/ | エージェントが作業 0 をする時に守るべきルール。 |
| 5 | .claude/agents/agent0.md | エージェント 0 の役割・スコープ。 |
- 1 は、エージェントとは無関係に必要な、ユーザ用の情報を書くファイルにします。
- 2 は、全エージェントに共通の説明・ルールを書くものですが、ここで、「README はユーザ用のドキュメントであり、README にある手順・コマンドはエージェントが実行するものではない」のように、README の位置づけをエージェントに明示します。
-
3 には、「このサブディレクトリはこのような構造で、このファイルの内容は…」といった説明を要するサブディレクトリについて、内容物の説明を書きます。フロントマターの
descriptionに「library/ の内容物についての説明」などと書けば、デフォルトで必要なときに利用されます。明示的に自動利用を禁止しない限り、Claude はdescriptionをもとに、必要なスキルを自動的に利用します。エージェント定義ファイルに「このスキルを使ってください」と書く必要はありません (書いてもよいとは思います)。 -
4 には、「Python スクリプトを書くとき」「LaTeX 文書を書くとき」「LaTeX 文書で数式を書くとき」など、作業ごとのルールを書きます。これもフロントマターの
descriptionに「LaTeX 文書 (.tex) を編集するときのルール」などと書けばよいです。 - 5 には、各エージェントの (キャラクター設定と) 役割・スコープのみを書きます。そのエージェントに必要な説明・ルールは 3, 4 に分離します。そうしておく方が、「やはり他のエージェントにもこの説明を見てほしい / この作業を依頼したい」となったとき、メンテナンスコストが不要 / 小さくなるし、毎回は使わない説明・ルールがある場合はコンテキストの節約にもなります。
ディレクトリ構成は以下のようになります。★ が今回位置づけを改めたファイルです。
ディレクトリ構成
workspace/ # 親ディレクトリ (ここで Claude Code を起動)
├─ README.md # ユーザ用のプロジェクト説明・ルール ★
├─ library/ # サブディレクトリ：参考文献とそのメモの置き場
├─ tex-factory/ # サブディレクトリ：LaTeX 文書置き場
├─ lab0/ # サブディレクトリ：実験室0
├─ lab1/ # サブディレクトリ：実験室1
└─ .claude/ # Claude Code 向け
├─ CLAUDE.md # 全エージェントに共通の説明・ルール ★
├─ skills/ # エージェントが特定条件下で見るべき説明・ルール ★
│ ├─ about-subdir0/SKILL.md
│ ├─ about-subdir1/SKILL.md
│ ├─ doing-work0/SKILL.md
│ └─ doing-work1/SKILL.md
├─ agents/ # エージェントたちの定義ファイル ★
│ ├─ agent0.md
│ ├─ agent1.md
│ └─ agent2.md
└─ agent-memory/ # エージェントが作成する永続的記憶・引継ぎファイル置き場
備考
- 3, 4 で Claude Code のスキルを、「特定条件下で必要な説明・ルールをエージェントに伝える手段」に使っていますが、もちろんその他のスキルも共存できます。
-
3 について、「サブディレクトリに関するルールは、サブディレクトリ以下の
CLAUDE.mdまたは.claude/rules/に置いてフロントマターに対称のpaths:を書くのが常套手段では」と思うかもしれません。が、これらはそのサブディレクトリ以下のいずれかのファイルを読み込むことが読み込みトリガーになるはずです。私の場合は、先んじて「そもそもどのファイルを読むのか」を指示したいので、ニーズに合致しませんでした。 -
4 についても、サブディレクトリ以下
CLAUDE.mdやフロントマター付き.claude/rules/を使えばよいのでは、と思うかもしれません。が、私の場合、「このエージェントはこのサブディレクトリを参照はするが編集はしない」というケースがよくあります。参照するだけのエージェントにまで編集ルールを読み込ませるのはコンテキストの無駄どころか作業遂行精度に害があるまであるので、やはりスキルの方がニーズに合っています。