mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-05-18 14:53:05 +08:00
docs: add native Japanese translation of ECC documentation (ja-JP)
Translate everything-claude-code repository to Japanese including: - 17 root documentation files - 60 agent documentation files - 80 command documentation files - 99 rule files across 18 language directories (common, angular, arkts, cpp, csharp, dart, fsharp, golang, java, kotlin, perl, php, python, ruby, rust, swift, typescript, web) - 199 skill documentation files Total: 455 files translated to Japanese with: - Consistent terminology glossary applied throughout - YAML field names preserved in English (name, description, etc.) - Code blocks and examples untouched (comments translated) - Markdown structure and relative links preserved - Professional translation maintaining technical accuracy This translation expands ECC accessibility to Japanese-speaking developers and teams. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude
433
docs/ja-JP/TROUBLESHOOTING.md
Normal file
433
docs/ja-JP/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# トラブルシューティングガイド
|
||||
|
||||
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/](./docs/) - 詳細なドキュメント
|
||||
- [examples/](./examples/) - 使用例
|
||||
Reference in New Issue
Block a user