872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
116 lines
6.5 KiB
Markdown
116 lines
6.5 KiB
Markdown
# Designing for Non-Technical Users ("Vibe Coders")
|
|
|
|
**The question that matters most** — because everything else is worthless if only engineers can use it.
|
|
|
|
### The Fundamental Principle (All 4 Models Converge)
|
|
|
|
> The human should **never have to think in code.** Not in input, not in output, not in error messages, not in verification, not in debugging. The entire technical layer should be absorbed by the system. The human operates purely in **intent, vision, preference, and judgment.**
|
|
|
|
### The Core Philosophy
|
|
|
|
| Human Provides | System Provides |
|
|
|---------------|-----------------|
|
|
| Vision & imagination | Engineering intelligence |
|
|
| Taste & aesthetic judgment | Technical translation |
|
|
| Direction & priorities | Architecture & implementation |
|
|
| "This feels off — calmer, like Linear" | Concrete CSS/animation/spacing changes |
|
|
|
|
### The 10 Pillars of a Magical Non-Technical Experience
|
|
|
|
#### 1. Intent-Based Input, Not Specification
|
|
Users speak naturally: *"I want an app where people can upload recipes and find them by ingredient."* The system runs a **discovery conversation** that feels like talking to a brilliant product partner — not filling out a requirements form. Behind the scenes, answers compile into structured specs, acceptance criteria, and interface contracts the human never sees.
|
|
|
|
> **Critical:** Questions should be about the *experience*, not the *implementation.* Never "relational or document store?" Always "should search find exact matches only, or also substitutable ingredients?"
|
|
|
|
#### 2. Show the Thing, Not the Process
|
|
After each milestone: a **working preview**, not a task list. The human interacts with the real thing at every checkpoint — clicks around, feels it, reacts. Progress is communicated as capability, not code: *"Your app can now save workouts and retrieve them later"* — not *"implemented REST endpoint."*
|
|
|
|
#### 3. Collaborative Builder, Not Command Executor
|
|
The agent should feel like a senior co-founder:
|
|
```
|
|
User: I want something like Notion but for recipes.
|
|
|
|
Agent: Here's how I'd approach that:
|
|
- Recipe database with tagging
|
|
- Search by ingredient
|
|
- Meal planner
|
|
|
|
Would you like to prioritize simplicity or advanced features?
|
|
```
|
|
This implicitly educates the user while avoiding wrong builds from vague specs.
|
|
|
|
#### 4. Problems, Not Errors
|
|
The human should **never see a stack trace**. Technical failures are either resolved silently or translated to domain-level questions:
|
|
|
|
| ❌ Never Show | ✅ Show Instead |
|
|
|--------------|----------------|
|
|
| `TypeError: Cannot read property 'map' of undefined` | "The recipe list isn't displaying correctly. I'm fixing it now — should be ready in a few minutes." |
|
|
| `ECONNREFUSED localhost:5432` | "I'm having trouble connecting to the database. Working on it." |
|
|
| Ambiguous technical decision | "When someone searches 'chicken,' should results include recipes where chicken is optional?" |
|
|
|
|
#### 5. Reactions, Not Reviews
|
|
Design for **reactions** to the running app, not code reviews. Like working with an interior designer: *"I love the color but the couch feels too big."* Visual, spatial, experiential feedback. **A/B comparison** is the most powerful pattern: show two versions, human picks which "feels better" in seconds.
|
|
|
|
#### 6. Engineering Tradeoffs as Simple Choices
|
|
Instead of *"Which auth provider?"* → ask *"Which matters more: A) Simplicity B) Maximum customization C) Enterprise security"* — the system maps answers to technical decisions automatically.
|
|
|
|
#### 7. Safety Blanket
|
|
- Auto-backups every slice + "undo entire feature" button
|
|
- **"Vibe Checkpoints"** — before every major change, a save point. "Go back to how it was ten minutes ago."
|
|
- Deployment previews before anything goes live
|
|
- No irreversible actions without plain-English confirmation
|
|
|
|
#### 8. Progressive Disclosure
|
|
Start ultra-simple. Offer "Advanced mode" toggle only if the user ever asks. The system should **progressively reveal engineering** — at first pure vision → later architecture tweaking → eventually deep collaboration. Many users will never leave the simple mode, and that's fine.
|
|
|
|
#### 9. Implicit Teaching
|
|
When the user asks *"why is that taking longer?"*:
|
|
> "The recipe search needs to look through all recipes every time. I'm adding an index — think of it like a table of contents — so it can find things faster."
|
|
|
|
Optional, triggered by curiosity, expressed in analogy. Over time, users develop useful mental models of software **without it ever being mandatory.**
|
|
|
|
#### 10. Invisible Deployment & Operations
|
|
"I want to share this with people" → receive a URL. Behind the scenes: hosting, domain, database, SSL, CI/CD. Ongoing maintenance equally invisible. Simple dashboard: *"Your recipe app had 340 visitors this week. Everything is running smoothly."*
|
|
|
|
### The Translation Layer (The Magic Glue)
|
|
|
|
A deterministic "Human Translator" node at the front of every orchestrator cycle:
|
|
|
|
```
|
|
Raw user message + references
|
|
↓
|
|
[Human Translator]
|
|
↓
|
|
Precise assumptions, invariants, success criteria
|
|
↓
|
|
[Rest of the god-tier orchestrator pipeline]
|
|
```
|
|
|
|
The rest of the graph never sees "vibe language" — only clean spec. This preserves all technical quality while shielding the user.
|
|
|
|
### The Scope Protection Layer
|
|
|
|
Non-technical users often don't realize how complex their requests are. The system must be honest — gently:
|
|
|
|
> *"That's a great idea. Adding social features is significant — it involves user profiles, a follow system, a feed algorithm, and notifications. It'll take as long as everything we've built so far. Want me to go ahead, or finish core recipe features first?"*
|
|
|
|
This respects agency while providing the information needed for good decisions.
|
|
|
|
### The Meta-Principle
|
|
|
|
> The system is a **creative tool**, not a development tool. It should feel like Photoshop or Ableton — a powerful instrument that lets a person with vision manifest that vision without understanding the underlying mechanics. A music producer doesn't need to understand digital signal processing. A filmmaker doesn't need to understand codec compression. **A person with a great app idea shouldn't need to understand React component lifecycle.**
|
|
|
|
### What Makes It Feel Magical
|
|
|
|
The most powerful systems feel magical when they:
|
|
- Understand vague ideas
|
|
- Ask smart clarifying questions
|
|
- Translate intent into architecture
|
|
- Show visible progress quickly
|
|
- Make experimentation safe
|
|
- Explain decisions clearly
|
|
- Hide complexity without blocking power
|
|
|
|
> When these align, the user experiences: **"I can build anything I imagine."** That feeling is the real product.
|
|
|
|
---
|