A Reliable Workflow for AI-Assisted Coding

AI coding assistants can turn a blank file into a working prototype quickly. They can also turn a small change into a 600-line diff that looks plausible, passes one happy-path test, and quietly breaks a contract nobody mentioned in the prompt.

The skill is not writing a magical prompt. It is designing a workflow in which the tool can help, the scope stays bounded, and you retain enough understanding to take responsibility for the result.

This playbook works across editor assistants and coding agents. Individual tools have different controls, permissions, and capabilities; always follow the documentation for the tool you use.

The five-stage loop

Define → Contextualize → Plan → Implement → Verify
   ↑                                      ↓
   └──────────── Learn from the diff ─────┘

The loop is intentionally boring. Boring is good when software changes affect other people.

1. Define the outcome, not the keystrokes

Weak task:

Make checkout better.

Better task:

Prevent duplicate orders when the same checkout request is submitted twice. Preserve the current successful checkout behaviour. Add a regression test for repeated equivalent requests. Do not change the checkout UI or the order schema unless the investigation shows it is necessary.

The better task says what must change, what must remain stable, and how success will be checked. It leaves implementation choices open while constraining blast radius.

Use this template:

Outcome:
Current behaviour:
Expected behaviour:
Constraints / non-goals:
Acceptance criteria:
Verification commands:

Not every ticket needs every field. The template is a thinking aid, not bureaucracy.

2. Give the assistant useful context

Context is not “paste the whole repository into the prompt.” It is the smallest set of information that lets the assistant reason about the task correctly.

Useful context may include:

• The ticket and acceptance criteria.
• The relevant files and their callers.
• Existing tests and project conventions.
• Runtime or dependency constraints.
• A failing test, exact error, or minimal reproduction.
• Explicit boundaries: files or behaviours that must not change.

If the repository has agent instructions, review them and keep them factual, concise, and current. Instructions can guide a tool; they cannot replace a human’s understanding of permissions or security boundaries.

3. Ask for investigation before editing

On an unfamiliar or risky task, use a two-pass approach.

Pass A — investigate: ask the assistant to trace the relevant flow, list evidence, name uncertainties, and propose a minimal plan. Do not permit edits yet.

Pass B — implement: approve or correct the plan, then ask for one coherent change at a time.

A high-signal investigation prompt:

Inspect the checkout path. Do not modify files. Identify the handler, business-logic function, persistence boundary, and relevant tests. Cite file paths and function names for each claim. Separate observed facts from hypotheses. End with the smallest test that would reproduce the reported failure.

The instruction “cite file paths” is not a guarantee of correctness. Open the files and check the claims.

4. Keep the diff reviewable

A coding assistant may optimize for finishing the request; you must optimize for a change you can understand and maintain.

Useful constraints include:

• Change only the files needed for the task.
• Follow existing conventions unless there is a reason not to.
• Avoid unrelated refactors and dependency upgrades.
• Add or update tests with the code change.
• Explain why each non-obvious change is necessary.
• Stop and ask if the task requires an unapproved schema, API, or architecture change.

Do not judge success by how much code the model wrote. A five-line correction with a regression test can be a better result than a sweeping rewrite.

5. Verify in layers

Use the cheapest meaningful check first, then expand:

1. Inspect the diff: git diff --check and review changed files.
2. Run focused tests: prove the changed behaviour.
3. Run broader tests and static checks: catch regressions and style/type problems.
4. Run the application or reproduction: exercise the real path where practical.
5. Check the edges: empty input, repeated requests, permission boundaries, failure paths, and unexpected state.

The exact commands depend on the project. Do not let an assistant claim tests passed unless they were run and the output supports that claim.

A green test suite reduces uncertainty; it does not prove the absence of bugs. Tests can be incomplete, assertions can be weak, and the wrong behaviour can be encoded in a test.

What should you delegate—and what should you retain?

Good candidates for assistance	Keep human judgment firmly involved
Boilerplate, test scaffolding, repetitive transformations	Product requirements and ambiguous trade-offs
Explaining a file or tracing a likely call path	Confirming facts against source and runtime behaviour
Generating alternative implementations	Choosing the right design for the constraints
Drafting documentation and migration steps	Security-sensitive decisions and access control
Suggesting edge cases	Deciding what risks are acceptable before release

This is not a fixed division of labour. Delegate more when the task is bounded, reversible, and easy to verify. Tighten oversight when the change is ambiguous, security-sensitive, expensive to roll back, or hard to test.

A useful mental model: the verification budget

Every generated change creates a review obligation. If the tool produces more code than you can reasonably inspect, your verification budget has been exceeded.

When that happens, reduce scope. Ask for a smaller patch, split the task, request a focused explanation, or implement the risky section manually. Do not compensate by skimming faster.

Common failure modes

The confident hallucination. The assistant uses a library method that does not exist. Check documentation and run the code.

The silent scope expansion. It updates unrelated packages or reformats half the repository. Revert unrelated changes and restate boundaries.

The test-shaped blind spot. It writes a test that mirrors its own incorrect assumption. Independently derive at least one expected result from the requirement.

The missing security review. It introduces unsafe deserialization, exposes a secret, or trusts unvalidated input. Review security boundaries explicitly.

The unexplained patch. The code works but you cannot explain it. Ask for a walkthrough, inspect the dependency chain, and simplify until you understand what you own.

A ready-to-use task prompt

Goal: [observable outcome]

Context: [relevant files, architecture, current behaviour]

Constraints: [non-goals, conventions, interfaces that must stay stable]

Acceptance criteria: [testable statements]

Workflow: first investigate without editing; list evidence and uncertainties; propose the smallest implementation plan. After I approve it, implement in small steps, add tests, run the relevant checks, and summarize the diff, test output, and remaining risks. Do not claim a check passed unless you ran it.

The principle to remember

AI should reduce the cost of producing and exploring code. It should not remove your responsibility to understand what changes, why it is correct, and how you know it is safe.

The best AI-assisted engineer is not the person who delegates the most. It is the person who creates the fastest reliable loop from intent to verified software.