Skip to content
Skills Library
Management & product · Planning

issue-driven-dev

/issue-driven-dev

Issue起点で人間+AIエージェントの開発を回すスキル。GitHub Issueの作成・分解・トリアージ、Issue Forms(YAML)テンプレート、ラベル体系(type/priority/status)とマイルストーン運用、GitHub Flow/トランクベースのブランチ戦略選択、AIエージェントへのタスク委任・並列化、ADR/Design Docの書き分けと記録設計、PRレビュー規律(Small CL・Conventional Comments・AI一次レビュー)の作業時に必ず使用する。「Issueを立てて」「Issueに分解して」「チケット化して」「タスク分割して」「ラベル設計して」「ブランチ戦略どうする」「ADR書いて」「Design Doc書いて」と言われたときにも使う。計画立案と Issue 作成の知識正本。

Repository
cc-plugins ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Issue起点で人間+AIエージェントの開発を回すスキル。GitHub Issueの作成・分解・トリアージ、Issue Forms(YAML)テンプレート、ラベル体系(type/priority/status)とマイルストーン運用、GitHub Flow/トランクベースのブランチ戦略選択、AIエージェントへのタスク委任・並列化、ADR/Design Docの書き分けと記録設計、PRレビュー規律(Small CL・Conventional Comments・AI一次レビュー)の作業時に必ず使用する。「Issueを立てて」「Issueに分解して」「チケット化して」「タスク分割して」「ラベル設計して」「ブランチ戦略どうする」「ADR書いて」「Design Doc書いて」と言われたときにも使う。計画立案と Issue 作成の知識正本。

Original author description

Issue起点で人間+AIエージェントの開発を回すスキル。GitHub Issueの作成・分解・トリアージ、Issue Forms(YAML)テンプレート、ラベル体系(type/priority/status)とマイルストーン運用、GitHub Flow/トランクベースのブランチ戦略選択、AIエージェントへのタスク委任・並列化、ADR/Design Docの書き分けと記録設計、PRレビュー規律(Small CL・Conventional Comments・AI一次レビュー)の作業時に必ず使用する。「Issueを立てて」「Issueに分解して」「チケット化して」「タスク分割して」「ラベル設計して」「ブランチ戦略どうする」「ADR書いて」「Design Doc書いて」と言われたときにも使う。計画立案と Issue 作成の知識正本。

How it works

  1. 分担線: AI がやること / 人間にしか決められないこと
  2. Step 1: 良い Issue を書く
  3. Step 2: 分解する — 1 Issue = 1 関心事 = 1 PR
  4. Step 3: ラベルとマイルストーンで整流する
  5. Step 4: トリアージを運用する
  6. Step 5: ブランチ戦略を選ぶ
  7. Step 6: エージェントに委任する
  8. Step 7: 記録を残す — ADR / Design Doc / AGENTS.md の書き分け
  9. Step 8: レビュー規律を守る
  10. 完了チェックリスト
Original SKILL.md headings · 151 lines, 627 words
SKILL.md preview
---
name: issue-driven-dev
description: "Issue起点で人間+AIエージェントの開発を回すスキル。GitHub Issueの作成・分解・トリアージ、Issue Forms(YAML)テンプレート、ラベル体系(type/priority/status)とマイルストーン運用、GitHub Flow/トランクベースのブランチ戦略選択、AIエージェントへのタスク委任・並列化、ADR/Design Docの書き分けと記録設計、PRレビュー規律(Small CL・Conventional Comments・AI一次レビュー)の作業時に必ず使用する。「Issueを立てて」「Issueに分解して」「チケット化して」「タスク分割して」「ラベル設計して」「ブランチ戦略どうする」「ADR書いて」「Design Doc書いて」と言われたときにも使う。計画立案と Issue 作成の知識正本。"
---

# Issue Driven Development — Issue起点で人間+AIエージェントの開発を回す

**鉄則: すべての作業は Issue を起点にする。「Issue を立てる→ブランチを切る→実装→PR→レビュー→マージで Issue クローズ」が1サイクル。**

なぜ: 作業の理由(why)と受入基準を作業前に文章化することを強制でき、受託では顧客との合意履歴・請求根拠・引き継ぎ資料を兼ね、AIエージェント体制では Issue がそのまま作業指示書(work order)になるため。

本スキルは dev-core における計画立案と Issue 作成の知識正本である。

## 分担線: AI がやること / 人間にしか決められないこと

このスキルを実行するエージェントは、以下の分担線を越えて勝手に確定しないこと。

| AI(このスキルを実行するエージェント)がやること | 人間にしか決められないこと |
|---|---|
| Issue ドラフト生成・分解案の提示 | 優先順位と受入基準の確定(=何を作るかの決定) |
| ラベル付け・重複検出・トリアージ提案 | 顧客要望の契約上の仕分け(見積対象/契約内/対応不可) |
| 実装・PR 作成・一次レビュー(全行の網羅チェック) | レビューの最終承認とマージ |
| ADR / Design Doc / リリースノートのドラフト | 決定そのもの(ADR の Decision の採否と責任) |
| Issue と PR の紐付け検査・進捗の可視化 | 本番への不可逆操作(デプロイ承認・ロールバック発動) |

なぜ: Issue を書く行為は「委任の契約書を書く行為」であり、何を作るかの決定と成果物への責任は委任できないため。

## Step 1: 良い Issue を書く

Issue 本文は必ず次の構造で書く:

1. **背景 / なぜ**(business context): この作業が必要な理由
2. **現状と期待**: 何がどうなっているか、どうなるべきか(バグなら再現手順・期待/実際・環境)
3. **受入基準**(acceptance criteria): チェックボックス形式。検証可能な条件のみ書く
4. **スコープ外**: この Issue でやらないことを明記
5. 技術メモ(任意): 実装ヒント・関連ファイル

タイトルは「何が・どうなるべきか」を一文で。

**合格ライン**: 「ジュニア開発者がこれだけ読んで実装に入れる粒度」= そのまま「AIエージェントが読んで実装に入れる粒度」。この基準を満たさない Issue でエージェントに実装させないこと。

なぜ: 曖昧な Issue は曖昧なコードになる(vague tickets become vague code)ため。

**記述コストの基準**: 作業サイズが30分未満または自明ならタイトル+一行で可。それ以上は受入基準必須。**AIエージェントに投げる Issue は常に受入基準必須。**

Issue Forms(YAML)テンプレート3種(バグ報告/機能要望/タスク)を `.github/ISSUE_TEMPLATE/` に置き、構造を強制する → references/issue-driven-dev.md §1。合格/不合格の実例 → 同 §3

## Step 2: 分解する — 1 Issue = 1 関心事 = 1 PR

- Issue が複数の関心事を含むなら分割する。親 Issue + sub-issues(GitHub の tasklist)で階層化する。
- 分割は**依存関係の少ない縦切り**(ユーザー価値単位のスライス)にする。
- なぜ: 独立した Issue なら複数エージェントを並列に走らせられる。**Issue 分割の質がそのまま並列エージェント数=スループットを決める**ため。
- PR 本文に `Fixes #N` を書き、マージで Issue を自動クローズする。ブランチ名に Issue 番号を含める(例: `feature/123-user-login`)。
- なぜ: Issue と PR が紐付かないと変更理由が追えなくなる。`Fixes #N` は PR テンプレートに組み込んで強制する。
- 巨大 Issue を数週間 open のまま放置しない。進捗が見えなくなったら分割のサインとして扱う。

## Step 3: ラベルとマイルストーンで整流する

ラベルは **3軸×各5個以内** に制限する:

| 軸 | ラベル例 | 用途 |
|---|---|---|
| `type/*` | bug / feature / chore / docs | 作業の種類 |
| `priority/*` | P0 / P1 / P2 / P3 | 優先度(P0=即時対応) |
| `status/*` | needs-triage / ready / blocked | 処理状態 |

なぜ: ラベルは増やすほど誰も付けなくなるため。それ以上の属性は GitHub Projects のカスタムフィールドへ逃がす。

マイルストーンは**リリース単位または契約フェーズ単位**で切る。なぜ: 期日と進捗率が自動で可視化され、受託では契約との紐付け(請求根拠)になるため。初期セットの定義 → references/issue-driven-dev.md §2

## Step 4: トリアージを運用する

1. 新規 Issue はすべて `status/needs-triage` で受ける。
2. **週次**で仕分ける: 優先度・マイルストーンを付け、`ready` に昇格するか、close する。
3. 受託では顧客からの要望 Issue をここで**契約仕分けゲート**にかける: **見積対象 / 契約内 / 対応不可** の3択に人間が仕分ける(AI は判断材料の整理まで)。金額の判断は自組織の見積・価格判断プロセスへ回す。
4. Slack・口頭・会議で決まったことは必ず Issue コメントに戻す。「議論は Issue 上で、決定は Issue に記録」を守る。

なぜ: 決定が Issue の外に散らばると「Issue が嘘をつく」状態になり、正本性が失われるため。受託では Issue 上のやり取り自体が変更管理の証跡として自動でたまる。

週次トリアージの手順チェックリスト → references/issue-driven-dev.md §6

## Step 5: ブランチ戦略を選ぶ

| 戦略 | 内容 | 選ぶ条件 |
|---|---|---|
| **GitHub Flow**(既定値) | main は常にデプロイ可能。機能ブランチ→PR→レビュー→マージ→即デプロイ | 頻繁デプロイの SaaS/Web 案件。迷ったらこれ |
| **トランクベース開発** | 全員(全エージェント)が短命ブランチで日次以上 main に合流。未完成機能はフィーチャーフラグで隠す | 強いテスト自動化とフラグ規律が既にある場合 |
| Git Flow | develop/release ブランチ常設 | 顧客都合のリリース列車が常設される場合のみ。それ以外は過剰(2026年時点の目安) |

**両者の実質差は「ブランチの寿命を1〜2日以内に縛るか」とフィーチャーフラグ規律の有無だけ**。名前の議論に時間を使わず、ブランチ寿命の上限を決めることに時間を使う。

CI 品質ゲート・ブランチ保護・デプロイ/リリース戦略の設計 → cicd-release-design 参照

## Step 6: エージェントに委任する

- **Issue はエージェントへのプロンプトである**。受入基準がそのままエージェントの完了条件・テスト仕様になる。
- 委任の型: 人間が口述 → AI が要件ドラフト → Issue 化 → **人間が受入基準を精査** → エージェントに割当。
- Issue を AI で一括生成した場合も、**1件ずつ人間が精査してから `ready` にする**。なぜ: 雑な Issue の大量生成はノイズ化し、トリアージ帯域を食い潰すため。
- 並列度を上げたいときは、エージェントを増やす前に Issue の依存関係を減らす(Step 2 の縦切り)。
- 人間のレビュー帯域がボトルネックになったら、介在点を減らす自動化(CI ゲート・受入基準の形式化)を先に整備する。なぜ: 並列エージェント数を増やしても人間の判断帯域は増えないため。

## Step 7: 記録を残す — ADR / Design Doc / AGENTS.md の書き分け

| 文書 | 粒度・寿命 | 目的 |
|---|---|---|
| **ADR** | 1決定1ファイル・**不変**(覆すときは新 ADR で supersede) | 決定と理由の記録 |
| **Design Doc** | 機能・システム単位。実装前に書き、実装後は歴史資料 | 作る前の合意形成・選択肢の探索 |
| **AGENTS.md / CLAUDE.md / README** | リポジトリ単位・常時更新 | 現在の正(人間と AI の共通入口) |

- **書き分けの原則**: Design Doc は「選択肢を探索し合意する文書」、ADR は「決定を記録する文書」。混ぜない。
- ADR を書く基準: **アーキテクチャ・技術選定・外部連携・セキュリティに関わる決定は必須**。それ以外は Issue コメントで足りる。「後任(または AI)が『なぜこうなってる?』と聞きたくなる決定」は全部書く。
- ADR は後から書き換えない。覆すときは新 ADR を作り supersede する。なぜ: 書き換えると履歴が嘘になるため。
- Design Doc は完璧さより早さ。実装前のフィードバック獲得が主目的。
- **ADR(不変の記録)と AGENTS.md(現在形)は役割を分ける**: ADR は決定時点を凍結し、AGENTS.md / CLAUDE.md は「現在の正」だけを持って常時更新する。なぜ: 腐った現在形は無い文書より有害(AI が古い情報を信じる)なため。
- 中身の設計(何を書き何を書かないか) → dev-core:conventions-as-guardrails Step 3 参照
- 過去案件の ADR 群は、次案件でエージェントに注入できる再利用資産(自組織の知識ベース)として蓄積する。

ADR / Design Doc のテンプレート → references/issue-driven-dev.md §4

## Step 8: レビュー規律を守る

- **Small CL**: 迷ったら想定より小さく分割する。なぜ: レビューの目的は「コードベースの健全性を時間とともに改善すること」であり、大きな PR はレビュー不能になるため。
- **応答 SLO: 1営業日以内**。なぜ: レビュー速度がレビュー文化の生死を分けるため。
- 指摘には **Conventional Comments**(`nit:` `suggestion:` `issue:` `question:` 等の接頭辞)を使い、重みを明示する → references/issue-driven-dev.md §5
- **AI 一次レビュー + 人間最終承認**の分担: AI が網羅性(全行チェック・セキュリティ・規約・明白なバグ)を、人間が妥当性(設計判断・ビジネス整合)を担当する。
- AI の指摘は鵜呑みにしない。一次情報(実ファイル・実行出力)で検証してから反映する。
- 承認基準は「完璧」ではなく「確実な改善」(better, not perfect)。

## 完了チェックリスト

作業サイクルの完了時に確認する:

- [ ] Issue に受入基準があり、すべてチェック済みか
- [ ] PR に `Fixes #N` があり、マージで Issue が閉じたか
- [ ] 実装の検証は済んだか → dev-core:verify 参照
- [ ] Issue の外(Slack・口頭)で決まったことを Issue に書き戻したか
- [ ] ADR を書くべき決定(アーキテクチャ・技術選定・外部連携・セキュリティ)が含まれていなかったか
- [ ] AGENTS.md / CLAUDE.md の更新が必要な「現在の正」の変化がなかったか

## 境界(他スキルへのポインタ)

- 実装完了の検証・証拠ベース完了判定 → dev-core:verify
- TDD・SOLID・コーディング規約・設計原則 → dev-core:best-practices
- バグ Issue の根本原因調査 → dev-core:debug
- Codex への独立レビュー・セカンドオピニオン依頼 → dev-core:codex-collab
- 受入基準を検証可能にするテスト技法・テスト計画 → test-design 参照
- CI/CD 品質ゲート・ブランチ保護・デプロイ戦略 → cicd-release-design 参照
- 要件定義から Issue への分解の上流工程 → requirements-definition 参照
- 顧客との合意形成・スコープ変更の進め方 → client-alignment / pm-delivery 参照
- 見積・価格・契約条件の判断 → 本スキルでは扱わない。自組織の見積・価格判断プロセスへ

---

注: 検収・契約仕分けなど契約に関わる記述は法的助言ではなく実務の型(2026年時点の目安・要確認)。最終判断は弁護士等の専門家に委ねること。
Files in this package (2)
  • SKILL.md 13 KB
  • references/issue-driven-dev.md 16 KB

Versions

The database has no other skills named issue-driven-dev.

Database snapshot: 13.11.2026 · package version a1eef2a9ee60 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100github-issue-flow
    Plan and execute issue-driven development using granular native GitHub sub-issues, parallel isolated worktrees, dependent feature PR stacks grouped into topic-specific stack/* review branches, human-approved stack/*-to-dev merges, squash dev-to-main releases, optional GitHub…
  • 100issue-triage
    Triage and categorize GitHub issues with priority labels. Use when user says "triage issues", "check issues", "review open issues", or during regular maintenance of GitHub issue backlog.
  • 100github-issue-model
    This skill should be used when working with GitHub's issue data model — issue types, sub-issues, dependencies, labels, milestones, issue forms and templates, and the community health files that configure them.
  • 100issue-triage
    Evidence-backed, report-only GitHub issue triage. Invoke directly with `/issue-triage` — not auto-triggered by the model.
  • 100manage-project
    Keep the organizzolini/codebase GitHub Project board filled in — set an issue's Status, Priority, and Effort, move work to In Progress, and know when a milestone applies. Use when starting or finishing work on an issue, after filing or sorting issues, when estimating effort or…
  • 91issue-create
    Creates a GitHub issue from the project's issue form templates. Use when the user asks to open an issue, not to fix a bug.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.