Designing agentic workflows: a practical example

Source: Dev.to

The previous post focused on failure modes—where agents fail, and where we fail when reviewing their output. This follow‑up shifts from diagnosis to design.

Sample workflow

What follows is a sample workflow that is explicitly structured to counter those failure modes. It is not the only way to do this, and it is not meant to be permanent. It is one workable design intended to turn known risks into explicit constraints and force verification back into the loop.

Note: This post assumes familiarity with the earlier analysis. If you haven’t read it, the failure modes this workflow responds to are covered here:
Designing agentic workflows: where agents fail and where we fail.

Intended Audience

• Developers new to agentic coding – looking for a cautious, structured starting point.
• Teams that require reviewable commits – with explicit verification gates built into the workflow.
• Enterprise environments – needing auditability, compliance, and low‑risk production deployment.
• Anyone aiming to avoid common AI failure modes – such as premature completion claims, silent test deletion, and shallow or hard‑coded implementations.

Not Intended For

• Exploratory hacking
• Green‑field personal projects
• Environments where reviewability and accountability are optional

As tools improve and teams gain experience, much of this scaffolding can be streamlined or removed. It is a temporary aid, not a permanent prescription.

Core Constraint

The workflow is built around a single constraint that was implicit in the first post but not yet operationalised:

Verification must be independent of the language model.

Earlier failure modes cluster around the structural issue of allowing the system to judge its own success. Confidence scores, summaries, and “done” signals become substitutes for evidence. This workflow explicitly separates proposal from verification.

Phases

The intent is trust, but verify.

Changing the optimisation surface

Agentic systems optimise against what they can observe:

• Green tests
• Plausible diffs
• Explicit completion signals

Humans under review pressure tend to do the same. To shift this optimisation surface, the workflow:

1. Bound work into small, reviewable units.
2. Make intent explicit and durable.
3. Force independent, machine‑verifiable evidence before claims of completion.
4. Prevent large, ambiguous diffs from accumulating.

Without the independent verification constraint, the workflow does not materially change those outcomes.

Loop Structure

Each task starts with a written intent that defines:

1. What is being changed
2. What is explicitly not being changed
3. What success looks like
4. What evidence will be used to verify it

This prevents intent from living only in conversation history and reduces silent scope drift.

Planning Step

The agent does not immediately start modifying code. It first produces an explicit, reviewable plan. Execution begins only after that plan is accepted, keeping architectural and behavioural decisions visible and reducing surprise diffs.

Scoped Loops

Each loop is constrained to a narrow scope:

• One concern
• One behavioural change
• One verification target

This keeps review within human cognitive limits and avoids the shift from verification to plausibility that occurs as diffs grow.

Independent Verification

Completion requires evidence produced by tools other than the language model, such as:

• Test execution results
• Static analysis outputs
• Type‑checker passes or failures
• Runtime traces or logs from real execution

The model’s explanations and summaries provide context, not verification.

Cleanup Pass

Every loop ends with a cleanup pass that:

• Removes temporary scaffolding
• Removes dead code
• Consolidates overlapping helpers
• Updates comments to match behaviour

Cleanup is treated as part of correctness rather than a cosmetic improvement; residue compounds review cost and cognitive load over time.

Repository and Documentation

The repository contains several variants of the same workflow, each adapted for a different tool. Structurally, the workflows are identical.

• Repository: (add link or path here)

What each workflow documents

• The phases of the loop
• What the agent is allowed to do in each phase
• What the human is expected to review
• Which artifacts must exist before progressing to the next phase

Methodology document

A generic methodology document (docs/methodology.md) describes the workflow shape and constraints in a tool‑agnostic way. It uses command‑style notation to illustrate the phases, emphasizing that the shape of the loop—not the exact syntax—is what matters.

# Example of command‑style notation (illustrative only)
phase 1: gather_requirements
phase 2: generate_solution
phase 3: review_by_human
phase 4: finalize_artifacts

Replace the placeholder example above with the actual notation used in the methodology file.

Limitations and Future Work

This post intentionally does not walk through the workflow step‑by‑step; the mechanics are documented in the repository. A follow‑up post will walk through one variant in detail and show how the constraints described here are enforced in practice.

The workflow does not attempt to fix the model; it changes the environment in which the model operates. Small scopes, durable intent, and independent verification reduce the surface area where:

• Requirements can disappear silently.
• Shallow implementations can pass unnoticed.
• Reviewers are pushed into plausibility checks.
• Architectural decisions slip through unexamined.

The workflow assumes these failures will occur if the structure allows them. Its job is to make them harder to hide and cheaper to detect.

Adoption Guidance

• Leverage existing workflows: If you already have strong internal processes, you may only need to adopt select pieces of this guidance.
• Start early, avoid pitfalls: If you’re just beginning with agentic coding, following a structured approach now can help you sidestep costly lessons later in production.

As tools incorporate better built‑in guardrails, some of these recommendations may become redundant. Until then, thoughtful workflow design remains the most reliable control surface we have.

Conclusion

The repository is meant to be copied, adapted, and eventually outgrown. This is one way to do it — not the only way.