Workflow Archetypes

Most AI coding frustration is not about model quality. It is about using the wrong workflow for the job. These four patterns cover most of the work people actually do.

1. The Bug Hunt

Use this when the problem is already visible and you want the smallest safe fix.

Reproduce the bug with a failing test, command, or screenshot.
Give the agent the error, the expected behavior, and only the relevant files.
Ask for root-cause analysis before implementation.
Make the smallest fix that resolves the failure.
Re-run the verification signal.

A good prompt sounds like: “Here is the failing test and the relevant files. Explain the root cause, then fix it without changing unrelated behavior.”

The usual mistake is throwing the whole repo at the model and hoping it guesses right.

Full worked example: Scenario - Fix a Bug

2. The Feature Build

Use this when you are adding new behavior and the shape of the work is still easy to change.

Write a short spec with requirements, constraints, and acceptance criteria.
Ask the agent to read the spec and discuss the approach first.
Break execution into small slices: schema, core logic, tests, UI, docs.
Verify each slice before moving on.
Update the spec when scope changes.

A good opening prompt is: “Read spec.md. Tell me what questions you have and propose the implementation plan before writing code.”

Why it works: it turns vague intent into a sequence the model can follow and you can check.

Full worked example: Scenario - Add a Feature

3. The Refactor

Use this when the code works, but living with it is getting expensive.

Capture current behavior with characterization tests.
Set explicit non-goals: no feature changes, no opportunistic fixes.
Refactor one seam at a time.
Re-run tests after every small step.
Stop when readability or maintainability improves enough.

A good prompt is: “This is a refactor. Preserve behavior. Do not change public interfaces unless the test or spec requires it.”

The trap here is mixing bug fixing, cleanup, and feature work into one big edit.

Full worked example: Scenario - Safe Refactor

4. The Codebase Explorer

Use this when you do not understand the codebase well enough to touch it confidently.

Ask the main agent to map the relevant subsystem.
Use subagents to explore the database layer, API layer, and tests in parallel if needed.
Ask for file paths, patterns, and conventions, not broad summaries.
Write down the useful findings.
Only then move into a bug, feature, or refactor workflow.

A good prompt is: “Investigate how X works in this repo. Report back with entry points, key files, and patterns. Do not modify anything.”

Which Workflow Should You Start With?

Situation	Start With
A broken test or clear bug report	Bug Hunt
New endpoint, feature, or UI path	Feature Build
Messy code with stable behavior	Refactor
Unfamiliar system	Codebase Explorer

What These Workflows Have in Common

verification matters more than confidence
smaller steps are easier to review than giant prompts
selective context works better than maximal context
when the model gets stuck, a fresh session usually beats another long rescue attempt