GitAgent入門 — AIエージェントをフレームワーク非依存で定義・運用する

AIエージェント開発の「書き直し問題」

AIエージェントを開発していると、避けて通れない問題があります。
フレームワークの乗り換えコストです。

LangChain、CrewAI、AutoGen、OpenAI Agents SDK、Claude Code。
2026年3月時点で主要なフレームワークだけで5つ以上あります。
それぞれがエージェントの定義方法、メモリ管理、ツール実行の仕組みを独自に持っています。

筆者は先日、Claude Codeで運用していたエージェントをCrewAIに移行しようとしました。
Claude CodeではCLAUDE.mdにシステムプロンプトを書き、.claude/以下にルールやコマンドを配置します。
一方、CrewAIではYAMLでロールを定義し、Pythonでタスクを組み立てます。

結果、移行作業に丸2日かかりました。
エージェントの「やること」は同じなのに、書き方がまったく違います。
プロンプトの移植、ツール定義の変換、メモリ構造の再設計。
ほぼゼロからの書き直しでした。

この「書き直し問題」はDockerが登場する前のデプロイ環境に似ています。
同じアプリケーションなのに、環境ごとに設定を書き直す。
Dockerがコンテナという標準フォーマットで解決したように、AIエージェントにも標準フォーマットが必要です。

なお、後述するGitAgentはエージェントの静的定義（何者か・何を知っているか・何ができるか）の標準化を担うものです。実行時のオーケストレーション（状態管理、ループ制御、エラーハンドリングなど）は各フレームワークの責務として残ります。Dockerのようにランタイムごと置き換えるものではなく、あくまで「定義のポータビリティ」に焦点を当てたツールです。

なぜ今、標準化が必要なのか

フレームワーク乱立の3年間

2023年から2026年にかけて、AIエージェントフレームワークは急速に増加しました。

時期	フレームワーク	エージェント定義方式
2023年前半	LangChain / LangGraph	Pythonクラス + チェーン定義
2023年後半	AutoGen (Microsoft)	Pythonクラス + 会話パターン
2024年前半	CrewAI	YAML + Pythonタスク定義
2024年後半	Claude Code (Anthropic)	Markdown（CLAUDE.md） + ルールファイル
2025年前半	OpenAI Agents SDK	Python + デコレータ
2025年後半	Google ADK (フレームワーク)	YAML + Pythonベースのエージェント定義
2025年後半	Google A2A (プロトコル)	JSONベースのAgent Card + Task

各フレームワークが独自のエージェント定義形式を持っています。
ロール定義、メモリ管理、ツール呼び出し、ワークフロー制御。
どれも同じ概念を扱っているのに、書き方が全く異なります。

「ポータビリティ問題」の本質

この状況はDockerが登場する前のデプロイ環境と構造的に同じです。

Dockerはアプリケーションの「実行環境」を標準化しました。
GitAgentはAIエージェントの「定義」を標準化しようとしています。

比較軸	Docker	GitAgent
標準化の対象	アプリケーションの実行環境	AIエージェントの定義
コアファイル	Dockerfile	agent.yaml + SOUL.md
レジストリ	Docker Hub	Gitリポジトリ
ポータビリティ	AWS / GCP / Azure / オンプレ	LangChain / CrewAI / Claude Code / OpenAI
バージョン管理	イメージタグ	Gitコミット / ブランチ
構成管理	docker-compose.yml	agents/（マルチエージェント構成）

Docker以前は「自分のマシンでは動く」が常套句でした。
今のAIエージェント開発では「自分のフレームワークでは動く」が同じ問題を引き起こしています。

GitAgentとは何か

GitAgentは2026年3月に公開されたOSSです。
「AIエージェントのDocker」と呼ばれています。

コンセプトは「Clone a repo, get an agent」。
Gitリポジトリの中にエージェントの定義をファイルとして格納します。
フレームワークに依存しない標準フォーマットでエージェントを記述し、CLIコマンド1つで各フレームワーク向けに変換できます。

3つのコアファイル

GitAgentの最小構成は2ファイルですが、実用上は3ファイルが中心になります。

agent.yaml（マニフェスト）

エージェントのメタデータ、使用モデル、コンプライアンス要件を定義します。

spec_version: "0.1.0"
name: code-review-agent
version: 1.0.0
description: コードレビューを自動実行するエージェント
model:
  preferred: claude-opus-4-6

最小構成ならname、version、descriptionの3項目だけで動きます。spec_versionは推奨項目ですが必須ではありません。

SOUL.md（性格定義）

エージェントのアイデンティティ、コミュニケーションスタイル、価値観をMarkdownで記述します。

# Code Review Agent

## Identity
あなたはシニアエンジニアとして振る舞うコードレビューエージェントです。

## Communication Style
- 指摘は具体的なコード例とともに提示する
- 改善案は必ず理由を添える
- 良い実装には積極的にコメントする

## Values
- セキュリティを最優先とする
- パフォーマンスへの影響を常に考慮する
- 可読性と保守性のバランスを取る

従来はPythonファイルの中にシステムプロンプトが散在していました。
SOUL.mdに集約することで、非エンジニアでもエージェントの性格を確認・編集できます。

DUTIES.md（責任分担）

エージェントの権限と制約を定義します。
特にエンタープライズ利用で重要な「職務分離（Segregation of Duties）」を宣言できます。

# Duties

## Role: analyst
- コードの分析と問題の検出
- レビューコメントの作成

## Restrictions
- マージの実行は禁止
- 本番環境への直接アクセスは禁止

ディレクトリ構造の全体像

コアファイルに加えて、オプションのディレクトリで機能を拡張できます。

my-agent/
├── agent.yaml          # マニフェスト（必須）
├── SOUL.md             # 性格定義（必須）
├── RULES.md            # 安全制約
├── DUTIES.md           # 職務分離ポリシー
├── skills/             # 再利用可能なスキル
├── tools/              # MCP互換のツール定義
├── workflows/          # マルチステップの手順
├── knowledge/          # 参照ドキュメント
├── memory/runtime/     # 実行時の状態
├── hooks/              # ライフサイクルハンドラ
└── agents/             # サブエージェント定義

Gitリポジトリそのものがエージェントになるため、変更履歴の追跡、ロールバック、ブランチによる環境分離がそのまま使えます。

ハンズオン: Claude Codeエージェントをexportする

既存のClaude CodeエージェントをGitAgentフォーマットに変換してみます。

1. インストール

npm install -g @open-gitagent/gitagent

Node.js 18以上が必要です。

2. 既存プロジェクトからインポート

Claude Codeのプロジェクトディレクトリで以下を実行します。

gitagent import --from claude .

CLAUDE.mdやルールファイルを読み取り、agent.yaml + SOUL.md + RULES.mdを自動生成します。

3. 生成されたファイルを確認

gitagent info

エージェントの概要が表示されます。
SOUL.mdの内容がCLAUDE.mdから適切に抽出されているか確認します。

4. バリデーション

gitagent validate

specに準拠しているかチェックされます。
コンプライアンス設定がある場合は--complianceフラグを追加します。

gitagent validate --compliance

Before/After: 同じエージェントをフレームワーク別に書いてみる

「コードレビューエージェント」を3つの方式で書いた場合の比較です。
同じ機能を持つエージェントが、フレームワークごとにどれだけ異なるかを確認します。

Claude Code方式

<!-- CLAUDE.md -->
# Code Review Agent

## 役割
あなたはシニアエンジニアとして振る舞うコードレビューエージェントです。

## ルール
- セキュリティを最優先とする
- 指摘は具体的なコード例とともに提示する
- 改善案は必ず理由を添える

<!-- .claude/commands/review.md -->
# コードレビュー実行

$ARGUMENTS のdiffを取得し、以下の観点でレビューしてください:
1. セキュリティリスク
2. パフォーマンス問題
3. 可読性・保守性

Claude Codeではすべてがマークダウンです。
構造化されているようで、実はフラットなテキストの羅列です。
ロール定義、ルール、コマンドが別ファイルに散在しています。

CrewAI方式

# agents.yaml
code_reviewer:
  role: "Senior Code Reviewer"
  goal: "Identify security risks, performance issues, and maintainability concerns"
  backstory: >
    あなたは10年以上の経験を持つシニアエンジニアです。
    セキュリティを最優先とし、具体的なコード例とともに指摘を行います。

# crew.py
from crewai import Agent, Task, Crew

reviewer = Agent(
    config=agents_config["code_reviewer"],
    tools=[GitDiffTool(), StaticAnalysisTool()],
    llm="claude-opus-4-6"
)

review_task = Task(
    description="Pull Requestのdiffをレビューし、問題点を報告する",
    agent=reviewer,
    expected_output="レビューコメントのリスト"
)

crew = Crew(agents=[reviewer], tasks=[review_task])

CrewAIではYAMLとPythonの二重管理が必要です。
エージェントの性格はYAMLに、オーケストレーションはPythonに書きます。
非エンジニアがプロンプトだけ編集したい場合でも、Pythonコードの存在を意識する必要があります。

GitAgent方式

# agent.yaml
spec_version: "0.1.0"
name: code-review-agent
version: 1.0.0
description: コードレビューを自動実行するエージェント
model:
  preferred: claude-opus-4-6
tools:
  - git-diff  # 実体は tools/git-diff.yaml に定義

<!-- SOUL.md -->
# Code Review Agent

## Identity
あなたはシニアエンジニアとして振る舞うコードレビューエージェントです。

## Communication Style
- 指摘は具体的なコード例とともに提示する
- 改善案は必ず理由を添える
- 良い実装には積極的にコメントする

## Values
- セキュリティを最優先とする
- パフォーマンスへの影響を常に考慮する
- 可読性と保守性のバランスを取る

GitAgent方式では、メタデータ（agent.yaml）とアイデンティティ（SOUL.md）が明確に分離されています。
SOUL.mdは純粋なMarkdownなので、非エンジニアでも直感的に編集できます。

3方式の比較

比較項目	Claude Code	CrewAI	GitAgent
定義ファイル形式	Markdown	YAML + Python	YAML + Markdown
非エンジニアの編集	可能（ただし構造が曖昧）	困難（Python必須）	容易（Markdown中心）
ツール定義	なし（ランタイム依存）	Pythonクラス	MCP互換JSON/YAML
他フレームワークへの移植	手動変換	手動変換	gitagent exportで自動
バージョン管理	Git（ただし非構造的）	Git	Git（構造化済み）

GitAgentのポイントは「定義の関心の分離」です。
何を知っているか（knowledge/）、何ができるか（tools/）、どう振る舞うか（SOUL.md）、何をすべきか（DUTIES.md）が明確にディレクトリで分かれています。

フレームワーク間の変換デモ

GitAgentの実用上の強みはexportコマンドにあります。
1つの定義から複数のフレームワーク向けコードを生成できます。

CrewAIへのエクスポート

gitagent export --format crewai

CrewAIのYAML設定ファイルが生成されます。
ロール定義、タスク、ツール呼び出しがCrewAIの形式に変換されます。

LangChainへのエクスポート

gitagent export --format system-prompt

system-promptフォーマットを使うと、SOUL.mdやRULES.mdの内容を結合したシステムプロンプトが出力されます。
LangChainやLangGraphの任意のノードにそのまま渡せます。

OpenAI Agents SDKへのエクスポート

gitagent export --format openai

OpenAI Agents SDK向けのPythonコードが生成されます。

対応フォーマット一覧

フォーマット	出力内容
system-prompt	結合されたシステムプロンプト（Markdown）
claude-code	CLAUDE.md形式
openai	OpenAI Agents SDK用Pythonコード
crewai	CrewAI YAML設定
openclaw	OpenClawワークスペース
nanobot	Nanobot設定
lyzr	Lyzr Studio APIペイロード
github	GitHub Actions agent設定

上記は主要なアダプタの一覧です。
このほかにもgemini、cursor、opencode、gitなどのフォーマットに対応しています。

gitagent exportは定義の静的変換を行います。
ランタイムのオーケストレーション（状態管理、ループ制御など）はフレームワーク側の責務として残ります。

export/importのハマりどころ

GitAgentのexport/importは便利ですが、万能ではありません。
実際に使ってみると遭遇する注意点をまとめます。

exportで変換されない情報

gitagent exportは定義の静的変換です。
以下の要素はexportの対象外であり、移行先のフレームワークで別途実装する必要があります。

変換される	変換されない
システムプロンプト（SOUL.md）	ランタイムのオーケストレーション
ロール定義（agent.yaml）	状態管理・ループ制御
ツール一覧（tools/）	ツールの実装コード
安全制約（RULES.md）	実行時のガードレール制御
職務分離ポリシー（DUTIES.md）	認証・認可の実装

たとえば、CrewAIで「タスクAの結果をタスクBに渡す」というオーケストレーションを組んでいた場合、それはexportされません。
GitAgentは「エージェントとは何か」を定義するものであり、「エージェントがどう動くか」はフレームワーク側の責務です。

SOUL.mdが長すぎる場合の対処

SOUL.mdにプロンプトを詰め込みすぎると、exportしたシステムプロンプトがモデルのコンテキストウィンドウを圧迫します。
実用上の目安として、SOUL.mdは2,000トークン以内に収めることを推奨します。

対処法は以下の通りです。

1. knowledge/に分離する — 参照ドキュメントはSOUL.mdではなくknowledge/ディレクトリに配置する。SOUL.mdには「knowledge/を参照すること」とだけ書く
2. skills/に切り出す — 具体的な手順や手法はskills/ディレクトリにスキルとして定義し、SOUL.mdはアイデンティティと価値観に絞る
3. DUTIES.mdを活用する — 権限・制約に関する記述はDUTIES.mdに移動する

# 悪い例: SOUL.mdに全部入り
SOUL.md (5,000トークン)
├── アイデンティティ
├── コミュニケーションスタイル
├── 技術的な判断基準（詳細）    → knowledge/ に移動
├── レビュー手順（詳細）        → skills/ に切り出し
└── 権限・制約                  → DUTIES.md に移動

# 良い例: 関心の分離
SOUL.md (800トークン) ... アイデンティティと価値観のみ
knowledge/review-criteria.md ... 技術的な判断基準
skills/code-review.md ... レビュー手順
DUTIES.md ... 権限・制約

ツール定義のMCP互換の限界

GitAgentのtools/ディレクトリはMCP（Model Context Protocol）互換のツール定義をサポートしています。
しかし、以下の制限があります。

• MCP非対応のツール: CrewAIの@toolデコレータで定義したPythonツールや、LangChainのカスタムToolクラスは、MCP形式に自動変換できない
• 認証情報の扱い: APIキーやOAuthトークンはtools/に含められない。環境変数や外部シークレットマネージャで別途管理する必要がある
• ストリーミング対応: MCPのStreamable HTTP transportに対応していないツールは、exportしても非同期処理ができない

対策として、ツール移行時は以下の手順を踏むのが確実です。

# 1. 既存ツールの一覧を確認
gitagent info --tools

# 2. MCP互換ツールはそのままexport
gitagent export --format crewai

# 3. 非互換ツールは手動でラッパーを作成
# tools/custom-tool.yaml にMCPスキーマだけ定義し、
# 実装は移行先フレームワークで書く

エンタープライズ利用

コンプライアンス対応

金融業界向けの規制マッピングが組み込まれています。

compliance:
  risk_tier: high
  frameworks: [finra, federal_reserve, sec]
  supervision:
    human_in_the_loop: always
    kill_switch: true
  recordkeeping:
    audit_logging: true
    retention_period: 7y
    immutable: true

gitagent auditコマンドでコンプライアンスレポートを生成できます。
FINRA Rule 3110（監督義務）、SEC 17a-4（記録保持）などの規制要件への対応状況を確認できます。

PRベースの承認フロー

エージェントの定義変更はGitのPull Requestで管理できます。
プロンプトの変更、ツールの追加、権限の変更がすべてdiffとして可視化されます。

# プロンプト変更のdiff
git diff main -- SOUL.md

# 誰がいつ変更したか
git blame SOUL.md

SOUL.mdやSKILL.mdはプレーンテキストのため、フォークされたリポジトリに悪意あるプロンプトが埋め込まれるリスクがあります。
外部のエージェント定義を取り込む際は、必ずdiffを確認してからマージしてください。

職務分離の強制

agent.yamlで職務分離のコンフリクトマトリクスを定義できます。

compliance:
  segregation_of_duties:
    roles:
      - id: analyst
        permissions: [create, submit]
      - id: reviewer
        permissions: [review, approve, reject]
    conflicts:
      - [analyst, reviewer]
    enforcement: strict

analystとreviewerを同一エージェントに割り当てることが禁止されます。
これにより、自己承認のない安全なワークフローを構築できます。

他の標準化アプローチとの比較

AIエージェントの標準化はGitAgentだけが取り組んでいるわけではありません。
現在、3つの異なるレイヤーで標準化が進んでいます。

3つの標準化レイヤー

GitAgent vs MCP vs A2A

比較軸	GitAgent	MCP	A2A
標準化の対象	エージェントの定義	ツール接続	エージェント間通信
解決する問題	フレームワーク間の移植性	ツール統合のN x M問題	異種エージェント間の相互運用
中心概念	agent.yaml + SOUL.md	Tool / Resource / Prompt	Agent Card + Task
提唱者	Open GitAgent (OSS)	Anthropic	Google
通信プロトコル	なし（静的ファイル）	JSON-RPC over stdio/HTTP	HTTP + JSON-RPC
実行時の役割	なし（定義のみ）	クライアント-サーバー接続	クライアント-リモートエージェント通信

補完関係の図解

3つの標準は競合ではなく、補完関係にあります。

• GitAgentは「エージェントとは何か」を定義します。SOUL.md、agent.yaml、DUTIES.mdで性格・能力・制約を記述します。実行時のプロトコルは持ちません
• MCPは「エージェントが外部ツールにどうアクセスするか」を標準化します。GitAgentのtools/ディレクトリはMCP互換のツール定義をサポートしており、両者は直接連携できます
• A2Aは「エージェント同士がどう会話するか」を標準化します。Agent Cardでエージェントの能力を公開し、Taskベースで作業を依頼します。GitAgentのagent.yamlからA2AのAgent Cardを生成する、という連携が将来的に考えられます

実務での使い分け

やりたいこと	使う標準
エージェントの定義をフレームワーク非依存で管理したい	GitAgent
データベースやAPIにエージェントからアクセスしたい	MCP
複数のエージェントを連携させたい（別チーム・別組織含む）	A2A
上記すべて	GitAgent + MCP + A2A（組み合わせ可能）

現時点では、GitAgentとMCPの組み合わせが最も実用的です。
A2Aはまだプロトコル策定の段階であり、プロダクション利用は時期尚早です。

注意点と今後の展望

GitAgentはまだspec version 0.1.0です。
以下の点は導入前に把握しておく必要があります。

• シークレット管理が.envベースのため、本番環境では外部のシークレットマネージャとの併用が必要になる
• エージェント間のツール検出（ディスカバリー）の仕組みがまだない
• exportで移植できるのは定義部分であり、ランタイムのオーケストレーションは各フレームワーク側で実装する必要がある
• SOUL.mdはプレーンテキストなので、外部リポジトリからフォークする際はプロンプトインジェクションのリスクに注意が必要

一方で、Gitネイティブという設計判断は理にかなっています。
バージョン管理、ブランチ戦略、PRレビュー、CI/CD。
開発者が日常的に使っているワークフローをそのままエージェント管理に適用できます。

AIエージェントの開発がチーム単位で進む場面が増えています。
フレームワークの選択を柔軟に保ちつつ、エージェントの定義を資産として管理したい場合、GitAgentは検討に値するツールです。

参考リンク