AI組織を動かし始めた直後に、3つの設計ミスをやらかしました。
Claude Codeでブログ記事執筆をAI組織にサポートさせようとしたのですが、最初は1記事あたり想定の5倍近いトークンを消費していたのです（Claude Code Proの5時間トークン上限を100とした場合、1記事あたり25〜50を消費していました）。
これはやばい！と、4日間・105コミットかけて試行錯誤した結果、消費量を1/5程度まで削減できました。
その過程で得た設計原則（学び）をまとめます。
AI編集部を作ると決めたきっかけ
ChatGPTが登場してから、ずっと心のうちにモヤモヤがありました。AIの波は止められないのに、自分がどう乗ればいいのかが具体的に見えていなかったのです。
コンサルタントとして働いているぼくにとって、AIが「人間の仕事をどこまで代替するか」は他人事ではありません。そのモヤモヤを抱えたまま時は経ち、Claude CodeとSkillsの組み合わせを触り始めた時に、ようやく一つの活路が見出しました。それが「自分のビジネスを持ち、AI組織で回す」です。
おりしも、本業でもAIで組織を作って仕事を回すことを考えていたので（この背景はこちらの記事に書きました）、まずリスクの低いこのブログの運営で実験してみることにしたのです。
よって、ぼくがやりたかったのは「AIに記事を書かせること」ではなく、「責任範囲を持ったAIエージェントたちが協調してブログ運営を回す組織を作ること」です。これに至る経緯はGeminiのGemsをやめてClaudeのSkillsに乗り換えた全理由で詳しく書いているので、あわせてどうぞ。
やらかした3つの設計ミス
そういうわけで手をつけてみました。具体的には、これまで使ってきた記事執筆伴走用のプロンプト群（もとはGeminiのGems、その後Skill化したもの）を元ネタに、Claude Codeと壁打ちしながらAIエージェントを設計、GitHubリポジトリに展開しました。
が、3つの壁（ミス）にぶち当たりました。それぞれ別のものに見えますが、根っこは同じで、「AIエージェントをプロンプトの束として設計する」という発想のまま動かしてしまったことです。
ミス①：コンテキスト分割ミス——情報を渡すほど重くなる
記事執筆を「（体験談やレビューメモなどの一次情報をインプットとした）戦略 → 事前調査 → 執筆 → リンク挿入」の4フェーズに分け、各フェーズを別のエージェントに担当させました。ところが実際には、司令塔となるエージェントが各エージェントのファイルを直接読み込んで、自分のコンテキストの中で実行していました。
4フェーズすべての作業内容が司令塔のコンテキストに累積し続けた結果、後半のフェーズになるほどトークン消費が爆発的に増大していきました。「分けたつもりが、全部つながっていた」という根本的なミスです。
気づいたのはレートリミットに当たった時でした。記事を書いている最中に「レートリミットに達しました」という通知が頻発するようになり、ぼくはそこで初めて問題の深刻さを悟ります。
サブスクの料金を上げれば解決するとか、とはいえ節約したいとかいうレベルの話で捉えることはできませんでした。これを解決しないと、そもそもAI組織が完全に作動停止し、ひいては自分が前時代的な作業をするハメになる。まるで、停電・断水・ガス停止が同時に起きてサバイバル生活を強いられるときのような「どうにかしなきゃ」感が襲ってきたのです。
解決策は「各エージェントをSkillツール経由で呼び出すように強制し、返り値をステータス1行のみに制限すること」でした。成果物の中身をコンテキストに展開しない。それだけで消費が大幅に落ちました。
ミス②：ブランチ運用の迷走——ツールの挙動を先に理解すべきだった
Claude Code（スマホ版）は、ハーネスとしてセッションごとにフィーチャーブランチを自動生成します。ぼくはこの挙動を最初に把握していませんでした。
記事ファイルがフィーチャーブランチにのみ存在する状態で、WordPress自動投稿のジョブをmainブランチにpushしてしまいました。GitHub Actionsが「ファイルが見つかりません」エラーを返し、複数回のリトライが発生しました。ワークフローに「作業前にmainブランチへ切り替える」指示がなかったのが根本原因です。
後から手順を追加したものの、根本的な方針を転換しました。「mainへのcheckoutをやめて、ハーネスが生成したブランチをそのまま使う」設計にしたのです。git push origin HEADに変えることで、ツールの挙動に逆らわずに済む構成になりました。
ワークフローはツールの挙動を理解してから設計する——あたりまえのことだったはずなのに、勢いで動かしてしまったのが失敗の原因でした。
ミス③：CLAUDE.mdの肥大化——毎回全部読まれることの重大さへの対処を後回しに
CLAUDE.mdはClaude Codeのセッション開始時に必ず読まれる設定ファイルです。ぼくは最初、ここをAI組織のCEOにやらせたいことや運営ルールなどあらゆることを書き込んでいました。176行・10KBです。
セッションが始まるたびに10KBのファイルが毎回全量読まれ、トークンを消費し続けていました。内容の大半は「ブランチ運用ポリシー」「記事執筆の細かい手順」「品質チェックリスト」など、毎回読む必要のない詳細でした。
最終的に22行・0.9KBまで圧縮しました。詳細ルールをすべてスキルに委譲し、CLAUDE.mdは「作業場としてのリポジトリの構成と設計意図」「AI組織のCEOが登場すべきタイミング」のみに絞り、CEOの存在価値を表すceo-values.mdも価値観・哲学を保持したうえで仕事のルーティングだけを担う設計にしたのです。90%の圧縮が、そのままセッション開始コストの削減につながりました。
3つの失敗から得た設計原則
ミスを修正していくうちに、3つに共通した設計原則が見えてきました。
コンテキストは消耗品
AIエージェントに情報を渡すことはコストです。「便利だから渡す」ではなく、「必要最小限しか渡さない」という発想への転換が必要です。
各エージェントは自分の仕事に必要な情報だけを持ち、成果物は内容ごと渡すのではなく「完了した」というステータスだけを返す。情報を削ぎ落とすほど全体のコストが下がります。
「同じ便利さなら、より軽くあるべき」というミニマリスト的な発想がそのまま機能しました。
エージェントはファンクションで設計する
「戦略エージェント」「執筆エージェント」というように、担うべき機能（ファンクション）を明確にして設計して初めて、コンテキストの分離が実現しました。プロンプトと生データを渡して実行させる発想のままでは、どこかで情報が重複・累積し、トークン大量消費が起きます。
「役職」や「人格」をエージェントに与えることには反対です（AI社員に人格は不要だと思う理由で詳しく書きました）。役職とは機能に認知しやすい名前をつけたものに過ぎません。大事なのは「このエージェントが何をするか」というファンクションの定義です。ファンクションが明確になれば、「この仕事はこのエージェントが全部やる、結果だけ報告すればOK」「そのために必要十分な情報はコレ」と、渡すべきコンテキストを切り離せる構造が自然に生まれます。
CLAUDE.mdは目次、詳細はスキルへ
CLAUDE.mdに書けば書くほど毎回のセッション開始コストが増えます。「ここに書く必要があるか」と問うたとき、「スキルを呼び出した時に読めばいい情報」であれば書かない——そのルールにしました。
設定ファイルは「全セッションで必ず使う最小限の情報」だけを置く場所で、それ以上でも以下でもない、という原則です。
誰でも再現できるか
正直、AI組織づくりは黎明期で、再現性の高い手順はまだ存在しないと思います。
AI組織の設計はまだ、ごく一部の人しかやっていない領域です。正解のやり方も、失敗を避けるロードマップも、ほぼ存在しない。いろんな人がいろんな工夫を試し、その学びを共有している段階にあります。
一番のハードルは技術的なことではありません。「多少お金や時間を失ってもいいからやったれ」という覚悟を決めることです。技術の進化や新しいモデルの登場で前提が変わり、「これまでの努力が水の泡」みたいなことが頻繁に起きる世界ですから、ケガせず飛び込むのは無理です。
「確実に成功したい」「失敗したくない」「時間を浪費したくない」という方には、AI組織はまだおすすめできません。でも試行錯誤や紆余曲折を学びに変えて楽しめるタイプには、これ以上ないトピックだと思います。
まとめ
4日間・105コミットで得た設計原則（というよりぼくの学び）は3つです。
- コンテキストは消耗品 — 情報を渡すほどコストが増える。最小化が効率化に直結する
- エージェントはファンクションで設計する — プロンプトの束ではなく、担うべき機能を定義し、関心事を分離させる設計とする
- CLAUDE.mdは目次 — 毎回読まれることを前提に、詳細はスキルに委譲する
1記事あたりのトークン消費は25〜40から10程度に削減できました（Claude Code Proプランの5時間あたりのトークン上限を100としたときの相対値です）。目標はコスト削減ではなく「使い続けられる仕組みを作ること」だったので、この状態になってようやく本格運用できる感触を得ています。
仕事でのAI組織設計に持ち込む前に、まずこのブログで実験できてよかったと思っています。失敗が安く済む場所で先に試すことの価値を、改めて感じました。
ここまで読んでいただきありがとうございました。
コメント