AI Navigate
インサイト最新記事AI大全カオスマップ

エージェント・ワークスペースをコードとして：プロジェクト間でCLAUDE.mdをコピペするのをやめよう

Dev.to / 2026/5/4

💬 オピニオンDeveloper Stack & InfrastructureIdeas & Deep AnalysisTools & Practical UsageModels & Research
原文を読む →
共有:

要点

  • この記事は、.agents/、CLAUDE.md、.cursorrules などのAIエージェント用ワークスペースのファイルをプロジェクト間でコピーし、後から少しずつ修正していくことで生じる「ドリフト（設定の食い違い）」と「肥大化」を指摘しています。
  • 「Agent Workspace as Code（AWaC）」として、Terraformのように“望ましい状態”を宣言して再現性を得る発想を、コードの上にあるエージェント層（ルール、スキル、ワークフロー、慣習）へ適用することを提案します。
  • workspace.yml という宣言的な設定で、core やAWSの安全策とTerraform整合、MCPのブートストラップ、プロダクト固有のスタックなどの「スタック」を組み合わせ、エージェントの挙動を標準化します。
  • bootstrap コマンドは、組織のレジストリからスタック定義を解決し、main上の最新コミットを各スタックからクローンし、衝突時の扱いを含めて .agents/{rules,skills,workflows} を決定論的に合成し、さらに CLAUDE.md やAGENTS.md、workspace.lock.yml を生成して追跡性を確保します。
  • 目的は、エージェント設定の不整合によって静かに生じる生産性低下を防ぎ、未使用・重複したエージェント設定ファイルがリポジトリに際限なく増える事態（無秩序な肥大化）を減らすことです。

あなたが聞かされていなかった「ドリフト問題」

Claude Code、Cursor、Aider、または他のどんなAIコーディングエージェントでも、2つ以上のプロジェクトにまたがって使ってきたなら、あなたはきっとこの状況を感じたことがあるはずです：

プロジェクトAを開始します。前回のプロジェクトから .agents/ フォルダ（または CLAUDE.md、.cursorrules）をコピーします。2つだけ調整します。完了。

6週間後にプロジェクトBを開始します。プロジェクトAからコピーします。今回は3つ調整します。すると、AとBはもう別物になります。

プロジェクトCを開始します。AWSの安全ルールはAではこうで、Bでは少し違っていて、どちらが正しかったか覚えていません。デプロイ用スキルは3つの微妙に異なるバージョンがあります。MCP設定は3つのリポジトリのうち2つにしか入っていません。

これは ドリフト です。そして、チーム全体でAIエージェントを本気で使い始めた後に生産性を静かに殺す“見えないキラー”です。

もう一つの失敗パターンが 肥大化 です。どの .agents/ フォルダも、200ファイルくらいになってしまい、誰も所有していない、誰も何がまだ有効か知らない、そして「念のためもう1つルール追加していいですか」が、どんなコードレビューでも勝ってしまう。

インフラにあったパターン

インフラの世界では10年前にこれを解決していました。2014年以前は、サーバーにSSHして、パッケージを入れて、nginx.confを編集して、次のサーバーでも同じことをやったはずだと思い出せることを祈っていたのです。そこからTerraformが登場しました。HCLで望ましい状態を宣言し、terraform applyを実行すると、世界はあなたのファイルに一致します。状態ドリフトは検出可能になります。再現性は“無料”で手に入ります。

Agent Workspace as Code（AWaC） は同じパターンで、コードの一段上、つまりあなたのAIコーディングエージェントが読むルール、スキル、ワークフロー、そして規約に適用します。

# workspace.yml
schema: workspace/1
name: my-feature
stacks:
  - core           # universal foundation
  - aws            # AWS safety + terraform parity
  - mcp            # MCP server bootstrap
  - my-product/agent-stack    # product-specific stack

wsp bootstrap を実行すると、CLIは次を行います：

  1. <your-org>/agent-stack-core/awac.yml にあるレジストリ経由でスタックのショートカットを解決します。
  2. 各スタックのリポジトリを、mainブランチの最新コミットでクローンします。
  3. 組み立てを .agents/{rules,skills,workflows}/ を決定論的に行います（衝突した場合は最後のスタックが勝ちます）。
  4. CLAUDE.md（正準のコンテキストファイル）と、CLAUDE以外のエージェント向けのミラーであるAGENTS.mdを生成します。
  5. 正確なコミットを記録する workspace.lock.yml を出力します。

これでループは終わりです。同じワークスペースを、どのマシンでも。コピペなし。ドリフトなし。

スタックとは何か

スタックは、次のレイアウトを持つシンプルなGitHubリポジトリです：

my-stack/
  awac.yml              # metadata: which product, which repos to clone
  rules/                # behavioral rules (always_on or trigger-based)
  skills/               # named procedures the agent invokes by reference
  workflows/            # multi-step processes
  templates/            # workspace.yml templates (optional)

公開されている参照用スタック（getGanemo/agent-stack-* 配下）は、ユニバーサルなニーズ（core）、AWS、MCP、Cloudflare、そして研究/ブランディング/論文テンプレートをカバーしています。自分のものも公開できます。規約に合っていれば、どんなものでも有効なスタックです。

エージェント優先が重要な理由

CLIは最初から、人間ではなくエージェントによって動かされることを前提に設計されました。具体的には：

  • すべてのコマンドが --json を受け取り、構造化された出力を返します。
  • エラーには4つのフィールドがあります：code（再試行ロジックのための安定した識別子）、category（環境/設定/ネットワーク等の分類）、cause（何が起きたか）、remediation（何をすべきか）。

つまり、あなたのエージェントが wsp doctor を実行していて、あるチェックが失敗した場合、それは次のように見えます：

{
  "code": "WSP_007",
  "category": "environment",
  "cause": "gh CLI not authenticated",
  "remediation": "Run: gh auth login"
}

そして、それを修正する（remediationを実行する）ことも、人間にフルコンテキスト付きでエスカレーションすることもできます。段落を読む必要はありません。推測もしません。

これは聞こえる以上に重要です。長時間動作するエージェントのループを本番で動かそうとした人なら、エラーハンドリングが難しさの80%だと知っています。安定したエラーコードは、CLIとエージェントの間の契約として最も近いものです。

AWaCをシンプルに保つために手放したこと

よく持ち上がる“非機能”がいくつかあります：

SaaSなし、ホスティングされたダッシュボードなし。 CLIは100%ローカルです。スタックはあなたのGitHubにあります。テレメトリも、バックエンドもありません。ドキュメントのADR 014がその理由を説明しています。これは収益のためではなく、導入のための最適化と思想的リーダーシップのためです。

まだPyPIではない。 配布はGitHub Releases経由（gh release download + pipx install）です。その理由（ADR 012）は、エージェント主導のインストール経路で機能するため、PyPIの名前空間の取り合いを必要としないこと。そしてOSS導入のシグナルがPyPI側のロードマップ参加を要求するまで、PyPIは後になります。

コアコマンドにインタラクティブなプロンプトなし。 AWaCはエージェント優先です。必要なackがあるものは明示的なフラグを使います（--yes、--update）。TTYプロンプトは決して使いません。ウィザードはユーザーフレンドリーですが、エージェントには敵対的です。

Apache 2.0ではなくMIT。 よりシンプル。十分。特許の付与は大規模なインフラプロジェクトでは重要です。しかしワークスペースCLIでは、MITが適切な最小要件です。

14個のADR

AWaCを作っている間、あらゆる議論の多い選択はArchitecture Decision Record（アーキテクチャ意思決定記録）を生みました。それらはドキュメントのリポジトリにあります。ツールを採用しないとしても、ざっと目を通す価値があります。ほとんどは、同様のものを作るときに直面するトレードオフの議論だからです。

例：

  • 001 — 構成の単位は、プロジェクトでも組織でもユーザーでもなく、ワークスペースです。
  • 004 — CLAUDE.mdは正準（canonical）で、AGENTS.mdはミラーです。推論の説明。
  • 007 — CLIは人間優先ではなくエージェント優先です。コマンドの表面、エラー、出力への影響。
  • 010 — DevVaultは2層モデルです（製品カタログごとにバージョン管理された層＋マシンごとにバージョン管理されないvaultのパス）。
  • 012 — GitHub Releasesによる配布（PyPIではない。現時点では）。
  • 014 — AWaCはオープンソースのままです。SaaSの予定はありません。

すべては github.com/getGanemo/awac-docs で読むことができます。

試してみる

返却形式: {"translated": "翻訳されたHTML"}
# インストール
TAG=$(gh release view --repo getGanemo/workspace-cli --json tagName -q .tagName)
gh release download "$TAG" --repo getGanemo/workspace-cli --pattern '*.whl' --dir /tmp/wsp
pipx install /tmp/wsp/wsp-*.whl

# ワークスペースを構成する
mkdir my-feature && cd my-feature
wsp init my-feature --template blank
wsp bootstrap

クローンから作業中のワークスペースまで、たった2分。これのどこがおかしいのか教えてください。

私が望んでいること

今回のリリースで私が最も欲しいのは、スターではありません（もちろんあると嬉しいですが）。欲しいのは抽象化に関する正直なフィードバックです：

  • あなたのルールのうち、スタックにきれいに収まらないものはどれですか？
  • AWaCが表現できない、あなたの作曲（コンポジション）パターンは何ですか？
  • あなたを混乱させたエラーメッセージは何でしたか？
  • 私がまだ作っていないのに存在すべきスタックは何ですか？

試してみて5分後に、issueを作成するか、この投稿に返信してください。ロードマップは公開されています（Roadmap issue）。さらに、サムズアップの反応があると優先度が上がります。

読んでいただきありがとうございます。ひとりで作りました。MITです。SaaSはありません。フォーク歓迎。issueでお会いしましょう。

— Fernando
github.com/GanemoCorp · ganemo.com

関連おすすめサービス

※当サイトはアフィリエイト広告を利用しています
🎧

Notta搭載AI議事録イヤホン ZENCHORD1

AI時代の仕事術。Notta搭載で会議の議事録を自動生成するスマートイヤホン。

🎙️

AI搭載ボイスレコーダー Plaud

世界100万人が愛用。AIで文字起こし・要約を自動化するボイスレコーダー。

🖼️

画像高画質化AIツール Aiarty Image Enhancer

AIで画像を高画質化。写真・イラストを簡単にアップスケール。