fix-bug

GitHub の Issue からバグを修正する

GitHub の Issue を起点に、DBHub のコードベースで修正を実装するための体系的なワークフローです。

ワークフロー

1. 取得 → 2. 分析 → 3. 特定 → 4. 再現 → 5. 計画 → 6. 実装 → 7. 検証 → 8. PR

ステップ 1：Issue を取得する

# From URL: https://github.com/owner/repo/issues/123
gh issue view 123 --json title,body,labels,comments,state

# From another repo
gh issue view 123 --repo owner/repo --json title,body,labels,comments,state

入力	取得方法
https://github.com/owner/repo/issues/42	gh issue view 42 --repo owner/repo
#42 または 42	gh issue view 42（現在のリポジトリ）
owner/repo#42	gh issue view 42 --repo owner/repo

ステップ 2：Issue を分析する

Issue から以下の情報を抽出します。

• 何が壊れているか：期待される動作と実際の動作
• 再現手順：バグを発生させる方法
• 環境：データベースの種類、接続方法（DSN、SSH トンネル、TOML 設定）、トランスポート（stdio/HTTP）
• ラベル／コメント：影響範囲や過去の調査が分かることがあります
• 関連付けられた PR／Issue：関連する情報がないか確認します

ステップ 3：関連するコードを特定する

Issue の詳細を使って、コードベースのどの部分が影響を受けているか特定します。DBHub は明確なモジュール構造を備えており、ほとんどのバグは次のいずれかの領域に当てはまります。

バグのカテゴリ	確認する場所	主なファイル
接続エラー	コネクターの実装	src/connectors/{db-type}/index.ts、src/connectors/manager.ts
SQL 実行エラー	ツールハンドラー	src/tools/execute-sql.ts、src/utils/allowed-keywords.ts
スキーマ／テーブルの一覧表示	検索ツール	src/tools/search-objects.ts
DSN 解析の問題	パーサーロジック	src/connectors/{db-type}/index.ts（DSNParser）、src/utils/dsn-obfuscate.ts、src/utils/safe-url.ts
SSH トンネルの問題	トンネルユーティリティ	src/utils/ssh-tunnel.ts、src/utils/ssh-config-parser.ts
TOML 設定の問題	設定の読み込み	src/config/toml-loader.ts、src/types/config.ts
複数データベースのルーティング	マネージャーとツール	src/connectors/manager.ts、src/utils/tool-handler-helpers.ts
カスタムツールの問題	カスタムハンドラー	src/tools/custom-tool-handler.ts、src/tools/registry.ts
HTTP トランスポート	サーバーのセットアップ	src/server.ts
読み取り専用違反	SQL 検証	src/utils/allowed-keywords.ts、src/utils/sql-parser.ts
行数制限	SQL の書き換え	src/utils/sql-row-limiter.ts
API エンドポイントの問題	API ハンドラー	src/api/sources.ts、src/api/requests.ts
AWS IAM 認証	トークン署名	src/utils/aws-rds-signer.ts

Issue に記載されているエラーメッセージ、関数名、ファイルパスを検索します。エントリーポイントから障害発生箇所まで、コードの実行経路を追跡します。

ステップ 4：再現する

該当領域に統合テストがある場合： バグを再現する失敗テストを作成します。DBHub のテストインフラを使えば簡単に実施できます。

• データベースコネクターのバグ → src/connectors/__tests__/ に既存の統合テストを追加
• ユーティリティのバグ → src/utils/__tests__/ の既存のユニットテストにケースを追加
• ツールハンドラーのバグ → src/tools/__tests__/ に追加
• 設定のバグ → src/config/__tests__/ に追加

複数データベースや readonly/max_rows のシナリオでは、src/__fixtures__/ のテストフィクスチャを使用します。

該当するテストインフラがない場合： コードを読み、実行経路を追跡してロジックの問題を確認します。

ステップ 5：修正を計画する

単純でない修正（複数ファイルに及ぶもの、アーキテクチャに影響するもの）には、EnterPlanMode を使用します。

単純な修正（単一の関数が対象で、根本原因が明らかなもの）は、そのまま進めます。

ステップ 6：実装する

• 症状だけでなく、根本原因を修正します
• 変更は最小限に抑え、対象を絞ります
• 既存のコード規約に従います（スタイルガイドは CLAUDE.md を参照）
• データベース操作にはパラメーター化クエリを使用します
• 適切な場合は zod スキーマで入力を検証します

ステップ 7：検証する

関連するテストを実行して、修正を確認します。

pnpm test:unit                    # Quick check — no Docker needed
pnpm test src/path/to/test.ts     # Run the specific test file
pnpm test:integration             # Full integration suite if needed

次の点を確認します。

• 作成した失敗テストがあれば、修正後に成功すること
• 既存のテストに悪影響がないこと
• 差分で Issue の内容に完全に対処できていること

ステップ 8：PR を作成する

1. ブランチを作成する：

   git checkout -b fix/issue-123
   

2. Issue を参照して変更をコミットする：

   git add <changed-files>
   git commit -m "$(cat <<'EOF'
   Fix: <short description>
   
   Closes #123
   EOF
   )"
   

3. プッシュして PR を作成する：

   git push -u origin fix/issue-123
   gh pr create --title "Fix: <short description>" --body "$(cat <<'EOF'
   ## Summary
   <What was broken and how this fixes it>
   
   ## Changes
   <Bullet list of changes>
   
   Closes #123
   
   ## Test plan
   - [ ] Existing tests pass
   - [ ] New test covers the bug scenario (if applicable)
   EOF
   )"
   

4. PR の URL をユーザーに返す。

よくある間違い

• 根本原因ではなく症状に対処する：修正する前に、コードパス全体をたどります
• 再現を省略する：再現なしの修正は推測にすぎません
• スコープの拡大：報告された問題を修正し、周辺コードのリファクタリングは行いません
• エッジケースの見落とし：コメントで言及されている関連シナリオも修正で処理できるか確認します
• 適切なデータベースでテストしない：バグが特定のデータベースに固有の場合は、そのコネクターでテストします