Show HN: DebugBrief – デバッグセッションを報告書に変換、AI不要

DebugBrief は、開発者がデバッグプロセスを体系的に記録し、明確で再現可能なレポートに変換するための革新的なコマンドラインツールです。完全にローカルで動作し、人工知能に依存せず、テレメトリも収集しないため、開発者のワークフロープライバシーが保護されます。

コア機能

DebugBrief は debugbrief run コマンドを介して、ユーザーが実行するコマンドとその出力をキャプチャします。各コマンドの終了コード、出力プレビュー、実行時間、および実行前の git スナップショットを記録します。すべての記録は実際に発生したイベント（試行したこと、失敗したこと、通過したテスト、変更されたファイル）に基づいており、ツールは根本原因を推測したり、ユーザーが得なかった結果を報告したりしません。

レポートは3つのモードで生成できます：PRモード（デフォルト）、引き継ぎモード、インシデントモード。レポートには、要約、赤から緑への遷移（失敗から成功までの時間枠）、検証コマンド、タイムライン、観察されたエラーが含まれます。空のセクションは自動的に省略されます。

インストールとクイックスタート

DebugBrief には Python 3.9 以降が必要です。pipx や uv ツールを使ってインストールできます：

pipx install debugbrief
# または
uv tool install debugbrief

使用方法は簡単です。セッションを開始し、コマンドを記録します：

debugbrief start "add() が間違った結果を返すのを修正"
debugbrief note "add() が減算を行っている；テストは5を期待。"
debugbrief run -- python -m pytest -q test_calc.py # テスト実行
# 修正を加える
debugbrief redo # 最後のコマンドを再実行
debugbrief end # PRレポートを生成

redo コマンドは最後にキャプチャしたコマンドを再実行し、end はデフォルトで PR レポートを生成します。また、コマンド出力を GitHub PR にパイプすることもできます：debugbrief end --stdout | gh pr comment --body-file -。

互換性と制限

DebugBrief は Linux と macOS をサポートしており（CI で Python 3.9 から 3.14 までテスト済み）、他の Unix 系システムでも動作する可能性がありますが、現在はテストされていません。ネイティブ Windows と PowerShell はサポートされていません。ツールは一般的なテストランナー（pytest、jest、go test、cargo test など）を自動認識しますが、他のコマンドも --verify フラグでチェックポイントとしてマークできます。

キャプチャは明示的で、debugbrief run 経由で実行されたコマンドのみを記録します。フルスクリーン TUI アプリケーション（vim、htop など）は効果的にキャプチャされません。プライバシー面では、ディスクに書き込む前にシークレットのサニタイズを試みますが、ベストエフォートであり、すべてのケースをカバーするわけではありません。

依存関係とライセンス

DebugBrief は Python 標準ライブラリとネイティブ git を使用します。Python 3.11 以降では追加の依存関係は不要ですが、Python 3.9/3.10 ではオプションの .debugbrief.toml 設定ファイルを読み込むために tomli パッケージが必要です。ツール自体はネットワークリクエストを行わず、AI を使用せず、テレメトリも収集しません。プロジェクトは MIT ライセンスの下で提供されています。

全体として、DebugBrief は軽量で誠実かつ信頼性の高いデバッグ記録ツールであり、透明性があり検証可能な開発プロセスを必要とするチームや個人に特に適しています。