セットアップガイド - Autonomous-Operations詳細設定

概要: Autonomous-Operationsを本格的に使用するための詳細なセットアップ手順と環境設定方法を説明します。

対象読者: Autonomous-Operationsを実環境で使用する開発者 所要時間: 15-30分 前提知識: クイックスタートを完了していること

セットアップの概要

Autonomous-Operationsを使用するには、以下のコンポーネントが必要です:

必須コンポーネント:
  ランタイム:
    - Node.js v20以上
    - Git v2.40以上
  ツール:
    - GitHub CLI (gh)
    - TypeScript/tsx
  認証:
    - GitHub Personal Access Token
    - Anthropic API Key (AI機能用)
  オプション:
    - Docker (コンテナ実行用)
    - tmux (並行実行モニタリング用)

必須ツールのインストール

1. Node.js のインストール

推奨バージョン: v20 LTS以上

macOS

# Homebrewを使用
brew install node@20

# バージョン確認
node -v  # v20.x.x
npm -v   # 10.x.x

Linux (Ubuntu/Debian)

# NodeSourceリポジトリを追加
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# インストール
sudo apt-get install -y nodejs

# バージョン確認
node -v
npm -v

Windows

# Chocolateyを使用
choco install nodejs-lts

# または公式インストーラーをダウンロード
# https://nodejs.org/

2. Git のインストール

推奨バージョン: v2.40以上

macOS

# Homebrewを使用
brew install git

# バージョン確認
git --version  # git version 2.40.x

Linux

# Ubuntu/Debian
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

# バージョン確認
git --version

Windows

# Chocolateyを使用
choco install git

# または公式インストーラーをダウンロード
# https://git-scm.com/

3. GitHub CLI のインストール

推奨バージョン: v2.40以上

macOS

brew install gh

# バージョン確認
gh --version  # gh version 2.40.x

Linux

# Ubuntu/Debian
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Windows

choco install gh

4. TypeScript/tsx のインストール

# グローバルインストール
npm install -g typescript tsx

# バージョン確認
tsc --version  # Version 5.x.x
tsx --version  # tsx 4.x.x

GitHub Personal Access Tokenの作成

Autonomous-OperationsはGitHub APIを使用するため、適切な権限を持つPersonal Access Token (PAT)が必要です。

必須スコープ

以下のスコープが必須です:

スコープ	用途	必須度
`repo`	リポジトリへのフルアクセス (Issue、PR、コード)	✅ 必須
`workflow`	GitHub Actionsワークフローの管理	✅ 必須
`read:project`	GitHub Projects V2の読み取り	✅ 必須
`write:project`	GitHub Projects V2への書き込み	✅ 必須
`notifications`	通知へのアクセス	🔶 推奨
`read:org`	Organization情報の読み取り	🔶 推奨

Classic Personal Access Tokenの作成手順

ステップ1: GitHubの設定ページにアクセス

https://github.com/settings/tokens にアクセス
「Generate new token」→「Generate new token (classic)」をクリック

ステップ2: Tokenの設定

設定項目:
  Note: "Autonomous Operations"
  Expiration: 90 days (推奨)
  Select scopes:
    - ✅ repo (全て選択)
    - ✅ workflow
    - ✅ read:project
    - ✅ write:project
    - ✅ notifications (推奨)
    - ✅ read:org (Organization使用時)

ステップ3: Token生成とコピー

「Generate token」をクリック
生成されたTokenをコピー（ghp_で始まる文字列）
⚠️ 重要: このページを離れると再表示できないため、必ず安全な場所に保存

Fine-grained Personal Access Token (推奨)

より細かい権限管理が可能なFine-grained PATの使用を推奨します:

ステップ1: Fine-grained Token作成ページにアクセス

https://github.com/settings/tokens?type=beta にアクセス

ステップ2: Token詳細の設定

Token名: Autonomous Operations
有効期限: 90 days
Repository access: 特定のリポジトリを選択

Repository permissions:
  Contents: Read and write
  Issues: Read and write
  Pull requests: Read and write
  Workflows: Read and write
  Metadata: Read-only (自動選択)

Organization permissions:
  Projects: Read and write

ステップ3: Token生成

「Generate token」をクリック
生成されたTokenをコピー（github_pat_で始まる文字列）
安全な場所に保存

環境変数の設定

オプションA: .envファイルを使用（推奨）

プロジェクトルートに.envファイルを作成します:

# プロジェクトディレクトリに移動
cd /path/to/your/project

# .envファイルを作成
cat > .env << 'EOF'
# GitHub Personal Access Token
GITHUB_TOKEN=ghp_your_token_here

# Anthropic API Key (AI機能用)
ANTHROPIC_API_KEY=sk-ant-your_key_here

# デバイス識別子 (複数環境で実行する場合)
DEVICE_IDENTIFIER="MacBook Pro 16-inch"

# Task Tool統合 (推奨)
USE_TASK_TOOL=true

# Git Worktree使用 (並行実行時)
USE_WORKTREE=true

# デバッグモード (オプション)
DEBUG=agents:*
EOF

# .envファイルのパーミッションを制限
chmod 600 .env

.gitignoreへの追加確認

.envファイルがGitにコミットされないよう確認:

# .gitignoreを確認
grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore

# 確認
cat .gitignore | grep "\.env"

オプションB: シェルの環境変数として設定

macOS/Linux (bash)

# ~/.bashrc または ~/.bash_profile に追加
cat >> ~/.bashrc << 'EOF'

# Autonomous Operations
export GITHUB_TOKEN=ghp_your_token_here
export ANTHROPIC_API_KEY=sk-ant-your_key_here
export DEVICE_IDENTIFIER="MacBook Pro 16-inch"
export USE_TASK_TOOL=true
export USE_WORKTREE=true
EOF

# 設定を反映
source ~/.bashrc

macOS/Linux (zsh)

# ~/.zshrc に追加
cat >> ~/.zshrc << 'EOF'

# Autonomous Operations
export GITHUB_TOKEN=ghp_your_token_here
export ANTHROPIC_API_KEY=sk-ant-your_key_here
export DEVICE_IDENTIFIER="MacBook Pro 16-inch"
export USE_TASK_TOOL=true
export USE_WORKTREE=true
EOF

# 設定を反映
source ~/.zshrc

Windows (PowerShell)

# 現在のセッションのみ
$env:GITHUB_TOKEN="ghp_your_token_here"
$env:ANTHROPIC_API_KEY="sk-ant-your_key_here"
$env:DEVICE_IDENTIFIER="Windows Desktop"

# 永続的に設定（システム環境変数）
[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token_here", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your_key_here", "User")

環境変数の確認

# .envファイルを読み込み (bash/zsh)
set -a && source .env && set +a

# 環境変数を確認
echo $GITHUB_TOKEN | head -c 10
# 出力: ghp_xxxxx

echo $ANTHROPIC_API_KEY | head -c 10
# 出力: sk-ant-xxx

リポジトリのセットアップ

新規プロジェクトの場合

# プロジェクト作成（自動セットアップ）
npx agentic-os init my-autonomous-project

# プロジェクトディレクトリに移動
cd my-autonomous-project

# 依存関係が正しくインストールされたか確認
npm list

既存プロジェクトに統合する場合

# リポジトリをクローン
git clone https://github.com/your-username/your-project.git
cd your-project

# Autonomous-Operationsをインストール
npm install --save-dev agentic-os

# セットアップスクリプトを実行
npx agentic-os setup

# ラベルを作成
npx agentic-os labels:sync

# ワークフローを配置
npx agentic-os workflows:deploy

# GitHub Projectsを作成
npx agentic-os project:create

ディレクトリ構造の確認

セットアップ後、以下の構造になります:

your-project/
├── .ai/                          # AI関連ファイル
│   ├── logs/                     # LDDログ
│   ├── parallel-reports/         # 並行実行レポート
│   └── issues/                   # Issue同期
├── .github/
│   ├── workflows/                # GitHub Actions
│   │   ├── autonomous-agent.yml  # 自動エージェント実行
│   │   ├── issue-labeler.yml     # Issue自動ラベリング
│   │   └── pr-automation.yml     # PR自動化
│   ├── labels.yml                # ラベル定義 (53個)
│   └── CODEOWNERS                # 責任者自動割り当て
├── scripts/                      # 自動化スクリプト
│   ├── parallel-executor.ts      # 並行実行
│   └── task-wrapper.ts           # Task tool統合
├── .env                          # 環境変数 (.gitignoreに含める)
├── package.json
└── README.md

Anthropic API Keyの設定

AI機能を使用するには、Anthropic API Keyが必要です。

ステップ1: Anthropicアカウントの作成

https://console.anthropic.com/ にアクセス
アカウントを作成（GitHubアカウントでログイン可能）

ステップ2: API Keyの作成

https://console.anthropic.com/settings/keys にアクセス
「Create Key」をクリック
Key名を入力（例: "Autonomous Operations"）
生成されたKeyをコピー（sk-ant-で始まる文字列）

ステップ3: 環境変数に設定

# .envファイルに追加
echo "ANTHROPIC_API_KEY=sk-ant-your_key_here" >> .env

# または直接エクスポート
export ANTHROPIC_API_KEY=sk-ant-your_key_here

使用量の確認

# APIの使用状況を確認
curl https://api.anthropic.com/v1/usage \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

コスト管理

料金体系 (2025年10月時点):
  Claude 3.5 Sonnet:
    Input: $3.00 / 1M tokens
    Output: $15.00 / 1M tokens

推定コスト:
  小規模タスク (1 Issue):
    - 約10,000 tokens
    - コスト: $0.10-0.30

  中規模タスク (複雑な機能):
    - 約50,000 tokens
    - コスト: $0.50-1.50

  並行実行 (3 Issues同時):
    - 約30,000 tokens
    - コスト: $0.30-0.90

動作確認

1. GitHub CLI認証の確認

# 認証状態を確認
gh auth status

# 出力例:
# github.com
#   ✓ Logged in to github.com as your-username (oauth_token)
#   ✓ Git operations for github.com configured to use https protocol.
#   ✓ Token: ghp_************************************

2. 環境変数の確認

# スクリプトで確認
cat > check-env.sh << 'EOF'
#!/bin/bash

echo "🔍 環境変数チェック"
echo "===================="

# GITHUB_TOKEN
if [ -n "$GITHUB_TOKEN" ]; then
  echo "✅ GITHUB_TOKEN: 設定済み (${GITHUB_TOKEN:0:10}...)"
else
  echo "❌ GITHUB_TOKEN: 未設定"
fi

# ANTHROPIC_API_KEY
if [ -n "$ANTHROPIC_API_KEY" ]; then
  echo "✅ ANTHROPIC_API_KEY: 設定済み (${ANTHROPIC_API_KEY:0:10}...)"
else
  echo "❌ ANTHROPIC_API_KEY: 未設定"
fi

# DEVICE_IDENTIFIER
if [ -n "$DEVICE_IDENTIFIER" ]; then
  echo "✅ DEVICE_IDENTIFIER: $DEVICE_IDENTIFIER"
else
  echo "⚠️  DEVICE_IDENTIFIER: 未設定 (オプション)"
fi

echo ""
echo "🛠️ ツールバージョン"
echo "===================="
echo "Node.js: $(node -v)"
echo "npm: $(npm -v)"
echo "Git: $(git --version | awk '{print $3}')"
echo "GitHub CLI: $(gh --version | head -n1 | awk '{print $3}')"
EOF

chmod +x check-env.sh
./check-env.sh

3. プロジェクト情報の取得テスト

# GitHub Projects V2の情報を取得
npm run project:info

# 期待される出力:
# 📊 Project Information
# =====================
# Project ID: PVT_kwDOABCD1234
# Title: Autonomous Operations
# Fields: 8
#   - Status
#   - Priority
#   - Agent
#   - Quality Score
#   - Duration
#   ...

4. 簡単なタスクで動作確認

# テスト用Issueを作成
gh issue create \
  --title "Test: Setup verification" \
  --body "This is a test issue to verify Autonomous Operations setup"

# Issue番号を確認（例: #1）
gh issue list

# エージェント実行テスト
npm run agents:parallel:exec -- --issues=1 --concurrency=1

# 実行ログを確認
cat .ai/logs/$(date +%Y-%m-%d).md

トラブルシューティング

エラー: "Your token has not been granted the required scopes"

原因: GitHub Tokenに必要なスコープが不足しています。

解決方法:

https://github.com/settings/tokens にアクセス
該当するTokenを選択
スコープを確認・追加:
- ✅ repo (全て)
- ✅ workflow
- ✅ read:project
- ✅ write:project
Tokenを再生成
.envファイルを更新

# .envファイルを編集
nano .env

# GITHUB_TOKENを新しい値に更新
GITHUB_TOKEN=ghp_new_token_here

# 環境変数を再読み込み
set -a && source .env && set +a

エラー: "GITHUB_TOKEN not set"

原因: 環境変数が設定されていません。

解決方法:

# .envファイルが存在するか確認
ls -la .env

# .envファイルを読み込み
set -a && source .env && set +a

# 確認
echo $GITHUB_TOKEN | head -c 10

# または直接設定
export GITHUB_TOKEN=ghp_your_token_here

エラー: "gh CLI authentication failed"

原因: GitHub CLIの認証が完了していません。

解決方法:

# 再認証
gh auth login

# プロンプトに従って選択:
# ? What account do you want to log into? → GitHub.com
# ? What is your preferred protocol for Git operations? → HTTPS
# ? Authenticate Git with your GitHub credentials? → Yes
# ? How would you like to authenticate GitHub CLI? → Login with a web browser

# 認証確認
gh auth status

gh CLI認証と環境変数が異なる

gh CLIは独自の認証を管理しており、GITHUB_TOKEN環境変数とは別です。

両方を設定:

# gh CLIで認証
gh auth login

# gh CLIのTokenを環境変数に設定
export GITHUB_TOKEN=$(gh auth token)

# .envファイルにも保存
echo "GITHUB_TOKEN=$(gh auth token)" >> .env

Anthropic API エラー

原因: API Keyが無効、または使用制限に達しています。

解決方法:

# API Keyをテスト
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

# 使用量を確認
# https://console.anthropic.com/settings/usage

Worktree競合エラー

原因: 既存のworktreeが残っています。

解決方法:

# 既存のworktreeを確認
git worktree list

# 不要なworktreeを削除
git worktree remove .worktrees/task-001

# または全て削除
git worktree prune

# worktreeディレクトリをクリーンアップ
rm -rf .worktrees/*

セキュリティのベストプラクティス

✅ すべきこと

Tokenを安全に保管

# .envファイルのパーミッションを制限
chmod 600 .env

# .gitignoreに追加
echo ".env" >> .gitignore

Tokenを定期的に再生成
- 推奨: 90日ごと
- カレンダーにリマインダーを設定
必要最小限のスコープのみ付与
- Fine-grained Tokenを使用
- 特定のリポジトリのみに権限を付与

Organization の場合はSSO有効化

# TokenがSSO対応しているか確認
gh api user/repos
# エラーが出る場合はSSO認証が必要

❌ してはいけないこと

Tokenをコードに直接記述しない

// ❌ 悪い例
const token = "ghp_abc123...";

// ✅ 良い例
const token = process.env.GITHUB_TOKEN;

Tokenを公開リポジトリにコミットしない

# コミット前に確認
git diff --cached | grep -i "ghp_\|sk-ant-"

Tokenを共有しない
- チームメンバーも各自のTokenを作成
不要なスコープを付与しない
- admin:org、delete_repoなどは不要
Tokenを平文でメッセージに含めない
- Slack、Discord、メールなどで共有しない

次のステップ

1. 基本コンセプトを学ぶ

基本コンセプトでAutonomous-Operationsの仕組みを理解:

Agent階層システム
GitHub as OS
Log-Driven Development

2. 実践的な使い方を学ぶ

CLI使用ガイドで高度なコマンドを習得:

並行実行
デバッグ方法
パフォーマンス最適化

3. アーキテクチャを理解する

システムアーキテクチャで内部構造を学習:

エージェントの動作原理
並行実行アーキテクチャ
品質保証プロセス

サポート

問題が解決しない場合は、Issueを作成してください:

gh issue create \
  --title "[Setup] セットアップに関する問題" \
  --label "📚documentation,❓question" \
  --body "## 問題の詳細

環境:
- OS:
- Node.js:
- Git:
- GitHub CLI:

エラーメッセージ:
\`\`\`
(エラーメッセージをここに貼り付け)
\`\`\`

試したこと:
-
"

または、GitHubリポジトリのDiscussionsで質問: https://github.com/ShunsukeHayashi/Autonomous-Operations/discussions

ドキュメントバージョン: 1.0.0 最終更新: 2025-10-10 メンテナー: Autonomous-Operations Team

🤖 このドキュメントはAutonomous-Operationsプロジェクトの一部です

セットアップガイド - Autonomous-Operations詳細設定

セットアップガイド - Autonomous-Operations詳細設定

目次

セットアップの概要

必須ツールのインストール

1. Node.js のインストール

macOS

Linux (Ubuntu/Debian)

Windows

2. Git のインストール

macOS

Linux

Windows

3. GitHub CLI のインストール

macOS

Linux

Windows

4. TypeScript/tsx のインストール

GitHub Personal Access Tokenの作成

必須スコープ

Classic Personal Access Tokenの作成手順

ステップ1: GitHubの設定ページにアクセス

ステップ2: Tokenの設定

ステップ3: Token生成とコピー

Fine-grained Personal Access Token (推奨)

ステップ1: Fine-grained Token作成ページにアクセス

ステップ2: Token詳細の設定

ステップ3: Token生成

環境変数の設定

オプションA: .envファイルを使用（推奨）

.gitignoreへの追加確認

オプションB: シェルの環境変数として設定

macOS/Linux (bash)

macOS/Linux (zsh)

Windows (PowerShell)

環境変数の確認

リポジトリのセットアップ

新規プロジェクトの場合

既存プロジェクトに統合する場合

ディレクトリ構造の確認

Anthropic API Keyの設定

ステップ1: Anthropicアカウントの作成

ステップ2: API Keyの作成

ステップ3: 環境変数に設定

使用量の確認

コスト管理

動作確認

1. GitHub CLI認証の確認

2. 環境変数の確認

3. プロジェクト情報の取得テスト

4. 簡単なタスクで動作確認

トラブルシューティング

エラー: "Your token has not been granted the required scopes"

エラー: "GITHUB_TOKEN not set"

エラー: "gh CLI authentication failed"

gh CLI認証と環境変数が異なる

Anthropic API エラー

Worktree競合エラー

セキュリティのベストプラクティス

✅ すべきこと

❌ してはいけないこと

関連ドキュメント

次のステップ

1. 基本コンセプトを学ぶ

2. 実践的な使い方を学ぶ

3. アーキテクチャを理解する

サポート