Reference - リファレンス

概要: Autonomous-Operationsの技術仕様書、マニュアル、詳細リファレンス集です。Agent運用マニュアル、Worker協調プロトコル、Label体系など、詳細な技術仕様を参照できます。

対象読者: 全開発者 所要時間: 必要に応じて 前提知識: Getting Started の基本を理解していること

目次

1. セクション概要
2. ドキュメント一覧
3. 使い方
4. 主要仕様
5. 次のステップ

セクション概要

Referenceセクションは、プロジェクトの詳細技術仕様書です。実装の詳細、プロトコル定義、ガバナンス規則など、開発に必要な正確な情報を提供します。

主要ドキュメント

• Agent運用マニュアル (v2.0.0): 1,349行の包括的な運用ガイド
• Worker協調プロトコル: Worker間の協調動作仕様
• Label体系ガバナンス: 65個のLabel管理規則
• LDDワークフロー: Log-Driven Development詳細仕様
• CLIパッケージ: CLI開発進捗とテスト結果
• 変更履歴: プロジェクトの変更ログ

ドキュメント一覧

1. agent-operations-manual.md

内容: Agent運用マニュアル v2.0.0 ページ数: 1,349行 最終更新: 2025-09-XX

主要トピック:

6種類のAgent詳細

• CoordinatorAgent: タスク分解、依存関係解決、並行実行制御
• CodeGenAgent: AI駆動コード生成、テスト自動生成
• ReviewAgent: 品質判定 (80点基準)、静的解析
• IssueAgent: Issue分析、Label自動付与
• PRAgent: PR自動作成、Reviewer割り当て
• DeploymentAgent: CI/CD実行、デプロイ、Rollback

5フェーズワークフロー

1. 初期化 (Initialization): Agent起動、コンテキスト読み込み
2. 計画 (Planning): タスク分解、依存関係解決
3. 並行実行 (Parallel Execution): DAGベース並行タスク実行
4. 検証 (Verification): 品質チェック、テスト実行
5. ハンドオフ (Handoff): 次Agentへの引き継ぎ

KPI定義

こんな時に使う:

• Agent動作の詳細を理解したい
• エスカレーション条件を確認したい
• KPI定義を参照したい

2. worker-coordination.md

内容: Worker協調プロトコル 最終更新: 2025-09-XX

主要トピック:

協調プロトコル

• 排他制御: ファイル単位のロック機構
• メッセージング: Worker間通信プロトコル
• 状態同期: 共有状態の整合性保証
• エラーハンドリング: Worker障害時の復旧手順

Worktree管理

# Worktree自動作成
git worktree add ../worktrees/issue-270 feature/issue-270

# 並行実行
npm run agents:parallel:exec -- --issues=270,240,276 --concurrency=3

# Worktree自動削除
git worktree remove ../worktrees/issue-270

バッティング回避戦略

1. ファイルレベル排他: 同一ファイル編集の防止
2. Worktree分離: Issue単位でブランチ分離
3. 依存関係順序保証: DAGベース実行順序制御

こんな時に使う:

• 並行実行の仕組みを理解したい
• Worktree管理を実装したい
• バッティング問題を解決したい

3. label-governance.md

内容: Label体系ガバナンス (65個のLabel) 最終更新: 2025-09-XX

主要トピック:

Label分類 (65個)

1. 責任者Label (5種)

• 👤担当-開発者: 個別開発者が担当
• 👥担当-テックリード: テックリードがレビュー
• 👑担当-PO: Product Ownerが判断
• 🤖担当-AI Agent: AI Agentが自動処理
• 🔄担当-未定: 担当者未決定

2. SeverityLabel (5段階)

• 🔥Sev.1-Critical: システムダウン、即対応必要
• ⭐Sev.2-High: 主要機能停止、24時間以内対応
• ➡️Sev.3-Medium: 一部機能影響、1週間以内対応
• 🟢Sev.4-Low: 軽微な問題、次スプリント対応
• ⬇️Sev.5-Trivial: 影響なし、時間がある時対応

3. 影響度Label (4段階)

• 📊影響度-Critical: 全ユーザー影響
• 📊影響度-High: 多数ユーザー影響
• 📊影響度-Medium: 一部ユーザー影響
• 📊影響度-Low: 限定的影響

4. AgentLabel (8種)

• 🤖CoordinatorAgent
• 🤖CodeGenAgent
• 🤖ReviewAgent
• 🤖IssueAgent
• 🤖PRAgent
• 🤖DeploymentAgent
• 🤖TestAgent
• 🤖MonitoringAgent

Label付与ルール

# Issue作成時
- IssueAgentが自動分析
- Severity、影響度、担当者を自動付与

# PR作成時
- PRAgentが自動分析
- Reviewerを自動割り当て

# エスカレーション時
- 担当者Labelを上位に変更 (開発者→テックリード→PO)

こんな時に使う:

• Label体系を理解したい
• 自動ラベリングを実装したい
• ガバナンス規則を確認したい

4. ldd-workflow.md

内容: Log-Driven Development ワークフロー詳細 最終更新: 2025-09-XX

主要トピック:

3つのコンポーネント

1. codex_prompt_chain (.ai/logs/YYYY-MM-DD.md)

intent: "何を達成するか"
plan:
  - "ステップ1（5-7語）"
  - "ステップ2（5-7語）"
implementation:
  - "変更ファイル: src/app.ts"
  - "追加機能: ログイン機能"
verification:
  - "実施した検証: ユニットテスト実行"
  - "結果: 全テスト合格"

2. tool_invocations (JSON形式)

{
  "command": "npm run lint",
  "workdir": "/path/to/repo",
  "timestamp": "2025-10-08T12:34:56Z",
  "status": "passed",
  "duration": "2.3s",
  "notes": "ESLintエラー0件"
}

3. memory_bank (@memory-bank.mdc)

• Agent間コンテキスト共有
• 90日保持ポリシー
• エスカレーション履歴記録

ログ保持期間

• codex_prompt_chain: 90日
• tool_invocations: 30日
• memory_bank: 90日

こんな時に使う:

• LDDを実践したい
• ログフォーマットを確認したい
• トレーサビリティを確保したい

5. cli-package.md

内容: CLIパッケージ開発進捗とテスト結果 最終更新: 2025-09-XX

主要トピック:

CLI機能

• agents:exec: 単一Agent実行
• agents:parallel:exec: 並行Agent実行
• test: テスト実行 (Unit、Integration、E2E)
• build: TypeScriptビルド
• lint: ESLint実行

テスト結果

Unit Tests:        ████████████████████ 45/45 ✅
Integration Tests: ████████████████████ 23/23 ✅
E2E Tests:         ████████████████████ 12/12 ✅

Total Coverage:    ████████████████████ 92% ✅

こんな時に使う:

• CLI開発進捗を確認したい
• テスト結果を参照したい
• パッケージビルドを理解したい

6. changelog.md

内容: プロジェクト変更履歴 最終更新: 2025-10-10

主要トピック:

• バージョンごとの変更内容
• 追加機能、修正バグ、破壊的変更
• マイグレーションガイド

フォーマット: Keep a Changelog 準拠

こんな時に使う:

• 最新の変更を確認したい
• バージョン間の差分を理解したい
• マイグレーション方法を確認したい

使い方

リファレンスの活用方法

1. 開発中の参照

実装中に詳細仕様を確認:

# Agent動作の詳細を確認
→ agent-operations-manual.md を参照

# Label付与ルールを確認
→ label-governance.md を参照

# LDDフォーマットを確認
→ ldd-workflow.md を参照

2. トラブルシューティング

問題発生時に仕様を確認:

# Agent実行エラー
→ agent-operations-manual.md のエラーハンドリングセクション

# Worker協調エラー
→ worker-coordination.md のエラーハンドリングセクション

# Label自動付与エラー
→ label-governance.md の付与ルールセクション

3. 新機能実装

新機能実装時に仕様を確認:

# 新しいAgentを追加
→ agent-operations-manual.md のAgent実装セクション

# 新しいLabelを追加
→ label-governance.md のLabel追加手順

# 新しいログタイプを追加
→ ldd-workflow.md のログフォーマットセクション

主要仕様

Agent階層システム

Human Layer (戦略・承認)
    ↓
Coordinator Layer (統括)
    ↓ タスク割り当て
Specialist Layer (実行)
  ├─ CodeGenAgent
  ├─ ReviewAgent
  ├─ IssueAgent
  ├─ PRAgent
  └─ DeploymentAgent

詳細: agent-operations-manual.md

Worker協調プロトコル

Issue #270 (Worker 1)    Issue #240 (Worker 2)
    ↓                         ↓
Worktree 1                Worktree 2
    ↓                         ↓
feature/issue-270         feature/issue-240
    ↓                         ↓
排他ロック                  排他ロック
    ↓                         ↓
並行実行                    並行実行

詳細: worker-coordination.md

Label体系 (65個)

詳細: label-governance.md

LDD 3コンポーネント

詳細: ldd-workflow.md

よくある質問

Q1: リファレンスはいつ読むべきですか?

A: 以下のタイミングで参照してください:

• 開発中: 仕様の詳細を確認したい時
• トラブル時: エラーハンドリングを確認したい時
• 新機能実装時: 実装ガイドラインを確認したい時
• レビュー時: コード規約を確認したい時

Q2: Agent運用マニュアルは全部読む必要がありますか?

A: いいえ、必要な部分だけ読んでください。

1,349行あるため、目次から必要なセクションを探して参照するのが効率的です。

Q3: Label体系を変更できますか?

A: はい、可能ですが、ガバナンス規則に従ってください。

label-governance.md のLabel追加手順を参照してください。

Q4: 変更履歴はどこで確認できますか?

A: changelog.md で確認できます。

バージョンごとの変更内容、追加機能、修正バグが記載されています。

次のステップ

このセクション完了後の理解度チェック

以下ができれば、Referenceセクションを活用できています:

• Agent運用マニュアルの目次を把握している
• Worker協調プロトコルの概要を理解している
• Label体系65個の分類を把握している
• LDD 3コンポーネントを理解している
• 必要な情報を素早く見つけられる

次に読むべきドキュメント

実装を始めたい方:

1. Guides - 実践ガイド
2. Integration - 統合ガイド

システムを理解したい方:

1. Architecture - システムアーキテクチャ
2. Phases - 実装フェーズ

コントリビュートしたい方:

1. Community - コミュニティ

関連ドキュメント

基礎知識

• Getting Started
• Architecture

実装ガイド

• Guides
• Integration
• Phases

作成日: 2025-10-10 更新日: 2025-10-10 メンテナー: Autonomous-Operations Team