Claude Codeのサブエージェント定義ファイルの作り方——.claude/agents/最小構成リファレンス

Claude Codeで新しい役割を持つサブエージェントを追加する方法が整理された。.claude/agents/というディレクトリにマークダウンファイルを1枚置くだけで新しいサブエージェントが認識される仕組みだ。必須項目は役割の名前と説明の2つで、そこにツール権限とモデル選択を加えることで、役割の重さに見合ったコスト管理ができる。ファイルの本文がそのエージェントのシステムプロンプトになり、業務指示書のように自然な日本語で「何をする人か」「どんな手順か」「何をしてはいけないか」を書くだけで動作する。

ここで優れているのは「権限分離のセキュリティパターン」として機能する点だ。レビュー役に書き換え権を渡さない、調査役にAPI呼び出し権を渡さないといった「役割に必要な権限だけを最小限」という考え方が実装されている。これは多くのAIツールにはない設計だ。なぜなら、他のツールは「全か無か」の権限管理しか用意していないからだ。チーム内に複数のAIが必要な場合、全員に同じ権限を渡すことは無駄であり、事故の温床になる。実装チームのすべてを最高性能モデルで回すのと同じ浪費だ。Claude Codeのこの設計は意外と実務的な強みであり、「デバッグ用のAI」と「本番投入するAI」を同じプロジェクト内で分けられるという柔軟性を与えている。

チーム内でAIを並立させるとき、全員に同じ権限を渡すな。調査・ドラフト・レビュー・実装といった段階ごとに「そのステップに必要な権限」だけを与え、本文に「やってはいけないこと」を明記することで、手作業での確認ポイントを劇的に減らせる。権限を細かく切ることは面倒に見えるが、実は「AIの暴走を予防する最強のフェンス」なのだ。