Issue-Driven Development Best Practices: Building Your Workflow Around Issues

Introduction

"Issue-driven development" is a development process where every piece of work starts from a GitHub Issue. Feature additions, bug fixes, refactoring -- everything begins with an Issue and concludes with an Issue-linked PR.

This process pairs exceptionally well with DevLoop Runner. Since DevLoop Runner operates using GitHub Issues as input, Issue quality directly translates to development quality.

This article covers the full picture of Issue-driven development, Issue writing best practices, classification and labeling strategies, template design, and how to integrate with DevLoop Runner.

What Is Issue-Driven Development?

The Basic Cycle

The fundamental cycle of Issue-driven development is straightforward.

Loading diagram...

Everything starts from an Issue and ends with an Issue. This provides several benefits.

Benefits of Issue-Driven Development

Benefit	Description
Traceability	Every change can be traced back to its originating Issue
Prioritization	All tasks managed as a backlog
Progress visibility	Issue status shows project progress at a glance
Communication	Decision history preserved in Issue discussions
DevLoop Runner integration	Automation starts with just an Issue URL

Eliminating "Work Without Issues"

The most important rule in Issue-driven development is no work without an Issue.

• "Quick fixes" get an Issue
• "While I'm at it" refactoring goes in a separate Issue
• "Urgent bug fixes" get an Issue first, then work begins

Enforcing this rule ensures every change has documented context and purpose.

Issue Writing Best Practices

The Ideal Issue Structure

Here's the structure that maximizes DevLoop Runner's effectiveness.

## Overview
[What this Issue aims to achieve / the problem to solve in 1-2 sentences]

## Background
[Why this work is necessary]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]

## Target Files (if known)
- [file path]

## Acceptance Criteria
- [Completion condition 1]
- [Completion condition 2]

## Test Conditions
- [Scenarios to test]

## Constraints (if any)
- [Compatibility, performance, security constraints]

Writing the Overview

The overview should concisely state "what to achieve."

Bad example:

Improve the code

Good example:

Add pagination to the user list page so it handles
100+ records smoothly

Writing Requirements

Requirements should be specific and verifiable.

Bad example:

- Improve performance
- Make the UI better

Good example:

- Display 20 users per page
- Navigate with "Previous" and "Next" buttons
- Show current page number and total pages
- Manage page number via URL parameter (support browser back)

Why Acceptance Criteria Matter

Acceptance criteria define "the standard for judging this Issue complete." DevLoop Runner's Project Evaluation phase (handled by Aoi) uses these criteria to determine PASS/FAIL.

## Acceptance Criteria
- User list is paginated at 20 items per page
- Page transitions complete within 500ms
- Page number reflected in URL; browser back returns to previous page
- Empty state shows "No users found"
- All tests pass

Issue Classification and Labeling Strategy

Effective Issue management requires classification and labeling.

Recommended Label System

Type labels:

Label	Purpose	DevLoop Runner Relevance
type: feature	New feature	All Phases mode recommended
type: bug	Bug fix	Implementation Only possible depending on cause
type: refactor	Refactoring	All Phases mode recommended
type: test	Test addition	All Phases mode recommended
type: docs	Documentation	Implementation Only mode sufficient
type: chore	Dependency updates, etc.	Implementation Only mode sufficient

Priority labels:

Label	Meaning
priority: critical	Immediate action needed
priority: high	This sprint
priority: medium	Next sprint
priority: low	When time permits

Size labels:

Label	Guideline	Estimated Dev Run Time
size: XS	A few lines changed	10-15 min
size: S	~50 lines changed	15-20 min
size: M	50-200 lines changed	20-30 min
size: L	200-500 lines changed	30-40 min
size: XL	500+ lines (consider splitting)	Split recommended

Label Usage Example

[type: feature] [priority: high] [size: M]
Add pagination to user list page

Labels alone tell you: "Run Dev Run in All Phases mode, address this sprint, medium-sized feature addition."

Designing Issue Templates

Setting up GitHub Issue templates ensures consistent quality across the team.

Feature Request Template

---
name: Feature Request
about: Add a new feature
labels: 'type: feature'
---

## Overview
<!-- What this feature achieves in 1-2 sentences -->

## Background
<!-- Why this feature is needed -->

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Target Files (if known)
<!-- Files that need changes -->

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Test Conditions
<!-- Scenarios to test -->

## References
<!-- Design mocks, API specs, related Issues -->

Bug Report Template

---
name: Bug Report
about: Report a bug
labels: 'type: bug'
---

## Bug Summary
<!-- What's happening -->

## Reproduction Steps
1.
2.
3.

## Expected Behavior
<!-- What should happen -->

## Actual Behavior
<!-- What currently happens -->

## Error Messages (if any)

<!-- Paste stack traces or console errors -->

## Target Files (if known)
<!-- Files suspected to contain the issue -->

## Environment
- OS:
- Browser:
- Node.js:

Refactoring Template

---
name: Refactoring
about: Code improvement / refactoring
labels: 'type: refactor'
---

## Overview
<!-- What to refactor -->

## Current Problems
<!-- Why refactoring is needed -->

## Expected Improvements
<!-- Desired state after refactoring -->

## Target Files
<!-- Files to change -->

## Constraints
<!-- API compatibility, performance requirements, etc. -->

Integration with Milestones

Linking Issues to milestones enables integration with release planning.

Milestone Design

Loading diagram...

How to use milestones:

1. Create a milestone per release
2. Link relevant Issues to the milestone
3. Track remaining work through milestone progress
4. Release when all Issues are complete

DevLoop Runner Integration

Submit milestone-linked Issues to Dev Run in priority order for planned releases.

Team Issue Management Rules

Core Rules

1. All work starts from an Issue: No work without an Issue
2. One Issue, one PR: Create one PR per Issue
3. Keep Issues small: Ideally completable in 1-2 days
4. Always apply labels: Specify type, priority, and size
5. Write acceptance criteria: Define completion conditions upfront

Issue Splitting Guidelines

Split large Issues. Here's when and how:

Split When	How to Split
Multiple features included	Split by feature
Frontend and backend changes	Split by layer
500+ lines of changes expected	Split into stages
Multiple file groups affected	Split by impact scope

Issue Lifecycle

Loading diagram...

Synergy with DevLoop Runner

Issue-driven development reaches its full potential when combined with DevLoop Runner.

Issue Quality Determines Dev Run Quality

In DevLoop Runner, the Issue is the sole input. Vague Issues lead to unintended implementations. Clear Issues produce high-quality PRs.

Issue Quality -------> Dev Run Quality -------> PR Quality

In other words, investing in Issue writing improves the quality of your entire development process.

Automating the Issue Lifecycle with Issue Run

DevLoop Runner's Issue Run automates Issue management itself with AI.

Feature	Role in Issue Lifecycle
Create Issue	Auto-discover and create new Issues
Rewrite Issue	Improve existing Issue quality
Close Issue	Clean up unnecessary Issues

The Operational Cycle

Loading diagram...

Running this cycle continuously maintains codebase health while enabling efficient development.

Summary

• Issue-driven development starts all work from Issues: The foundation for traceability, prioritization, and progress visibility
• Issue quality directly impacts development quality: Write specific overviews, requirements, and acceptance criteria
• Labels streamline management: Adopt a system of type, priority, and size labels
• Templates standardize quality: Prepare templates for features, bug reports, and refactoring
• Milestones connect to release planning: Track release readiness through Issue progress
• Exceptional synergy with DevLoop Runner: Issue URL as input means Issue quality equals development quality

Issue-driven development delivers maximum impact when combined with DevLoop Runner, whether you're on a team or working solo. Start by introducing Issue templates.