claude-code-debug

Claude Code のデバッグ

拡張機能、フック、予期しない動作をトラブルシューティングします。

クイック診断

# Enable debug mode
claude --debug

# Check loaded extensions
/hooks        # View registered hooks
/agents       # View available agents
/memory       # View loaded memory files
/config       # View current configuration

よくある問題

症状	クイックチェック
スキルが有効にならない	説明にトリガーキーワードが含まれていることを確認します
フックが実行されない	chmod +x を確認し、/hooks を実行します
エージェントが委任しない	説明に「Use proactively」を追加します
MCP 接続に失敗する	npx でサーバーを手動でテストします
アクセスが拒否される	settings.json の許可ルールを確認します

デバッグモードの出力

claude --debug
# Shows:
# - Hook execution and errors
# - Skill loading status
# - Subagent invocations
# - Tool permission decisions
# - MCP server connections

クイック修正

スキルが読み込まれない

# Check structure
ls -la .claude/skills/my-skill/
# Must have: SKILL.md

# Verify YAML frontmatter
head -10 .claude/skills/my-skill/SKILL.md
# Must start/end with ---

# Check name matches directory
grep "^name:" .claude/skills/my-skill/SKILL.md

フックが実行されない

# Make executable
chmod +x .claude/hooks/my-hook.sh

# Test manually
echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh
echo $?  # Check exit code

# Verify JSON syntax
jq '.' ~/.claude/settings.json

エージェントが使用されない

# Check file location
ls ~/.claude/agents/
ls .claude/agents/

# Verify description includes "Use for:" or "Use proactively"
grep -i "use" agents/my-agent.md | head -5

# Explicitly request
# "Use the my-agent agent to analyze this"

検証

# Run all validations
just test

# YAML validation only
just validate-yaml

# Name matching only
just validate-names

公式ドキュメント

• https://code.claude.com/docs/en/hooks - フックのリファレンス
• https://code.claude.com/docs/en/skills - スキルのリファレンス
• https://code.claude.com/docs/en/sub-agents - カスタムサブエージェント
• https://code.claude.com/docs/en/settings - 設定

追加リソース

• ./references/common-issues.md - 問題 → 解決策の一覧表
• ./references/debug-commands.md - すべての検査コマンド
• ./references/troubleshooting-flow.md - 判断フロー

---

関連項目： フックのデバッグについては claude-code-hooks、正しい構成については claude-code-templates を参照してください。