動機

最近 Superpowers や Spec Kit といったコーディングエージェントのフレームワークが登場していますが、いわゆる Spec ファイル（その機能の要件や実装方針を記した markdown ファイル）をリポジトリに含めて永続管理する前提のフレームワークがほとんどです。

それらのフレームワークは GitHub Issue を中心とした自分の個人開発にマッチしないと感じたので、自分用にフレームワーク issuekit を作ってみました。

コンセプト

issuekit では、GitHub Issue を中心とした開発スタイルを提供します。

AI 用の特殊な spec ファイルを用意せず、追加したい機能や修正したいバグに関して Issue を起票し、適宜その Issue を実装していく従来の Issue ワークフローをそのまま使う流れです。

Issue ドリブンのメリット

• Spec ファイルを使うフレームワークと違い、実装中の計画や方針など実装後は参照されなくなる情報を GitHub Issue 側で管理するため、コードベースが余計なファイルで膨らみません。
• まだ実装着手まではしたくない事項に関しても GitHub Issue として起票してエージェントと方針の会話だけ進めておくことができます。

Issue の項目と受け入れ条件の明確化

Issue に次の項目を記載します。

• ステータス
• 依存 Issue
• 概要
• 背景
• 受け入れ条件
• スコープ外

特に重要なのが 受け入れ条件

(=What) です。これが明確化できていれば、ユーザと AI で完成像が食い違って「思っていた機能と違う」という手戻りを防止できます。

実装方針 (=How) は Issue に記載されていなくても構いません。

ただ、追加したい機能を思いついたとき、その場で受け入れ条件まで全て記載するには時間がないケースもあるでしょう。そこで、ステータス

で受け入れ条件が明確化されているかを管理しています。ステータス: Ready

= 明確化されている、ステータス: Draft

= 明確化されていない、です。issue-implement

は ステータス: Ready

の Issue でしか動きません。

全体像

issuekit における開発の流れの全体像を記します。

• Issue をステータス：Ready にするまでの流れ

• ユーザが〇〇の機能が欲しいと伝えると、エージェントが issue-create で Issue を起票します。

• ユーザが要望すると、ユーザがエージェントを介さずに雑に起票した Issue を、エージェントが issue-refine でフォーマットを整えます。

• ユーザがどの Issue を着手すべきか相談すると、エージェントが issue-pick で Issue を選択します。

• ステータス：Ready の Issue の着手から PR 作成までの流れ

• ユーザがこの Issue を着手して欲しいと伝えると、エージェントが issue-implement を使って Issue を元に実装します。

• エージェントは実装後に cross-review を使って別エージェントにコードレビューを依頼します。

• エージェントは commit 前に acceptance-check を使って、Issue の受け入れ条件を満たしているかチェックします。

• ユーザがこの Issue を着手して欲しいと伝えると、エージェントが

後は、ユーザが PR を確認してマージするだけです。

インストール方法

issuekit は、skills.sh 経由で利用できます。

npx skills add hirokisakabe/issuekit

を実行すると、必要な Skill ファイルがインストールされます。

後は、Claude Codeなどのコーディングエージェントを起動し、前述の流れで開発していくだけです。

まとめ

ここ一ヶ月ほど個人開発で使っていますが、Spec ファイルでコードベースを膨らませずに、Issue を実装計画の置き場として扱うスタイルが自分にはちょうどよく感じています。GitHub Issue を中心に開発している方は試してみてください。