AI Project Architecture Workflow
Design a system's architecture on its real trade-offs instead of a confident diagram — put the model in an architect's seat, work the decisions one at a time, and write down the why.
The problem
Architecture is the set of decisions that are expensive to reverse, and 'ask AI to design it' produces a confident diagram that ignores your constraints, reaches for the trendy option, and is forgotten by next sprint. Designing architecture well is about the trade-offs — where the boundaries go, how data flows, what you optimize for and what you give up — and writing the reasoning down so the next person, usually future-you, knows why. This workflow puts the model in an architect's seat, works the decisions one trade-off at a time, and ends with a document, not a forgotten chat.
Recommended workflow
Each step uses an existing NewPrompt tool, pre-filled by a matching resource. Open the resource to read it, or jump straight into the tool with the inputs ready.
-
Put the model in an architect's seat
Anchor the model as a software architect so it reasons about boundaries, data flow, scale, and reversibility — the decisions that are expensive to undo — instead of jumping straight to code.
Goal The model designing like an architect, weighing trade-offs, not writing code.
Open this step in Role Prompt GeneratorResource Software Architect Role Prompt -
Work the trade-offs one decision at a time
Break the design into its real decisions — service boundaries, data model, sync versus async, build versus buy — and for each, lay out the options and what each one trades away. One reasoned decision at a time beats a single hand-wave diagram.
Goal Each key architecture decision with its options and the trade-off it accepts.
Open this step in Multi-Step Prompt Builder -
Document the decisions and their why
Capture the chosen architecture and, more importantly, the reasoning — the trade-offs accepted, the alternatives rejected — in a document the team can return to when someone asks 'why is it built this way?'
Goal An architecture document that records the decisions and their reasoning.
Open this step in Markdown Output BuilderResource Technical Documentation Prompt
Expected outcome
A system architecture decided on its real trade-offs and written down — boundaries, data flow, and technology choices, each with the reasoning behind it — so the build starts from a deliberate design and the team can answer 'why is it this way?' months later.
Best for
- Designing the architecture of a new system or feature
- Choosing between architectural options on their trade-offs
- Recording architecture decisions so the reasoning survives
Not for
- Scoping a first release — use the AI MVP Planning Workflow
- Documenting existing code — use the AI Code Documentation Workflow
- Understanding an existing system's architecture — use the AI Codebase Onboarding Workflow
FAQ
How is this different from the AI MVP Planning Workflow?
MVP planning decides WHAT to build first — the scope. This decides HOW to build it — the structure: boundaries, data flow, technology. Different axis: scope versus architecture. You'd usually scope the MVP, then design the architecture for that scope.
How is this different from the AI Code Documentation Workflow?
Code documentation describes code that already exists. This designs and documents architecture decisions for code you haven't built yet — forward design, not reverse description. The output is decisions and trade-offs, not API docs.
Does the AI decide my architecture for me?
No. It structures the trade-offs and pressure-tests the options so your decision is deliberate and recorded. The architecture call — and owning its consequences — stays with you.
Part of these blueprints
Complete build journeys that include this workflow as a stage.
Where to go next
Related workflows