Complete Guide to Writing GitHub Issues: How to Give AI-Friendly Instructions

Introduction

DevLoop Runner reads GitHub Issues and automatically generates code based on their content. This means how you write your Issues directly impacts the output quality.

DevLoop Runner's Dev Run operates through a structured 10-phase workflow, and every phase starts from the Planning phase where the AI reads your Issue. If the Issue is vague, the plan suffers — and that impact cascades through design, implementation, and testing.

This article provides a detailed guide on writing Issues that AI can accurately understand to generate high-quality code, complete with templates and concrete examples.

5 Fundamentals of Writing Good Issues

1. Make Titles Specific and Concise

The title is the first thing the AI reads to understand the task. Specificity matters.

Good examples:

• Add email duplicate check to user registration form
• Implement pagination on product list page (20 items per page)
• Add multi-language support for login error messages

Bad examples:

• Add feature — What feature?
• Please fix bug — What bug?
• About XX — Not specific enough

Tip: Include "what" and "where" in your title. Starting with a verb (add, fix, update, remove) makes it immediately clear.

2. Structure Your Description

Structure your Issue body with separate sections for background, requirements, and constraints so the AI can parse it accurately.

Background/Purpose — Why this change is needed:

## Background
Currently, there is no email duplicate check during user registration.
Users can register multiple times with the same email address.

Implementation Requirements — What to build:

## Requirements
- Check for email duplicates when registration form is submitted
- Display error message if duplicate exists
- Error message: "This email address is already registered"

Technical Constraints — Rules and conditions to follow:

## Technical Constraints
- Use existing users table
- Validation should be server-side

3. Specify Acceptance Criteria

Write specific acceptance criteria so the AI can determine when the task is "complete." Checklist format works best.

## Acceptance Criteria
- [ ] Error is displayed when registering with existing email
- [ ] Registration succeeds with new email
- [ ] Error message is displayed correctly
- [ ] Duplicate check is case-insensitive

4. Provide Context

AI generates more appropriate code when it understands related files and existing implementation patterns.

## Reference Information
- Related files: `src/pages/Register.tsx`, `src/api/users.ts`
- Existing validation implementation: Reference `src/utils/validation.ts`
- Design: Figma link (if available)

5. Define Scope Clearly

Clearly defining implementation scope ensures you get exactly what you need. Explicitly stating what's not included is especially important.

## Scope
### Included
- Email duplicate check logic
- Error display UI

### Not Included
- Password strength check (separate Issue)
- Registration confirmation email

Templates by Issue Type

Different types of tasks call for different Issue structures. Here are templates for the three most common types.

New Feature

Title: Add [feature] to [location]

## Background
[Why this feature is needed, current pain points]

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

## UI/UX (if applicable)
- [Placement and design specifications]
- [User interaction flow]

## Technical Constraints
- [Libraries, APIs, existing patterns to follow]

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

## Out of Scope
- [Explicitly excluded items]

Bug Fix

Title: Fix [symptom] in [location]

## Symptom
[Describe what's happening in specific terms]

## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment (if applicable)
- Browser: [e.g., Chrome 120]
- OS: [e.g., Windows 11]

## Related Files
- [File paths where the issue occurs]

## Acceptance Criteria
- [ ] [The issue no longer occurs following the reproduction steps]
- [ ] [Existing functionality is not affected]

Refactoring

Title: Refactor [target] to [approach]

## Background
[Why refactoring is needed, current problems]

## Current Problems
- [Problem 1: e.g., Function exceeds 200 lines, reducing readability]
- [Problem 2: e.g., Same logic duplicated in 3 places]

## Approach
[How to refactor]

## Target Files
- [File 1]
- [File 2]

## Constraints
- External behavior must remain unchanged
- [Other constraints]

## Acceptance Criteria
- [ ] [All existing tests pass]
- [ ] [Code duplication is resolved]

Common Mistakes and How to Fix Them

Mistake 1: The Vague Issue

Before:

Title: Improve login feature

Please make the login process better.

After:

Title: Add password reset functionality to login screen

## Background
When users forget their password, they currently have to contact
an administrator. We need a self-service password reset feature.

## Requirements
- Add a "Forgot your password?" link on the login screen
- Entering an email address sends a reset link via email
- Reset link expires after 24 hours
- New password must be at least 8 characters

## Acceptance Criteria
- [ ] Reset link is displayed on the login screen
- [ ] Reset email is sent to registered email addresses
- [ ] No error is shown for unregistered emails (security consideration)
- [ ] Reset link becomes invalid after 24 hours

The problem: Words like "improve" and "make better" are the hardest instructions for AI to interpret. Be specific about what you want changed and how.

Mistake 2: The Everything Issue

Before:

Title: Implement user management feature

## Requirements
- Create user list page
- Create user detail page
- Create user creation form
- Implement user editing
- Implement user deletion
- Implement role management (admin, regular, guest)
- Implement user search and filtering
- Implement CSV export
- Implement pagination
- Implement sorting

The problem: 10+ requirements crammed into a single Issue. When an Issue is too large, the AI struggles to maintain consistency across all the moving parts, and quality drops.

The fix: Split into focused Issues:

Issue 1: Create user list page (with pagination and sorting)
Issue 2: Implement user creation form
Issue 3: Implement user edit and delete functionality
Issue 4: Implement role management
Issue 5: Implement user search and filtering
Issue 6: Add CSV export to user list

Mistake 3: The Missing-Context Bug Report

Before:

Title: Search feature doesn't work

The search button doesn't return results. Please fix.

After:

Title: Product search returns 0 results when query contains special characters

## Symptom
When searching for products with keywords containing "&" or "+",
the search returns 0 results even when matching products exist.

## Steps to Reproduce
1. Navigate to the product list page (/products)
2. Enter "A&B" in the search box
3. Click the search button
4. Results show "0 items found"

## Expected Behavior
Products with "A&B" in their name should appear in search results.

## Actual Behavior
"Search results: 0 items" is displayed. Regular strings
(e.g., "test") work normally.

## Related Files
- `src/api/products.ts` - searchProducts function
- `src/pages/ProductList.tsx` - search handling

## Acceptance Criteria
- [ ] Special characters (&, +, #, %) in search queries return correct results
- [ ] Existing normal search functionality is unaffected

The problem: "Doesn't work" gives the AI nothing to work with. Reproduction steps and expected behavior let the AI pinpoint the fix.

Mistake 4: The Implementation-Only Issue

Before:

Title: Refactor user.ts

Rewrite the getUser function in user.ts to async/await.
Also add caching.

After:

Title: Improve user data fetching performance

## Background
The user data fetch makes a full API call every time, causing
loading spinners on every page navigation. Response time
needs improvement.

## Current Problems
- `src/api/user.ts` getUser function uses callbacks, making
  error handling overly complex
- The same user data is fetched multiple times in quick succession

## Requirements
- Refactor getUser to async/await
- Add in-memory cache with 5-minute TTL for user data
- Skip API call on cache hit

## Acceptance Criteria
- [ ] All existing tests pass
- [ ] Second and subsequent fetches for the same user are faster
- [ ] Cache expires after 5 minutes

The problem: Writing not just "what to do" but "why we're doing it" gives the AI the context to make better implementation decisions.

Issue Granularity: Not Too Big, Not Too Small

Issue size has a significant impact on Dev Run quality.

When Issues Are Too Large

Loading diagram...

When too many requirements are packed into a single Issue, the AI must juggle the big picture while satisfying each individual requirement. Quality suffers.

Rule of thumb: Aim for Issues that change 10 files or fewer.

When Issues Are Too Small

On the other hand, Issues that are too small lack the context the AI needs to make good decisions.

❌ Too granular:
Issue 1: Add email_verified column to users table
Issue 2: Set email_verified type to boolean
Issue 3: Set email_verified default to false

These should be a single Issue.

Rule of thumb: Group all changes needed to achieve one purpose into one Issue.

Finding the Right Size

Granularity	Example	Verdict
Entire user management system	List, create, edit, delete, search	❌ Too large
User list page	List display, pagination, sorting	✅ Just right
Changing a sort icon	Swap icon to an arrow	❌ Too small

How Issue Quality Affects Dev Run

The way you write Issues directly impacts each phase of Dev Run.

Issue Element	Affected Phases	Impact When Missing
Background/Purpose	Planning, Requirements	AI misinterprets the goal, leading to an off-target plan
Requirements	Requirements, Design	AI fills in implicit requirements that may not match your intent
Technical Constraints	Design, Implementation	Design or code that doesn't align with existing codebase
Acceptance Criteria	Test Scenario, Evaluation	Insufficient test cases, lenient quality assessment
Scope	All phases	Unnecessary features implemented, or required features missing

The most important element is Background/Purpose. The AI supplements unwritten requirements by analyzing the codebase, but without a clear "why," those supplements may go in the wrong direction.

Summary

Key points for writing good Issues:

1. Specific titles — Make "what" and "where" clear at a glance
2. Structured descriptions — Separate background, requirements, and constraints
3. Clear acceptance criteria — Checklists that define "done"
4. Sufficient context — Related files and reference information
5. Explicit scope — What is and isn't included
6. Right-sized granularity — Not too big, not too small; one purpose per Issue
7. Type-appropriate structure — Use different formats for features, bugs, and refactoring

Issue quality directly determines Dev Run output quality. Investing time in writing good Issues is a "down payment" that saves time on reviews and rework. Start putting these tips into practice with your next Issue.