debug-cli

CLI デバッグスキル

このスキルでは、forge CLI アプリケーションの変更をデバッグして検証するための体系的なワークフローを紹介します。

基本原則

1. 必ず最初に最新のドキュメントを確認する：--help を実行し、現在のコマンドとオプションを確認します
2. テストには -p を使う：-p フラグを指定してタスクを与え、forge をテストします
3. コミットしない：これはデバッグ専用です。変更をコミットしないでください
4. 会話を複製する：会話に関するバグをデバッグするときは、再現する前に元の会話を複製します

ワークフロー

1. アプリケーションをビルドする

変更を加えた後は、必ずデバッグモードでビルドします。

cargo build

デバッグには絶対に cargo build --release を使わないでください。ビルドに大幅に時間がかかり、検証にも不要です。

2. 最新のドキュメントを確認する

現在のコマンドとオプションを把握するため、必ず最新のヘルプを確認することから始めます。

# Main help - do this first
./target/debug/forge --help

# Command-specific help
./target/debug/forge [COMMAND] --help

# Subcommand help
./target/debug/forge [COMMAND] [SUBCOMMAND] --help

3. -p フラグを使ってテストする

-p フラグを使うと、インタラクティブモードを使わずに、forge に完了させるタスクを渡せます。

# Test with a simple prompt
./target/debug/forge -p "create a hello world rust program"

# Test with specific functionality
./target/debug/forge -p "read the README.md file and summarize it"

# Test with complex tasks
./target/debug/forge -p "analyze the code structure and suggest improvements"

4. 会話ダンプを使ってデバッグする

プロンプトや会話に関する問題をデバッグするときは、conversation dump を使って会話をエクスポートします。このコマンドはタイムスタンプ付きのファイルを自動的に作成します。

# Dump conversation as JSON (creates: YYYY-MM-DD_HH-MM-SS-dump.json)
./target/debug/forge conversation dump <conversation-id>

# Export as HTML for human-readable format (creates: YYYY-MM-DD_HH-MM-SS-dump.html)
./target/debug/forge conversation dump --html <conversation-id>

# Use dumped JSON to reproduce issues
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json

5. バグを再現する前に複製する

重要：ユーザーからバグのある会話が提供された場合は、必ず最初に複製してください。

# Clone the conversation
./target/debug/forge conversation clone <source-conversation-id>

# This creates a new conversation ID - use that for testing
./target/debug/forge --conversation-id <new-cloned-id>

# Keep cloning the source until the fix is verified
# Never modify the original conversation

複製する理由

• 元のバグの証拠を保持できます
• 複数回の再現を試せます
• 修正の A/B テストができます
• 元の会話を変更せずに保てます

よくあるテストパターン

新機能をテストする

# Build and test new command
cargo build
./target/debug/forge --help  # Verify new command appears
./target/debug/forge new-command --help  # Check command docs
./target/debug/forge -p "test the new feature"

報告されたバグを再現する

# 1. Dump the conversation (creates timestamped JSON file)
./target/debug/forge conversation dump <bug-conversation-id>

# 2. Clone it for testing (preserves original)
./target/debug/forge conversation clone <bug-conversation-id>

# 3. Reproduce with the cloned conversation
./target/debug/forge --conversation-id <cloned-id> -p "reproduce the issue"

# 4. After fix, verify with new clone
./target/debug/forge conversation clone <bug-conversation-id>
./target/debug/forge --conversation-id <new-clone-id> -p "verify fix"

エッジケースをテストする

# Test with missing arguments
./target/debug/forge command

# Test with invalid input
./target/debug/forge -p "invalid task with special chars: <>|&"

# Test with boundary values
./target/debug/forge -p "create a file with a very long name..."

プロンプトを最適化する

# 1. Dump conversation to analyze prompts (creates timestamped JSON)
./target/debug/forge conversation dump <id>

# 2. Review the conversation structure
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# 3. Export as HTML for easier reading
./target/debug/forge conversation dump --html <id>

# 4. Test modified prompts
./target/debug/forge -p "your optimized prompt here"

開発ワークフローとの統合

コードを変更した後

1. ビルド：cargo build
2. ドキュメント：./target/debug/forge --help（ドキュメントを確認）
3. テスト：./target/debug/forge -p "relevant task"
4. 検証：出力が期待どおりであることを確認

バグ報告のデバッグ

1. 複製：./target/debug/forge conversation clone <source-id>
2. ビルド：cargo build（必要に応じて修正を加える）
3. テスト：./target/debug/forge --conversation-id <cloned-id> -p "reproduce"
4. 繰り返す：検証が完了するまで繰り返します
5. デバッグ中はコミットしない：完全に検証した後にのみコミットします

クイックリファレンス

# Standard debug workflow
cargo build
./target/debug/forge --help  # Always check docs first
./target/debug/forge -p "your test task"

# Dump conversation (creates timestamped file)
./target/debug/forge conversation dump <id>
# Output: 2025-11-23_12-28-52-dump.json

# Export as HTML for review
./target/debug/forge conversation dump --html <id>
# Output: 2025-11-23_12-28-52-dump.html

# Use dumped conversation
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json

# Clone and test bug
./target/debug/forge conversation clone <source-id>
./target/debug/forge --conversation-id <cloned-id> -p "reproduce bug"

# Debug prompts with jq (use actual filename)
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# Test with verbose output
./target/debug/forge --verbose -p "test task"

ヒント

• まず必ず --help を確認する：テスト前に最新のドキュメントを確認します
• テストには -p を使う：インタラクティブにテストせず、プロンプトを使います
• 会話を複製する：元のバグのある会話は変更しないでください
• コミットしない：これはデバッグ専用です
• ダンプでファイルが作成される：dump はタイムスタンプ付きファイルを自動的に作成します（> は不要です）
• HTML エクスポート：人が読みやすい会話ビューには --html フラグを使います
• 相対パスを使う：プロジェクトルートからのバイナリの場所は ./target/debug/forge です
• 終了コードを確認する：echo $? を使って終了コードを確認します
• 警告に注意する：ビルド時の警告は、問題を示していることがよくあります