基本コンセプト - Autonomous-Operationsの仕組み
概要: Autonomous-Operationsを支える核となる概念とアーキテクチャの基本を理解します。
対象読者: Autonomous-Operationsの仕組みを理解したい開発者 所要時間: 20分 前提知識: クイックスタート、セットアップガイド
目次
- Autonomous-Operationsのビジョン
- コンセプト1: Agent階層システム
- コンセプト2: GitHub as Operating System
- コンセプト3: 並行実行システム
- コンセプト4: Log-Driven Development (LDD)
- コンセプト5: 組織設計原則
- システムの全体像
- 次のステップ
Autonomous-Operationsのビジョン
Autonomous-Operationsは完全自律型AI開発オペレーションを実現するプラットフォームです。
基本理念
vision:
goal: "AIによる完全自律型ソフトウェア開発の実現"
principles:
- 人間は戦略決定・承認のみ
- Agentが計画・実装・検証・デプロイを自動化
- 組織設計原則による明確な責任・権限・階層
- データ駆動の客観的判断
metrics:
success_rate: 97% # AI Task成功率
time_reduction: 83% # 時間削減率 (240分→40分)
quality_score: 92/100 # 平均品質スコア
automation_rate: 95%+ # 自動化率
従来の開発 vs Autonomous-Operations
| 項目 | 従来の開発 | Autonomous-Operations |
|---|---|---|
| Issue対応 | 手動で実装 | AI Agentが自動実装 |
| コードレビュー | 人間が全件レビュー | AIが品質チェック+人間が承認 |
| テスト作成 | 手動で作成 | AIが自動生成 |
| デプロイ | 手動実行 | 自動化 |
| 並行作業 | 手動調整 | DAGベース自動調整 |
| 所要時間 | 4時間 | 40分 (83%削減) |
コンセプト1: Agent階層システム
Autonomous-Operationsは6種類のAI Agentが協調して動作します。
Agent階層構造
agent_hierarchy:
# 統括層
coordinator_layer:
CoordinatorAgent:
role: タスク分解・Agent統括・並行実行制御
authority: リソース配分、Agent割り当て
escalation: TechLead、Product Owner
# 専門層
specialist_layer:
CodeGenAgent:
role: コード生成・テスト自動生成
authority: 実装レベル決定
escalation: TechLead
ReviewAgent:
role: 静的解析・セキュリティスキャン・品質判定
authority: 品質合否判定 (80点基準)
escalation: TechLead、CISO
IssueAgent:
role: Issue分析・Label付与・担当者割り当て
authority: Label自動付与
escalation: Product Manager
PRAgent:
role: PR作成・説明文生成・Reviewer割り当て
authority: Draft PR作成
escalation: TechLead
DeploymentAgent:
role: CI/CD実行・デプロイ・Rollback
authority: Staging環境デプロイ
escalation: CTO (本番環境)
Agent間の協調フロー
graph TD
A[GitHub Issue] --> B[IssueAgent]
B --> C[Label自動付与]
C --> D[CoordinatorAgent]
D --> E[タスク分解]
E --> F[依存関係解析]
F --> G[並行実行計画]
G --> H1[CodeGenAgent]
G --> H2[CodeGenAgent]
G --> H3[CodeGenAgent]
H1 --> I1[実装1]
H2 --> I2[実装2]
H3 --> I3[実装3]
I1 --> J[ReviewAgent]
I2 --> J
I3 --> J
J --> K{品質スコア≥80?}
K -->|YES| L[PRAgent]
K -->|NO| M[自動修正]
M --> H1
L --> N[Draft PR作成]
N --> O[人間レビュー]
O --> P[Merge承認]
P --> Q[DeploymentAgent]
Q --> R[本番デプロイ]
各Agentの詳細
1. CoordinatorAgent - 統括エージェント
責務:
- Issue本文からタスクを分解
- 依存関係をDAG (有向非巡回グラフ) で構築
- 最適な並行度を計算
- 各タスクに適切なAgentを割り当て
実行例:
# Issue #270: Firebase Authentication修正
input:
issue_number: 270
title: "fix: Firebase Auth invalid-credential error"
body: |
問題:
1. ログイン時にinvalid-credentialエラー
2. E2Eテストが失敗
3. ドキュメントが古い
output:
tasks:
- id: task-1
type: fix
description: Firebase Auth修正
priority: 1
dependencies: []
assigned_to: CodeGenAgent
- id: task-2
type: test
description: E2Eテスト追加
priority: 2
dependencies: [task-1]
assigned_to: CodeGenAgent
- id: task-3
type: docs
description: ドキュメント更新
priority: 3
dependencies: [task-1, task-2]
assigned_to: CodeGenAgent
execution_plan:
phase_1: [task-1] # まずバグ修正
phase_2: [task-2] # 次にテスト
phase_3: [task-3] # 最後にドキュメント
estimated_duration: 15分
2. CodeGenAgent - コード生成エージェント
責務:
- AI駆動のコード生成
- ユニットテスト自動作成
- 既存コードとの整合性保証
実行例:
// 生成されたコード例
// src/auth/firebase-auth.ts
import { signInWithEmailAndPassword } from 'firebase/auth';
import { auth } from './firebase-config';
export async function loginWithEmail(
email: string,
password: string
): Promise<User> {
try {
const userCredential = await signInWithEmailAndPassword(
auth,
email,
password
);
return userCredential.user;
} catch (error) {
// invalid-credentialエラーを適切にハンドリング
if (error.code === 'auth/invalid-credential') {
throw new Error('Invalid email or password');
}
throw error;
}
}
3. ReviewAgent - 品質保証エージェント
責務:
- ESLint、Prettierによる静的解析
- TypeScriptの型チェック
- セキュリティスキャン (CodeQL)
- テストカバレッジ確認
- 品質スコア算出 (80点基準)
評価基準:
quality_metrics:
code_quality:
weight: 30%
checks:
- ESLint violations: 0
- Prettier formatting: 合格
- TypeScript errors: 0
test_coverage:
weight: 30%
target: 80%以上
security:
weight: 20%
checks:
- CodeQL alerts: 0 critical, 0 high
- Dependency vulnerabilities: 0 critical
performance:
weight: 20%
checks:
- Build time: <30秒
- Bundle size: 変化 <10%
passing_score: 80点
4. IssueAgent - Issue管理エージェント
責務:
- Issueの自動分析
- 適切なLabel自動付与
- 担当者自動割り当て
- 優先度判定
Label体系:
label_categories:
responsibility:
- 👤担当-開発者
- 👥担当-テックリード
- 👑担当-PO
- 🤖担当-AI Agent
- 🔒担当-Guardian
severity:
- 🔥Sev.1-Critical # 本番障害
- ⭐Sev.2-High # 重要機能不全
- ➡️Sev.3-Medium # 通常バグ
- 🟢Sev.4-Low # 軽微な問題
- ⬇️Sev.5-Trivial # タイポ等
impact:
- 📊影響度-Critical # 全ユーザー影響
- 📊影響度-High # 多数ユーザー影響
- 📊影響度-Medium # 一部ユーザー影響
- 📊影響度-Low # 限定的影響
agent_type:
- 🤖CoordinatorAgent
- 🤖CodeGenAgent
- 🤖ReviewAgent
- 🤖IssueAgent
- 🤖PRAgent
- 🤖DeploymentAgent
5. PRAgent - プルリクエスト管理エージェント
責務:
- Draft PR自動作成
- 変更内容の説明文生成
- Reviewer自動割り当て
- テスト結果の添付
PR説明文テンプレート:
## 概要
Issue #270 で報告されたFirebase Auth invalid-credentialエラーを修正しました。
## 変更内容
- ✅ `firebase-auth.ts`でエラーハンドリング追加
- ✅ ユニットテスト追加 (カバレッジ: 95%)
- ✅ E2Eテスト追加
- ✅ ドキュメント更新
## 品質スコア
**92点 / 100点** ✅ 合格
- コード品質: 95点
- テストカバレッジ: 95%
- セキュリティ: 問題なし
- パフォーマンス: 良好
## テスト結果
✓ 15 tests passed ✓ Build: 18.3s ✓ Lint: passed ✓ Type check: passed
## スクリーンショット
(必要に応じて)
---
🤖 Generated by CodeGenAgent
Quality assured by ReviewAgent
6. DeploymentAgent - デプロイ管理エージェント
責務:
- CI/CDパイプライン実行
- Staging環境への自動デプロイ
- 本番デプロイの準備
- Rollback実行
デプロイフロー:
deployment_stages:
1_build:
- npm run build
- Docker image build
2_test:
- Unit tests
- Integration tests
- E2E tests
3_staging_deploy:
authority: 自動実行
steps:
- Deploy to staging
- Smoke test
- Performance test
4_production_deploy:
authority: 人間承認必要
steps:
- Create release
- Deploy to production
- Monitor metrics
- Rollback if needed
コンセプト2: GitHub as Operating System
Autonomous-OperationsはGitHubの15機能をOS Componentsとして統合します。
GitHubのOS化
github_os_architecture:
# ユーザースペース (アプリケーション層)
user_space:
Issues: タスクキュー
Pull Requests: コードレビュー・マージ
Discussions: メッセージキュー・ナレッジベース
Wiki: 永続的ドキュメント
# カーネルスペース (制御層)
kernel_space:
Actions: プロセス実行エンジン
Webhooks: イベントバス
Projects V2: データベース・状態管理
API: システムコール
# ハードウェア層 (インフラ)
hardware_layer:
Runners: コンピューティングリソース
Packages: ストレージ・配布
Pages: ウェブサーバー
Container Registry: コンテナレジストリ
# セキュリティ層
security_layer:
CodeQL: 静的解析
Dependabot: 依存関係管理
Secret Scanning: シークレット検出
CODEOWNERS: アクセス制御
統合完了フェーズ (10/10完了)
| Phase | Component | 用途 | 実装時間 |
|---|---|---|---|
| A | Projects V2 | データベース・進捗管理 | 4時間 |
| B | Webhooks | イベント駆動アーキテクチャ | 5時間 |
| C | Discussions | メッセージキュー | 2時間 |
| D | Packages | NPM SDK配布 | 4時間 |
| E | Pages | ダッシュボード | 6時間 |
| F | Security | セキュリティスキャン | 2時間 |
| G | API Wrapper | GitHub OS SDK | 統合済 |
| H | Environments | 環境管理 | 1時間 |
| I | Releases | リリース自動化 | 1時間 |
| J | Integration | 最終統合 | 1時間 |
合計: 26時間（見積36時間から28%効率化）
GitHub Projects V2の活用例
// カスタムフィールドで進捗管理
const projectFields = {
Status: 'In Progress', // ステータス
Agent: 'CodeGenAgent', // 担当Agent
Priority: 'High', // 優先度
QualityScore: 92, // 品質スコア
Duration: 15, // 実行時間(分)
Cost: 0.45, // APIコスト(USD)
Sprint: 'Sprint 23', // スプリント
Dependencies: '#240, #276' // 依存関係
};
コンセプト3: 並行実行システム
複数のタスクを安全に並行実行するシステムです。
DAGベース依存関係解決
# Issue #300の例
dependencies:
task-1:
description: データベーススキーマ変更
depends_on: []
estimated: 10分
task-2:
description: API実装
depends_on: [task-1] # task-1完了後
estimated: 15分
task-3:
description: フロントエンド実装
depends_on: [task-2] # task-2完了後
estimated: 20分
task-4:
description: E2Eテスト
depends_on: [task-2, task-3] # task-2とtask-3完了後
estimated: 15分
execution_plan:
phase_1: [task-1] # 最初にDB
phase_2: [task-2] # 次にAPI
phase_3: [task-3] # 次にフロント
phase_4: [task-4] # 最後にテスト
total_time: 60分 (逐次実行)
parallel_time: 60分 (この例は依存関係が強いため並行化困難)
Git Worktree による分離
各タスクは独立したWorktreeで実行され、競合を回避:
# 自動的に作成されるWorktree構造
Autonomous-Operations/
├── .git/ # メインGitディレクトリ
├── .worktrees/ # Worktreeルート
│ ├── task-001/ # Task 1専用
│ │ ├── src/
│ │ └── [full repo]
│ ├── task-002/ # Task 2専用
│ │ ├── src/
│ │ └── [full repo]
│ └── task-003/ # Task 3専用
│ ├── src/
│ └── [full repo]
└── src/ # メイン作業ディレクトリ
バッティング回避メカニズム
conflict_prevention:
# ファイルレベルの排他制御
file_locking:
- task-1が`src/auth.ts`を編集中
- task-2が`src/auth.ts`を必要とする
- → task-2はtask-1完了まで待機
# 共有ファイルの保護
critical_files:
- package.json
- package-lock.json
- tsconfig.json
- .github/workflows/*.yml
strategy: 1タスクずつ順次実行
# ロックファイルによる管理
lock_files:
location: .task-locks/
format: JSON
expiration: 60分
heartbeat: 5分ごと更新
並行実行の実行例
# 3つのIssueを並行度2で実行
npm run agents:parallel:exec -- \
--issues=270,240,276 \
--concurrency=2
# 実行フロー:
# T=0min: Issue #270, #240 開始
# T=3min: #270 完了、#276 開始
# T=5min: #240 完了
# T=8min: #276 完了
#
# 逐次実行: 15分
# 並行実行: 8分 (47%削減)
コンセプト4: Log-Driven Development (LDD)
すべての実行ログを構造化して記録し、再現性と監査可能性を保証します。
LDDの3コンポーネント
1. Codex Prompt Chain
# .ai/logs/2025-10-10.md
## Task: Firebase Auth Bug Fix
### Intent
Firebase Authenticationの`invalid-credential`エラーを修正する
### Plan
1. エラーログを分析 (5分)
2. エラーハンドリングを追加 (10分)
3. ユニットテストを作成 (5分)
4. E2Eテストを更新 (5分)
5. ドキュメントを更新 (5分)
### Implementation
変更ファイル:
- src/auth/firebase-auth.ts (50行追加)
- tests/auth/firebase-auth.test.ts (新規作成、120行)
- docs/AUTH.md (15行更新)
### Verification
実施した検証:
- ✅ ユニットテスト: 15 passed
- ✅ E2Eテスト: 8 passed
- ✅ Lint: passed
- ✅ Build: successful (18.3s)
- ✅ 品質スコア: 92点
2. Tool Invocations
{
"timestamp": "2025-10-10T12:34:56Z",
"task_id": "task-270-001",
"agent": "CodeGenAgent",
"invocations": [
{
"command": "npm run lint",
"workdir": "/path/to/repo",
"timestamp": "2025-10-10T12:35:00Z",
"duration_ms": 3200,
"status": "passed",
"output": "✓ 0 errors, 0 warnings",
"notes": "ESLintチェック合格"
},
{
"command": "npm run test",
"workdir": "/path/to/repo",
"timestamp": "2025-10-10T12:36:00Z",
"duration_ms": 8500,
"status": "passed",
"output": "✓ 15 tests passed",
"notes": "全テスト合格、カバレッジ95%"
},
{
"command": "npm run build",
"workdir": "/path/to/repo",
"timestamp": "2025-10-10T12:37:00Z",
"duration_ms": 18300,
"status": "passed",
"output": "Build completed successfully",
"notes": "ビルド成功、bundle size: 245KB"
}
]
}
3. Memory Bank
# @memory-bank.mdc
## Context: Firebase Authentication
### Recent Issues
- #270: invalid-credential エラー修正 (2025-10-10)
- Root cause: エラーハンドリング不足
- Solution: try-catchブロック追加
- Quality score: 92点
### Lessons Learned
- Firebase Auth v9 APIではエラーコードが変更
- `auth/wrong-password`から`auth/invalid-credential`へ
- 既存コードの更新が必要
### Next Steps
- 他の認証メソッドも同様に更新
- エラーメッセージの多言語対応
LDDのメリット
benefits:
reproducibility:
- 全実行ログが記録されている
- 任意の時点の状態を再現可能
- デバッグが容易
auditability:
- AIが行った変更を追跡
- コンプライアンス要件に対応
- 品質保証プロセスの証跡
knowledge_sharing:
- Agent間でコンテキスト共有
- チームメンバーが進捗確認
- ベストプラクティス蓄積
continuous_improvement:
- 実行データから学習
- パフォーマンス最適化
- エラーパターン分析
コンセプト5: 組織設計原則
Autonomous-Operationsは組織設計原則5原則に基づいています。
5原則の実装
| 原則 | 実装内容 | KPI | 目標 | 実績 |
|---|---|---|---|---|
| 1. 責任と権限の明確化 | Agent階層、Label体系、CODEOWNERS | 担当者アサイン率 | 100% | 100% |
| 2. 結果重視 | Quality Score、KPI自動収集 | AI Task成功率 | 95%+ | 97% |
| 3. 階層の明確化 | Coordinator-Specialist階層 | エスカレーション正答率 | 100% | 100% |
| 4. 誤解・錯覚の排除 | 構造化プロトコル、完了条件チェック | 完了条件明示率 | 100% | 100% |
| 5. 感情的判断の排除 | 数値ベース判定 (80点基準) | データ駆動判定実施率 | 100% | 100% |
原則1: 責任と権限の明確化
responsibility_authority:
CoordinatorAgent:
責任: タスク全体の統括
権限: Agent割り当て、リソース配分
判断不可: 技術的詳細実装
CodeGenAgent:
責任: コード実装
権限: 実装レベル決定
判断不可: アーキテクチャ変更
ReviewAgent:
責任: 品質保証
権限: 合否判定 (80点基準)
判断不可: 実装方法の指示
原則2: 結果重視
quality_metrics:
ai_task_success_rate: 97%
average_quality_score: 92/100
test_coverage: 92%
time_reduction: 83%
# 結果が基準を満たさない場合
failure_handling:
score_below_80:
action: 自動修正試行
retry_count: 最大3回
escalation: TechLead (3回失敗後)
critical_error:
action: 即座にエスカレーション
target: Guardian (CTO/TechLead)
原則3: 階層の明確化
escalation_hierarchy:
Level_1_Specialist:
- CodeGenAgent
- ReviewAgent
- IssueAgent
- PRAgent
- DeploymentAgent
Level_2_Coordinator:
- CoordinatorAgent
Level_3_Human:
- TechLead (技術的判断)
- Product Owner (要件判断)
- CTO (戦略的判断)
escalation_rules:
- Specialistは技術的問題をCoordinatorへ
- Coordinatorは方針問題をTechLeadへ
- TechLeadは戦略問題をCTOへ
原則4: 誤解・錯覚の排除
completion_criteria:
# すべてのタスクに明確な完了条件
example_task:
description: ログインページ実装
acceptance_criteria:
- ✅ コンポーネントが実装されている
- ✅ バリデーションが動作する
- ✅ ユニットテストが合格
- ✅ E2Eテストが合格
- ✅ Lintが合格
- ✅ ビルドが成功
- ✅ 品質スコア≥80点
# 構造化プロトコル
communication_protocol:
format: YAML/JSON
required_fields:
- task_id
- status
- result
- evidence (ログ、スクリーンショット等)
原則5: 感情的判断の排除
objective_decision_making:
# すべて数値ベース
quality_judgment:
method: 品質スコア算出
threshold: 80点
criteria:
- コード品質: 30%
- テストカバレッジ: 30%
- セキュリティ: 20%
- パフォーマンス: 20%
priority_judgment:
method: Severity Level
scale:
- Sev.1 (Critical): 即座対応
- Sev.2 (High): 24時間以内
- Sev.3 (Medium): 1週間以内
- Sev.4 (Low): 2週間以内
- Sev.5 (Trivial): バックログ
resource_allocation:
method: 予測実行時間ベース
algorithm: DAGトポロジカルソート
optimization: クリティカルパス最小化
システムの全体像
エンドツーエンドフロー
sequenceDiagram
participant User
participant GitHub
participant IssueAgent
participant CoordinatorAgent
participant CodeGenAgent
participant ReviewAgent
participant PRAgent
participant Human
User->>GitHub: Issue作成
GitHub->>IssueAgent: Webhook通知
IssueAgent->>IssueAgent: Issue分析
IssueAgent->>GitHub: Label自動付与
GitHub->>CoordinatorAgent: Issue割り当て
CoordinatorAgent->>CoordinatorAgent: タスク分解
CoordinatorAgent->>CoordinatorAgent: DAG構築
CoordinatorAgent->>CodeGenAgent: タスク割り当て
CodeGenAgent->>CodeGenAgent: コード生成
CodeGenAgent->>CodeGenAgent: テスト作成
CodeGenAgent->>ReviewAgent: レビュー依頼
ReviewAgent->>ReviewAgent: 静的解析
ReviewAgent->>ReviewAgent: テスト実行
ReviewAgent->>ReviewAgent: 品質スコア算出
alt 品質スコア≥80
ReviewAgent->>PRAgent: PR作成依頼
PRAgent->>GitHub: Draft PR作成
GitHub->>Human: レビュー依頼
Human->>GitHub: 承認
GitHub->>GitHub: Merge
else 品質スコア<80
ReviewAgent->>CodeGenAgent: 修正依頼
CodeGenAgent->>CodeGenAgent: 自動修正
end
主要メトリクス
performance_metrics:
# タイムライン
initialization: 30秒
planning: 1-2分
execution: 5-15分
verification: 3-5分
handoff: 1-2分
total: 10-25分
# 品質指標
success_rate: 97%
quality_score: 92/100
test_coverage: 92%
# 効率指標
time_reduction: 83% (240分→40分)
parallel_efficiency: 72%
automation_rate: 95%+
# コスト指標
average_task_cost: $0.30-0.90
cost_per_hour_saved: $0.15
roi: 10倍
関連ドキュメント
- クイックスタート - 5分で始めるガイド
- セットアップガイド - 詳細な環境構築
- システムアーキテクチャ - 技術詳細
- Agent階層システム - Agent設計の詳細
- 並行実行アーキテクチャ - 並行処理の詳細
- Log-Driven Development - LDDの詳細
次のステップ
初心者向け
-
- 実践的なコマンド例
- デバッグ方法
- パフォーマンス最適化
-
- 各Agentの詳細な使い方
- トラブルシューティング
上級者向け
-
- 内部設計の理解
- カスタマイズ方法
-
- 外部システムとの連携
- プラグイン開発
ドキュメントバージョン: 1.0.0 最終更新: 2025-10-10 メンテナー: Autonomous-Operations Team
🤖 このドキュメントはAutonomous-Operationsプロジェクトの一部です