Claude Codeで組織化したモノレポを運用する設計思想
Claude Codeでモノレポを運用していて、ある時期から急にAIの判断精度が上がったタイミングがありました。きっかけはツールでも新機能でもなく、フォルダ構成を「会社組織」に見立てて再設計したことです。部署・秘書室・案件フォルダ──比喩としての組織構造が、実はAIへのコンテキスト前提として機能していました。本記事では、組織メタファーをAIへの指示書として使う設計思想と、frontmatter統一・横断走査・部署メタファーを統合した実装ノウハウを、私自身の運用ベースで解説します。
組織メタファーがなぜAIへの指示書になるのか
Claude Codeのようなコーディングエージェントは、最初に対象プロジェクトのファイル構造を読み取って文脈を組み立てます。つまりフォルダ名・階層・ファイル配置そのものが、明示的な指示なしにAIへ伝わる「暗黙のプロンプト」になっています。
たとえばclients/coconala/customer-a/とclients/direct/customer-b/という2つの案件があるとき、AIは何の説明もなしに「この2件は獲得経路が違う案件だ」と理解できます。逆にすべてがprojects/直下にフラットに並んでいると、AIにとっては全部が等価で、「何を優先すべきか」「どれが似ているか」の判断が取れません。
ここで効くのが組織メタファーです。「秘書室」「部署」「案件フォルダ」という比喩は、人間にとって直感的なだけでなく、AIにとっても「この階層に入っている=こういう責務を持つ」という強い前提を作ります。比喩は単なる気持ちの問題ではなく、AIエージェントが横断走査・判断する際の構造的な前提条件として働きます。
2025年以降、AIコーディングアシスタントとモノレポの相性に関する議論が増えています。海外の解説記事でも「リポジトリ境界がエージェントに摩擦を生み、文脈損失・重複セットアップ・横断変更の手動調整が発生する」という指摘が共通しています（参考: Aviator: What is Monorepo? Benefits, Use Cases, and Best Practices）。私の実践はこの流れを、もう一段ローカルなレイヤー──モノレポ内部の組織構造──に押し下げた話と言えます。
「会社組織」に見立てたフォルダ構造の実例
私は1人で複数事業を運営していますが、st-dev0/projectsという1つのプライベートリポジトリにすべてを集約しています。例外的に独立gitを切るのは「デプロイ単位」だけ──コーポレートサイト、AI査定SaaS、クライアント納品アプリの3つです。それ以外はすべて1リポジトリに同居しています。
その内部を「会社組織」として配置しているのが下表です。
パス | 比喩 | 役割 |
|---|---|---|
| 取締役室・秘書室 | AI参謀が常駐。全プロジェクト統括・優先度判断 |
| 法人ブランド事業の部署 | コーポレートサイト・SaaS・出品管理を束ねる |
| 個人ブランド発信の部署 | YouTube・note・X・Substack・セミナー |
| 案件フォルダ | 獲得経路（coconala/lancers/direct）でsource分類 |
| 請求管理部門 | Stripe商品・顧客・サブスクの管理 |
| 雛形棚 | クライアント案件・新規プロジェクトの雛形 |
| 資材庫 | GDrive同期で1箇所だけ管理（symlink分配） |
新規プロジェクトの置き場所判断が即決できる
この構造に切り替えてから、新規プロジェクトを追加するときの「どこに置くか問題」が消えました。新規クライアント案件ならclients/{獲得経路}/{案件名}/に雛形をコピー、新規の自社プロダクトならfyve/配下、個人発信系ならtajima/配下──判断に5秒もかかりません。
これは私だけが楽になったわけではありません。AIに対して「この案件はクライアント案件として扱って」「この発信は個人ブランドとして扱って」と毎回説明する必要がなくなりました。フォルダパスがそのまま責務の宣言になっているからです。
クライアント案件は獲得経路で分類する
細かい話ですが、クライアント案件をclients/{source}/{name}/とsource（獲得経路）でまず切るのは意図的な設計です。プラットフォーム経由（coconala/lancers/crowdworks）と直契約（direct）は、契約形態・手数料・コミュニケーションチャネルがまったく違います。最初に獲得経路で分類しておくと、「プラットフォーム案件はメッセージのやりとりが内蔵チャットに集中する」「direct案件はメール+SMSが主」といった動線の違いがフォルダ階層から自動的にAIに伝わります。
案件がプラットフォーム範囲を超えて継続化したらclients/direct/へ「卒業」させる、という運用ルールも、フォルダ移動という物理操作で表現しています。
frontmatter統一が「AIの一次情報源」になる
組織メタファーを最大限に効かせるための仕掛けが、すべてのプロジェクトで同じスキーマのfrontmatterを持たせることです。クライアント案件・自社プロダクト・自社コンテンツ・インフラ・マーケティングなど、種類はバラバラでも、各CLAUDE.mdの冒頭は次のように統一しています。
---
project_type: client | own-product | own-content | own-infra | own-marketing | own-platform
priority: high | medium | low | paused
status: <project_typeに応じた値>
next_action: 次にやるべき具体的アクション
next_action_by: YYYY-MM-DD
last_touched: YYYY-MM-DD
---同じスキーマだから横断走査ができる
このスキーマが揃っていると、AIは一律のクエリで全プロジェクトを走査できます。私の環境では「AI参謀」と呼んでいるエージェントが、毎朝7時に全プロジェクトのfrontmatterを舐めて優先度マトリックスを生成しています。
もしプロジェクトごとに違うスキーマだったら、こんなことはできません。AIは「クライアント案件用のCLAUDE.md」「自社プロダクト用のCLAUDE.md」と個別にパースする必要があり、走査コストが跳ね上がります。スキーマ統一の恩恵は、「AIが横断的に判断する」ための前提整備そのものです。
frontmatterは「AIの一次情報源」
運用上、私はfrontmatter = AIの一次情報源と位置づけています。next_actionが古いままだと、AI参謀の判断が古い情報に引きずられて、見当外れのタスクを朝のブリーフィングで提示してきます。statusが更新されていないと、すでに納品完了した案件が「進行中」として優先度マトリックスに残り続けます。
frontmatter更新漏れ=そのままAI判断のズレ。この一点だけを徹底すれば、AIエージェントの出力品質はかなり安定します。
状態はファイル配置ではなくfrontmatterで表現する
もう1つの設計原則として、active/done/archiveのようなステージごとのフォルダ分けはしないと決めています。状態はstatus frontmatterで表現し、物理的なファイル移動は最小化します。
理由は単純で、ファイル移動は履歴を壊すからです。「2週間前に納品した案件」と「今日納品した案件」を別フォルダに動かすと、git履歴上の追いやすさが落ちますし、過去のメッセージリンクも崩れます。frontmatterだけ更新する運用にしておけば、案件は同じ場所にあり続け、状態だけが時系列で変わります。
部署メタファー × AI参謀の相互作用
組織比喩のなかでもっとも効いているのが、「秘書室」フォルダの存在です。secretariat/というメタレイヤーを設けて、ここにAI参謀（私の場合は固有名で運用しています）の人格定義・タスクファイル・ブリーフィング出力先を集約しています。
「全部署を統括する場所」をAIに与える
fyve（法人事業）・tajima（個人発信）・clients（案件群）はそれぞれ独立した部署として動きますが、その上位で「今日どれを優先すべきか」を判断する場所が必要です。それを担うのがsecretariat/です。
このフォルダにあるtasks/には、横断的な施策や経営課題（例: モノレポ全体のインフラ整備、月次キャッシュフロー戦略）を記録します。AI参謀は朝のブリーフィングで、各プロジェクトのfrontmatterとsecretariat/tasks/を統合走査して、「クライアント案件のどれが期限切迫」「自社プロダクトのどれが手が止まっている」を判断します。
もしsecretariatという「メタな場所」がなく、すべての判断が個別プロジェクト内に閉じていたら、こうした横断的な意思決定は構造的に不可能です。「上位レイヤーをフォルダで明示する」ことが、AIに統括判断の権限を与える設計上の鍵になっています。
2層ルールアーキテクチャでコンテキストを節約
もう1つの工夫が、ルールファイルを2層に分ける運用です。
- rules/: 自動読み込み。常時適用される普遍ルール（例: クライアント特定情報を書かない、表記統一）
- skill-components/: スキル実行時に手動Read。コンテキスト効率を重視（例: SEO記事の文字数規定、画像生成の細かいパラメータ）
すべてをrules/に入れると、起動のたびに大量のトークンを消費します。逆にすべてをskill-components/に入れると、AIが「常に守るべき普遍ルール」を見落とすリスクがあります。常時必要なものと、その場で必要なものを分ける──これは中小企業経営における「常駐スタッフ」と「業務委託」の使い分けに似ています。
子プロジェクトのCLAUDE.mdからは、親の共通ルールを../.claude/rules/article-writing.mdのように相対パスで参照させています。同じルールを各プロジェクトに重複して書かない設計です。
Hooksとlaunchdで「規律」を仕組み化する
frontmatter駆動の運用は、人間の規律に依存しすぎると壊れます。私は2つの自動化で規律を仕組み化しています。
Hooksでfrontmatter更新を強制
クライアント案件のmessages/フォルダ（やりとり履歴）を編集すると、ほぼ確実に案件状態が動きます。だから「messages/を編集したらCLAUDE.mdのfrontmatterも見直す」というルールを、Claude CodeのHooksで強制しています。具体的にはPostToolUse Hookで「messages/編集後にリマインド出力」、Stop Hookで「セッション終了時に編集差分を監査」という2層構成です。
このHooks設計の詳細は別記事に書いているので、ここでは「組織メタファーを支える規律装置として、Hooksが要になる」とだけ押さえてください。
launchdで毎日23時に自動commit/push
もう1つはmacOSのlaunchdを使った自動commit/pushです。毎晩23時にscripts/git-autocommit.shが起動して、全リポジトリ（モノレポ本体+独立git3つ）をgit add -A && git commit && git pushで同期します。スリープ中はスキップ、復帰時に実行という設計です。
なぜこれが組織メタファーと繋がるかというと、「会社の業務日誌が毎日リモートに保存される」状態を作るためです。物理PCが壊れても、別Macでgit cloneすれば即復元できる。秘書室のキャビネット（GitHub）に毎日業務記録が押し込まれているイメージで、これがあるから安心して1リポジトリにすべてを集約できます。
launchdの自動commit運用は、参考になる海外事例も少ない領域です。私自身もハマりどころが多く、設定の落とし穴は別記事で解説しました。
シンプルかつ強固を貫く設計哲学
組織メタファーを運用していて気づいたのは、「複雑さの排除」を最優先にすることでした。
装飾的なフォルダ階層を作らない
最初の頃、私は「クライアント案件のステータス別」「サービスメニュー別」「年度別」みたいな細かいフォルダ階層を作ろうとして、何度も挫折しました。階層を増やすたびに、AIにもユーザー（自分）にも判断負荷がかかり、運用が止まります。
今は、1階層で表現できるものは1階層で表現すると決めています。年度別の整理が必要なら、フォルダではなくfrontmatterのstarted_atでやる。サービス別の集計が必要なら、フォルダではなくタグでやる。状態管理はstatusフィールドでやる。物理階層は最小限に保ちます。
自動化は段階的に追加する
もう1つは、自動化を一気に作り込まないことです。最初は手動で運用してみて、「これは毎回やるな」と判明したものだけHooksやlaunchdに移します。
たとえば朝のブリーフィングは、最初の2週間は私が手動で「今日の優先度は？」とAIに聞いていました。問いかけのパターンが固まってから、ようやくScheduled Routine（リモートエージェントが毎朝7時に自動実行）に移行しています。パターンが固まる前に自動化すると、自動化が固まったパターンを縛ってしまう──これが学びです。
組織メタファーの効果測定
定量的な計測は難しい領域ですが、私の主観的な体感としては次のような変化がありました。
- 新規プロジェクトの置き場所判断: 数分悩む → 5秒で確定
- 朝の優先度判断: 自分で全プロジェクトを脳内整理 → AIブリーフィングを読むだけで5分
- クライアントとのやりとりで「次に何をすべきか」を見失う頻度: 月数回 → ほぼゼロ
- 新しいAIエージェント・スキルを書くときの初期コスト: 都度ゼロから設計 → 既存frontmatterスキーマに乗せるだけ
とくに最後の点は大きいです。frontmatter駆動の運用基盤ができていると、新しい自動化を作るときの限界コストが下がります。次に新しい朝ブリーフィング系・週次レポート系のエージェントを書いても、データ取得部分は既存スキーマの走査クエリを再利用できる、という資産化が進みます。
導入の最小ステップ
「組織メタファーで設計し直したい」と思った場合、以下の順で進めるのが現実的です。
1. 既存リポジトリの「組織図」を描いてみる
いきなりフォルダを動かす前に、紙でもMarkdownでも構わないので、自分が今やっている事業・案件・コンテンツを会社組織として書き出します。「これは部署」「これは案件」「これは経営判断レイヤー」と分類するだけで、現状のフォルダ構造との差分が見えます。
2. 一斉移行はしない
すべてを一気に動かすと、必ず途中で挫折します。私のやり方は「次にそのプロジェクトを触るタイミングで新構造に揃える」です。1ヶ月もすればアクティブな案件はだいたい新構造に乗り、休眠中のものは旧構造のまま放置します。それで問題ありません。
3. frontmatterスキーマだけ先に決める
フォルダ移動より先に、frontmatterスキーマを先に決めて公開します。私の場合は.claude/rules/project-frontmatter-schema.mdとして定義しました。スキーマがあると、新規プロジェクトを作るたびに「このスキーマで書いておけば後で必ず役に立つ」という安心感があります。
4. 「秘書室」レイヤーを設ける
secretariat/のようなメタレイヤー（全部署を統括する場所）は、最初は空でも作っておきます。中身は後から追加できますが、「ここがAIの統括判断レイヤーだ」と最初に宣言しておくと、後の自動化（朝ブリーフィング、週次レポート、優先度マトリックス）の置き場所に迷いません。
5. 規律装置はあとで足す
Hooksやlaunchdの自動化はあとで足せばいいです。最初は手動運用で「frontmatterを更新する習慣」を作り、自分で漏れに気づいてイラッとしてから、Hooksでの強制に移行する。この順番が結局いちばん早く着地します。
まとめ: ファイル構造はAIへの指示書である
組織メタファーは、人間の認知整理のためだけにあるのではありません。AIエージェントにとっても、フォルダ名・階層・配置はそのまま判断の前提条件として読み込まれます。
本記事で扱った3点を統合すると、次の構図になります。
- 部署メタファーでフォルダ階層に「責務の宣言」を持たせる
- frontmatter統一でAIに横断走査の権限を与える
- 秘書室レイヤーで統括判断の置き場所を作る
ここに規律装置（Hooks・launchd）とシンプルさの徹底が加わると、1人で複数事業を回しながらAIに判断を委ねられる仕組みが完成します。
2025〜2026年にかけて、AIコーディングエージェントとリポジトリ構造の関係について、海外でも議論が一気に増えました。AGENTS.mdのようなリポジトリレベルのコンテキストファイルの標準化、フォルダ構造をエージェント・アーキテクチャとして扱う研究などが代表例です。「ファイル構造はAIへの指示書である」という考え方は、もはや特殊な思想ではなく、AIエージェント時代の前提条件になりつつあります。
関連記事として、モノレポ戦略の世界3派と私の選択を解説した記事もあります。
frontmatter更新の規律をHooksで強制する3層防御の設計はこちらです。
AI活用顧問サービスでは、こうした「AIに会社を理解させる仕組み」を中小企業の業務文脈に合わせて設計するところから伴走しています。社内のドキュメント構造・命名規則・タスク管理を整え直すだけで、AIエージェントの出力品質は驚くほど安定します。
御社の業務に合わせたClaude Code導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。