Seeing the Architecture

I've spent the last three weeks building fast. Four projects from idea to MVP. DataSphere shipped in eleven days. Coaching Animator went from concept to working prototype in hours.

This is exactly what vibe coding promised: velocity without getting stuck in tutorial hell.

But there was a problem I didn't see coming.

The Invisible Architecture Problem

When you're moving fast with AI agents, the code appears like magic. You describe what you want, the agent writes it, tests pass, feature ships.

Except - where did it put the validation logic? How is state being managed? What happens if that API call fails?

I could ship features. I just couldn't tell you how they actually worked.

The code wasn't invisible because it was bad. It was invisible because I had no framework for seeing it.

The Shift: Spec-Driven Development

Then I found spec-driven development tools (Spec-Kit, GSD). The idea is simple: before writing code, write a PRD. Then break it down into structured specs, plans, and tasks.

I thought this would slow me down. The opposite happened.

Here's what changed:

Before:

• Me: "Build a data visualization dashboard"
• AI: [Writes 800 lines of code]
• Me: "Uh... okay, looks good?"

After:

• Me: [Writes PRD defining requirements]
• Spec tool: [Generates functional spec, technical plan, task breakdown]
• AI: [Executes Task 1: Set up routing structure]
• Me: "Oh - so that's where the pages live. Got it."
• AI: [Executes Task 2: Create data service layer]
• Me: "And that's the abstraction for API calls. Makes sense."

The difference? I could see what was being built, step by step.

What I'm Actually Seeing Now

I still don't fully understand the code. I can't write a React component from scratch. But now I can see:

• Architecture patterns: "This uses a service layer to separate concerns"
• Data flow: "User input goes through validation, hits the API, updates state"
• Error boundaries: "If the API fails, it falls back to cached data"

It's like the difference between watching someone cook versus following a recipe. I'm not a chef yet. But I know why they added the garlic before the tomatoes.

The Security Wake-Up Call

Shipping fast also meant I was shipping vulnerabilities I didn't know existed.

Things I wasn't thinking about:

• Rate limiting: What stops someone hammering my API?
• Input validation: Am I trusting user input I shouldn't?
• Secret exposure: Are API keys visible in client code?
• Client-side calculations: Can users manipulate pricing logic in the browser?

Vibe coding taught me to ship. Spec-driven development is teaching me to ship safely.

Now my PRDs include a security checklist:

• Where does validation happen?
• What needs rate limiting?
• Are secrets server-side only?
• What's the blast radius if this fails?

I don't implement these perfectly. But at least I'm asking the questions.

What This Actually Looks Like

Here's a real example from DataSphere:

The vibe-coded version (Week 1):

• No error handling
• Secrets in environment variables (but exposed client-side)
• Zero rate limiting

The spec-driven rebuild (Week 2):

• PRD defined data flow and security requirements
• Tasks broke down: validation layer, error boundaries, rate limiting
• AI implemented each piece with clear separation

Same feature. Same AI. Different approach.

The first version worked. The second version was something I could maintain.

The Tradeoff I'm Still Figuring Out

Spec-driven development takes longer upfront. Writing a PRD and breaking it into specs adds 30-60 minutes before any code gets written.

But execution is faster. And I'm not backtracking to fix security holes or untangle spaghetti architecture.

The pattern I'm testing:

• Quick prototypes: Vibe code it. See if the idea has legs.
• Real tools: Spec it first. Build it right.

Still early. Ask me again in three months.

What I Learned

Velocity without visibility is fragile.

I can ship features fast with AI agents. But if I can't see the architecture, I can't maintain it. Or secure it. Or explain it.

Spec-driven development didn't slow me down. It gave me a map of what was being built.

I still don't write the code myself. But now I can see the shape of what's being created. That's the difference between using AI as a black box and using it as a collaborator.

The goal isn't to understand every line of code. It's to understand the system well enough to ask: "Is this what we actually need?"

Sometimes the answer is yes. Sometimes it's "wait, why are we calculating prices on the client?"

That's the question I couldn't ask three weeks ago.

Now I can.

---

Tools I'm exploring:

• Spec-Kit: Spec-driven development framework
• GSD: Claude power development workflow
• Qdrant: Vector database for RAG applications
• OpenRouter: Multi-model API access

What's next:

• DataSphere: Learning Management System to host a colleague's Data Science expertise
• Coaching Animator: Visual training session builder
• Security hardening: Retrofitting older projects with proper validation

If you're vibe coding fast and starting to feel like you're building on sand - try writing a PRD before your next feature. Even a bad spec is better than no spec.

You might not understand the code. But at least you'll see what's being built.