← ドキュメント一覧/ガイド

Guides - 実践ガイド

Guides - 実践ガイド

概要: Autonomous-Operationsを実際に使いこなすための実践的なガイド集です。CLI操作、Agent実行、テスト戦略など、日常的に使う機能の詳細を学びます。

対象読者: 実装者、運用担当者 所要時間: 2時間 前提知識: Getting Started を完了していること

目次

  1. セクション概要
  2. ドキュメント一覧
  3. 推奨読書順序
  4. クイックリファレンス
  5. 次のステップ

セクション概要

Guidesセクションでは、以下の実践的な内容をカバーしています:

主要トピック

  • Agent別ガイド: 6種類のAgentの詳細な使い方
  • CLI使用方法: コマンドラインツールの実践例
  • テスト戦略: Unit、Integration、E2Eテストの実行方法
  • 環境設定: GitHub Token、NPM、環境変数の設定
  • トラブルシューティング: よくある問題と解決方法

このセクションを完了すると、プロジェクトを日常的に使いこなし、トラブル時にも自己解決できるようになります。

ドキュメント一覧

Agent別ガイド (agents/)

各Agentの詳細な使用方法を解説:

1. agents/coordinator.md

内容: CoordinatorAgent - タスク統括 所要時間: 20分

主要機能:

  • タスク分解 (Issue本文→サブタスク)
  • 依存関係解決 (DAG構築)
  • Agent割り当て (最適Agentの自動選択)
  • 並行実行制御 (concurrency管理)

使用例:

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

2. agents/codegen.md

内容: CodeGenAgent - AI駆動コード生成 所要時間: 20分

主要機能:

  • AI駆動コード生成
  • テスト自動生成
  • 静的解析
  • コードレビュー準備

使用例:

# CodeGenAgent単体実行
npm run agents:codegen -- --issue=270

3. agents/review.md

内容: ReviewAgent - 品質判定 所要時間: 20分

主要機能:

  • 品質スコア判定 (80点基準)
  • 静的解析 (ESLint、TypeScript)
  • セキュリティスキャン (npm audit)
  • エスカレーション判定

品質基準:

  • 85点以上: 優秀 (自動マージ可能)
  • 80-84点: 良好 (承認推奨)
  • 70-79点: 要改善 (修正後再レビュー)
  • 70点未満: 不合格 (エスカレーション)

4. agents/issue.md

内容: IssueAgent - Issue分析とラベリング 所要時間: 15分

主要機能:

  • Issue内容分析
  • 自動ラベリング (65個のLabel体系)
  • 担当者割り当て
  • 優先度判定

Label体系:

  • 責任者: 👤担当-開発者、👥担当-テックリード、👑担当-PO、🤖担当-AI Agent
  • Severity: 🔥Sev.1-Critical ~ ⬇️Sev.5-Trivial
  • 影響度: 📊影響度-Critical/High/Medium/Low

5. agents/pr.md

内容: PRAgent - PR自動作成 所要時間: 15分

主要機能:

  • PR自動作成
  • 説明文生成 (AI生成)
  • Reviewer自動割り当て
  • CI/CDトリガー

使用例:

# PR自動作成
npm run agents:pr -- --issue=270

6. agents/deployment.md

内容: DeploymentAgent - CI/CD実行 所要時間: 20分

主要機能:

  • CI/CD実行
  • デプロイ (dev/staging/prod)
  • ヘルスチェック
  • Rollback

環境:

  • Development: 自動デプロイ
  • Staging: 承認後デプロイ
  • Production: 手動承認必須

CLI使用ガイド

7. cli-usage.md

内容: CLIコマンド実践例 所要時間: 30分

基本コマンド:

# 基本実行
npm run agents:parallel:exec -- --issues=270 --concurrency=2

# Task tool有効化
USE_TASK_TOOL=true npm run agents:exec -- --issue=270

# Worktree分離
USE_WORKTREE=true npm run agents:parallel:exec -- --issues=270,240

# デバッグモード
DEBUG=agents:* npm run agents:exec -- --issue=270

高度な使い方:

  • 並行度調整
  • タイムアウト設定
  • ログレベル制御
  • 環境変数設定

環境設定ガイド

8. github-token-setup.md

内容: GitHub Token設定 所要時間: 10分

必要なスコープ:

  • repo: リポジトリ全権限
  • workflow: GitHub Actions実行
  • project: Projects V2アクセス
  • packages: NPM Package公開

設定方法:

# 環境変数で設定
export GITHUB_TOKEN="ghp_your_token_here"

# .envファイルで設定
echo "GITHUB_TOKEN=ghp_your_token_here" > .env

9. npm-publication.md

内容: NPM公開手順 所要時間: 15分

公開手順:

  1. パッケージビルド
  2. テスト実行
  3. バージョンバンプ
  4. NPM公開
  5. GitHubリリース作成

10. termux-android.md

内容: Android Termux実行ガイド 所要時間: 20分

Termuxセットアップ:

# Node.js インストール
pkg install nodejs-lts

# Git インストール
pkg install git

# プロジェクトクローン
git clone https://github.com/ShunsukeHayashi/miyabi_doc.git

テストガイド

11. testing.md

内容: テスト戦略ガイド 所要時間: 30分

テスト種別:

  • Unit Test: 個別関数テスト
  • Integration Test: コンポーネント統合テスト
  • E2E Test: エンドツーエンドテスト
  • Agent Test: Agent動作テスト

実行方法:

# すべてのテスト実行
npm test

# Unit Testのみ
npm run test:unit

# Integration Testのみ
npm run test:integration

# E2E Testのみ
npm run test:e2e

Test Coverage目標: 80%以上 (現在92%)

トラブルシューティング

12. troubleshooting.md

内容: よくある問題と解決方法 所要時間: 20分

主要トピック:

  • 環境設定エラー
  • Agent実行エラー
  • GitHub API制限
  • 並行実行の問題
  • ログ解析方法

推奨読書順序

初めて実践する方 (所要時間: 2時間)

  1. cli-usage.md (30分)

    • まずCLIコマンドの使い方を理解

  2. agents/coordinator.md (20分)

    • CoordinatorAgentの動作を理解

  3. agents/codegen.md (20分)

    • CodeGenAgentでコード生成を体験

  4. testing.md (30分)

    • テストの実行方法を学ぶ

  5. troubleshooting.md (20分)

    • トラブル対処法を確認

特定のAgentを深く学びたい方

CoordinatorAgentに興味がある方:

  1. agents/coordinator.md
  2. ../02-architecture/parallel-execution.md
  3. ../06-reference/agent-operations-manual.md

CodeGenAgentに興味がある方:

  1. agents/codegen.md
  2. ../04-integration/claude-code-task-tool.md
  3. testing.md

ReviewAgentに興味がある方:

  1. agents/review.md
  2. testing.md
  3. ../02-architecture/organizational-principles.md

クイックリファレンス

よく使うコマンド

# 基本実行
npm run agents:exec -- --issue=270

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

# Task tool有効化
USE_TASK_TOOL=true npm run agents:exec -- --issue=270

# デバッグモード
DEBUG=agents:* npm run agents:exec -- --issue=270

# テスト実行
npm test

# ビルド
npm run build

# リント
npm run lint

環境変数

# GitHub Token
GITHUB_TOKEN=ghp_xxxxx

# Task Tool有効化
USE_TASK_TOOL=true

# Worktree有効化
USE_WORKTREE=true

# デバッグモード
DEBUG=agents:*

# ログレベル
LOG_LEVEL=debug

品質基準

スコア判定アクション
85点以上優秀自動マージ可能
80-84点良好承認推奨
70-79点要改善修正後再レビュー
70点未満不合格エスカレーション

よくある質問

Q1: どのAgentから学ぶべきですか?

A: CoordinatorAgentから始めることをおすすめします。

CoordinatorAgentは他のAgentを統括する役割を持つため、全体の流れを理解するのに最適です。

Q2: CLIコマンドが多すぎて覚えられません

A: cli-usage.md のクイックリファレンスをブックマークしてください。

よく使うコマンドは5-6個程度なので、実践しながら覚えていけば大丈夫です。

Q3: テストはすべて実行する必要がありますか?

A: 開発中はUnit Testのみで十分です。

  • 開発中: Unit Test (npm run test:unit)
  • PR作成前: すべてのテスト (npm test)
  • リリース前: E2Eテスト含むすべて

Q4: トラブルが発生したらどうすればいいですか?

A: 以下の順番で対処してください:

  1. troubleshooting.md を確認
  2. ログを確認 (DEBUG=agents:* で詳細ログ出力)
  3. GitHubのIssues で検索
  4. それでも解決しない場合は新しいIssueを作成

次のステップ

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

以下ができれば、実践ガイドをマスターしています:

  • 基本的なCLIコマンドを実行できる
  • 各Agentの役割と使い方を理解している
  • 並行実行を設定できる
  • テストを実行して結果を理解できる
  • トラブル時に自己解決できる

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

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

  1. Architecture - システムアーキテクチャ
  2. Reference - リファレンス

統合を実装したい方:

  1. Integration - 統合ガイド
  2. Phases - 実装フェーズ

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

  1. Community - コミュニティ

関連ドキュメント

前提知識

関連セクション

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

← ドキュメント一覧ホームへ →