Architecture - システムアーキテクチャ
概要: Autonomous-Operationsのシステムアーキテクチャ全体を理解するためのセクションです。6-Agent階層システム、並行実行、GitHub as OSなどの設計思想を学びます。
対象読者: アーキテクト、上級開発者 所要時間: 4時間 前提知識: Getting Started を完了していること
目次
セクション概要
Architectureセクションでは、以下のトピックをカバーしています:
- システム全体像: リポジトリ構造とコンポーネント間の関係
- Agent階層システム: 6種類のAgentの設計と役割分担
- 並行実行アーキテクチャ: DAGベースの依存関係解決とWorktree管理
- GitHub as OS: GitHub全15機能のOS統合アーキテクチャ
- Log-Driven Development: ログベース開発手法
- 組織設計原則5原則: データ駆動型意思決定フレームワーク
このセクションを完了すると、システムの設計思想を深く理解し、独自のカスタマイズや拡張ができるようになります。
アーキテクチャの全体像
システム構造図
┌─────────────────────────────────────────────────────────────┐
│ Human Layer (戦略・承認) │
│ Strategic Decision Making │
└─────────────────────────────────────────────────────────────┘
↓ 戦略指示
┌─────────────────────────────────────────────────────────────┐
│ Coordinator Layer (統括) │
│ CoordinatorAgent - Task Orchestration │
│ (タスク分解、依存関係解決、並行実行制御) │
└─────────────────────────────────────────────────────────────┘
↓ タスク割り当て
┌─────────────────────────────────────────────────────────────┐
│ Specialist Layer (実行) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CodeGen │ │ Review │ │ Issue │ │ PR │ │
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ │
│ │Deployment│ │
│ │ Agent │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
↓ GitHub API
┌─────────────────────────────────────────────────────────────┐
│ GitHub as OS Platform │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Projects V2 │ │ Webhooks │ │ Discussions │ │
│ │ (Data) │ │ (EventBus) │ │ (Queue) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Actions │ │ Packages │ │ Pages │ │
│ │ (Workflow) │ │ (Registry) │ │ (Dashboard) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
主要コンポーネント
| コンポーネント | 役割 | ドキュメント |
|---|---|---|
| Agent階層 | タスク実行の中核 | agent-hierarchy.md |
| 並行実行エンジン | DAGベース並行実行 | parallel-execution.md |
| GitHub OS | プラットフォーム基盤 | github-os.md |
| LDDシステム | ログ駆動開発 | ldd-system.md |
| 組織設計原則 | 意思決定フレームワーク | organizational-principles.md |
ドキュメント一覧
1. overview.md
内容: システム全体像とリポジトリ構造 所要時間: 45分 こんな方におすすめ: システム全体を俯瞰したい方
主要トピック:
- リポジトリ構造
- データフロー
- コンポーネント間の関係
- ディレクトリレイアウト
2. agent-hierarchy.md
内容: 6種類のAgent階層システムの詳細 所要時間: 60分 こんな方におすすめ: Agent設計を理解したい方
主要トピック:
- CoordinatorAgent: タスク分解と統括
- CodeGenAgent: AI駆動コード生成
- ReviewAgent: 品質判定 (80点基準)
- IssueAgent: Issue分析とラベリング
- PRAgent: PR自動作成
- DeploymentAgent: CI/CD実行
KPI:
- Agent Task完了率: >90%
- 平均品質スコア: 92点
- エスカレーション率: <10%
3. parallel-execution.md
内容: 並行実行アーキテクチャの詳細 所要時間: 60分 こんな方におすすめ: 並行実行の仕組みを理解したい方
主要トピック:
- DAG構築アルゴリズム
- トポロジカルソート
- Git Worktree自動管理
- バッティング回避戦略
- 依存関係解決
実績:
- 時間削減: 83% (240分→40分)
- 並行度: concurrency=3で3タスク同時実行
- 成功率: 95%+
4. github-os.md
内容: GitHub as OSアーキテクチャ 所要時間: 45分 こんな方におすすめ: GitHub統合の仕組みを理解したい方
主要トピック:
- User Space: Issues、PRs、Discussions
- Kernel Space: Actions、Webhooks、Projects V2
- Hardware Layer: Runners、Packages、Pages
- Security Layer: CodeQL、Dependabot
Phase完了率: 10/10 (100%)
5. ldd-system.md
内容: Log-Driven Development システム 所要時間: 30分 こんな方におすすめ: ログベース開発を実践したい方
主要トピック:
- codex_prompt_chain: 意図→計画→実装→検証
- tool_invocations: コマンド実行ログ
- memory_bank: Agent間コンテキスト共有
- 90日保持ポリシー
6. organizational-principles.md
内容: 組織設計原則5原則 所要時間: 30分 こんな方におすすめ: データ駆動型意思決定を学びたい方
5原則:
- 責任と権限の明確化
- 結果重視
- 階層の明確化
- 誤解・錯覚の排除
- 感情的判断の排除
KPI達成率: 100% (全原則)
推奨読書順序
初めてアーキテクチャを学ぶ方 (所要時間: 4時間)
-
overview.md (45分)
- まず全体像を把握する
-
agent-hierarchy.md (60分)
- Agent階層の詳細を理解
-
parallel-execution.md (60分)
- 並行実行の仕組みを学ぶ
-
github-os.md (45分)
- GitHub統合を理解
-
organizational-principles.md (30分)
- 設計思想を学ぶ
特定のトピックを深く学びたい方
Agent設計に興味がある方:
並行実行に興味がある方:
GitHub統合に興味がある方:
主要設計原則
1. 階層的責任分離
Human Layer (戦略)
↓
Coordinator Layer (統括)
↓
Specialist Layer (実行)
各層は明確な責任範囲を持ち、上位層への適切なエスカレーションを実施。
2. データ駆動型意思決定
すべての判断は数値ベース:
- 品質スコア: 80点基準
- AI Task成功率: 95%+目標
- エスカレーション率: <10%目標
3. 並行実行最適化
DAGベースの依存関係解決により、安全かつ効率的な並行実行を実現:
- 83%時間削減
- 72%並行実行効率
4. GitHub Native統合
GitHub全15機能をフル活用し、外部依存を最小化:
- Projects V2: データ永続化
- Webhooks: イベント駆動
- Discussions: メッセージキュー
5. Log-Driven開発
すべての操作をログ化し、トレーサビリティと再現性を確保:
- codex_prompt_chain
- tool_invocations
- memory_bank
技術スタック
Core Technologies
- Runtime: Node.js 16+
- Language: TypeScript
- Package Manager: NPM
- Version Control: Git 2.20+
GitHub Integration
- API: GitHub REST API v3, GraphQL API v4
- CLI: GitHub CLI (gh)
- Components: Projects V2, Webhooks, Discussions, Actions, Pages
AI Integration
- Claude Code: Task Tool API
- Gemini AI: Context Engineering
- Vector DB: Pinecone (計画中)
パフォーマンス指標
| 指標 | 値 | 目標 | ステータス |
|---|---|---|---|
| 平均実行時間 | 3分 | <5分 | ✅ 達成 |
| 並行実行効率 | 72% | 50%+ | ✅ 達成 |
| 時間削減率 | 83% | 70%+ | ✅ 達成 |
| 品質スコア | 92点 | 85点+ | ✅ 達成 |
| Test Coverage | 92% | 80%+ | ✅ 達成 |
| AI Task成功率 | 97% | 95%+ | ✅ 達成 |
よくある質問
Q1: なぜAgent階層を3層にしたのですか?
A: 責任の明確化とスケーラビリティのためです。
- Human Layer: 戦略的意思決定に専念
- Coordinator Layer: タスク分解と統括に専念
- Specialist Layer: 専門タスク実行に専念
この構造により、各層の責任範囲が明確になり、システムの拡張が容易になります。
Q2: DAGベース並行実行の利点は?
A: 安全性と効率性の両立です。
- 依存関係の自動解決: 実行順序を自動決定
- 並行度の最大化: 独立タスクを同時実行
- バッティング回避: Worktree分離で衝突防止
結果として83%の時間削減を達成しています。
Q3: なぜGitHubをOSとして使うのですか?
A: 統合性と信頼性のためです。
- 統合性: 15機能すべてがGitHub上で完結
- 信頼性: GitHubの99.9%稼働率を活用
- 保守性: 外部依存を最小化
次のステップ
このセクション完了後の理解度チェック
以下の質問に答えられれば、アーキテクチャを理解できています:
- 6種類のAgentの役割と責任範囲を説明できる
- DAGベース並行実行の仕組みを理解している
- GitHub as OSの主要コンポーネントを列挙できる
- 組織設計原則5原則を説明できる
- LDDシステムの3コンポーネントを理解している
次に読むべきドキュメント
実装を始めたい方:
詳細仕様を確認したい方:
コントリビュートしたい方:
関連ドキュメント
前提知識
実践編
詳細仕様
作成日: 2025-10-10 更新日: 2025-10-10 メンテナー: Autonomous-Operations Team