Blog

Stop Describing Your Architecture to AI. Draw It Instead.

The Specification Gap

You spend real time writing out your system to an AI assistant. You're careful. You cover the main components, the flows, the key decisions. The code comes back and it's... close. But the auth layer is missing. A service is calling the wrong database. A parameter type got guessed wrong. An hour later you're still fixing decisions you never actually made.

This isn't a bad prompt. This is what happens when you try to describe a complex system in natural language and expect zero ambiguity.

The two obvious alternatives are both painful. You can write a full spec upfront - but prose specs are hard and slow to write, developers hate doing it, and AI still misinterprets these specs anyway. Alternatively, you can skip the spec, provide short description of what you need, and then fix things after code generation - which feels faster until you realize you're spending more time correcting than you saved. Even switching to voice input doesn't help. It's the same ambiguous language, just spoken instead of typed.

There's a Better Way to Spec

SpecRabbit takes the right approach - writing the spec before generating code - and makes it significantly less painful than writing text specs.

Instead of writing prose, you draw your architecture. Nodes for every component, flows connecting them, parameters defined inside each one. When you're done, you export a single JSON or YAML file and hand it to your AI coding agent. It reads your architecture as structured data - not prose it has to interpret, but explicit facts it can act on directly.

The export also includes built-in instructions for the AI unambiguously explaining exactly how to read every element - node types, parameter meanings, flow relationships, etc. Misinterpretations drop significantly because the AI isn't guessing at meaning, it's reading a document designed to be unambiguous. If you want to understand what the AI is reading, the user guide is the human-readable version of those instructions: https://app.specrabbit.com/help/user-guide.html

What You Can Draw

Seven node types cover the full stack:

  • UI Form — controls, sections, validation rules, etc.
  • API Endpoint — HTTP method, path, auth level, etc.
  • Backend Component — parameters, return types, etc.
  • Database — table definitions, relationships, queries, etc.
  • File Storage — blob and file management.
  • Scheduler — scheduled and recurring tasks.
  • Custom Node — anything that doesn't fit the above.

What Lives Inside Each Node

This is where SpecRabbit goes further than a diagram. Every node has structured parameters - HTTP method, auth level, controls, database queries - and a free text description field for anything that doesn't fit a schema.

Say you're building an order placement service. The structured parameters define the inputs, return type, and what database calls it makes. The description field is where you write, for example:

Must verify inventory availability before reserving stock. If payment fails, roll back the inventory reservation immediately. Do not send the confirmation email until both the payment and inventory steps succeed.

That description travels with the node into the export. The AI generating the service reads both the typed parameters and your behavioral notes together - right there, attached to the component they apply to. No separate documentation to maintain, no context to manually paste in.

The Tool Won't Let You Leave Gaps

You can't add a connection to a database node without specifying the query it should call. You can't add an API Endpoint without specifying the HTTP method and auth level. The constraints are intentional - they force you to make the decisions the AI would otherwise guess at. Which is exactly the point.

One Place for Your Tech Stack

Set your global parameters once - backend framework, frontend renderer, database engine, ORM, auth method, cloud provider, CI/CD platform, compliance requirements, etc. They apply across the entire spec. Validation rules catch incompatible combinations before they reach the AI.

The Export

One JSON or YAML file. Not a screenshot, not a Mermaid diagram, not prose - raw graph topology as structured data. Nodes, edges, typed parameters, flows, etc. The AI reads it natively, no image recognition, no conversion, no guessing. Minimal amount of tokens needed.

The Sync Question

What happens when the code drifts from the spec during development? Can SpecRabbit sync back automatically?

Not yet – and two-way sync feature has a big problem. When AI tries to reconstruct a diagram from existing code, it makes mistakes. It misses things, misreads patterns, produces incomplete graphs. Run that back and forth between diagram and code a few times and the discrepancies pile up. That's not a problem with the spec format - it's just how LLMs work. One-directional is more reliable right now.

The practical workaround: when architecture changes, update the diagram in SpecRabbit, re-export, and ask your AI agent to compare the new spec against the current codebase and reconcile the differences. It's a manual step, but it keeps the spec useful as a living reference throughout the project instead of just a launch artifact.