AI Coding Agent Workflow: From Task to Reviewed Merge

Problems this guide solves

• Agents start coding before the problem and finish line are understood.
• Parallel runs share files, ports, or credentials and interfere with each other.
• A polished summary hides untested assumptions or incomplete work.

Step 1

Turn an issue into an executable brief

The task should be narrow enough to review and concrete enough to test.

1. Describe the user-visible problem and why it matters.
2. Point to relevant modules, constraints, and examples without prescribing every edit.
3. List acceptance checks that can be observed or run.
4. State what is out of scope and which decisions require a human.

Step 2

Create a controlled run

Isolation and permissions keep a failed attempt cheap.

1. Use a branch or worktree and a separate port or test resource when needed.
2. Load current repository instructions and only the context relevant to the task.
3. Approve commands by risk: read and test broadly, restrict secrets, deploys, and destructive actions.
4. Require checkpoints for architecture changes, new dependencies, and public API changes.

Step 3

Demand evidence at handoff

Completion means the result is reviewable, not that the agent stopped.

1. Review the diff, generated files, migrations, and lockfile changes.
2. Check the commands and tests actually run, including failures or skipped checks.
3. Reproduce the target behavior and at least one important failure case.
4. Record unresolved risks, then merge or send the task back with specific evidence.

Final checklist

• The task has a user problem, scope, and acceptance checks.
• The run is isolated from unrelated work.
• Repository instructions are current and short.
• Permissions match the task risk.
• New dependencies and public interfaces receive explicit review.
• The handoff includes diffs, commands, results, and unresolved risks.

Common questions