Claude Codeで複数のプロジェクトを回しているうちに、サブエージェントが増え続けました。
必要になるたびに1つずつ作っていたら、22個になっていました。
先月、17個まで減らしました。
ただ、たたむときに、なぜたたむのかを書き残していませんでした。
3か月後にアーカイブフォルダを開いてみると、なぜやめたのか分かりませんでした。
5つのうち、理由が書かれていたのは1つだけでした。
作ったのは自分ひとりなのに、それでもそうなりました。
なぜ22個まで増えたのか
増やすときは、理由はいつも明確です。必要だから作ります。
問題は逆です。たたむときには、"もしかしたら後で使うかも" がずっと引っかかります。
役に立たないと確信できないので、そのまま残します。そうして22個になりました。
今振り返ると、増えた原因は1つでした。
「これはエージェントではなくツールであるべきだ」を判断するゲートがありませんでした。
反復作業で、手順が固定されていて、文脈判断が不要なら、それはエージェントではありません。
スキルやスクリプトとして作れば済みます。トークンを使わず、再現性は100%で、セッションが変わっても忘れません。
このゲートがないと、全部エージェントになります。
たたんだ5つ
振り返って整理すると、処分は4種類に分かれていました。この区分が重要でした。
1つは、そもそもエージェントであるべきではありませんでした。
コンテンツ作成を担当していたものでしたが、手順が完全に固定されていました。
スキル2つで置き換えて終了しました。これは復元禁止として明記しました。
そうしないと、いつか誰かがまた作ります。
3つは、ほかのものと役割が重複していました。
セキュリティ点検はコード監査と、cron監視はヘルスチェックと、企画は実行と重なっていました。
どれも同じ領域で同じ権限でした。
ここで得た基準が1つあります。
2つのエージェントが同じ領域・同じ権限で重なるなら、
分離を維持するコスト（管理負荷、委任判断の遅延）はメリットを上回ります。
「どちらも必要ではある」という感覚に長く足を引っ張られましたが、
必要かどうかではなく、分けておく価値があるかを問うべきでした。
1つは、単に誰も使っていませんでした。
その機能のトラフィックは70日間で0件でした。
これは廃止ではなく休眠として扱いました。サービスが再開したらそのまま復元します。
数字を書くときに学んだこと
22 → 17をドキュメントに書きながら、1つ気づきました。
この数字はファイル数ではありません。運用中のエージェント数です。
ディレクトリ外に定義があるものも1つあるので、ファイルだけ数えると21と16になります。
そのため、ドキュメントの冒頭に、この数字が何を数えたものなのかを先に書きました。
そして git ls-tree で検証した結果も一緒に入れました。
そうしないと、後で誰かがファイルを数えて「合っていません」で終わります。
数字を書くときは、定義と検証方法を一緒に書くべきだと分かりました。
たたむときに守ることにしたもの
今回痛い目を見たことで、ルールが4つできました。
-
廃止時点で理由をファイルに書く。書かないと3か月後に逆算することになります。実際にそうなりました。
-
削除せず、renameで移動する。内容が100%保存されるので、元のまま復元できます。
-
復元禁止項目を明記する。書かないと、いつか誰かが復活させます。
-
復元手順に「吸収先で重複役割を除去」を入れる。これを抜くと、復活させたときに両者が同じ仕事をします。
一緒に整理したもの
この機会に、4年分のルールをまとめて公開しました。いくつかだけ書いてみます。
こっそり迂回しない
エージェントが制約にぶつかったとき、突破せずに報告させるためのルールです。
正当なブロックなら、その段階だけ保留し、残りはそのまま進めます。
誤判定に見えるブロックでも、勝手に迂回しません。根拠を整理して上げ、確認を受けます。
そして、ブロックがルール自体の欠陥を明らかにしたなら、その欠陥を直すところまでが対応です。
実際、このルール自体がそうやって生まれました。ブロックを経験してから作りました。
FAILをPASSとして書かない
指示でクローズする案件でも、実測状態をそのまま書き、再オープン条件を残します。
報告はBefore/Afterの実測値で行い、残件とリスクを成果より先に書きます。
エージェントは基本的に成功報告をしようとする圧力を受けます。ルールで防がないと、ずっとそうします。
自律性を定量しきい値で定義する
「修正可/修正不可」という二分法ではなく、分析型エージェントが自力で直せる範囲を数字で定めました。
-
1ファイルのみ
-
5行未満
-
上位等級ファイルではない
-
インパクトスコアのしきい値未満
すべて満たす（AND） 場合のみで、1つでも引っかかれば上申します。
そして最後の条項が核心です — 曖昧なら委任を要請する。デフォルトが保守的であるべきで、そうでないとルールは崩れます。
判定と執行の分離
検証・調査は読み取り専用のサブエージェントに並列ファンアウトし、
ファイル・DBの執行はオーケストレーターが中央で直列に処理します。
共有ファイルを複数のエージェントが同時に変更すると、必ず壊れるからです。
代償はあります。大規模作業では中央直列はボトルネックです。
遅くなると分かっていても、衝突よりはましだと判断した結果です。
リポジトリ
https://github.com/YoungChulMoon/claude-agent-harness
Markdownファイルが数個あるだけです。インストールするものはありません。
テンプレートを .claude/agents/ の下に置き、必要な部分だけ埋めれば使えます。
唯一の正解というより、この環境で4年間動いたやり方です。
チーム規模やプロジェクトの性質によっては合わないかもしれません。
増やす話は多いのに、減らす話はあまり見かけませんでした。
同じようにエージェントが膨らんでいる人の参考になればうれしいです。
まだコメントはありません。