GITHUB OPERATIONS — ISSUE / PR / DoD
同僚向け勉強会 / GitHub運用の話
開発現場で、本当によく聞く言葉。しかも厄介なのは、技術力不足だけで起きる問題ではないこと。
それでも、なぜか手戻りが多いチームは普通に存在する。
理由はシンプル。問題は「実装力」ではなく「認識のズレ」だから。
「コミュニケーション品質」を、実務目線で整理します。
開発というと「コードを書くこと」が一番大変に見える。でも実際に工数を溶かしているのは、むしろこっち。
つまり、ソフトウェア開発の工数の多くは 「不確実性」。
そして、この不確実性は コミュニケーション品質でかなり削減できる。
「認識ズレによる無駄な工数」を減らすために。
例えば、こんなIssue。
検索UIを改善する
- レイアウト修正
- バグ対応
これだと、実装者はまず 推測 から始めないといけない。
人間は、空白があると勝手に脳内補完する。そして、その補完はかなり高確率でズレる。
強いIssueは、単なるタスク管理ではない。
「実装者が最短で正しく理解するためのドキュメント」 になっている。
次の3枚で、記事のサンプルをそのまま見てみる。
# Background
営業側では価格を500万円単位で扱っているが、
検索UIでは細かい数値入力ができてしまう。
そのため、
営業資料と検索条件にズレが発生している。
# Problem
1200万円で検索した場合、
営業資料上は1000万円帯として扱われるが、
検索条件は1200万円のまま保持されてしまう。
# User Story
ユーザーとして、
営業資料と同じ粒度で価格検索したい。
なぜなら、
営業担当と同じ条件で物件を探したいから。
→ なぜやるのか / 何が問題か / 誰のための機能か が冒頭で揃う
# Acceptance Criteria
- 入力値を500万円単位へ丸める
- 1200 → 1000
- 1499 → 1500
- slider操作時も適用
- SP/PC両対応
- URL query parameterも同様に丸め込み
# Reproduction
1. 検索画面を開く
2. 価格に「1200」を入力
3. 検索条件を確認
4. 1200万円として保持される
# Expected
1000万円へ丸め込まれること
→ 完了条件が数値で決まっている / 再現と期待結果が明記されている
# Possible Cause
price normalization処理が
manual input時のみ未適用の可能性あり
# Test Cases
- manual input
- slider input
- query parameter復元
- 検索条件再表示
- SP/PCレイアウト崩れ確認
# Out of Scope
- API変更
- DB変更
- 検索ロジック変更
→ どこから見ればよいか / 何をテストすべきか / どこまでやるか まで揃う
特に不具合対応では、この3つがかなり重要。再現方法がないIssueは、調査コストが一気に上がる。
さらに、原因の目星 まであるとかなり強い。
# Possible Cause
manual input側のみ normalize utilityが適用されていない可能性あり
予想が外れることもある。でも「どこから見ればよいか」の初動速度が大きく変わる。Issue段階のテスト観点は、実装者自身の確認漏れ防止にも効く。
どれだけ丁寧にIssueを書いても、認識ズレは普通に起きる。むしろ危険なのは——
ソフトウェア開発は複雑。これらは普通に発生する：
重要なのは「Issueを完璧にすること」ではなく、認識合わせを始めやすい状態にすること。
優秀なチームほど、こういう動きがかなり多い。
一見、コミュニケーションコストが高そうに見える。でも実際は逆。
Issueが雑だと、会話も雑になる。前提が揃っていないから。逆に Background / Problem / Acceptance Criteria / Out of Scope / Test Cases が整理されていると——
雑なPRもかなり多い。
バグ修正しました。
確認お願いします。
これだけ粒度が粗いと、Reviewerからすると「何を？」となる。
全部コードを読んで推測しないといけない。これは普通に高コスト。
強いPRは、Reviewerだけを見ていない。
BUSINESS QA REVIEWER 将来の自分
全員に向けて書かれている。次の3枚で、記事のサンプルをそのまま見てみる。
# Summary
価格検索入力を500万円単位へ統一
# Background
営業資料と検索条件の価格単位に差異があり、
ユーザー混乱が発生していたため。
# RCA
## Root Cause
manual input時のみ price normalization処理が適用されていなかった。
slider側には既存実装が存在したが、input側で同じutilityを利用していなかった。
## Why Not Detected
slider操作中心で確認されており、manual inputの確認が漏れていた。
また、price normalizationに対する unit testも存在していなかった。
→ Summary で要点 / Background で動機 / RCA で「なぜ起きた・なぜ気づけなかった」
# Changes
- manual input時の丸め込み追加
- slider操作時も共通utilityへ統一
- URL query parameter復元時にも適用
- unit test追加
# Before
- 1200 → 1200のまま検索
- sliderとmanual inputで挙動差異あり
# After
- 1200 → 1000へ丸め込み
- 全入力経路で同一仕様へ統一
# Main Changes
- src/features/search/PriceFilter.tsx
- src/utils/price.ts
- tests/price-filter.test.ts
→ 変更点 / Before・After / 主要ファイル が一目で分かる
# Test
## Manual
- 1200 → 1000
- 1499 → 1500
- slider操作確認
- query parameter復元確認
- SP/PC確認
## Regression
- 他検索条件との組み合わせ
- 検索結果件数変化確認
# Review Focus
- 丸め込み仕様違和感ないか
- 共通utility化による副作用ないか
- 既存検索条件への影響ないか
→ 何をどう確認したか / レビューで特に見てほしい場所、まで書いてある
強いチームほど、「バグを直す」だけで終わらない。RCA（Root Cause Analysis）を共有知に変える。
これがあると → 再発防止 / レビュー品質向上 / テスト不足の発見 / 設計負債の把握 につながる。
逆にRCAがないと「直ったけど、なぜ起きたかは曖昧」な状態に。これは将来的な再発リスク。
PRで特に効果が大きいのが Before / After を書くこと。レビュー時の認識コストがかなり下がる。
また、「テストしました」だけでは弱い。
少なくとも「エンジニアがどう確認すればよいか」は書いてあると助かる。
「何をもって完了とするのか」をチームで揃えること。これが曖昧なチーム、かなり多い。
「実装が終わったらDone」
review approve → QA完了 → staging反映 → Business確認 → release完了 まで含めてDone
→ 全員が「終わったつもり」で会話してしまう。これは危険な兆候。
地味だけど、かなり怖いやつ。例えば「公開」。この単語、チームによって意味が違うことがある。
全員が 同じ単語で別の話 をしている。しかもこういうズレは release直前で爆発 しやすい。
→ だから強いチームほど、最初に言葉を揃える。
最近は、生成AIに実装そのものをかなり任せられるようになってきた。Issue作成もPR作成も、以前よりかなり楽。
かなり高品質に出してくれる。だから——
生成AIを使わない手はない。
AIは実装も文章も作れる。でも「何を作るべきか」を決めるのは人間。認識がズレたまま指示を出すと——
さらにAIは普通に嘘をつく。
→ ファクトチェック / 実装内容との整合性確認 / 変更file確認 / テスト内容確認 を人間側が必ずやる。
AIは強力。でも「認識責任」まで肩代わりしてくれるわけではない。
開発が速いチームは、コードを書く速度だけが速いわけではない。
だから、無駄な往復が少ない。結果として速い。
ソフトウェア開発は、コードを書く仕事に見える。
でも実際は 「人間同士の認識を揃え続ける仕事」 にかなり近い。
Issueを書く / PRを書く / RCAを共有する / 完了条件を揃える / 言葉を揃える / 途中で会話する
一見地味。でも、ここを丁寧にやるチームほど——
品質が高い / 手戻りが少ない / 開発速度が安定する / 属人化しにくい / Businessとの信頼が強い
そして結局、それが一番速い。
議論したいポイントあればどうぞ 🙌
PDF化したいときは index.html?print-pdf をブラウザで開いて印刷 → PDF保存