Claude Code Routines: 公式ドキュメントが教えてくれないこと

Anthropic が Claude Code の Routines を正式にドキュメント化しました。HN のスレッドは docs link で 122 ポイントを獲得しており、ドキュメントとしては異例の高い反応でした。

ここでは、ドキュメントがカバーしている内容、スキップしている内容、そして 5 つのエージェントで 30 日以上本番運用しながら Routines を回して学んだことをまとめます。

ドキュメントに書いてあること

Routines は、Claude Code が要求に応じて実行する再利用可能な一連の指示を定義できます。スラッシュコマンドで起動したり、セッション開始／終了イベントに組み込んだり、連結したりできます。

# .claude/commands/deploy-check.md
git status を実行し、コミットされていない変更が あるかを 確認し、テストが通るかを検証して、その後 出荷準備ができている内容を要約します。

多くのチームはここで止まります。

ドキュメントがスキップしていること

1. Routines は呼び出し間でステートレス

各実行は、明示的に状態をディスクに書き込まない限り、前回実行の記憶を持ちません。朝のブリーフィング用 Routine は毎日同じ 3 つのファイルを再要約していました。

修正: 各 Routine の末尾で .last-run のタイムスタンプを書き込み、開始時にそれを確認します。

# morning-brief.md
1. ~/Desktop/Agents/Atlas/last-run.txt を読み取る
2. 最終実行が今日なら、出力: "Already ran today. Skipping."
3. それ以外: [実際の作業を行う]
4. 今日の日付を ~/Desktop/Agents/Atlas/last-run.txt に書き込む

2. フックは「条件」ではなく「イベント」で発火

PreToolUse と PostToolUse は、ファイルが変更されたときや条件が満たされたときではなく、ツールが呼び出されたときに動きます。条件ベースのトリガーが必要なら、外部の cron もしくは watchdog が必要です。私たちのオーケストレータでは、90 秒間隔のポーリングループを使っています。

3. Routine の連結には深さ制限がある

深いチェーン（A → B → C → D）は、コンテキストの蓄積問題にすぐぶつかります。各ホップでオーバーヘッドが増えます。実用的な上限は、フラットにするかサブエージェントに引き渡す前に 3 ホップです。

4. 権限は「ルーチン単位」ではなく「セッション単位」

Routine に bash が必要なのに bash が自動で承認されていない場合、Routine は無人セットアップで静かに停止（待機）します。修正: 夜間実行をスケジュールする前に、必要なツールを settings.json で事前に承認しておきます。

5. Routines はデフォルトではバージョン管理されない

あなたの .claude/commands/ ディレクトリはリポジトリ内にあります。Routine を更新すると、実行中のすべてのエージェントがすぐにその変更を取り込みます。スプリントの途中で deploy-check Routine を更新したところ、バックグラウンドのエージェントがタスク途中で挙動を予期せず変更しました。

修正: Routines にバージョンを付ける（deploy-check-v2.md）か、ヘッダーに最終更新日をスタンプします。

私たちが使っている本番運用のパターン

朝のオーケストレーション: セッション開始時に発火し、タスクキューを読み取り、最優先のアイテムを選んで、適切なエージェントへ引き渡します。

EOD レポート: 最終ウェーブの後に、すべてのセッション出力を 1 つの markdown ファイルに要約します。Atlas-Memory/Daily-Reports/ に書き込みます。

自己修復: 詰まっているワーカーをチェック（15 分以上出力がない）、それらを kill して再起動し、インシデントを記録します。複数の夜間実行が救われました。

本当の価値

Routines は単なる保存されたプロンプトではありません。AI ワークフローを反復可能な運用システムとして動かすための骨組みです。.claude/commands/ は本番インフラだと思って扱いましょう—バージョン管理し、テストし、ドキュメント化します。

ドキュメントは扉を見せてくれます。ここから先がその裏側です。

Claude Code でマルチエージェントシステムを作っていますか？ Atlas Starter Kit には、本番用の Routines 12 個、ウェーブベースのオーケストレーション、自己修復するワーカーテンプレートが含まれます。whoffagents.com で $97。