🛠️ 開発・MCP コミュニティ

auto-claude-troubleshooting

Auto-Claudeのインストール問題、ビルド失敗、エージェントエラー、パフォーマンス問題などを解決するために、デバッグやトラブルシューティングを支援するSkill。

📜 元の英語説明(参考)

Auto-Claude debugging and troubleshooting guide. Use when fixing installation issues, debugging build failures, resolving agent errors, or diagnosing performance problems.

🇯🇵 日本人クリエイター向け解説

一言でいうと

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⚡ おすすめ: コマンド1行でインストール(60秒)

下記のコマンドをコピーしてターミナル(Mac/Linux)または PowerShell(Windows)に貼り付けてください。ダウンロード → 解凍 → 配置まで全自動。

🍎 Mac / 🐧 Linux

mkdir -p ~/.claude/skills && cd ~/.claude/skills && curl -L -o auto-claude-troubleshooting.zip https://jpskill.com/download/9362.zip && unzip -o auto-claude-troubleshooting.zip && rm auto-claude-troubleshooting.zip

🪟 Windows (PowerShell)

$d = "$env:USERPROFILE\.claude\skills"; ni -Force -ItemType Directory $d | Out-Null; iwr https://jpskill.com/download/9362.zip -OutFile "$d\auto-claude-troubleshooting.zip"; Expand-Archive "$d\auto-claude-troubleshooting.zip" -DestinationPath $d -Force; ri "$d\auto-claude-troubleshooting.zip"

完了後、Claude Code を再起動 → 普通に「動画プロンプト作って」のように話しかけるだけで自動発動します。

💾 手動でダウンロードしたい(コマンドが難しい人向け)

1. 下の青いボタンを押して auto-claude-troubleshooting.zip をダウンロード
2. ZIPファイルをダブルクリックで解凍 → auto-claude-troubleshooting フォルダができる
3. そのフォルダを C:\Users\あなたの名前\.claude\skills\(Win)または ~/.claude/skills/(Mac)へ移動
4. Claude Code を再起動

⬇ .zip でダウンロード(推奨) ⬇ .skill 形式(上級者用) 元のソース ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
- · macOS / Linux: ~/.claude/skills/
- · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →

最終更新: 2026-05-18
取得日時: 2026-05-18
同梱ファイル: 1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

Auto-Claude トラブルシューティング

Auto-Claude のあらゆる問題に対する包括的なデバッグガイドです。

クイック診断

システム要件の確認

# Python のバージョン (3.12 以上が必要)
python3 --version

# Node.js のバージョン (24 以上が必要)
node --version

# Claude Code CLI
claude --version

# Git
git --version

インストールの検証

cd apps/backend

# 仮想環境の確認
source .venv/bin/activate  # または .venv\Scripts\activate
python --version

# インポートのテスト
python -c "from core.client import create_client; print('OK')"

# 依存関係の確認
pip list | grep claude-agent-sdk

設定の確認

# 環境変数
cat .env | grep -v "^#" | grep -v "^$"

# OAuth トークン
echo $CLAUDE_CODE_OAUTH_TOKEN | head -c 20

# Claude Code のテスト
claude --version

よくある問題

インストールに関する問題

Python のバージョンの不一致

# 間違った Python のバージョン
$ python3 --version
Python 3.9.7  # 古すぎます！

# 修正: Python 3.12 以上をインストールする
# macOS
brew install python@3.12

# Ubuntu
sudo apt install python3.12 python3.12-venv

# Windows
winget install Python.Python.3.12

# 正しいバージョンで venv を作成する
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

node-gyp エラー (Windows)

# エラー: node-gyp rebuild failed

# 修正: Visual Studio Build Tools をインストールする
# 1. https://visualstudio.microsoft.com/visual-cpp-build-tools/ からダウンロード
# 2. 「C++ によるデスクトップ開発」を選択
# 3. ターミナルを再起動
npm install

許可が拒否されました

# エラー: Permission denied

# 修正: sudo を使用するか、所有者を変更する
sudo npm install -g @anthropic-ai/claude-code

# または npm の権限を修正する
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

認証に関する問題

OAuth トークンが無効

# エラー: Invalid OAuth token

# 修正: トークンを再生成する
claude setup-token

# .env に追加する
echo "CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token --output)" >> apps/backend/.env

トークンが見つかりません

# エラー: CLAUDE_CODE_OAUTH_TOKEN が設定されていません

# 設定されているか確認する
echo $CLAUDE_CODE_OAUTH_TOKEN

# 手動で設定する
export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"

# または .env に追加する
echo "CLAUDE_CODE_OAUTH_TOKEN=your-token-here" >> apps/backend/.env

サブスクリプションに関する問題

# エラー: Claude Pro/Max サブスクリプションが必要です

# 修正: https://claude.ai/upgrade でサブスクリプションを確認する
# 有効な Pro または Max サブスクリプションが必要です

ビルドの失敗

Spec が見つかりません

# エラー: Spec 001 が見つかりません

# 利用可能な spec を一覧表示する
python run.py --list

# spec ディレクトリを確認する
ls -la .auto-claude/specs/

# 最初に spec を作成する
python spec_runner.py --interactive

エージェントのタイムアウト

# エラー: Agent timed out

# タイムアウトを増やす
API_TIMEOUT_MS=600000 python run.py --spec 001

# または .env に追加する
echo "API_TIMEOUT_MS=600000" >> .env

ビルドが停止しました

# ビルドが停止しているようです

# 進捗状況を確認する
tail -f .auto-claude/specs/001-feature/build-progress.txt

# PAUSE ファイルを確認する
ls -la .auto-claude/specs/001-feature/PAUSE

# ポーズを削除する
rm .auto-claude/specs/001-feature/PAUSE

# 停止を解除するために人間の入力を追加する
echo "Please proceed with the next subtask" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

セキュリティフックの拒否

# エラー: Command not allowed

# セキュリティログを確認する
cat .auto-claude-security.json

# security.py の許可リストにコマンドを追加する
# またはサンドボックスなしで実行する (推奨されません)

ワークスペースに関する問題

ワークツリーが既に存在します

# エラー: Worktree already exists

# 既存のワークツリーを削除する
git worktree remove .worktrees/auto-claude/001-feature

# または強制的に削除する
git worktree remove --force .worktrees/auto-claude/001-feature
git worktree prune

ブランチが既に存在します

# エラー: Branch auto-claude/001-feature already exists

# 既存のブランチを削除する
git branch -D auto-claude/001-feature

# その後、再試行する
python run.py --spec 001

マージコンフリクト

# エラー: Merge conflicts detected

# 手動で解決する
cd .worktrees/auto-claude/001-feature/
git merge main --no-commit
git status

# エディタでコンフリクトを解決する
code path/to/conflicted/file

# マージを完了する
git add .
git commit -m "Resolved conflicts"
cd ../../apps/backend

メモリシステムに関する問題

Graphiti が動作しない

# エラー: Graphiti initialization failed

# 有効になっているか確認する
grep GRAPHITI apps/backend/.env

# プロバイダーの認証情報を確認する
# OpenAI の場合
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

# Ollama の場合
curl http://localhost:11434/api/tags

埋め込み次元の不一致

# エラー: Embedding dimension mismatch

# 埋め込みをクリアして再インデックスする
rm -rf ~/.auto-claude/memories/embeddings
python run.py --spec 001

データベースの破損

# エラー: Database corrupted

# バックアップしてリセットする
mv ~/.auto-claude/memories ~/.auto-claude/memories.backup
python query_memory.py --search "test"  # 新しい DB を作成します

QA に関する問題

QA ループが完了しない

# QA が拒否し続ける

# QA レポートを確認する
cat .auto-claude/specs/001-feature/qa_report.md

# 一時的に QA をスキップする
python run.py --spec 001 --skip-qa

# またはイテレーションを制限する
MAX_QA_ITERATIONS=5 python run.py --spec 001 --qa

QA Fixer が修正しない

# QA Fixer が問題を修正できない

# 修正リクエストを確認する
cat .auto-claude/specs/001-feature/QA_FIX_REQUEST.md

# 人間のガイダンスを追加する
echo "Focus on fixing the session storage issue first" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

デバッグモード

詳細ログを有効にする

# レベル 1: 基本
DEBUG=true DEBUG_LEVEL=1 python run.py --spec 001

# レベル 2: 詳細
DEBUG=true DEBUG_LEVEL=2 python run.py --spec 001

# レベル 3: 詳細 (すべて)
DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

ファイルにログを記録する

# ファイルにログを記録する
DEBUG=true DEBUG_LOG_FILE=debug.log python run.py --spec 001

# リアルタイムで表示する
tail -f debug.log

エージェント通信

(原文がここで切り詰められています)

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

Auto-Claude Troubleshooting

Comprehensive debugging guide for all Auto-Claude issues.

Quick Diagnostics

Check System Requirements

# Python version (need 3.12+)
python3 --version

# Node.js version (need 24+)
node --version

# Claude Code CLI
claude --version

# Git
git --version

Verify Installation

cd apps/backend

# Check virtual environment
source .venv/bin/activate  # or .venv\Scripts\activate
python --version

# Test import
python -c "from core.client import create_client; print('OK')"

# Check dependencies
pip list | grep claude-agent-sdk

Check Configuration

# Environment variables
cat .env | grep -v "^#" | grep -v "^$"

# OAuth token
echo $CLAUDE_CODE_OAUTH_TOKEN | head -c 20

# Test Claude Code
claude --version

Common Issues

Installation Problems

Python Version Mismatch

# Wrong Python version
$ python3 --version
Python 3.9.7  # Too old!

# Fix: Install Python 3.12+
# macOS
brew install python@3.12

# Ubuntu
sudo apt install python3.12 python3.12-venv

# Windows
winget install Python.Python.3.12

# Create venv with correct version
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

node-gyp Errors (Windows)

# Error: node-gyp rebuild failed

# Fix: Install Visual Studio Build Tools
# 1. Download from https://visualstudio.microsoft.com/visual-cpp-build-tools/
# 2. Select "Desktop development with C++"
# 3. Restart terminal
npm install

Permission Denied

# Error: Permission denied

# Fix: Use sudo or change ownership
sudo npm install -g @anthropic-ai/claude-code

# Or fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Authentication Issues

OAuth Token Invalid

# Error: Invalid OAuth token

# Fix: Re-generate token
claude setup-token

# Add to .env
echo "CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token --output)" >> apps/backend/.env

Token Not Found

# Error: CLAUDE_CODE_OAUTH_TOKEN not set

# Check if set
echo $CLAUDE_CODE_OAUTH_TOKEN

# Set manually
export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"

# Or add to .env
echo "CLAUDE_CODE_OAUTH_TOKEN=your-token-here" >> apps/backend/.env

Subscription Issues

# Error: Claude Pro/Max subscription required

# Fix: Verify subscription at https://claude.ai/upgrade
# Must have active Pro or Max subscription

Build Failures

Spec Not Found

# Error: Spec 001 not found

# List available specs
python run.py --list

# Check spec directory
ls -la .auto-claude/specs/

# Create spec first
python spec_runner.py --interactive

Agent Timeout

# Error: Agent timed out

# Increase timeout
API_TIMEOUT_MS=600000 python run.py --spec 001

# Or add to .env
echo "API_TIMEOUT_MS=600000" >> .env

Build Stuck

# Build appears stuck

# Check progress
tail -f .auto-claude/specs/001-feature/build-progress.txt

# Check for PAUSE file
ls -la .auto-claude/specs/001-feature/PAUSE

# Remove pause
rm .auto-claude/specs/001-feature/PAUSE

# Add human input to unstick
echo "Please proceed with the next subtask" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

Security Hook Rejection

# Error: Command not allowed

# Check security log
cat .auto-claude-security.json

# Add command to allowlist in security.py
# Or run without sandbox (not recommended)

Workspace Issues

Worktree Already Exists

# Error: Worktree already exists

# Remove existing worktree
git worktree remove .worktrees/auto-claude/001-feature

# Or force remove
git worktree remove --force .worktrees/auto-claude/001-feature
git worktree prune

Branch Already Exists

# Error: Branch auto-claude/001-feature already exists

# Delete existing branch
git branch -D auto-claude/001-feature

# Then retry
python run.py --spec 001

Merge Conflicts

# Error: Merge conflicts detected

# Manual resolution
cd .worktrees/auto-claude/001-feature/
git merge main --no-commit
git status

# Resolve conflicts in editor
code path/to/conflicted/file

# Complete merge
git add .
git commit -m "Resolved conflicts"
cd ../../apps/backend

Memory System Issues

Graphiti Not Working

# Error: Graphiti initialization failed

# Check if enabled
grep GRAPHITI apps/backend/.env

# Verify provider credentials
# For OpenAI
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

# For Ollama
curl http://localhost:11434/api/tags

Embedding Dimension Mismatch

# Error: Embedding dimension mismatch

# Clear embeddings and re-index
rm -rf ~/.auto-claude/memories/embeddings
python run.py --spec 001

Database Corruption

# Error: Database corrupted

# Backup and reset
mv ~/.auto-claude/memories ~/.auto-claude/memories.backup
python query_memory.py --search "test"  # Creates fresh DB

QA Issues

QA Loop Never Completes

# QA keeps rejecting

# Check QA report
cat .auto-claude/specs/001-feature/qa_report.md

# Skip QA temporarily
python run.py --spec 001 --skip-qa

# Or limit iterations
MAX_QA_ITERATIONS=5 python run.py --spec 001 --qa

QA Fixer Not Fixing

# QA Fixer fails to fix issues

# Check fix request
cat .auto-claude/specs/001-feature/QA_FIX_REQUEST.md

# Add human guidance
echo "Focus on fixing the session storage issue first" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

Debug Mode

Enable Verbose Logging

# Level 1: Basic
DEBUG=true DEBUG_LEVEL=1 python run.py --spec 001

# Level 2: Detailed
DEBUG=true DEBUG_LEVEL=2 python run.py --spec 001

# Level 3: Verbose (everything)
DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

Log to File

# Log to file
DEBUG=true DEBUG_LOG_FILE=debug.log python run.py --spec 001

# View in real-time
tail -f debug.log

Agent Communication

# See agent messages
DEBUG=true python run.py --spec 001 2>&1 | tee agent.log

# Search for errors
grep -i error agent.log
grep -i failed agent.log

Recovery Procedures

Restart Clean

# Full reset for a spec
rm -rf .auto-claude/specs/001-feature
rm -rf .worktrees/auto-claude/001-feature
git branch -D auto-claude/001-feature 2>/dev/null
git worktree prune

# Recreate spec
python spec_runner.py --task "Your task description"

Resume from Checkpoint

# Continue interrupted spec
python spec_runner.py --continue 001-feature

# Continue interrupted build
python run.py --spec 001

Manual Intervention

# 1. Pause the build
touch .auto-claude/specs/001-feature/PAUSE

# 2. Make manual changes in worktree
cd .worktrees/auto-claude/001-feature/
# ... edit files ...
git add .
git commit -m "Manual fix"

# 3. Resume
cd ../../apps/backend
rm .auto-claude/specs/001-feature/PAUSE
python run.py --spec 001

Performance Issues

Slow Builds

# Use faster model
AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929 python run.py --spec 001

# Reduce thinking tokens
# Edit agent creation to use max_thinking_tokens=3000

# Skip research phase
SKIP_RESEARCH_PHASE=true python spec_runner.py --task "..."

High Memory Usage

# Monitor memory
watch -n 1 'ps aux | grep python'

# Reduce context
MAX_CONTEXT_FILES=30 python run.py --spec 001

# Use smaller embedding model
OLLAMA_EMBEDDING_MODEL=all-minilm
OLLAMA_EMBEDDING_DIM=384

API Rate Limits

# Error: Rate limit exceeded

# Wait and retry
sleep 60
python run.py --spec 001

# Or use different endpoint
ANTHROPIC_BASE_URL=http://localhost:3456 python run.py --spec 001

Getting Help

Gather Diagnostics

# System info
echo "Python: $(python3 --version)"
echo "Node: $(node --version)"
echo "Git: $(git --version)"
echo "Claude: $(claude --version)"

# Auto-Claude version
cat package.json | grep '"version"'

# Last 50 lines of logs
tail -50 .auto-claude/specs/*/build-progress.txt

Community Resources

Discord: https://discord.gg/KCXaPBr4Dj
GitHub Issues: https://github.com/AndyMik90/Auto-Claude/issues
Discussions: https://github.com/AndyMik90/Auto-Claude/discussions

Report a Bug

Include:

Operating system and version
Python and Node.js versions
Auto-Claude version
Steps to reproduce
Error messages
Relevant logs

Related Skills

auto-claude-setup: Installation guide
auto-claude-cli: CLI reference
auto-claude-optimization: Performance tuning