最近、AIエージェントに「次の最小タスクを選んで実装して」と頼むことが増えました。これ、かなり便利なんですが、Issueがあるだけだと意外とすぐには進みません。

大きいIssueをそのまま渡すと、調査、設計、実装、検証、記事化、PR作成が全部混ざります。進んでいる感じは出るけれど、あとから見ると「で、このPRは何を閉じるんだっけ？」となりやすいです。

なので自分は、AIエージェントに実装を頼む前に、まず すぐPRにできるIssueかどうか を見ます。ここで言う「すぐ」は、雑に作るという意味ではなく、変更範囲と検証方法が小さく閉じている、という意味です。

Issueだけ見て決めない

まず現在地を見る

最初に見るのは、Issue本文だけではありません。Issueには「やりたいこと」が書いてありますが、それが今の実装状態と合っているとは限らないからです。

自分はだいたい、この順番で見ます。

git status --short --branch
gh issue list --state open

そのうえで、対象になりそうなIssueを開いて、READMEや関連docs、今の実装ファイルも見ます。

gh issue view 123
rg -n "関連しそうな言葉" README.md docs src

Issue本文だけを読んで「これできそう」と判断すると、すでに実装済みだったり、別PRで前提が変わっていたりします。特に個人開発では、Issueを書いた日と実装する日がずれるので、現在地の確認を挟むのが大事です。

作業ブランチも見る

もう1つ、今どのブランチにいるかも見ます。

git status --short --branch
git log --oneline -5

前のPRブランチにいるまま次の作業を始めると、差分が混ざります。小さいPRにしたいなら、まずmainを最新化して、そこから作業ブランチを切るほうが安全です。

git switch main
git pull --ff-only origin main
git switch -c feature/small-task

ここを雑にすると、Issueの粒度以前にPRの差分が読みにくくなります。

すぐPRにできるIssueの条件

変更範囲が1つに閉じている

自分の中で一番分かりやすい条件は、変更範囲が1つの論点に閉じていることです。

たとえば、次のようなIssueはPRにしやすいです。

  • 記事を1本追加する
  • READMEに手順を1つ追記する
  • 診断表示を1箇所だけ増やす
  • 入力ガードを1つ追加する
  • CIの失敗ログから分かった原因をdocsへ残す

逆に、次のようなIssueは、そのままだと大きいことが多いです。

  • UIを全体的に改善する
  • AIエージェント運用を整える
  • ブログ設計を見直す
  • テストをちゃんとする
  • 使いやすくする

こういうIssueが悪いわけではありません。ただ、PRにする前に「どの画面」「どのファイル」「どの検証」まで切る必要があります。

検証コマンドが言える

次に見るのは、検証コマンドが言えるかです。

npm run test:content
npm run content:index:check
npm run lint:prose
npm run build

記事追加ならcontent checkとbuild。UI変更ならbuildに加えてスクリーンショット確認。CI修正なら該当jobの再実行。ここが言えないIssueは、まだ作業単位として粗いことが多いです。

実装前に完璧な検証計画を作る必要はないですが、「このPRは何が通ればOKか」を一言で言える状態にはしておきたいです。

PR本文で閉じ方が書ける

Issueを選ぶとき、PR本文を先に想像するのも効きます。

## 概要

Issue #123 対応です。

Closes #123

## 変更内容

- ...

## 確認

- ...

この形に入らないなら、まだIssueが大きいか、目的が曖昧です。PR本文を書ける粒度まで絞ると、実装中に寄り道しにくくなります。

大きいIssueは切り直す

分解はサボりではない

大きいIssueを見つけたとき、無理に全部やらないほうがいいです。AIエージェントは手が速いので、任せると一気に進めてくれます。でも、速く進むほど差分も大きくなります。

自分は、大きいIssueを見たら次のように分けます。

  • まず調査だけ
  • 次にdocs追記だけ
  • 次に小さい実装だけ
  • 最後に導線や整理

分解するとIssue数は増えます。ただ、これはサボりではなく、レビューできる形にするための準備です。

「あとでやる」をIssueに残す

小さいPRにすると、当然ながら残るものがあります。その残りを頭の中に置くと忘れます。

だから、残りはIssue本文や別Issueに書きます。

## 残タスク

- Windowsでの動作確認は別Issueで行う
- UI文言の整理は次PRに分ける
- 価格や仕様の最新確認は公開前に行う

ここまで書いておくと、今回のPRでやらないことが明確になります。やらないことが見えているPRは、かなりレビューしやすいです。

AIエージェントに渡す前のチェックリスト

自分用の基準

最近は、Issueを選ぶ前にこのあたりを見ています。

  • 変更範囲は1つの論点に閉じているか
  • 触るファイルはだいたい1〜2箇所に収まりそうか
  • 検証コマンドを先に言えるか
  • PR本文に Closes #... を入れられるか
  • やらないことを説明できるか
  • privateなログやsecretを本文や差分に持ち込まないか

全部に厳密である必要はありません。ただ、このうち半分以上が曖昧なら、いきなり実装に入らず、Issueを切り直したほうがいいです。

小さいPRは、あとから効く

小さいPRは、作っている最中は少し地味です。でも、あとから効きます。

どのIssueを閉じたか分かる。どの検証をしたか分かる。レビューで見ればいい差分が少ない。必要ならrevertもしやすい。AIエージェントに任せるなら、この「あとから追える」ことがかなり大事だと思っています。

速く作れるようになったからこそ、最初に少しだけ切る。IssueをPRに変える前の、この小さい棚卸しを入れるだけで、作業の見通しはかなり良くなります。