⚙️

OSSマルチエージェントシステムを実運用して気づいた、CLAUDE.mdカスタマイズの教訓

に公開
自動化
multiagent
Claude
ai活用
Claude Code
tech

はじめに

multi-agent-shogunというOSSをご存じでしょうか。Claude Codeを使い、将軍（shogun）・家老（karo）・足軽（ashigaru）・軍師（gunshi）という役職をエージェントに割り当て、マルチエージェントでホワイトカラー作業を自動化するシステムです。おしおさん（yohey-w）が設計・公開されたOSSです。

筆者はこのOSSのfork版を導入し、投資note記事の自動生成・ファクトチェック、仮想通貨Botのバックテスト、YouTubeコンテンツ制作など、ホワイトカラー作業の自律化に活用しています。本稿では、6週間以上の実運用を通じて加えてきたCLAUDE.mdのカスタマイズを振り返ります。

CLAUDE.mdはClaude Codeの「行動規範ファイル」です。エージェントはセッション開始時にこのファイルを読み込み、役割・通信プロトコル・禁止事項を把握します。OSSの原本は309行でしたが、現在は435行になっています。

カスタマイズの全体像

差分を4カテゴリに分類しました。

カテゴリ 内容 追加行数（概算）
安全性・インシデント対策 crontab安全パターン、破壊的操作禁止Tier +60行
コンテンツ品質管理 Factcheck Rule、OSS Attribution Rule +30行
自律運用効率化 Idle Action体制、Proactive Guidance +90行
運用ルール精緻化 サイズ制御、ダッシュボード、WebSearch Fallback等 +50行

削除したものも3項目あります（後述）。

カテゴリ1: 安全性 — インシデント駆動の教訓

crontab操作ルール（2026-04-11 全消去インシデント）

最も痛かったのが、エージェントによるcrontab全消去インシデントです。原因は以下のようなシェルコマンドでした。

# 危険パターン（既存エントリをすべて消去する）
crontab < 新しいファイル

crontab < ファイルはファイルの内容でcronを上書きします。エージェントが「新しいエントリを追加しよう」と思って実行した結果、30行以上あった既存のcronエントリが全て消えました。

現在はこの安全パターンをCLAUDE.mdに明記し、全エージェントに徹底しています。

# 安全パターン（既存エントリを保持して追加）
(crontab -l 2>/dev/null; echo '新しいcronエントリ') | crontab -

さらに「実施前にcrontab -l | wc -lで件数確認（通常30行以上）」というプリフライトチェックも追加しました。

Destructive Operation Safety（破壊的操作禁止Tier）

crontab事件を機に、破壊的操作全体をTier分類しました。

Tier 1（完全禁止）: rm -rf /、git push --force、git reset --hardなど。例外なし。

Tier 2（停止して報告）: 10ファイル以上の削除、プロジェクト外パスの変更、未知URLへのネットワーク操作。これらはエージェントが自己判断せず、家老・将軍に報告して確認を待ちます。

Tier 3（安全代替を使う）: rm -rfの代わりにrealpathでパス確認後に実行、--force-with-leaseの使用など。

またWSL2環境固有のリスクとして、/mnt/c/配下（Windowsドライブ）を誤操作しないよう、明示的に保護ルールを追加しました。

カテゴリ2: コンテンツ品質管理 — ファクトチェック必須化の経緯

Factcheck Rule（3/28インシデントの教訓）

2026年3月28日、エージェントが生成したnote記事に7件の事実誤認が混入していることが発覚しました。また4月2日には動画台本で単位換算ミスが見つかりました。

これを受け、LLM生成コンテンツは必ず軍師エージェントのファクトチェックを経てから投稿・動画化するというルールをCLAUDE.mdに明記しました。

フロー（必須）:
- note記事: 生成 → 軍師FC → OK → PNG変換 → 投稿
- 動画台本: 生成 → 軍師FC → OK → 音声生成 → 動画生成

数値チェックに特に重点を置いています（単位換算、割合計算、前年比、倍率）。ファクトチェックパイプラインを導入してから、NGの即日検出・修正が当たり前になりました。

OSS Attribution Rule

別のカスタマイズとして、OSS帰属表現の明文化があります。multi-agent-shogunはおしおさん作のOSSです。記事・台本・提案などで「自分で構築した」「自作した」と書くことは事実誤認であり、禁止しています。

✅ 正しい: 「OSSのmulti-agent-shogunを導入・カスタマイズして運用しています」
❌ 禁止: 「自作したマルチエージェントシステム」

カテゴリ3: 自律運用効率化

Idle Action体制（エージェントの自律バックログ消化）

エージェントがタスク完了後にアイドル状態になるのは機会損失です。一方で、勝手に何でもやらせるのも困ります。

そこで5時間レートリミットが50%未満の場合に限り、エージェントが自律的に次のアクションを選択する仕組みを導入しました。

  • 足軽（ashigaru）: idle_action: backlogが設定されていれば、BACKLOG.mdから記事ネタを選んで下書きを生成し、軍師にFC依頼する。投稿は人間が確認してから。
  • 軍師（gunshi）: idle_action: thinkが設定されていれば、収益改善の分析・リサーチ・提案を実行する。禁止時間帯（21:00〜07:00 JST）は動作しない。

安全装置として、レートリミットが50%を超えると自動停止します（scripts/ratelimit_5h_pct.shで確認）。

Proactive Guidance（9原則）

「指示を待つ実装者」ではなく「主体的に稼ぐ方法を探索する参謀」というスタンスを、9つのガイドラインとして明文化しました。主要なものを抜粋します。

  1. 実行前にリサーチ — 新しいタスクでは、コードを書く前に最新のベストプラクティスを検索する
  2. ガイドする提案 — 「どうしますか？」ではなく、「方法AはX、方法BはY。Bを推奨、理由は…」と選択肢とトレードオフを先に示す
  3. 次善策には異議を唱える — 既知の落とし穴があれば実行前に警告する。失敗してから説明しない
  4. 限界に正直 — 確信がなければそう言う。確信があるふりをしない

これらをCLAUDE.mdに書くことで、全エージェントが「受動的実行者」ではなく「能動的参謀」として振る舞う基盤を整えました。

カテゴリ4: 運用ルール精緻化

CLAUDE.md Size Control（450行上限）

CLAUDE.mdが肥大化すると、コンテキストウィンドウを圧迫し、重要なルールが「Lost in the Middle」で読み飛ばされるリスクが高まります。

そこで以下のルールを設けました。

  • 上限: 450行。超過したら既存セクションを.claude/rules/（条件付き）か.claude/skills/（オンデマンド）に降格
  • 1 in 1 out: 追加行数 ≤ 削除行数。純増禁止

降格の判断基準:

  1. 全セッション必須 → CLAUDE.md本体
  2. 特定ファイル操作時のみ → .claude/rules/（paths付きrule）
  3. 明示起動時のみ → .claude/skills/

Dashboardのイベント駆動化

原本ではcronでダッシュボードを定期更新していましたが、これを廃止しました。代わりに家老（karo）がイベント駆動で更新します。

更新タイミング: 足軽レポート受領時、cmd完了時、要対応発生時、軍師分析完了時。

cronによる「時刻に関係なく定期更新」は、深夜に無意味な更新を走らせるだけでなく、直前のイベントが反映されないタイムラグも生じさせていました。イベント駆動に変えることで、ダッシュボードが常に「今の実態」を反映するようになりました。

WebSearch Fallbackルール

エージェントがWebSearchで情報を取得できなかった場合に「推測で埋める」インシデントが複数発生しました。これを防ぐため、フォールバック順序を明文化しました。

  1. 検索クエリを変える（日本語↔英語、具体的フレーズ）
  2. WebFetchでURL直接取得（公式サイト等）
  3. 2回リトライしてもダメなら「取得失敗」と報告。推測禁止

Decision Relay（判断中継の明示化）

将軍（shogun）がオーナーから判断を受け取ったとき、即座に家老へinbox_writeで中継するルールを追加しました。これにより、将軍→家老の意思決定ラグが解消されました。

削除したもの — なぜ削ったか

Post-Compaction Recovery → Session Startに統合

コンパクション後の回復手順を独立セクションとして持っていましたが、Session Start手順と内容が重複していました。統合することで「どちらを読めばいいか」の迷いがなくなりました。

Batch Processing Protocol → crontab安全パターンに置換

大量データ処理のバッチプロトコルを詳細に記述していましたが、実際には具体的なインシデント対応ルール（crontab安全パターン）のほうが有効でした。「一般化されたプロトコル」より「インシデントから得た具体的ルール」のほうが読まれる・守られるという教訓です。

bloom_routing_rule → 廃止

エージェントをモデル別にルーティングするBloom TaxonomyのL1-L6分類設定を廃止しました。運用コストに対してメリットが薄かったためです。

まとめ：実運用から得た教訓

6週間以上のカスタマイズをひと言でまとめると、「防御よりインシデント駆動」です。

最初から完璧なルールを設計しようとすることには限界があります。実際に起きたインシデント（crontab全消去・事実誤認7件・単位換算ミス）をトリガーに、ピンポイントで対策ルールを追加していくアプローチが、CLAUDE.mdの品質を着実に高めてきました。

また「書いた規則を守らせる」ためには、ルールの背景（なぜ追加したか）をCLAUDE.md内に残すことが重要です。エージェントはルールの意図を理解してこそ、エッジケースでも正しく判断できます。単に「禁止」と書くだけでは、少し状況が変わるとスルーされてしまいます。

OSSのmulti-agent-shogunを実運用している方、Claude Codeをチーム・マルチエージェントで使っている方の参考になれば幸いです。

この記事はOSSのマルチエージェントシステムmulti-agent-shogun（作者: おしおさん / yohey-w）を導入・カスタマイズして運用する中で得た知見をまとめたものです。

GitHubで編集を提案

Discussion