AI時代の個人開発でIssueをどう書くべきか
はじめに
AI（Claude Code、ChatGPT）を使った開発では、Issue の品質が実装の品質に直結します。曖昧な Issue では AI に曖昧な実装をされてしまうため、明確で構造化された Issue が必須です。本記事では、AI に任せやすい Issue の書き方を具体例で解説します。
悪い Issue の例
Title: ユーザー機能を改善
Description:
ユーザー管理画面を改善したい。
UI をわかりやすくして、
バグも修正してほしい。
問題：
- 「改善」の定義が曖昧
- どのバグか不明
- 成功条件が不明確
- AI が勝手に複数ファイルを変更する可能性
良い Issue の構造
# Issue Title: ユーザープロフィール編集画面のバリデーション改善
## 背景
現在のユーザープロフィール編集画面では、
フォーム送信時に全フィールドを送信しており、
空白値でも送信可能。
ユーザーから「入力忘れに気づきにくい」という
フィードバックが複数件。
## 目的
各フィールドの入力漏れを事前に検出し、
わかりやすいエラーメッセージを表示する。
## 実装範囲
対象ファイル:
- src/components/UserProfileForm.tsx（修正）
- tests/components/UserProfileForm.test.tsx（テスト追加）
対象フィールド:
- ユーザー名（必須、1-50 文字）
- メールアドレス（必須、有効形式）
- 自己紹介（任意、0-500 文字）
対象外:
- プロフィール画像のアップロード機能
- DB スキーマ変更
- サーバーサイド validation（既存使用）
## 完了条件
- [ ] 各フィールドの入力チェックが実装されている
- [ ] 空白のまま送信ボタンを押すと、
「必須フィールドを入力してください」と表示
- [ ] 文字数制限超過時に「nn 文字以内で入力してください」と表示
- [ ] メールアドレスが不正形式の場合、
「有効なメールアドレスを入力してください」と表示
- [ ] 既存テスト全 pass
- [ ] 新規テストケース 5 個以上で検証
## 参考資料
既存の validation 例: src/components/LoginForm.tsx
テストパターン: tests/components/LoginForm.test.tsx
エラーメッセージ定義: src/constants/messages.ts
## 注意点
- 修正中は既存機能を壊さない
- エラーメッセージは既存の messages.ts を参照
- UX 関連の変更は避ける（エラー表示のロジックのみ）
Issue の 5 要素
1. 背景（Why）
## 背景
現状の問題：
- ユーザーがどのフィールドが必須か判からない
- エラーメッセージが技術的
根拠：
- サポートチケット過去 3 件が「入力エラーで困った」
- ユーザーテスト結果：入力エラー率 35%
2. 目的（Goal）
## 目的
実装後の期待状態：
- 入力エラー率 10% 以下
- サポートチケット削減
- ユーザー満足度向上
3. 実装範囲（Scope）
## 実装範囲
対象ファイル: 明確に列挙
修正対象:
- src/components/UserForm.tsx
作成対象:
- なし
テスト:
- tests/components/UserForm.test.tsx に 5 ケース追加
対象外:
- DB スキーマ
- サーバーサイド
- デザイン変更
4. 完了条件（Definition of Done）
## 完了条件
実装完了とみなす基準：
技術的:
- [ ] TypeScript で型エラーなし
- [ ] 既存テスト全 pass
- [ ] 新規テスト 5 ケース pass
- [ ] git diff が 100 行以下
機能的:
- [ ] 各フィールド validation が動作
- [ ] エラーメッセージが表示される
- [ ] 正常な入力で送信可能
品質:
- [ ] ChatGPT コードレビュー通過
- [ ] 既存メッセージ定義を使用
5. 参考資料（Reference）
## 参考資料
既存コード例:
- src/components/LoginForm.tsx（validation 参考）
テストパターン:
- tests/components/LoginForm.test.tsx
メッセージ定義:
- src/constants/messages.ts
API 仕様:
- docs/api/users.md
Issue を書くときのチェックリスト
背景（Why）
- [ ] 現状の問題が説明されているか
- [ ] なぜこの Issue が必要か理由が明確か
- [ ] 根拠（ユーザーフィードバック、バグなど）があるか
目的（Goal）
- [ ] 実装後の期待状態が明確か
- [ ] 測定可能な成功基準があるか
実装範囲（Scope）
- [ ] 対象ファイルが明記されているか
- [ ] 対象外（やらないこと）が明確か
- [ ] テスト対象が具体的か
完了条件（DoD）
- [ ] テスト項目がチェックリスト形式か
- [ ] 合格基準が数値化されているか
- [ ] AI が判定可能か
参考資料（Reference）
- [ ] 似た機能の実装例があるか
- [ ] テストパターン例があるか
- [ ] API 仕様へのリンクがあるか
AI に Issue を渡すときのコツ
コツ1：Issue をそのまま AI に渡す
人間：「Issue を実装してください」
↓
Claude Code が Issue を読んで実装開始
→ 背景と完了条件が明確なら、質問が少ない
→ スムーズに実装が進む
コツ2：迷ったら Issue で確認
実装中に質問が出た時：
Claude Code：「ここはどうしますか？」
↓
Issue を再度確認：
「対象外」と書かれていれば、その部分は実装しない
「参考資料」で例を確認
コツ3：Issue の優先度を示す
## 優先度
High: バグ、セキュリティリスク
Medium: 機能改善、パフォーマンス
Low: UI 改善、ドキュメント更新
この Issue は: Medium（完了期限なし）
まとめ
AI を使った開発では、Issue の質が実装の質を決めます。
良い Issue の要素：
- 背景（Why）：なぜこの Issue が必要か
- 目的（Goal）：実装後の期待状態
- 実装範囲（Scope）：対象ファイル、対象外を明確に
- 完了条件（DoD）：テスト項目をチェックリスト化
- 参考資料（Reference）：既存コード例へのリンク
Issue が明確なら：
- AI は質問が少なくて済む
- 実装が早い
- 品質が高い
- 修正が少ない
AI に任せるタスクと人間が決めるタスクの分け方と合わせることで、Issue ベースの開発が最大の効果を発揮します。