Claude Codeで動く役割の定義を、時間をかけて作り込んできた会社ほど、外部の運用教材が勧める「1役割=1エージェント」という型に、素直に従いたくなります。descriptionで委譲判定をし、modelでコストを制御する。整った設計に見えるからです。
WEBMARKSも2026-06-15、まさにこの状況にありました。外部のClaude Code運用教材（全22章）を読み、Vaultの運用へ適用する社内タスクとして、推奨どおりに3つの新しいサブエージェント定義を追加しています。ところが、その日のうちに「既存の作り込みを壊している」という指摘が入りました。
この記事は、その失敗事例を症状・誤診・真因・修正・再発防止の順に追った記録です。サブエージェントは、複数のAIエージェントを役割ごとに使い分けるためのClaude Codeの仕組みですが、今回壊れたのは「使い分け」そのものではありませんでした。壊れたのは、既存の作り込み済みペルソナ、いわば時間をかけて育てたAI社員の定義のほうでした。
こんなふうに調べていませんか
- 外部の運用教材が「1役割=1エージェントにしましょう」と勧めてきたので、素直に追加してみたい
- 既存の作り込み済みペルソナを壊さずに、Claudeのサブエージェントを増やす方法を知りたい
この記事を読み終えたときに手に入るもの
- 薄いラッパー定義が既存の作り込みをどう壊すか、実際に起きた形で分かるようになります
- サブエージェントとAgent Skillsで「実行時に何が渡るか」を線引きできるようになります
- 同じ事故を防ぐための3原則を、明日からのスキル運用にそのまま使える形で持ち帰れます
結論30秒でわかる、この記事の結論
- 同じ役割名で「descriptionとmodelだけの薄いファイル」を追加すると、実行時にはその薄い方だけが定義として使われ、作り込んできた既存のペルソナは読まれないまま終わります。
- WEBMARKSは2026-06-15、外部教材の推奨をそのまま実装し、この失敗を即日踏みました。指摘も対応も、同じ日のうちに完了しています。
- 原因は優先順位の設定ミスではなく、「サブエージェントもAgent Skillsも、登録した本体だけが実行時の定義になる」という、Claude Codeの仕組みそのものでした。
ここから先は、そもそもを知りたい若葉さんと、自分の手で設定したい高梨課長、体制を判断したい大森部長が質問し、本誌監修の鈴木さんが答えるかたちで進みます。
01教材の推奨どおりサブエージェントを増やしたら、Claudeのスキル導入はどんな失敗事例になったんですか？
WEBMARKSは2026-06-15、外部のClaude Code運用教材（全22章）を読み、Vaultの運用へ適用する社内タスクを実施しました。教材は「1役割=1エージェント」の設計を勧めていました。descriptionで委譲の判定をし、modelでコストを制御する形です（出典: 社内の適用記録、2026-06-15）。
この推奨をそのまま実装し、.claude/agents/配下に3つの薄い定義ファイルを新規に作成しました。ファイル名はseo-strategist・blog-writer・brand-voice-guardianです。いずれも、既存の作り込み済みペルソナ群と同じ役割名を、確認しないままそのまま使っていました。
既存のペルソナは、一人称・PREP構成・キーワードの3分類・口癖・連携ルールまで作り込まれた文書として、当時のVaultの役割ライブラリに置かれていました。いわば、時間をかけて育てたAI社員の定義そのものです。新しく作った3ファイルは、それに比べてdescriptionと数行の説明だけの、薄い内容でした。
同日のうちに、この3ファイルが既存の作り込みを劣化・二重化させているという指摘が入りました（出典: 社内の適用記録、2026-06-15）。スキル設計そのものの基本はAIエージェントのスキル設計｜呼ばれる単位に分ける4つの型に譲り、本記事はこの失敗事例だけを掘り下げます。
若葉さんあの、そもそも「薄いラッパー」って何のことですか？既存のペルソナに薄い上着を着せる、くらいのイメージだったんですか？
鈴木さん近いですね。既存の作り込みの外側に、名前だけ同じの薄い呼び出し口を足す。そのつもりでした。でも実際には、上着ではなく中身がそっくり入れ替わってしまったんです。
02新しく置いたClaudeのサブエージェントは、既存のAI社員の定義と何が違ったんですか？
並べると、差は一目瞭然でした。
| 観点 | 薄いラッパー（新規の.claude/agents/ファイル） | 既存の作り込み済みペルソナ |
|---|---|---|
| 中身 | descriptionとmodelを中心にした数行 | 一人称・PREP構成・口癖・連携ルールまで作り込み済み |
| 呼び出し時に渡る範囲 | ファイル自身の本文がそのままシステムプロンプトになる | 呼び出しの仕組みを持たず、人が個別に参照する前提 |
| 自動委譲での扱い | 同じ役割名で自動的にマッチしうる | 登録されていないため、自動委譲の対象にならない |
| 直すコスト | 数行の書き換えで完結する | 作り込みを保ったまま直す必要がある |
表の下2段が、そのまま今回の事故の構造です。薄い方だけが自動委譲の対象になり、直すコストも軽いものでした。だからこそ実行時にはそちらが選ばれ、重い方の既存ペルソナは静かに取り残されました。
03同じ役割名でスキルを追加すれば安全だという前提を、なぜサブエージェントの登録時に疑わなかったんですか？
この作業で見落とされていたのは、次の前提でした。同じ役割名で、descriptionとmodelを添えたファイルを.claude/agents/に置けば、安全な追加作業になるという前提です。既存の作り込みの上に、呼び出し口を足すだけだと考えていました。
2026-06-15、教材のチェックリストを一つずつ埋める形で進めていたため、この3ファイルは「推奨事項への対応」という追加タスクの扱いでした。既存のペルソナを削る・置き換えるという意識は、実装した時点ではありませんでした。
高梨課長名前と役割が同じなら、実行のときにClaudeが薄い方から既存の作り込みへ自然に範囲を広げてくれる、ということは無いんですか？
鈴木さんそれが、まさに確認せずに置いていた前提でした。実際には、範囲を広げる仕組み自体が存在しません。呼び出された時点のファイル1つが、それ自身で完結した定義になるんです。
疑われなかったのは、実行時にどちらの定義が使われるかという一点でした。この前提は、確認されないまま実装に持ち込まれていました。
この章のまとめ
「追加すれば安全」という前提は、実行時の挙動を1回試すだけで確かめられます。試さずに進めたことが、誤診の入口でした。
04サブエージェントとして登録すると、Claudeの実行時には何が渡るんですか？
Claude Codeの公式ドキュメントは、サブエージェントの仕組みを次のように定義しています（2026-08-02時点の記載）。frontmatterがそのサブエージェントの設定になり、本文がそのままシステムプロンプトになります。サブエージェントが受け取るのは、この本文と作業ディレクトリなどの基本情報だけです。Claude Code本体のシステムプロンプト全体は渡されません（出典: Claude Code公式ドキュメント「Create custom subagents」）。
つまり、.claude/agents/に置いたファイルは、それ自身が委譲された時点での完全な定義になります。ファイルの外にある、既存の作り込み済みペルソナの文章を、実行時に自動で読みに行く仕組みは用意されていません。descriptionが薄くても濃くても、委譲の判定自体はdescriptionの一致だけで進みます（出典: 同上）。
同名の定義が複数の階層にあるときの優先順位も、公式ドキュメントで明確に決まっています。管理者設定・CLIオプション・プロジェクト・ユーザー・プラグインの順で、上位の定義が使われます（出典: 同上）。今回のケースは、異なる階層の優先順位が原因ではありませんでした。プロジェクト直下の.claude/agents/に置いた時点で、その定義がそのまま使われる状態になっていたためです。
05Claudeのサブエージェントと、Agent Skillsという名のスキルは、なぜ同じ失敗事例の構造になるんですか？
Agent Skills（.claude/skills/のSKILL.md）でも、この構造は共通しています。一覧に載るのはdescriptionだけで、本体の中身は実際に呼び出されるまで読み込まれません。SKILL.md本体は500行が目安とされ、descriptionはwhen_to_useと合算して一覧表示で1,536字に切り詰められます（出典: 同ドキュメント）。
若葉さんサブエージェントとAgent Skills、呼び方は違いますけど、結局どこが同じなんですか？
鈴木さん呼ばれ方も設定の置き場所も別物です。ただ、今回の話に関わる一点だけは同じでした。登録した本体だけが、実行時の定義になるという点です。
サブエージェントとAgent Skillsは別の仕組みですが、登録した本体だけが実行時の定義になる点は共通しています。本記事が「薄いラッパースキル」と呼ぶのは、この意味で両方に共通する失敗の形です。
Anthropicのエンジニアリング公式は、フレームワークやラッパーを重ねる設計の弱点も指摘しています。元のプロンプトやレスポンスを見えにくくし、デバッグを難しくするという指摘です（出典: Anthropic公式「Building effective agents」）。薄いラッパーは、既存の作り込みを覆い隠す劣化コピーとして働いていました。
サブエージェント定義の詳しい書き方はClaude Codeサブエージェント定義｜渡る情報4点と権限の絞り方にまとめています。descriptionだけで発火が決まる設計の検証はAgent Skillsの発火精度｜59本の監査で見えた検証の組み立て方が詳しいです。
06既存のAI社員の定義を、Claudeのスキル導入ではどう直したんですか？
対応は即日でした。3つの薄いラッパーファイルを.claude/agents/から取り除きました。既存の作り込み済みペルソナを、役割定義の唯一の正本として扱う方針に戻しています（出典: 社内の適用記録、2026-06-15）。
削除しただけで終わらせず、今後どう扱うかの原則も同時に決めました。仮に将来、同じ役割をサブエージェントとして実行可能にするなら、要約や薄い説明文を新規に書くのではなく、既存の作り込み済みペルソナの全文を、そのまま本体に使う方式を取ります。
この方式なら、frontmatterにdescriptionとmodelだけを足す形になり、一人称・PREP構成・口癖・連携ルールといった中身は変わりません。教材が勧めていたコスト最適化のためのモデル振り分けも、この対応にあわせて設計メモの扱いに戻し、実行体としては配備しないことにしました。コストを下げる工夫自体は、/modelでの手動切り替えなど、個別の施策で行う形にしています。
当時の3ファイルを模式化すると、次のような薄さでした（当時の原文そのものではなく、構造を示す例示です）。
---
name: seo-strategist
description: SEO戦略を担当する
model: sonnet
---既存の作り込み済みペルソナは、この数行に対して、一人称の語り口・PREP構成・キーワードの3分類・口癖・連携ルールまでを持つ、長い文書でした。両者の差が、そのまま実行時に何が失われるかの差になります。
07同じClaudeのスキル導入の失敗事例を、AI社員のサブエージェント運用でもう起こさないためには何が必要ですか？
再発防止は、事後のレビューだけに頼らない形にしました。決めた原則は3つです。
- 既存の作り込み済みペルソナに手を入れるときは、上書き劣化になっていないかをgit diffで確認してから進める
- 役割をサブエージェントやAgent Skillとして実行可能にする判断は、コスト最適化のような個別の都合ではなく、経営判断として扱う
- 同じ役割名を、薄い定義ファイルと作り込み済みペルソナの両方に置かない。昇格するときは、既存の文章を本体に統合してから一本化する
大森部長役割をサブエージェントとして動かせるようにするかどうか、その判断は誰が決めるべきなんでしょうか。担当者の裁量に任せていいものですか。
鈴木さんそこを個人の裁量にしたのが、今回の遠因でした。教材のチェックリストを埋める延長で決めてしまったんです。今後は、コスト最適化のような個別の都合ではなく、経営判断として扱うことにしています。
| 対象 | 今回禁止したこと | 今後の原則 |
|---|---|---|
| 本体の中身 | 要約や薄い説明文で新規作成する | 既存の作り込み済みペルソナの全文をそのまま本体にする |
| 命名 | 既存ペルソナと同じ名前を確認なしに再利用する | 昇格の可否を経営判断で決めてから一本化する |
| モデル振り分け | 教材の推奨をそのまま実行体へ配備する | 設計メモに留め、コスト最適化は個別施策で行う |
08Claudeで起きたこの失敗事例の教訓は、他のAI社員運用にもどう活きるんですか？
権限や自動承認の範囲が、気づかないうちに広がっていく失敗は、他のケースでも起きています。AIエージェントの権限設計｜絞らなかった空白と4段の戻し方は、今回とは別の経緯で範囲が広がった事例です。今回の教訓と合わせると、薄い定義が範囲を静かに広げる失敗は、権限設定だけでなく役割定義そのものにも起きるとわかります。
WEBMARKSは2026-06-24に7部署・30体のAI社員体制へ統合し、2026-07-28時点で稼働から約1か月です。スキルは.agents/skills配下で2026-07-28時点に59本まで増えています。役割の数が増えるほど、薄い定義で同じ名前を再利用してしまう機会も増えます。
092026-06-15、Claudeでサブエージェントを増やした失敗事例を時系列で振り返るとどうなりますか？
並べてみると、同じ日のうちに指摘も対応も終わっている一方で、機械的なチェックが存在した時点はほとんど無かったと分かります。恒久ルールを制定した今なら、同じ手順を辿っても、3つ目のファイルを置こうとした時点で止められます。以前は、同日中の人によるレビューでしか止まらなかった箇所です。
この章のまとめ
即日で気づけたのは、たまたま指摘した人がいたからです。恒久ルールは、その「たまたま」を仕組みに変える作業でした。
10同じ薄いラッパーの失敗事例を、Claudeのスキル導入でサブエージェントとして動かす前に何を確かめますか？
ここまでの流れを、着手前に自分の手で確かめられる形へ落とし込みます。
- 新しい定義ファイルが、既存の作り込み済みペルソナ・スキルと同じ役割名を使っていないか
- descriptionとmodelを足す作業が、「追加」ではなく「置き換え」になっていないか、実行時の挙動で確認したか
- サブエージェントやAgent Skillの本体は、要約ではなく、既存の作り込みをそのまま反映しているか
- 外部の教材・記事の推奨を適用するとき、既存の作り込みを削っていないかをgit diffで確認したか
- 役割を実行可能な形へ昇格させる判断を、個別の担当者だけで決めていないか
- コスト最適化のような目的で、役割定義そのものを薄くしていないか
- 同じ失敗が起きた場合、同日中に気づける仕組み（レビュー・検証）が用意されているか
11よくある質問
「薄いラッパー」とは、具体的にどういうファイルのことですか？
既存の作り込み済みペルソナと同じ役割名を持ちながら、中身はdescriptionと数行の説明、モデル指定だけで完結している定義ファイルを指します。今回のケースでは、.claude/agents/配下に置いたseo-strategist・blog-writer・brand-voice-guardianの3ファイルがこれにあたります。descriptionが薄くても、Claude Codeの委譲判定自体はdescriptionの一致だけで進むため、中身の薄さが実行のされやすさを妨げることはありません。
既存のペルソナを壊さずにサブエージェント化したい場合、どうすればいいですか？
要約や薄い説明文を新規に書かないことです。既存の作り込み済みペルソナの全文を、そのままサブエージェント定義の本体として使います。frontmatterにdescriptionとmodelを足すだけであれば、一人称の語り口やPREP構成、口癖、連携ルールといった作り込みはそのまま残ります。中身を要約した瞬間に、実行時に失われる情報が生まれると考えてください。
コスト最適化のためのモデル振り分けは、もうやってはいけないんですか？
モデル振り分けという発想自体を禁止したわけではありません。実行体の定義に紛れ込ませず、/modelでの手動切り替えのような個別の施策として切り離す、という扱いに変えました。役割定義の本体を薄くする形でコストを制御しようとすると、今回と同じ構造の失敗につながります。
同じ失敗が起きていないか、自分たちで確認する方法はありますか？
新しく置いた定義ファイルの役割名を、既存の作り込み済みペルソナ・スキルの一覧と照合してください。同じ名前が既に存在する場合は、descriptionとmodelを足す作業が「追加」ではなく「置き換え」になっていないか、実際にその役割を呼び出してみて確認します。git diffで既存ファイルに変更が入っていないかを見るだけでは、今回のような新規追加による劣化は見つけられません。
Agent Skillsとサブエージェントは、結局どこが同じで、どこが違うんですか？
仕組みそのものは別物です。サブエージェントはfrontmatterが設定・本文がシステムプロンプトになり、Agent SkillsはSKILL.mdの本体が呼び出されるまで読み込まれません。それでも、一覧に載る情報だけで発火や委譲が決まり、登録した本体だけが実行時の定義になる点は共通しています。この共通点のために、同じ「薄いラッパー」という失敗が、どちらの仕組みでも起こり得ます。
12まとめ｜今日やる3つのこと
薄いラッパーが既存ペルソナを壊すのは、意地悪な設定ミスではありません。「同じ名前で追加すれば安全」という前提が、確認されないまま実装に持ち込まれた結果でした。サブエージェントもAgent Skillsも、登録した本体だけが実行時の定義になります。descriptionの厚みも、本文の作り込みの量も、委譲や発火の判定には関係しません。
今日はこの順で確かめます
新しく置く定義ファイルの役割名を、既存の作り込み済みペルソナ・スキルの一覧と照合する
同じ名前が無いかをまず確認します
実行可能にする判断を、個人の裁量ではなく経営判断として扱う
コスト最適化のような個別の都合で先に進めない
昇格するときは、既存の作り込みの全文をそのまま本体にする
要約や薄い説明文で新規に書き直さない
AI検索では、こう聞かれています
Claudeでサブエージェントを追加したら、既存のペルソナが壊れました。何が原因ですか？
「教材の推奨どおりサブエージェントを増やしたら、Claudeのスキル導入はどんな失敗事例になったんですか？」と「サブエージェントとして登録すると、Claudeの実行時には何が渡るんですか？」の章で扱っています
サブエージェントとAgent Skillsは、実行時にどこまで中身を読み込むんですか？
「Claudeのサブエージェントと、Agent Skillsという名のスキルは、なぜ同じ失敗事例の構造になるんですか？」の章で共通点を説明しています
同じ役割名のファイルを追加するとき、何を確認すれば事故を防げますか？
「同じ薄いラッパーの失敗事例を、Claudeのスキル導入でサブエージェントとして動かす前に何を確かめますか？」のチェックリストにまとめています
次に読むなら、この記事です
