mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-05-18 23:03:06 +08:00
434 lines
12 KiB
Markdown
434 lines
12 KiB
Markdown
# トラブルシューティングガイド
|
||
|
||
Everything Claude Code (ECC) プラグインの一般的な問題と解決策。
|
||
|
||
## 目次
|
||
|
||
- [メモリとコンテキストの問題](#メモリとコンテキストの問題)
|
||
- [エージェントハーネスの障害](#エージェントハーネスの障害)
|
||
- [フックとワークフローのエラー](#フックとワークフローのエラー)
|
||
- [インストールとセットアップ](#インストールとセットアップ)
|
||
- [パフォーマンスの問題](#パフォーマンスの問題)
|
||
- [一般的なエラーメッセージ](#一般的なエラーメッセージ)
|
||
- [ヘルプを得る](#ヘルプを得る)
|
||
|
||
---
|
||
|
||
## メモリとコンテキストの問題
|
||
|
||
### コンテキストウィンドウのオーバーフロー
|
||
|
||
**症状：** 「Context too long」エラーまたは不完全なレスポンス
|
||
|
||
**原因：**
|
||
- トークン制限を超える大きなファイルのアップロード
|
||
- 蓄積された会話履歴
|
||
- 単一セッション内の複数の大きなツール出力
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 1. 会話履歴をクリアして新しく開始
|
||
# Claude Code: 「New Chat」または Cmd/Ctrl+Shift+N
|
||
|
||
# 2. 分析前にファイルサイズを縮小
|
||
head -n 100 large-file.log > sample.log
|
||
|
||
# 3. 大きな出力にはストリーミングを使用
|
||
head -n 50 large-file.txt
|
||
|
||
# 4. タスクを小さなチャンクに分割
|
||
# 代わりに: 「50ファイルすべてを分析して」
|
||
# 使用: 「src/components/ ディレクトリのファイルを分析して」
|
||
```
|
||
|
||
### メモリ永続化の失敗
|
||
|
||
**症状：** エージェントが以前のコンテキストや観測を覚えていない
|
||
|
||
**原因：**
|
||
- 継続学習フックが無効化されている
|
||
- 観測ファイルが破損している
|
||
- プロジェクト検出の失敗
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 観測が記録されているか確認
|
||
ls ~/.claude/homunculus/projects/*/observations.jsonl
|
||
|
||
# 現在のプロジェクトのハッシュIDを検索
|
||
python3 - <<'PY'
|
||
import json, os
|
||
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
|
||
with open(registry_path) as f:
|
||
registry = json.load(f)
|
||
for project_id, meta in registry.items():
|
||
if meta.get("root") == os.getcwd():
|
||
print(project_id)
|
||
break
|
||
else:
|
||
raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
|
||
PY
|
||
|
||
# そのプロジェクトの最近の観測を表示
|
||
tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
|
||
|
||
# 破損した観測ファイルを再作成前にバックアップ
|
||
mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
|
||
~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)
|
||
|
||
# フックが有効か確認
|
||
grep -r "observe" ~/.claude/settings.json
|
||
```
|
||
|
||
---
|
||
|
||
## エージェントハーネスの障害
|
||
|
||
### エージェントが見つからない
|
||
|
||
**症状：** 「Agent not loaded」または「Unknown agent」エラー
|
||
|
||
**原因：**
|
||
- プラグインが正しくインストールされていない
|
||
- エージェントパスの設定ミス
|
||
- Marketplaceと手動インストールの不一致
|
||
|
||
**解決策：**
|
||
```bash
|
||
# プラグインのインストールを確認
|
||
ls ~/.claude/plugins/cache/
|
||
|
||
# エージェントの存在を確認（Marketplaceインストール）
|
||
ls ~/.claude/plugins/cache/*/agents/
|
||
|
||
# 手動インストールの場合、エージェントは以下に配置:
|
||
ls ~/.claude/agents/ # カスタムエージェントのみ
|
||
|
||
# プラグインをリロード
|
||
# Claude Code → Settings → Extensions → Reload
|
||
```
|
||
|
||
### ワークフロー実行のハング
|
||
|
||
**症状：** エージェントが開始するが完了しない
|
||
|
||
**原因：**
|
||
- エージェントロジック内の無限ループ
|
||
- ユーザー入力でブロックされている
|
||
- API待ちのネットワークタイムアウト
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 1. スタックしたプロセスを確認
|
||
ps aux | grep claude
|
||
|
||
# 2. デバッグモードを有効化
|
||
export CLAUDE_DEBUG=1
|
||
|
||
# 3. より短いタイムアウトを設定
|
||
export CLAUDE_TIMEOUT=30
|
||
|
||
# 4. ネットワーク接続を確認
|
||
curl -I https://api.anthropic.com
|
||
```
|
||
|
||
### ツール使用エラー
|
||
|
||
**症状：** 「Tool execution failed」またはパーミッション拒否
|
||
|
||
**原因：**
|
||
- 必要な依存関係の不足（npm、python等）
|
||
- ファイルパーミッションの不足
|
||
- パスが見つからない
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 必要なツールがインストールされているか確認
|
||
which node python3 npm git
|
||
|
||
# フックスクリプトのパーミッションを修正
|
||
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
|
||
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
|
||
|
||
# PATHに必要なバイナリが含まれているか確認
|
||
echo $PATH
|
||
```
|
||
|
||
---
|
||
|
||
## フックとワークフローのエラー
|
||
|
||
### フックが発火しない
|
||
|
||
**症状：** Pre/Postフックが実行されない
|
||
|
||
**原因：**
|
||
- フックがsettings.jsonに登録されていない
|
||
- 無効なフック構文
|
||
- フックスクリプトが実行可能でない
|
||
|
||
**解決策：**
|
||
```bash
|
||
# フックが登録されているか確認
|
||
grep -A 10 '"hooks"' ~/.claude/settings.json
|
||
|
||
# フックファイルが存在し実行可能か確認
|
||
ls -la ~/.claude/plugins/cache/*/hooks/
|
||
|
||
# フックを手動でテスト
|
||
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
|
||
|
||
# フックを再登録（プラグイン使用時）
|
||
# Claude Code設定でプラグインを無効化してから再度有効化
|
||
```
|
||
|
||
### Python/Nodeバージョンの不一致
|
||
|
||
**症状：** 「python3 not found」または「node: command not found」
|
||
|
||
**原因：**
|
||
- Python/Nodeがインストールされていない
|
||
- PATHが設定されていない
|
||
- 間違ったPythonバージョン（Windows）
|
||
|
||
**解決策：**
|
||
```bash
|
||
# Python 3をインストール（不足している場合）
|
||
# macOS: brew install python3
|
||
# Ubuntu: sudo apt install python3
|
||
# Windows: python.orgからダウンロード
|
||
|
||
# Node.jsをインストール（不足している場合）
|
||
# macOS: brew install node
|
||
# Ubuntu: sudo apt install nodejs npm
|
||
# Windows: nodejs.orgからダウンロード
|
||
|
||
# インストールを確認
|
||
python3 --version
|
||
node --version
|
||
npm --version
|
||
|
||
# Windows: python3ではなくpythonが動作することを確認
|
||
python --version
|
||
```
|
||
|
||
### 開発サーバーブロッカーの誤検出
|
||
|
||
**症状：** フックが「dev」を含む正当なコマンドをブロックする
|
||
|
||
**原因：**
|
||
- ヒアドキュメントの内容がパターンマッチをトリガー
|
||
- 引数に「dev」を含む非開発コマンド
|
||
|
||
**解決策：**
|
||
```bash
|
||
# v1.8.0+で修正済み（PR #371）
|
||
# プラグインを最新バージョンにアップグレード
|
||
|
||
# 回避策: 開発サーバーをtmuxでラップ
|
||
tmux new-session -d -s dev "npm run dev"
|
||
tmux attach -t dev
|
||
|
||
# 必要に応じてフックを一時的に無効化
|
||
# ~/.claude/settings.jsonを編集してpre-bashフックを削除
|
||
```
|
||
|
||
---
|
||
|
||
## インストールとセットアップ
|
||
|
||
### プラグインが読み込まれない
|
||
|
||
**症状：** インストール後にプラグイン機能が利用できない
|
||
|
||
**原因：**
|
||
- Marketplaceキャッシュが更新されていない
|
||
- Claude Codeバージョンの非互換性
|
||
- プラグインファイルの破損
|
||
- ローカルのClaude設定がワイプまたはリセットされた
|
||
|
||
**解決策：**
|
||
```bash
|
||
# まずECCがこのマシンについて認識している情報を確認
|
||
ecc list-installed
|
||
ecc doctor
|
||
ecc repair
|
||
|
||
# doctor/repairで不足ファイルを復元できない場合のみ再インストール
|
||
|
||
# 変更前にプラグインキャッシュを確認
|
||
ls -la ~/.claude/plugins/cache/
|
||
|
||
# プラグインキャッシュを削除せずバックアップ
|
||
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
|
||
mkdir -p ~/.claude/plugins/cache
|
||
|
||
# Marketplaceから再インストール
|
||
# Claude Code → Extensions → Everything Claude Code → Uninstall
|
||
# その後Marketplaceから再インストール
|
||
|
||
# 問題がMarketplace/アカウントアクセスの場合、ECC Toolsのbilling/アカウントリカバリーを別途使用
|
||
# 再インストールをアカウントリカバリーの代替として使用しない
|
||
|
||
# Claude Codeバージョンを確認
|
||
claude --version
|
||
# Claude Code 2.0+が必要
|
||
|
||
# 手動インストール（Marketplaceが失敗する場合）
|
||
git clone https://github.com/affaan-m/everything-claude-code.git
|
||
cp -r everything-claude-code ~/.claude/plugins/ecc
|
||
```
|
||
|
||
### パッケージマネージャー検出の失敗
|
||
|
||
**症状：** 間違ったパッケージマネージャーが使用される（pnpmの代わりにnpm）
|
||
|
||
**原因：**
|
||
- ロックファイルが存在しない
|
||
- CLAUDE_PACKAGE_MANAGERが設定されていない
|
||
- 複数のロックファイルが検出を混乱させている
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 優先パッケージマネージャーをグローバルに設定
|
||
export CLAUDE_PACKAGE_MANAGER=pnpm
|
||
# ~/.bashrcまたは~/.zshrcに追加
|
||
|
||
# またはプロジェクトごとに設定
|
||
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
|
||
|
||
# またはpackage.jsonフィールドを使用
|
||
npm pkg set packageManager="pnpm@8.15.0"
|
||
|
||
# 警告: ロックファイルの削除はインストールされた依存関係のバージョンを変更する可能性がある
|
||
# まずロックファイルをコミットまたはバックアップし、フレッシュインストールを実行してCIを再実行
|
||
# パッケージマネージャーを意図的に切り替える場合のみ実行
|
||
rm package-lock.json # pnpm/yarn/bunを使用する場合
|
||
```
|
||
|
||
---
|
||
|
||
## パフォーマンスの問題
|
||
|
||
### レスポンスの遅延
|
||
|
||
**症状：** エージェントの応答に30秒以上かかる
|
||
|
||
**原因：**
|
||
- 大きな観測ファイル
|
||
- アクティブなフックが多すぎる
|
||
- APIへのネットワーク遅延
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 大きな観測を削除せずアーカイブ
|
||
archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
|
||
mkdir -p "$archive_dir"
|
||
find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
|
||
for file do
|
||
base=$(basename "$(dirname "$file")")
|
||
gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
|
||
: > "$file"
|
||
done
|
||
' sh {} +
|
||
|
||
# 未使用のフックを一時的に無効化
|
||
# ~/.claude/settings.jsonを編集
|
||
|
||
# アクティブな観測ファイルを小さく保つ
|
||
# 大きなアーカイブは ~/.claude/homunculus/archive/ に配置
|
||
```
|
||
|
||
### 高CPU使用率
|
||
|
||
**症状：** Claude CodeがCPUを100%消費
|
||
|
||
**原因：**
|
||
- 無限の観測ループ
|
||
- 大きなディレクトリのファイル監視
|
||
- フック内のメモリリーク
|
||
|
||
**解決策：**
|
||
```bash
|
||
# 暴走プロセスを確認
|
||
top -o cpu | grep claude
|
||
|
||
# 継続学習を一時的に無効化
|
||
touch ~/.claude/homunculus/disabled
|
||
|
||
# Claude Codeを再起動
|
||
# Cmd/Ctrl+Q で終了後、再起動
|
||
|
||
# 観測ファイルのサイズを確認
|
||
du -sh ~/.claude/homunculus/*/
|
||
```
|
||
|
||
---
|
||
|
||
## 一般的なエラーメッセージ
|
||
|
||
### "EACCES: permission denied"
|
||
|
||
```bash
|
||
# フックのパーミッションを修正
|
||
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
|
||
|
||
# 観測ディレクトリのパーミッションを修正
|
||
chmod -R u+rwX,go+rX ~/.claude/homunculus
|
||
```
|
||
|
||
### "MODULE_NOT_FOUND"
|
||
|
||
```bash
|
||
# プラグインの依存関係をインストール
|
||
cd ~/.claude/plugins/cache/ecc
|
||
npm install
|
||
|
||
# または手動インストールの場合
|
||
cd ~/.claude/plugins/ecc
|
||
npm install
|
||
```
|
||
|
||
### "spawn UNKNOWN"
|
||
|
||
```bash
|
||
# Windows固有: スクリプトが正しい改行コードを使用していることを確認
|
||
# CRLFをLFに変換
|
||
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
|
||
|
||
# またはdos2unixをインストール
|
||
# macOS: brew install dos2unix
|
||
# Ubuntu: sudo apt install dos2unix
|
||
```
|
||
|
||
---
|
||
|
||
## ヘルプを得る
|
||
|
||
問題が解決しない場合：
|
||
|
||
1. **GitHub Issuesを確認**: [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
|
||
2. **デバッグログを有効化**:
|
||
```bash
|
||
export CLAUDE_DEBUG=1
|
||
export CLAUDE_LOG_LEVEL=debug
|
||
```
|
||
3. **診断情報を収集**:
|
||
```bash
|
||
claude --version
|
||
node --version
|
||
python3 --version
|
||
echo $CLAUDE_PACKAGE_MANAGER
|
||
ls -la ~/.claude/plugins/cache/
|
||
```
|
||
4. **Issueを作成**: デバッグログ、エラーメッセージ、診断情報を含めてください
|
||
|
||
---
|
||
|
||
## 関連ドキュメント
|
||
|
||
- [README.md](./README.md) - インストールと機能
|
||
- [CONTRIBUTING.md](./CONTRIBUTING.md) - 開発ガイドライン
|
||
- [docs/](./) - 詳細なドキュメント
|
||
- [examples/](./examples/) - 使用例
|