01. Requirements & Architecture — Vibe Coding Series

Three weeks into the project, I realized I’d misunderstood the requirements from day one.

The client said “users can assign tasks to each other.” I heard that, the AI implemented that — a user picks a task, picks a recipient, hits assign. Done. Simple.

But during the demo, the client asked: “Wait, why can’t the team lead approve before assigning?” I froze. Nobody mentioned an approval flow. I didn’t ask. The AI didn’t ask. We both assumed.

Three weeks of code, one demo session, and I had to redesign the entire permission model.

---

Context

In article 00, I introduced the Vibe Coding Framework — 8 phases from idea to production — and covered environment setup for working with AI agents. This article dives into Phase 1: gathering requirements, analyzing them, and locking in architecture before writing a single line of code.

This is the phase most people skip. And that’s exactly why they spend weeks fixing things that shouldn’t have existed in the first place.

---

The Problem: Requirements Are Where AI Hallucinates Most

AI is great at writing code. But AI is terrible at knowing what it’s writing code for.

When you hand AI a vague brief — “build task management for a team” — it won’t ask clarifying questions. It will assume. It will fill in the blanks with what it’s seen in training data: Trello, Jira, Asana. The result is something that looks familiar but isn’t what you actually need.

This isn’t the AI’s fault. It’s a process failure.

Requirements are the only place in the entire development cycle where ambiguity compounds exponentially. One wrong assumption here → wrong architecture → wrong implementation → wrong tests → wrong product. And you only find out at the end.

---

Techniques for Analyzing Requirements with AI

Socratic Questioning: Let AI Ask You Back

Instead of handing AI a brief and telling it to implement, hand it the brief and tell it to question you.

Prompt:
"Here's my brief: [brief]. Before implementing anything,
ask me all the questions needed to clarify the requirements.
Focus on: edge cases, permission models, hidden business rules,
and things I might have assumed without stating."

When I tried this with TaskFlow, the AI immediately asked:

• “When a task is deleted, are comments and attachments deleted too?”
• “Can a user assign a task to themselves?”
• “Is the deadline in the user’s timezone or the server’s timezone?”
• “If a member is removed from the team, what happens to their assigned tasks?”

Four questions. Four edge cases I hadn’t thought about. And this was just a fraction of one feature.

Creating User Stories + Acceptance Criteria with AI

Once requirements are clarified, use AI to format them into user stories with clear acceptance criteria. The format I use:

User Story: Assign task
As a [team member]
I want to [assign a task to another member]
So that [the assignee knows they're responsible for it]

Acceptance Criteria:
- [ ] Only task creator or team lead can assign
- [ ] Assignee receives email notification within 5 minutes
- [ ] Task shows assignee's avatar in list view
- [ ] Cannot assign to user outside the team
- [ ] Assigning to self is allowed
- [ ] Previous assignee is notified when reassigned

The value of this format: it forces you to think about who does what and why — not just “we need a task assign feature.” And when AI implements, it has a concrete checklist to validate against.

Finding Edge Cases and Conflicts Early

After you have user stories, use AI to find conflicts:

Prompt:
"Here's my list of user stories: [list]. Please find:
1. Conflicts between stories (story A and B contradict each other)
2. Missing stories (story A exists but story B, which is a prerequisite, is missing)
3. Ambiguous acceptance criteria (criteria that can be interpreted multiple ways)"

With TaskFlow, the AI immediately caught: the story “team lead can view all tasks” conflicted with “tasks are only visible to assignee and creator” — two requirements from two different stakeholders, and nobody noticed until they were placed side by side.

---

Locking in Architecture: AI as a Sparring Partner

Ask the Right Questions to Get Architecture Proposals

Don’t ask AI “what’s the best architecture for my app.” That’s too broad — you’ll get a generic answer.

Ask more specifically:

Prompt:
"Given these requirements: [requirements], a 2-person team, 3-month timeline,
limited budget, and a need to scale to 10k users in year one — propose
3 different architectures with the trade-offs of each. I'll decide."

You’re the one deciding. AI is the one presenting options.

Trade-off Analysis: A Real Example

With TaskFlow, I asked AI about the database choice. Here’s a summary of the trade-off it laid out:

	PostgreSQL (Supabase)	MongoDB	PlanetScale (MySQL)
Best for	Relational data, RLS, realtime	Flexible schema, document-heavy	Serverless, branching
Strengths	ACID, Row Level Security built-in	Schema flexibility	Horizontal scale
Weaknesses	Schema migrations need care	Consistency is more complex	No native RLS
For TaskFlow	✅ Best fit — RLS for multi-tenant	⚠️ Overkill, data is still relational	⚠️ Missing RLS

I chose PostgreSQL/Supabase. Not because AI said so — but because I understood why after reading the trade-offs.

Ownership Map: Who Owns What

After locking in architecture, create an ownership map — a document that defines which parts AI implements, which parts humans implement, and which parts require mandatory human review.

# TaskFlow — Ownership Map

| Module | Owner | Review Required |
|--------|-------|-----------------|
| Auth (Supabase) | AI | Human final check |
| Row Level Security policies | Human | — |
| CRUD API routes | AI | Human spot-check |
| Email templates | AI | Human review |
| Payment integration | Human | — |
| Database migrations | Human | — |
| UI components | AI | Human review |
| Deployment config | Human | — |

Rule of thumb: anything touching security, money, or data integrity — humans own it. AI can draft, but a human must review and approve.

---

Real-World Example: TaskFlow from Vague Brief to Locked Architecture

Original brief (what I started with):

“Build a task management app for indie teams. Auth, task CRUD, dashboard, invite members, email notifications.”

After Socratic questioning — what AI asked and I answered:

• Multi-tenant? → Yes, each team is a separate workspace
• Role-based access? → Yes: Owner, Admin, Member
• Real-time updates? → Not needed for MVP
• File attachments? → Not in MVP
• Mobile app? → No, web only

User stories generated: 23 stories, grouped into 5 epics (Auth, Team, Task, Dashboard, Notification)

Conflicts found: 2 conflicts around visibility rules, 1 missing story for “deactivate member”

Architecture locked:

• Next.js 15 App Router (full-stack, single repo)
• Supabase (PostgreSQL + Auth + RLS)
• Resend (email)
• Vercel (deploy)
• Monolith — no microservices (small team, MVP, scale later)

From a 50-word brief to a clear architecture: about 2 hours. Not 3 weeks.

---

Pitfalls

Approving AI-proposed architecture without understanding it. AI might suggest microservices because it’s “best practice” — but for a 2-person team and a 3-month MVP, microservices are overkill. If you don’t understand the trade-offs, you can’t push back. And you’ll live with that decision for months.

Ignoring non-functional requirements. “The app should be fast” is not a requirement. “API response < 200ms at the 95th percentile with 1000 concurrent users” is a requirement. AI won’t ask about performance, security, or scalability unless you do. You have to be proactive.

---

Summary

• Hand AI your brief and tell it to ask you back — fastest way to surface hidden assumptions
• User story + acceptance criteria is the “contract” between you and AI — without it, AI will assume
• Use AI to find conflicts and missing stories before coding, not after
• Trade-off analysis: AI presents options, you decide — never the other way around
• Ownership map defines who’s responsible for what — especially critical for security and data

---

What’s Next

Phase 2 tackles the next problem: when frontend and backend build in parallel without a shared contract, integration is a nightmare. The next article covers writing an API spec before coding — and why this is the single biggest time-saver in the entire framework.

→ Article 02: Specs & API Contract First

← Article 00: Foundation & Setup