AIに「いい感じに直して」と頼むのをやめて、GitHub Issueを作業の正本にした

この記事は、自分の個人開発の中で気づいたことを、AIに整理してもらいながら書いています。この記事では、実体験、仮説、未検証の構成案を分けて残します。実体験としてあるのは「AIに実装を任せるとき、雑な依頼よりIssueの書き方の方が効いた」という部分です。

この記事の対象読者

• Codex / Claude Code / GitHub Copilot coding agent などに実装を任せている人
• AIに「いい感じに直して」と頼んで、差分が大きくなりすぎたことがある人
• GitHub IssueをAI開発の作業単位として使いたい人
• レビューしやすいAI PRを作りたい人
• 検証コマンドや完了条件をIssueにどう書くか迷っている人

この記事で得られること

• AIに渡しやすいGitHub Issueの最小フォーマット
• 設計メモとGitHub Issueの違い
• Goal / Scope / Done / Out of scope の使い方
• 検証コマンドをIssueに固定する理由
• AIが触りすぎるのを減らすための書き方
• 自分の個人開発repoで直近20PRを見たときの運用規模

結論

AIに実装を任せるとき、プロンプトを頑張るより先に、GitHub Issueを作業の正本にした方が効く場面があると気づいた。

最初は、設計メモを書いてからAIに詳しく説明すればうまく動くと思っていた。

でも実際には、設計メモだけでは作業の状態が流れやすかった。背景、目的、触ってよい範囲、触ってはいけない範囲、完了条件、検証コマンドがGitHub Issueに残っていないと、AIも人間も「このPRは何を閉じるものか」を後から追いにくい。

もうひとつ大きかったのは、GitHub Issueの方が開発フローに組み込みやすかったことだ。

ChatGPTで相談して出てきた実装案を、そのままIssue候補に整形し、GitHub Issueとして作成できる。そこからCodexや別のAIエージェントに渡し、PR、CI、レビューへつなげられる。

つまり、自分にとってのGitHub Issueは、単なるタスク管理ではなく、ChatGPTで考えたことを開発フローへ流し込む入口になった。

ざっくりした体感では、ChatGPTで相談した内容からIssue化するものは1日5-10件くらいある。

もちろん、すべてがそのまま実装されるわけではない。調査で止めるもの、保留するもの、あとでまとめるものもある。

それでも、ChatGPT上で流れていく相談をIssue候補に変換できると、思いつきが開発フローに乗る確率はかなり上がった。

自分にとって大きかったのは、以前は相談や設計までは進んでも、最後まで到達しないことが多かった点である。

会話の中では「これは良さそう」と思う。設計メモも書ける。けれど、次に何を実装し、どのPRで閉じ、どの検証で完了にするかが曖昧なままだと、途中で別の話題に流れてしまう。

GitHub Issueにすると、少なくとも「この作業はまだopenなのか」「どのPRで閉じるのか」「Doneは何か」が残る。

それによって、相談で終わっていたものを、完了まで運びやすくなった。

今のところ、自分の個人開発では、Issueに次の4つを書くと扱いやすい。

Goal
Scope
Done
Out of scope

この記事は「Issue駆動開発はこうあるべき」という話ではない。AIに作業を任せるときに、なぜ設計メモだけでなくGitHub Issueに落とすのか、Issueをどう書くとPRレビューしやすくなるかを整理したメモである。

直近の個人開発repoで見た数字

この記事を書いている時点で、自分の個人開発repoの直近20件のPRとIssueを見てみた。

これは厳密な効果測定ではない。Issueテンプレを入れる前後で比較したわけでもないし、Scope外変更を1件ずつ分類したわけでもない。

ただ、AIに作業を任せるときに、どのくらいの量のIssue/PRが流れているのかを示す材料にはなる。

2026-05-19時点で、GitHub上の直近20件を見ると次のような状態だった。

対象	見た件数	結果
PR	20件	19件merged、1件closed
Issue	20件	13件closed、7件open
PRの変更ファイル数	20件	中央値3.5ファイル、最小1ファイル、最大12ファイル

この数字から言えるのは、「Issueを書けば必ずうまくいく」ということではない。

むしろ、自分の個人開発では、短い期間に小さめのPRが何本も流れる状態になっていた。こうなると、チャットの中だけで依頼を管理するのはつらい。

PRが増えるほど、次を後から追えることが重要になる。

• 何を直すIssueだったか
• どのPRで閉じたか
• どの検証コマンドを通したか
• 何をScope外にしたか
• 途中でcloseしたPRはなぜ閉じたか

だから、自分にとってGitHub Issueは「AIに渡すプロンプト」ではなく、作業の状態を残すための正本に近くなった。

ちなみに、今回の数字は次のような観点で見た。

gh pr list --state all --limit 20
gh issue list --state all --limit 20

次にちゃんと測るなら、PRごとに「Scope外変更があったか」「Doneの検証コマンドがPR本文やコメントに残っているか」を数えたい。

対話で整理する

A: AIに頼むなら、チャットで詳しく説明すればよくない？

B: 最初はそう思っていた。ただ、チャットだけだと作業単位が流れやすい。

A: Issueを書くのは面倒では？

B: 面倒ではある。ただ、後からPRを読むときに、Issueがある方が「何を直すはずだったか」を確認しやすい。

A: AIなら広く読んで、ついでに直してくれる方がよくない？

B: 小さい修正なら逆に困ることがある。ついでの修正が増えると、レビューが重くなる。

背景

AIコーディングを使うと、実装そのものは速くなる。

ただ、自分の中で困ったのは、AIが速すぎることではなく、作業の境界が曖昧になることだった。

たとえば、こんな依頼をすると危ない。

この周辺をいい感じに直してください。

人間同士なら、暗黙の文脈で伝わることがある。

でもAIに渡すと、どこまで読んでよいのか、どこまで直してよいのか、どの検証が通れば完了なのかが曖昧になる。

その結果、次のようなことが起きやすい。

• 変更範囲が広がる
• 関係ないリファクタが混ざる
• テストやworkflowまで触る
• 完了条件が分からない
• レビュー時に「これは必要だったのか」が判断しづらい

自分も、最初は「ついでに直してくれるなら助かる」と思っていた。

でも、小さな修正のつもりだったのに、周辺の整理や別の検証まで入り始めると、PRを見る側の負荷が上がる。AIが悪いというより、渡し方が曖昧だった。

ここで、Issueを単なるタスクメモではなく、AIに渡す作業契約として書いた方がよさそうだと感じた。

設計メモではなくGitHub Issueにする理由

A: それなら、先に設計メモを書けば十分では？

B: 設計メモも必要だと思う。ただ、AIに実装を任せる作業単位としては、GitHub Issueの方が扱いやすかった。

設計してから実装すること自体は大事である。

ただ、自分がIssueに寄せたいと思った理由は、設計内容そのものではなく、作業の状態がGitHub上に残ることだった。

設計メモとGitHub Issueでは、役割が少し違う。

観点	設計メモ	GitHub Issue
目的	考えを深める	作業単位を固定する
状態	書いた時点で止まりやすい	open / closedで追える
PRとの関係	手動で紐づける	Closes #123 で紐づく
コメント	文書への追記になりがち	作業ログ、質問、判断が時系列で残る
CIとの関係	直接はつながらない	PR、checks、reviewと一緒に追える
検索性	Vaultやローカル検索に寄る	GitHub上でIssue/PR横断検索できる
AIへの渡し方	文脈として渡す	作業チケットとして渡す
ChatGPTからの接続	メモとして残る	Issue候補として作成し、AI実装フローへ渡せる

自分の中では、設計メモは「考える場所」、GitHub Issueは「作業を発行する場所」に近い。

AIに任せるときに欲しいのは、きれいな設計文書だけではなかった。

欲しかったのは、次が1か所にまとまっていることだった。

• この作業は何を閉じるのか
• 誰が、いつ、何を判断したのか
• どのPRにつながったのか
• どのCIが通ったのか
• レビューで何を指摘されたのか
• 最後にcloseされたのか

これは設計メモだけだと弱い。

GitHub Issueにしておくと、PR本文に Closes #123 を書ける。コメントで質問も残せる。ラベルで bug、enhancement、codex-ready のように状態も分けられる。あとから同じ失敗を探すときも、IssueとPRをまとめて追いやすい。

さらに、ChatGPTで相談した内容をIssue化できるのも大きい。

たとえば、ChatGPTとの会話で次が出る。

• 背景
• 問題
• 実装方針
• 反対意見
• 検証コマンド
• やらないこと

これをそのまま記事や設計メモで終わらせると、あとで開発に戻すときにもう一度整理が必要になる。

でも、Goal / Scope / Done / Out of scope に圧縮してGitHub Issueにすると、そのままAI実装フローへ渡せる。

だから、自分にとってのIssue駆動は「設計してからやる」の言い換えではなく、設計した作業をGitHub上の追跡可能な単位に変換することだった。

もう少し正確に言うと、ChatGPTで考えたことを、GitHub Issueという実行可能な作業単位へ変換することだった。

この形にしてから、Scope外変更は明らかに減ったと感じている。

ただし、ここはまだ体感である。導入前後でPR差分行数やScope外変更件数を集計したわけではないので、この記事では「減った」と断定しすぎず、次に測る対象として残しておく。

雑な依頼とIssue駆動依頼の違い

A: 具体的に何が違うの？

B: AIへのお願いではなく、GitHub上で追跡できる作業単位にするところが違う。

雑な依頼:

このエラーを直してください。

Issue駆動の依頼:

## Goal

`npm run typecheck` の失敗を直す。

## Scope

- 変更してよい: `src/**/*.ts`
- 変更しない: workflow, package manager, test fixtures

## Done

- `./scripts/verify.sh fast` が通る

## Out of scope

- integration test
- E2E
- package build

この差は大きい。

Issue駆動にすると、AIにとっても人間にとっても、次が分かりやすくなる。

• 何を達成するか
• どこを触ってよいか
• どこを触らないか
• 何が通れば完了か
• 今回やらないことは何か

自分が使いやすかったIssueの型

今のところ、最小はこれでよいと感じている。

## Goal

何を達成するかを1文で書く。

## Background

なぜ必要かを書く。長くしすぎない。

## Scope

- 変更してよい:
- 変更しない:

## Done

- 通すコマンド:
- 確認する画面:
- 更新するドキュメント:

## Out of scope

- 今回やらないこと:

## Notes

- 迷いそうな制約:
- 関連Issue:
- 参考ログ:

全部を毎回埋める必要はない。

ただ、Goal、Scope、Done、Out of scope はできるだけ入れたい。

なぜScopeを書くのか

A: Scopeを書くと、AIの良さを狭めない？

B: 大きな調査では狭めすぎない方がよい。ただ、小さな修正ではScopeがない方が危ない。

AIに任せるとき、自由度が高いほど良いとは限らない。

特に小さなPRでは、変更範囲を狭くした方がレビューしやすい。

たとえば、TypeScriptの型エラーを直したいだけなのに、workflowやpackage managerまで変わると困る。

Issueにこう書いておくだけで、AIにも人間にも境界が見える。

## Scope

- 変更してよい: `src/**/*.ts`
- 変更しない: `.github/workflows/**`, `package.json`, `pnpm-lock.yaml`

もちろん、AIが作業中に「Scope外を触らないと直らない」と判断することもある。

その場合は、勝手に広げるのではなく、コメントやメモで止まる方が扱いやすい。

Doneには検証コマンドを書く

Issue駆動で一番効いたのは、Done に検証コマンドを書くことだった。

## Done

- `./scripts/verify.sh fast` が通る

これだけで、AIに渡す指示がかなり変わる。

雑な指示:

直してください。

検証条件つきの指示:

このIssueでは `./scripts/verify.sh fast` が通るところまで直してください。

AIは「何をもって完了か」が分かる。

人間も、PRを見るときに同じコマンドで確認できる。

Out of scopeでやらないことを決める

A: やらないことまで書く必要がある？

B: AIに任せるときほど、やらないことを書いた方がよかった。

AIは親切に見える修正を足しがちである。

もちろん、それが助かる場面もある。

ただ、Issue単位で小さく進めたいときは、親切な追加修正がレビュー負荷になる。

たとえば、今回のIssueではE2Eまで見ないなら、最初から書く。

## Out of scope

- E2Eの修正
- package buildの改善
- workflowの整理
- ついでのリファクタ

これはAIを縛るというより、今回のPRを小さく保つための境界線である。

IssueをAIに渡す前のチェックリスト

自分なら、AIに渡す前にこれを見る。

[ ] Goalが1文で書けている
[ ] 変更してよいファイルが書かれている
[ ] 変更しないファイルが書かれている
[ ] Doneに検証コマンドがある
[ ] Out of scopeがある
[ ] 失敗ログがある場合、code failureかplatform failureか分けている
[ ] 1PRで終わる粒度になっている

CIが失敗しているIssueなら、失敗の種類も分ける。

分類	例	AIに任せるか
code failure	test, typecheck, lint	任せやすい
workflow failure	install, cache, workflow設定	任せられるが確認が必要
platform failure	billing, quota, runner不足	コード修正ではない
external failure	registry, network, 外部API	再実行や待機を検討

この分類をしないと、AIにコードを直させても解決しない失敗を、ずっとコード側で追うことになる。

小さく始める手順

最初からIssue運用を完璧にする必要はない。

まずは、次の順番でよいと思う。

1. 直近でAIに任せたい小さな修正を1つ選ぶ。
2. その修正を Goal / Scope / Done / Out of scope に分ける。
3. Done に検証コマンドを1つ書く。
4. GitHub Issueとして作る。
5. AIにIssue URLまたはIssue番号を渡す。
6. PR本文に Closes #issue_number を入れる。
7. PR差分がScope内に収まっているか見る。
8. 検証コマンドが通ったか確認する。
9. Scope外の変更が出たら、Issueテンプレを直す。

最初の目的は、自動化ではなく、レビューしやすい作業単位を作ること。

GitHub Issueにする意味は、ここで出る。

チャットや設計メモだけだと、作業が終わったあとに「どの依頼から始まったPRか」を追いづらい。Issueにしておけば、Issue、PR、CI、レビュー、closeがつながる。

コピペ用テンプレート

最後に、実際に使うならこのくらいの短さでよいと思っている。

## Goal

<!-- 何を達成するかを1文で書く -->

## Scope

- 変更してよい:
- 変更しない:

## Done

- [ ] 検証コマンド:
- [ ] 確認内容:

## Out of scope

- 今回やらないこと:

## Notes

- 関連ログ:
- 関連Issue:
- 迷いそうな制約:

AIに渡すときは、このIssue本文を正本にして、チャット側では補足だけを渡す。

失敗しやすいIssue

やっていて危ないと感じたIssueはこういうものだった。

• Goalが複数ある
• Scopeがない
• Doneが「いい感じになっている」になっている
• Out of scopeがない
• 調査、設計、実装、検証が1つのIssueに混ざっている
• 失敗ログがなく、AIが再現できない
• 1PRで終わらない

ただ、自分の場合は「AIが変なコードを書く」よりも前の段階で止まることが多かった。

つまり、相談、設計、調査までは進むが、実装、PR、検証、closeまで到達しない。

これはIssueの中身が悪いというより、作業単位がGitHub上に発行されていなかったことが大きかった。Issueがないと、ChatGPTで考えた内容が会話ログやメモの中に残るだけで、開発フローに乗らない。

GitHub Issueにしてからは、少なくとも次の状態を追えるようになった。

• openのまま残っている
• PRに紐づいた
• CIで落ちている
• review待ちになっている
• closeされた

「最後まで到達しない」を減らすには、Issue本文をきれいにするだけでなく、Issueとして発行して状態を持たせることが効いた。

特に、調査もして、設計もして、実装もして、必要ならテストも直して のようなIssueは大きくなりやすい。

AIに渡すなら、次のように分けた方が扱いやすい。

Issue 1: 原因を調べる
Issue 2: 修正方針を決める
Issue 3: 最小修正を入れる
Issue 4: テストを追加する
Issue 5: ドキュメントを更新する

まとめ

AIに実装を任せるとき、プロンプトをうまく書くことも大事だと思う。

ただ、自分の個人開発では、それ以上にGitHub Issueを作業の正本にすることが効いた。

設計メモは考える場所として必要である。

一方で、AIに任せる作業は、GitHub Issueにした方が追いやすい。

理由は、IssueがPR、CI、レビュー、コメント、close状態とつながるからである。

今のところ、Issueには次を書くのが扱いやすい。

• Goal
• Scope
• Done
• Out of scope
• 必要ならBackgroundとNotes

AIに「いい感じに直して」と頼むより、Issueに作業境界と検証条件を書く。

それだけで、PRが小さくなり、レビューしやすくなり、失敗したときも戻しやすくなる。

AIがコードを書く時代には、人間の仕事はプロンプトを書くことだけではなく、AIが迷わず、人間が後から追えるGitHub Issueを書くことにも寄っていくのかもしれない。