User Flows as AI Context
Map it before you build it, and give the map to your AI
You’re building a new product, workflow, or feature and your coding agent is helpful, but unmoored. It’s making strange decisions because it doesn’t know what comes before or after at each step of the process.
That’s not a prompt problem, it’s a documentation problem.
User Flows are the best ways to fix that.
This artifact is called by many names, so to be clear, I am referring to the step-by-step path, rendered as a visual diagram, that a user takes through a digital product to accomplish a goal.
In their current form, a user flows are created, used for alignment and design input, and then forgotten.
That’s a waste. User flows were always reference artifacts. With AI coding agents, they become build context.
The Workflow
Exactly how to generate the necessary files
Create the user flow diagram in your tool of choice, like FigJam, Miro, Microsoft Whiteboard…whatever, it doesn’t matter.
Export the file as a PNG. If it’s really big, slice it up into smaller PNGs from left to right, and then number them in either on the doc or in the filename, so the LLM can re-assemble them. Screenshots will work.
Create a directory in your main project directory called User Flows and save all these files there.
Convert the flow to a markdown (.md) file by dropping those files into Claude or ChatGPT along with this prompt:
The image(s) attached show a user flow diagram for [PRODUCT OR FEATURE NAME]. If there are multiple images, treat them as sequential sections of a single larger flow, ordered as numbered.
Convert this into a machine-readable markdown document to be used as persistent LLM context for a product being actively built. Structure the output as follows:
Overview — One short paragraph describing what this flow represents: the user’s goal, where the flow begins, and what a successful end state looks like.
Flow Diagram — A Mermaid flowchart capturing the complete flow: every step, decision point, branch, and termination state visible in the image(s).
Step-by-Step Breakdown — A numbered list of every step in the flow. For each step, describe what is happening on screen, what the user is doing or deciding, and what comes next. Call out branches explicitly.
Edge Cases and Error States — Any alternative paths, error conditions, empty states, or failure modes visible in the diagram. If none are shown, note that.
Context Notes — Observations useful to someone building or extending this product: assumptions the flow makes about the user, handoff points between user and system, steps that seem underspecified, or anything that would affect implementation decisions.
Output the entire document as a single markdown file. Write it as documentation for a technical collaborator, not a design review. Be specific and structural — the goal is machine-readability, not narrative description.
Here’s a sample of what the markdown output looks like.
# User Flow: Setup Workshop
## Overview
This flow maps the setup and onboarding experience for a workshop teaching participants to use Claude and Claude Code. The user begins as a complete novice (Guide), moves through installing and configuring Claude Code, then progresses through three workshop blocks — each building on the last — ending with a Closing. A successful end state is a participant who has installed Claude Code, created a global `CLAUDE.md`, set up a local project directory with context, and run a live MCP-powered workflow that produces a real output artifact.
---
## Flow Diagram
```mermaid
flowchart LR
A([Guide]) --> B[Go to Claude and ask for\ninstructions to install Claude Code]
B --> C[Open Terminal and\nInstall Claude Code]
C --> D{Installation\nsuccessful?}
D -- Yes --> E["Type 'Claude' to launch"]
D -- No --> C
E --> F[Say Hi to Claude]
F --> G[Create your global\nClaude.md file]
G --> H([BLOCK 2 INTRO])
G -.-> G2["Ask it to create a file\non your desktop that says hello"]
H --> I[Choose your workflow]
I --> J[Stakeholder updates]
I --> K[Research synthesis]
J --> L[Create local Project\nDirectory in Claude]
K --> L
```
---
## Step-by-Step Breakdown
1. **Guide** — Entry point. Participant arrives at the workshop with no assumed prior setup.
2. **Go to Claude and ask for instructions to install Claude Code** — Participant opens Claude (web or app) and uses it to retrieve installation instructions. Note: a pre-workshop prompt instructs facilitators to tell participants that if they have a setup question, they should try asking Claude first.
3. etc....
---
## Edge Cases and Error States
- **Installation failure loop** — If installation is unsuccessful at step 4, the flow returns to step 3 with no defined exit condition. There is no escalation path (e.g., ask facilitator, consult docs) shown. This is a gap.
- **Workflow branch divergence** — Branches A and B in Block 2 (stakeholder updates vs. research synthesis) converge at step 10, but it is not shown whether the workflow content in Block 3 differs by branch. The Block 3 branches (transcript to tickets, research synthesis, stakeholder updates) suggest the workflow type persists and shapes the output — but the handoff is implicit.Download and save this .md document from the LLM to the same folder where you saved the image(s) of the workflow.
You now have the context needed.
How to use it
Planning & Building
Spot check your designs against the user flows by including the image files and the user flow markdown file and asking the agent to point out where the designs deviate, skip steps or otherwise impede the workflow. It will find your blind spots whether you like it or not.
Write your PRD with the user flow as primary context. Feed the flow document to Claude or ChatGPT and then have it draft requirements against it. When you're done, ask the agent to cross-reference the PRD against the flow and flag any inconsistencies or steps the requirements don't cover. You'll catch gaps before they become assumptions baked into the build.
Generate a build plan file before you start building, with the flow as a guide. Ask your agent to produce a checklist of every screen, state, decision point, and edge case the flow requires. Use that as your definition of done before you open a code editor. As you build, have the agent check items off the checklist.
Post-Build & Iteration
Use the flow as a QA document against the live app. Instruct your coding agent to walk through the live product against the flow file and report where the implementation diverges, where edge cases are unhandled, and where the user experience breaks from what was intended. You get a structured gap analysis in minutes instead of hours.
When you're adding new features, ask the agent what the implications of the new functionality are for the existing flow. What breaks, what needs to branch, what new states are introduced, etc. This forces you to think in system terms before you're already mid-build and committed to a direction.
Artifacts as Infrastructure
Stop thinking of the artifacts you create as “deliverables” to be used once and discarded. Your user flow doesn't stop being useful when the build starts. It becomes the context your agent uses for the entire life of the product, which can be updated and modified as time goes on.
User flows are just the beginning. There’s a whole discovery process worth of context that most product builders never convert into usable formats. The process is the same: convert the artifact into a machine readable format and make it accessible to the coding agent.
We’ll cover how to use these other artifacts as context as we go:
User Research & Customer Interviews
Journey Maps
Wireframes & Comps
Content Strategy
Product Strategy
OKRs
KPIs
Meeting Notes
We’ll get into the rest in future articles and conversations - subscribe to follow the series.
About Us
Design Language is a newsletter for all product builders (PMs, Engineers, Founders, etc) who want to improve their design literacy, hone their sense of taste, and improve their craft when building products.
Jeremy Belcher is a 15 year product and design veteran. He has designed UX/UI for products used by tens of millions for brands like Google, Salesforce, Saturday Night Live, DirecTV, BMW, Emirates, Visa and in the past several years has focused on new enterprise workflow products. He runs the product studio Robot Heart, which designs, builds, and validates 0 → 1 B2B workflow tools for teams and founders.
David Issa is a digital strategy and product design leader with over 15 years of experience guiding companies through transformation. He has helped scale products and teams across healthcare, fintech, and enterprise software, translating complex systems into human-centered experiences. David runs a strategic design practice focused on aligning purpose, architecture, and execution—bridging design, AI, and organizational strategy to help teams build with clarity and intent.