A Structured Six-Step Framework for Building AI Agent Workflows That Ship

The gap between a working AI prototype and a deployed production system is larger than it first appears. Prompting your way through a complex build without structure leads to orphaned code, inconsistent architecture, and systems that break in ways that are hard to trace. A repeatable framework — six steps from initial structure through deployment — closes that gap. The approach applies to any agent workflow, regardless of what tools or APIs it connects to.

Step One: Structure Before Anything Else

The first action is creating a CLAUDE.md file in the project directory. This is a persistent instruction file that tells the AI how to organise everything it builds. Without it, the AI makes its own architectural decisions — which are sometimes good and sometimes not, and often inconsistent across a long session.

A useful CLAUDE.md establishes a three-layer architecture. The directive layer contains SOPs written in plain language — markdown files that define objectives, inputs, tool scripts to use, outputs, and edge cases. Think of these as instructions you would give a capable employee. The decision layer tells the AI how to navigate choices — which directive to consult, which tool to call, in what order. The execution layer holds the actual scripts and code, with credentials stored separately in an environment file to keep API keys out of committed code.

This structure works because LLMs are probabilistic — they make mistakes — while business logic is deterministic. Separating the two means errors compound less catastrophically.

Steps Two and Three: Ideation and Planning

Before writing any code, run the AI in plan mode and ask it to propose three different approaches to building what you want. Seeing the options — and their tradeoffs — before committing to one prevents a common mistake: starting down a technical path that creates problems two hours in.

Once you have chosen an approach, ask for two documents: an implementation spec and a task checklist. The spec covers architecture, data flow, and required APIs. The checklist breaks the build into ordered steps. These documents become the reference point for everything that follows. The more structured they are, the more consistently the AI follows them during the build phase.

Step Four: The Build

With structure, ideation, and planning done, the actual code generation is mostly supervised watching. The AI works through the task checklist, creates the directory structure established in CLAUDE.md, writes the scripts, and asks for credentials when it needs them. Credentials go into the environment file; the AI reads them from there and does not embed them anywhere else.

Expect to provide input at key junctures — a specific channel ID, an API key, a clarification on behavior — but the AI handles the structural work without detailed guidance at each step.

Step Five: Testing and Iteration

The first run rarely produces something perfect. Identify what is wrong specifically — formatting issues, missing data, incorrect structure — and describe the problems in plain language. The AI revises and re-runs. Adding a skill (a structured prompt bundle for a specific capability) can meaningfully improve output quality in areas like design, formatting, or domain-specific processing.

Clear the conversation context before re-running complex tasks to avoid the AI carrying incorrect assumptions forward.

Step Six: Deployment with Modal

Modal is a serverless compute platform that charges per execution rather than per month. Deploying to it requires only a brief authorisation flow and a prompt specifying the schedule. The AI handles the Modal configuration. Once deployed, you get a dashboard showing deployment history, execution logs, and the next scheduled run.

Takeaway

The framework's value is not that it makes AI more capable — it makes the AI's output more predictable. Structure, ideation, planning, build, test, deploy, in that order, with documents at each stage. Systems built this way are easier to maintain, easier to hand off, and easier to debug when something goes wrong.