調査レポート作成ガイド
ワークフロー
調査レポート作成は以下のステップで進める:
- •調査目的の明確化 - チケットリンクと調査範囲を定義
- •データ収集 - ログ分析、コード調査、過去の議論の追跡
- •分析・検証 - 仮説検証、動作確認、影響範囲の特定
- •レポート作成 - 構造化された形式で結果をまとめる
- •対応方針の決定 - 具体的なアクションを👉で明示
レポート構造テンプレート
markdown
# 目的 - [#チケット番号 タイトル](チケットシステムへのリンク) - 調査の背景と目的を1-2行で記述 # 調査ログ ## 調査項目1 - 調査内容と発見事項 - コードリンク: [src/path/to/file.rb#L123](リポジトリへのリンク) - データによる裏付け（SQLクエリ結果など） **対応方針:** - 👉具体的な対応内容 ## 調査項目2 （同様の構造で続ける） ## 対応方針まとめ - 全体の対応方針を箇条書きで整理
ベストプラクティス
実例に基づく具体的な記述
- •チケットへのリンク: Redmine、Jira、GitHub Issue等の具体的なリンク
- •コードへの直接リンク: GitLab/GitHubの行番号付きリンク
- •過去の議論の引用: Slackやチケットの議論を参照
- •データで裏付け: BigQueryクエリ結果、ログ分析結果を提示
MECE原則
- •相互排他的: 重複のない分類
- •完全網羅的: 漏れのない調査
ピラミッド原則
code
結論 ├── 理由1 │ ├── 根拠1-1 │ └── 根拠1-2 ├── 理由2 │ ├── 根拠2-1 │ └── 根拠2-2 └── 理由3
5W1Hの活用
- •What: 何を調査したか
- •Why: なぜ調査したか
- •Who: 誰が影響を受けるか
- •When: いつ対応するか
- •Where: どこに問題があるか
- •How: どう解決するか
データドリブン
markdown
❌ 悪い例: 「レスポンスが遅い」 ✅ 良い例: 「レスポンス時間が平均3.2秒（目標500ms）、P95で5.8秒を記録」
視覚化の使い分け
| 視覚化 | 用途 |
|---|---|
| フローチャート | 処理の流れ |
| シーケンス図 | 時系列の相互作用 |
| ER図 | データ構造 |
| グラフ | 時系列データ、比較 |
| テーブル | 構造化された情報 |
絵文字（👉⚠️等）の使用ルール
原則: 絵文字は「強調」のために使用。全項目に同じ絵文字を付けると意味がなくなる。
使用すべき場合（1セクションにつき最大1-2箇所）:
- •最も重要な結論・推奨アクション
- •重要な意思決定ポイント
- •リスクの高い変更への警告（⚠️を使用）
使用してはいけない場合:
- •すべての箇条書きに同じ絵文字を付ける
- •単純な事実の羅列
- •複数の選択肢を列挙する場合
markdown
## 悪い例（全項目に絵文字） - 👉Native SQLに変更する - 👉D_COUPONテーブルへのJOINを追加する - 👉MySQLとSQL Serverの両方に対応する ## 良い例（結論のみに絵文字） - Native SQLに変更し、D_COUPONテーブルへのJOINを追加する - MySQLとSQL Serverの両方に対応する - 👉ただし、呼び出し元で使用されていないため、撤去の方が適切
リファレンス
詳細な情報は以下を参照:
- •
references/patterns.md - 調査タイプ別のレポートパターン集（5パターン）
- •テーブル移行に伴うレガシーAPI調査
- •テーブル移行に伴う対応要否調査
- •エラー調査とリプレース方針検討
- •運用フロー・設計ドキュメント
- •バッチ処理調査
- •
references/techniques.md - 調査ツールと実践テクニック
- •調査ツール一覧（Grep、BigQuery、Slack検索等）
- •アクセスログ分析の判断基準
- •デッドコード特定方法
- •論理的矛盾の発見方法
- •
references/examples.md - 具体的な記述例とアンチパターン
- •過去の議論の引用例
- •動作確認の記録例
- •ER図を使った関係性整理
- •避けるべきアンチパターン
チェックリスト
調査前
- • 調査目的が明確
- • 調査範囲が定義済み
- • 関連チケット番号を確認
- • 必要なツールへのアクセス確認
調査中
- • 体系的にデータ収集
- • 仮説を立てて検証
- • コードへの行番号付きリンクを記録
- • 証拠を記録（クエリ結果、スクリーンショット）
- • 過去の議論を追跡（Slack、チケット）
レポート作成
- • 「# 目的」セクションにチケットリンクあり
- • 「# 調査ログ」で調査項目ごとに区切り
- • 各調査項目に👉で対応方針を明示
- • GitLab/GitHubの行番号付きリンクを提示
- • データベースクエリ結果を提示
- • 「対応方針まとめ」で総括
レビュー
- • 技術的正確性
- • 論理的一貫性
- • 完全性（MECE）
- • データによる裏付け