良いIssueの書き方 Why と体験をチームとAIに伝える

Transcript

1. チーム WE部 勉強会 / ISSUE の書き方 良い Issue の書き方 Why と体験を チームと AI に伝える Why AI
   エージェント Issue 解決したい問題 体験 誰の・どの場⾯を・どう変えるか どれでもいい junhat6 / 2026-10 How
   A How
   B How
   C
2. Issue に、めっちゃ細かい仕様書を書く。 AI エージェントで書くと、 ごっつい仕様書ができあがる。 正直、何が書いてあるか分からない。 読む気が起きない。 2
3. その Issue 自体が、ほとんどレビューできない。 機能の話ばかりで、認知的に全部は読めない。 結局、Issue をほとんど無視して PR を出す。 3
4. PR で「そもそもこれって何で困ってたんだっけ？」 「じゃあこれ、仕様として間違ってますよね」 このちゃぶ台返しを食らうのが、しんどい。 IdeaBoost でよくあること。根っこは、Issue に Why を書いていないこと 4
5. 蜂須賀さんの講演の例: 記事を移動中に聴きたい 蜂須賀大貴「AIでコードは書けるのに、つくりたいものがつくれないあなたへ」DevFest Kansai 2026 p19 docswell.com/s/PassionateHachi/KN73NR-2026-10-18-161120 5
6. 保存・検索・音声化・再生。 欲しい機能は全部そろった。 でも、画面を消すと再生が止まる。 機能は手段でしかない。 上の 3 行は同じ講演の p17・p22 より 6
7. Why が大事 Why と実現したい体験がはっきりしていれば、 どんな How でもいい Why とか解決したい問題がハッキリしていれば、どんな How を取ってもほぼ解決できるはず 7
8. 今日の話は 3 章 1 Why
   と体験 機能より体験を書く 2 親⼦
   Issue
   を作る PBI
   と
   Task、レビューしやすい⼤きさ 3 Issue
   で合意を取る PR
   の前にコメントで合意する 8
9. 機能 ⼿段 1 / 3 Why と体験 機能より体験を書く 1 誰の 体験 2 どの場⾯を 3 どう変えるか 9
10. 機能から書いた Issue 僕が書いた #688。タイトルは機能の名前 で、本文は動画 2 本だけ。 Why を書いていないので、 何に困っているのか伝わりにくい。 何を解決すればいいのか、 どこまでやればゴールなのかも分からない。 IdeaBoost #688 10
11. 体験から書いた PBI #737 は、ユーザーストーリーと Why と提供 する体験から書いている。 ゲージの形は「設計時に決める」と書いて、 How を決めていない。 IdeaBoost #737 11
12. Why と体験がはっきりしていれば、どんな How でもいい 1 決めること
    (PBI
    #737) Why 数字だけでは、締め切りが迫る感覚を捉えにくい 体験 ⾳がなくても、開始・停⽌・終了が分かる 2 How
    の候補 どれでもいい ゲージ表⽰ (#688) 開始時に⼤きくなるアニメ (#655
    のコメント) 数字の補助表⽰ 12
13. 誰の・どの場面を・どう変えるか #737 では 誰の ワークショップの参加者 どの場面を 残り時間を気にしながら、アイデアを出している最中 どう変えるか 時間の余裕や終了を感じ取り、締め切りを意識して集中できる 「機能を考えるな、体験を考えろ。誰の / どの場面を / どう変えるかが全て」(蜂須賀さんの講演 p10) docswell.com/s/PassionateHachi/KN73NR-2026-10-18-161120 13
14. PBI 2 / 3 親子 Issue を 作る Issue Type で PBI と Task を分ける 体験 Task 作業 Task 作業 14
15. PBI と Task で親子関係を作る PBI #737 PBI 残り時間をゲージで捉え、 集中して取り組める =
    実現したい体験 Sub-issue Task =
    そのための作業 Task #655 タイマーの開始が気づきにくい Task #688 ゲージ表⽰にする ⾃由に動かせるフローティングにする 15
16. レビュワーがレビューしやすい単位に区切る 目安は 1 Issue 1 PR #688 には「ゲージ表示」と「自由に動かせるフローティング」の 2 つが入って いる 確かめることが別々なら、Task を分けたほうがレビューしやすい 16
17. どの話題に関するものか分かるように、 親子 Issue を作る。 ただ、親がデカすぎると、 いつまでもその親 Issue を閉じられない。 17
18. Issue Why・概要 3 / 3 Issue で 合意を取る Issue コメントを活用する ⽅針案 質問 合意 PR 18
19. 細かく書いてある。でも、どう進めたいのか分からない #642: 参加者の完了状況で 次へ進める相談 僕のコメント: 「いきなり具体例から始まったから イメージ掴みづらかった」 #642 に残っている再分類前の本文 (一部) と、10/13 の僕のコメント 19
20. PR が出たあとも、方針の相談が続いていた Issue #642 PR #645 ⽅針の相談中 1 10/13
    昼 3 10/13
    午後 4 10/15 ⼤きな⽅針を 確認したい PR
    で詳細に 書く予定です 過半数案を選ぶ 2 10/13
    昼過ぎ PR
    が作られる 5 後から整理 相談は『過半数』 実装は『半数以上』 時間 接続中 4 人の場合、相談では 3 人、実装では 2 人の完了で次へ進める github.com/engineer-first/idea-boost/issues/642 20
21. 方針案・質問・メモを分けてコメントする Issue
    本⽂ コメント Why・概要 1 ⽅針案 最初に 考えていること 2 質問 3 メモ 4 ⽅針の変更 「この⽅針で進めたいので、レビューをお願いします」 「A
    案と
    B
    案、どちらがいいですか?」 仕様
    →
    セキュリティ
    →
    設計 →
    実装と詰めていく 「記録⽤です。レビューの依頼ではありません」 「相談したので、⽅針を変えます」 21
22. Issue を立てるハードルを上げない Issue はやるべきことのメモ。ハードルのせいで書き忘れると辛い 立てる時点では、細かい仕様はまだ思いつかないことが多い だから テンプレートは過剰にしない IdeaBoost も PR #747 で、Issue を Why 中心に立てる形に変えた 22
23. Why やユーザーストーリーを入れるには、 できるだけ多くのことを入力しておくとよい。 いつもはキーボードだと思うけど、 僕のおすすめは音声入力。 23
24. 話すと、場面を思い出しやすい キーボード入力に気を取られない 人に説明するように話すから、想像力が働いて、いろんな場面を思いつく 入力が新鮮で、言いたいことがちゃんと言えてる感じがする 僕の経験談。このスライドの元になったメモも、音声入力で話したもの 24
25. AI エージェントに書かせる時は、過剰に書かせない 1 話す ⼈ ⾳声⼊⼒で、 場⾯をたくさん話す 話した内容 だけ渡す 2 整える 3 確かめる Why
    と体験の形に まとめてもらう 話していない仕様が ⾜されていないか AI ⼈ 話していない仕様を⾜す AI
    がやりがちなこと 25
26. 配布するテンプレートは 2 つ 書くこと 後で詰めること PBI ユーザーストーリー / Why / ユーザーに提供する体験 How・細かい仕様 Task 親 PBI / この作業の Why How・細かい仕様 テンプレート: github.com/junhat6/issue-templates (Use this template でコピーできる) 26
27. まとめ Why と体験がはっきりしていれば、どんな How でもいい。 1 Why と体験 機能より体験。誰の・どの場面を・どう変えるかを書く 2 親子 Issue を作る PBI と Task で親子関係を作る。親はデカくしすぎない 3 Issue で合意を取る 仕様は PR の前に、Issue のコメントで合意する 書くときは音声入力がおすすめ。AI には過剰に書かせない。実例: github.com/engineer-first/idea-boost/issues 27
28. 付録 自分で書き直してみる スライドか記事を見ながら、一人でできる 28
29. 課題: #688 を、背景が伝わる Task にする 元のタイトル:「タイマーをgartic phone みたいなゲージ表示にする かつ自由に 場所を動かせるフローティングにする」 親 PBI #737 の Why: 数字だけのタイマーでは、残り時間の長さや締め切りが迫 る感覚を捉えにくい 親 PBI #737 の体験: ゲージの残量と減る速さから、時間の余裕や終了を感じ取 れる 書くのは「Task の短い本文」と「相手に聞きたい質問コメント 1 つ」 29
30. 手順 1. 機能の案と、変えたい体験を分けて書く 2. この Task が、親 #737 のどの体験に関わるかを 1 文で書く 3. ゲージ表示とフローティングを分けるかを決め、理由を残す 4. 材料だけでは分からないことは、質問コメントにする 音声入力や AI を使ってもよい。材料に無い事情を、決まったことのように書かない 30
31. 書き直しの例 タイトル 作業中に、タイマーの残り時間を捉えやすくする 親 PBI #737 Why 数字だけでは残り時間の余裕を捉えにくい。参加者が時間を意識しながら作業で きるようにしたい 質問 フローティングで動かしたいのは、どの場面で何に重なるからですか? これは教材用の例。How が違っても、Why と体験を説明できていれば正解 31
32. 自分で確かめる 読んだ人が、誰の何を変えたいのか説明できるか 親の体験と、この Task の作業がつながっているか 思いついた How を、決まったことのように書いていないか 足りなければ 1 文直して終わり。提出は要らない 32