Your First Dev Run Tutorial: From Issue to PR

Introduction

With DevLoop Runner, you enter a GitHub Issue and AI automatically implements the code and creates a PR. But if you're using it for the first time, it might not be clear where to begin.

This article walks you through the entire flow step by step: connecting your repository, running your first Dev Run, reviewing the PR, and executing the Finalize process.

Follow along, and you'll have your first PR ready in 20-30 minutes.

Prerequisites

Before starting this tutorial, make sure you have:

• A DevLoop Runner account created
• A GitHub account
• Push access to the target repository
• AI credentials configured (Claude API key or OpenAI API key)

Step 1: Connect Your Repository

First, connect a GitHub repository to DevLoop Runner.

1. Open the DevLoop Runner dashboard
2. Click "Add Repository"
3. Select the target repository on the GitHub integration screen
4. Confirm access permissions and click "Connect"

Once connected, the repository appears in your repository list.

Tip: The initial connection requires permissions for repository reading, branch creation, and PR creation.

Step 2: Create Your First Issue

Dev Run uses a GitHub Issue as its input. Start small.

What Makes a Good First Issue

For your first Dev Run, choose an Issue that meets these criteria:

Criteria	Reason
Small scope of change	Easy to verify results
Clear requirements	AI can implement without ambiguity
Easy to test	You can check the testing phase results
Low risk	You want to experiment with confidence

Example Issues

These types of Issues work well for a first Dev Run.

Example 1: Adding a Utility Function

## Overview
Add a utility function that formats dates as "YYYY/MM/DD".

## Requirements
- Create the function in src/utils/dateFormat.ts
- Accept a Date object and return a string
- Return an empty string when null or undefined is passed

## Tests
- Normal date conversion
- null / undefined handling
- Single-digit padding (e.g., 2024/1/5 -> 2024/01/05)

Example 2: Minor Component Update

## Overview
Add a "Blog" link to the header component's navigation.

## Target File
- src/components/Header.tsx

## Requirements
- Add to the end of existing navigation links
- Link destination: /blog
- Display text: "Blog"
- Responsive support (add to mobile menu as well)

Create the Issue on GitHub, then copy its URL.

Step 3: Run Dev Run

Now it's time to run Dev Run.

1. Open your repository page in DevLoop Runner
2. Click "New Job"
3. Select Dev Run
4. Paste the Issue URL
5. Choose an execution mode ("All Phases" recommended for first-timers)
6. Click "Run"

About Execution Modes

Mode	Description	First-Time Recommendation
All Phases	Runs all 10 phases	Recommended
Planning Only	Planning, Requirements, Design only	When you want to review design first
Implementation Only	Planning, Implementation, Documentation, Report	Small changes that don't need tests

For your first run, choose "All Phases" to experience the complete workflow.

Step 4: Monitor Progress

Once Dev Run starts, you can monitor progress in real-time on the job detail screen.

The 10-Phase Flow

Loading diagram...

During each phase, you'll see the assigned AI persona's icon and what's being processed.

Phase	Assigned To	Estimated Time
Planning	Aoi (PM)	1-2 min
Requirements	Aoi (PM)	1-2 min
Design	Riku (Tech Lead)	2-3 min
Test Scenario	Sumire (QA)	1-2 min
Implementation	Riku (Tech Lead)	3-5 min
Test Implementation	Sumire (QA)	2-3 min
Testing	Sumire (QA)	1-2 min
Documentation	Kohaku (Tech Writer)	1-2 min
Report	Riku (Tech Lead)	1-2 min
Evaluation	Aoi (PM)	1-2 min

Total: approximately 15-25 minutes (varies by Issue complexity)

What to Watch During Execution

Artifacts are displayed when each phase completes. Pay special attention to:

• Planning Phase: Has AI correctly understood the Issue's intent?
• Design Phase: Are the target files for changes appropriate?
• Testing Phase: Did all tests pass?

Step 5: Review the Results

When all phases complete, the project evaluation result is displayed.

Understanding Evaluation Results

Verdict	Meaning	Next Action
PASS	All requirements met	Review and Finalize
PASS WITH ISSUES	Requirements met with minor concerns	Check issues, then decide
FAIL	Requirements not met	Revise Issue and re-run

What to Check

1. Report: A summary of what changed and how
2. Test Results: Whether all tests passed
3. Draft PR: The draft PR created on GitHub

Step 6: Review the PR

A draft PR has been created on GitHub. Review it just like any normal PR.

Review Points

Code quality:

• Does the change meet the Issue requirements?
• Does it follow coding conventions?
• Is there any unnecessary code?

Test quality:

• Are test cases sufficient?
• Are error cases tested, not just happy paths?
• Do test names clearly describe what's being tested?

Documentation:

• Has documentation been updated?
• Does the content match the code?

When Fixes Are Needed

If you find issues during review, you can:

• Rollback: Roll back to a specific phase and re-run
• New Issue: Document the fixes needed in a new Issue and run Dev Run again

Step 7: Execute Finalize

When the review is complete and everything looks good, execute Finalize.

1. Click the "Finalize" button on the job detail screen
2. Finalize executes
3. The draft PR is converted to a public PR
4. Commits are cleaned up

For more on Finalize, see How to Use Finalize.

Important: Finalize is a human approval process. AI-generated code is never automatically merged. Always review before running Finalize.

Common First-Time Issues and Solutions

1. Vague Issue Description

Symptom: AI implements something different from your intent

Solution:

• Specify target files explicitly
• Write concrete input/output examples
• State constraints (compatibility, performance, etc.)

Before:

Improve the login feature.

After:

## Overview
Add validation to the login form.

## Target File
- src/components/LoginForm.tsx

## Requirements
- Email format validation
- Minimum password length check (8+ characters)
- Display error messages below the form
- Enable submit button only after validation passes

2. Test Failures

Symptom: Some tests fail during the testing phase

Solution:

• Check the test result report for failure causes
• Roll back to the implementation phase and re-run
• Add testing framework or test style information to the Issue

3. Scope Too Large

Symptom: Unexpected files are modified, PR becomes huge

Solution:

• Limit the Issue scope specifically
• Use a "Target Files" section to be explicit
• Split large tasks into multiple Issues

4. Doesn't Match Coding Conventions

Symptom: Generated code style differs from the project

Solution:

• State "follow existing coding conventions" in the Issue
• Reference specific files (e.g., "match the style of src/components/Button.tsx")

Next Steps

After your first successful Dev Run, explore these articles:

• Dev Run Workflow Complete Guide: Understand the 10 phases in detail
• Let AI Handle Refactoring: Using Dev Run for refactoring
• Let AI Write Your Tests: Using Dev Run for test creation
• Automating Documentation Updates: Using Dev Run for documentation

Summary

• Start with a small Issue: Utility function additions or minor fixes are ideal
• Issue quality is the key to success: Be specific about target files, requirements, and test conditions
• Use All Phases mode to see the full picture: Experience all 10 phases on your first run
• Track progress in real-time: Review each phase's artifacts as they complete
• Review like any normal PR: Check code quality, tests, and documentation
• Finalize is a human approval step: Always review before executing

The more you use DevLoop Runner, the better you'll get at writing Issues that produce great results. Follow this tutorial to take your first step.