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 ベースの開発が最大の効果を発揮します。