---
session: S04
exercise: B-3
title: Issue を起票する
duration: 7min
difficulty: 2
prerequisite: [B-2]
phases:
  テンプレートと記入例を読む: 2min
  5見出しを埋める: 3min
  再現手順をなぞる: 2min
files_to_edit:
  - kadaiB/issues/ISSUE_002_〈内容がわかる名前〉.md  # 自分で新規作成します
hints: hints/step06_issue_driven.md
challenge: true
tags: [Issue, テンプレート, 再現手順]
---

# 演習B-3 Issue を起票する

| 項目 | 内容 |
|---|---|
| 所要時間 | 7分 |
| 難易度 | 中 |
| 使うもの | `kadaiB/issues/` ／ Claude Code パネル ／ ブラウザ |
| 前提 | [B-2](exB2_plan_hunt.md) でバグ候補を2件特定していること |
| 次のステップ | [B-4 修正して、動かして、テストを通す](exB4_fix_and_test.md) |

---

## 目的

見つけた不具合を、**他人が読んで再現できる形の文書**にします。

B-2 で見つけた2件は、いまのところあなたの頭の中と `memo.md` の走り書きにしかありません。この状態で AI に「直して」と頼むと、直す対象が毎回ぶれます。会話の中で説明し直すことになり、説明の粒度によって出てくる修正も変わります。

**直す対象を先に文章で確定させる**のが Issue 駆動の入口です。文章にすると、直したかどうかの判定基準も同時に決まります。

---

## 操作

### 1. テンプレートを読む

`handson/kadaiB/issues/ISSUE_TEMPLATE.md` を開きます。見出しは5つです。

| 見出し | 何を書くか |
|---|---|
| 現象 | 何をしたら、何が起きたか。画面表示やエラーメッセージをそのまま |
| 期待する動作 | 本来どうなるべきか。業務ルールのどれに当たるかを明記する |
| 発生箇所 | ファイル名 / クラス名 / メソッド名 |
| 再現手順 | 起動から症状が出るまでを番号付きで |
| 修正方針 | どこをどう直すか、修正後の確認方法 |

**この5つを増やしも減らしもしません。** 項目が決まっていることに意味があります。読む側が、どこに何が書いてあるかを探さずに済みます。

### 2. 記入例を読む

`kadaiB/issues/ISSUE_001_詳細画面がエラーになる備品がある.md` を開きます。B-2 で見つけた1件目は、既にこの形で起票されています。

読むときに見てほしいのは、**再現手順の粒度**です。「詳細画面を開く」ではなく、どの備品のリンクを押したかまで書かれています。この粒度なら、初めて見る人でも同じ操作ができます。

### 3. 2件目のファイルを自分で作る

`kadaiB/issues/` の下に、新しい Markdown ファイルを作ります。ファイル名は次の形です。

```
ISSUE_002_〈内容がわかる名前〉.md
```

名前の付け方の例です。症状を短く言い切る形にします。

- `ISSUE_002_在庫5個の備品に要補充が出ない.md`
- `ISSUE_002_購入日の表示形式が一覧と詳細で違う.md`

この2つはどちらも実在の食い違いです。B-2 で自分が画面で再現できたほうを書いてください。両方見つけた場合は片方を `ISSUE_002_`、もう片方を `ISSUE_003_` にして、時間があれば B-4 の発展課題で直します。

### 4. 5見出しを埋める

`ISSUE_TEMPLATE.md` の中身をコピーして貼り付け、上から埋めます。埋めにくい欄は AI に相談します。

```
@kadaiB/issues/ISSUE_TEMPLATE.md の形式で、いま見つけた〈症状を自分の言葉で〉について Issue の下書きを作ってください。再現手順は実際に操作した順で書いてください。「期待する動作」には CLAUDE.md の業務ルールのどれに当たるかを書いてください。
```

### 5. 再現手順を自分でなぞる

**ここがこのステップで最も大事な手順です。**

AI が書いた下書きをそのまま採用せず、再現手順の1から順に、実際に操作してください。書かれたとおりに操作して、同じ症状が出ますか。

出ない場合は、手順が足りていません。よくある抜けは次の3つです。

- アプリの起動から書き始めていない
- どの備品を選ぶかが書かれていない（「任意の備品」では再現しないことがあります）
- 検索や絞り込みなど、途中の操作が抜けている

抜けを見つけたら、自分で書き足してください。**AI に直させるより、自分で1行足すほうが速い**場面です。

---

## 自分で考える

AI が書いた再現手順のとおりに操作して、本当に同じ症状が出ましたか。

**出なかった場合、どの一手順が足りていませんでしたか。**

足りなかった手順は、あなたが「言うまでもない」と思って伝えなかったことのはずです。AI は、あなたが画面で何をしたかを見ていません。伝えた範囲でしか書けません。**再現手順が書けないバグは、直ったことも確認できません。**

---

## 生成物の名前と場所

`handson/kadaiB/issues/ISSUE_002_〈内容がわかる名前〉.md`

中身は5見出しがすべて埋まった状態にします。空欄や「（記入予定）」を残さないでください。

---

## OK基準

- ファイル名が `ISSUE_002_` で始まり、内容がわかる日本語が続いている
- 5つの見出しがすべて埋まっている
- 「期待する動作」に、`CLAUDE.md` の業務ルール5項目のどれに当たるかが書かれている
- 「発生箇所」にファイル名とメソッド名が書かれている
- 再現手順どおりに操作して、実際に症状が再現した

---

## 追加と考察

Issue はここではローカルの Markdown ファイルです。本研修では課題管理ツールも共有リポジトリも使いません。

それでも機能します。理由は、Issue の価値が**保管場所ではなく、書く項目が決まっていること**にあるからです。5項目が埋まっていれば、修正を依頼するときに `@` でファイルを指すだけで、対象と判定基準がまとめて伝わります。

実務で使うときは、次の順で足していくと無理がありません。

1. まずテンプレートを決める（今日のこれ）
2. 置き場所をチームで1か所に決める
3. 必要になったら、課題管理ツールに移す

順番を逆にして、ツールから入ると「項目が埋まっていない Issue」が溜まります。埋める項目が決まっていないと、AI にも人にも渡せません。

---

## 発展課題

「修正方針」の欄を、AI に2案出させてください。

```
この Issue の修正方針を2案出してください。それぞれについて、影響が及ぶ範囲と、確認しなければならないことを書いてください。
```

2案のうちどちらを選ぶかを決めるとき、**あなたは何を基準にしましたか。** 変更が小さいこと、他の画面に影響しないこと、業務ルールへの合致、いずれも基準になります。選んだ基準を Issue の「修正方針」欄に1行書き足してください。

この1行があると、あとから読んだ人が「なぜこの直し方にしたのか」を辿れます。

---

## 詰まったときは

**新しいファイルの作り方がわからない**

VSCode のエクスプローラで `issues` フォルダを右クリックし、「新しいファイル」を選びます。ファイル名を入力すると空のファイルが作られます。AI に作らせる場合は、置き場所とファイル名を明示してください。

```
kadaiB/issues/ISSUE_002_〈名前〉.md というファイルを作ってください。
```

**「期待する動作」に何を書けばよいかわからない**

`handson/CLAUDE.md` の `## 業務ルール（課題B）` を開き、5項目を読んでください。いま見つけた症状は、そのどれかに反しているはずです。反している項目をそのまま引用して書きます。

**再現手順が長くなりすぎる**

起動からの操作をすべて書く必要はありません。**症状が出る直前の3手順**が具体的なら十分です。ただし、どの備品を選ぶかは必ず書いてください。

**AI が Issue に修正コードまで書いてしまった**

Issue には方針だけを書きます。コードは次のステップで書きます。次のように直させてください。

```
Issue にはコードを書かないでください。「どこをどう直すか」の方針だけに書き直してください。
```

**ファイル名に日本語が使えるか不安**

使えます。既にある `ISSUE_001_詳細画面がエラーになる備品がある.md` が同じ形式です。空白は入れず、区切りにはアンダースコアを使ってください。
