仕様書駆動AI開発の実践： Issue→Skill→PRテンプレで 再現性を作る

2026/01/31開催の機械学習の社会実装勉強会第55回 (https://machine-learning-workshop.connpass.com/event/382892/) の発表資料です。

Transcript

1. 機械学習の社会実装勉強会第55回 仕様書駆動AI開発の実践： Issue→Skill→PRテンプレで 再現性を作る 📅2026/01/31 👤西岡 賢一郎
2. アジェンダ 01 背景：詰まりの正体 02 仕様：Issueで明確化 03 実装：Issueに従う 04 レビュー：PRテンプレ 05 デモ＋改善
3. 背景：AI導入で詰まる点  PRが簡素で意図不明  仕様が曖昧で肥大化  検証不足で差し戻し
4.  典型の失敗 （例：曖昧Issue）  BEFORE  AC（完了条件）が無い / 弱い  Non-goals（やらない） が無い  背景が薄く迷う  AFTER  ACが明確で判定可能  範囲外が明記されている  背景・目的が明確 
5.  典型の失敗 （例：簡素PR）  BEFORE  Summaryだけ  Verificationなし  何を見れば不明  AFTER  Summary + Why記述  結果証拠あり  変更箇所が明確 
6. 全体像：再現性を作る3層構造 結論 3層（入力・処理・出力）で再現性を担保する    Issue テンプレ INPUT  Skills PROCESS  PR テンプレ OUTPUT
7. 提案 スタート地点：仕様は曖昧 01 まずIssueを作る  02 AIと議論して深掘り  03 人間が最終確定する   
8. Ask User Questionで深掘り  AIからの質問 曖昧な点を具体的に問う  人間からの回答 仕様・制約を補完する  RESULT Issueが明確化される Point  AIが質問して詰める  目的：情報の欠落を埋める  最終Issueは明確に
9.  深掘りの質問テンプレ（4点） CHECKLIST  誰の何の課題を解決するのか？ 背景・WHY  完了（成功）と言える条件は？ AC  今回スコープ外とすることは？ NON-GOALS  守るべき制約や影響範囲は？ CONSTRAINTS
10.  Issueテンプレ：入力の型 TEMPLATE 必須 最終Issueの必須：Why ＋ AC ＋ Non-goals ＋ Constraints 1 Problem / Why （背景） PROBLEM 2 Acceptance Criteria （受け入れ条件） AC 3 Non-goals （やらないこと） NON-GOALS 4 Constraints （制約事項） CONSTRAINTS 5 Tasks （作業チェック） TASKS
11. ACが形骸化する問題 ? “〜できる”は曖昧  手段を書くと縛る  結果が観測できない  結論：ACガイドが必要
12.  ACガイドライン 01 02 03 04  観測可能な結果を書く  入出力例が最強  例外系を1つ入れる  テストに落とせる形
13.  1 Issue 1 PR：粒度ルール 01 02 03 04  目的は1つに絞る  15〜60分でレビュー可  ロールバックしやすい  大きいIssueは分割
14.  実装の原則：Issueに従う 01 02 03  Issue（AC）を優先  迷ったらIssueへ戻る  planで範囲を宣言
15. 🛠️ Skills：手順の型 ➡️ ➡️ 🚀 実務版 create-issue （/issue-draft + /spec） ➡️ resolve-issue 🖨️ 生成される成果物 📄 spec.md 📝 plan.md 🐙 PR_DRAFT.md 📄 /spec Issue ⬇️ spec.md 1 📋 /plan やる / やらない ⬇️ 実装計画 2 🚢 /ship 実装・テスト ⬇️ PR作成 3
16.  PRテンプレ：出力の型  Summary 何を実装・変更したか 簡潔に記述する ? Why なぜこの変更が必要か 背景や意図を説明  Changes 具体的な変更箇所や 技術的な詳細リスト  Verification 作者が実行したコマンドと 結果要約を記述 （レビュワーは再実行可）  Risk / Rollback 潜在的なリスクと 問題時の切り戻し手順  Fixes #Issue 関連するIssue番号を リンクして自動クローズ
17. チェックが形骸化する問題  チェックだけでは証拠がない  “やったつもり”が増える  結論：結果を書く
18.  PRチェックのコツ（証跡を残す） REVIEW TIPS  未実施の項目はチェックを入れない NG行動  証跡：コマンド＋実行者＋結果要約 推奨  記述例：ファクトを残す make test（作者）： ✅ Fail0 / 5s EXAMPLE
19. 🖥️ デモ：ゴールと手順 🏁 GOAL テンプレが埋まった状態のPRを自動生成する ➡️ ➡️ ➡️ 👁️ Issue確認 📄 /spec 🚢 /ship ✅ PR本文(Verification)確認 ➡️ ➡️ ➡️ 📋 /plan 追加 ❌ テスト失敗 🛠️ AIが修正 ✅ 成功・PR作成 5 MIN 10 MIN 実務版（2コマンド） create-issue (/issue-draft + /spec でIssue+Spec作成) ➡️ resolve-issue (Spec再確認→実装→PR) ⚠️ ゲート：plan相当の「やる/やらない」を出す
20.  まとめ＋次アクション POINT：再現性を作る3つの型   NEXT ACTIONS  Issue 入力の型  Skill 手順の型  PR 出力の型  PREPARATION Issueを作り溜め Why / AC / Non-goals / 制約  EXECUTION resolve-issueでPR作成 （証跡を残す）