AIエージェントを活用した自動化基盤の運用が本格化すると、ワークスペースのディレクトリ構成が急速に複雑化していきます。Ragateが開発・運用するOpenclawというマルチエージェント自動化基盤においても、スキル定義・自動化スクリプト・ナレッジデータ・一時生成ファイルが混在し、「どこに何があるのか」という問いへの答えが難しくなる局面を経験しました。本記事では、実際のOpenclawワークスペースのディレクトリ構成を例に挙げながら、単一責任原則と関心の分離を軸にしたリファクタリング手法と、中長期の運用保守性を高めるための設計・運用ノウハウを解説します。

Openclawワークスペースの全体構成

OpenclawのワークスペースはAgentが直接読み書きする「ホームディレクトリ」です。現在のディレクトリ構成は以下のようになっています。

workspace/
├── AGENTS.md              # エージェントへの設計書・ルール定義
├── skills/                # スキル定義（エージェントの能力モジュール）
│   ├── blog/              # ブログ投稿スキル群
│   │   ├── common/        # 共通規約・テンプレート
│   │   └── media/         # 媒体別スキル
│   ├── x-reply/           # X返信スキル
│   ├── facebook-reply/    # Facebook返信スキル
│   └── ... (合計20以上のスキル)
├── scripts/               # 自動化スクリプト群
│   ├── microcms/          # microCMS操作スクリプト
│   ├── slack/             # Slack通知・承認スクリプト
│   ├── x/                 # X投稿スクリプト
│   └── common/            # 共通ユーティリティ
├── knowledge/             # RAGデータ・参照ナレッジ
│   └── ragate/latest/     # 最新のリサーチデータ
├── memory/                # エージェントの長期記憶
└── tmp/                   # セッション一時ファイル
    ├── generated/         # 生成物の一時保存
    ├── attachments/       # ユーザー添付ファイル
    └── logs/              # 一時ログ

※ 上記のディレクトリ構成・スクリプトパス・スキル名は参考例です。実際の値はご自身の環境に合わせて変更してください。

各ディレクトリは明確な役割を持って設計されており、AGENTS.mdがエージェントに対してこの構造の意味を説明する「設計書」として機能します。これは2025年以降のAIエージェント設計トレンドである「プログレッシブ・ディスクロージャー原則」に沿ったアプローチです。フラットなディレクトリ一覧を提示するのではなく、各ディレクトリの目的・役割・アクセス権限をエージェントに明示することが重要です。

運用が進むにつれて現れる構成の問題

スキルの数が増え、自動化の対象が広がるにつれて、AIエージェントワークスペースには典型的な問題が発生しがちです。Openclawでも実際に経験した課題を整理します。

最初に現れる問題がディレクトリの肥大化と命名のゆらぎです。当初はシンプルだったスキルディレクトリが機能追加のたびに肥大化し、「このスキルはどれが最新版か」という問いへの答えが難しくなります。異なるタイミングで追加したスキルが命名規約を統一していないケースも生じます。x-replyとx-lead-postとx-book-promo-postが並存する状態では、新しいスキルを追加するときに「どのパターンに従えばよいか」が不明確です。AIエージェント自身も命名のゆらぎがあるとコンテキスト理解の精度が低下します。

次に一時ファイルと永続ファイルの混在、共通処理の重複という問題が生じます。生成されたHTML・画像・ペイロードJSONなどの一時ファイルが永続的なスクリプトと同一ディレクトリに混在すると、Gitコミット時の管理が複雑になります。複数のスキルが同一の処理（Slack通知、APIキー取得など）を個別に実装することで、バグ修正の際に複数箇所を修正しなければならなくなります。

リファクタリングの指針となる設計原則

これらの問題を解決するにあたり、Openclawでは以下の設計原則をリファクタリングの指針としました。ソフトウェアエンジニアリングの古典的な原則ですが、AIエージェントのワークスペース設計にも直接適用できます。

単一責任原則（SRP）は、「各ディレクトリ・各ファイルには1つの明確な役割を持たせる」ことを求めます。Robert C. Martinの言葉を借りれば「同じ理由で変わるものをまとめ、異なる理由で変わるものを分ける」ということです。スキルと共通スクリプトとナレッジデータを明確に分離することがこの原則の実践です。

関心の分離（SoC）はシステム・モジュールレベルで適用する設計原則です。Openclawのワークスペースでは、以下の「関心」ごとにディレクトリを分けています。

さらに参照集中化として、複数のスキルから参照される共通定義を1箇所にまとめます。ブログ投稿スキルでは、skills/blog/common/に共通規約（regulation.md・image-prompt-template.md・pipeline-contract.md）を集約し、各媒体スキルはそれを参照する構造にしました。

リファクタリング前後の構成比較

ブログ投稿スキルのリファクタリング前後を具体的に比較します。

リファクタリング前は、各媒体スキルがバラバラに存在し、共通ルールが重複記述されていました。

skills/
├── engineer-blog-post/    # ルール・スクリプト混在
│   ├── SKILL.md           # スキル定義とルールが混在
│   └── blog-rules.md      # 部分的なルール抜粋
├── openclaw-blog-post/    # 重複したルール記述
│   └── SKILL.md
└── mashiko-blog-post/
    └── SKILL.md           # 独自ルールと共通ルールが混在

リファクタリング後は、共通定義をcommon/に集約し、各媒体スキルは差分のみを定義します。

skills/
└── blog/
    ├── common/                       # 共通定義（単一の真実の情報源）
    │   ├── regulation.md             # 投稿ルール共通定義
    │   ├── image-prompt-template.md  # 画像生成テンプレート
    │   ├── media-matrix.yaml         # 媒体別設定マトリクス
    │   └── pipeline-contract.md      # 投稿パイプライン仕様
    └── media/                        # 媒体別スキル（差分のみ定義）
        ├── developer_knowledge/
        │   └── SKILL.md
        └── mashiko/
            └── SKILL.md

この変更によって、共通ルールの修正が1箇所に集約され、媒体スキルは「差分定義のみ」を持つシンプルな構造になりました。スキル全体がblog/という名前空間にまとまることで、関連スキルの検索が直感的になっています。

命名規約と参照集中化による保守性の向上

ディレクトリ構造と並んで重要なのが命名規約の統一です。2025年のモノレポ設計ベストプラクティスでは、ディレクトリ名にケバブケース（kebab-case）を使用し、単数形の名詞を原則とすることが推奨されています。Openclawでは、スキルディレクトリの命名を以下のパターンに統一しています。

この規約により、新しいスキルを追加する際に「どの命名パターンを使えばよいか」が一目でわかります。scripts/ディレクトリも同様に、サービス名をディレクトリ名とするシンプルな規約（scripts/microcms/、scripts/slack/、scripts/x/）を採用し、共通処理はscripts/common/に集約しています。セッション中に生成された一時ファイルは、すべてtmp/以下に配置する原則を徹底することで、Gitコミット時の誤コミットを防いでいます。

中長期運用を支えるベストプラクティス

構造を整えただけでは、時間の経過とともに再び混乱が生じます。Openclawの運用経験から、中長期にわたって構成の健全性を保つためのプラクティスをご紹介します。

まずAGENTS.mdを「生きた設計書」として維持することが重要です。ディレクトリ構成を変更したら必ずAGENTS.mdも更新する習慣が、長期的な整合性を保ちます。2025年以降のAIエージェント設計では、プロジェクトルートのAGENTS.mdが「エージェントへのアクセス制御と役割定義のドキュメント」として機能する標準が定着しています。

次にスキルは自己完結型フォルダで管理することです。各スキルをSKILL.md + スクリプト + テンプレートを含む独立したフォルダとして管理することで、スキルの追加・削除・更新が他に影響を与えず安全に行えます。

また読み取り専用と書き込み可能の境界を明示することがAIエージェント運用の要です。AGENTS.mdの「Red Lines」セクションで破壊的操作の禁止を明確にし、承認フローを経た変更のみが設定ファイルに反映される仕組みにすることで、エージェントの自律的な動作がシステムを壊すリスクを低減できます。ワークスペース内の変更は論理的な単位ごとにGitコミットを作成し、「何をなぜ変更したか」をコミットメッセージに記録することで、監査ログとしても機能します。

AIエージェント基盤のディレクトリ設計は、一度決めたら終わりではなく、運用しながら継続的に改善していくものです。設計原則に基づいたリファクタリングと、それを支える運用規約の整備を繰り返すことで、スケールしても保守しやすいワークスペースを維持できます。Openclawでの取り組みが、AIエージェントを本番運用するエンジニアの皆さんの参考になれば幸いです。