Agent gera código cego. Como fazer entender design?

Agent gera código cego. Como fazer entender design?

Você é founder de SaaS.

Você tem AI agent (code generation, automação, assistente).

Agent é rápido (gera 100 linhas/segundo).

But there's a problem:

Your agent workflow: ├─ You: "Create a login form with email validation" ├─ Agent: Generates code (HTML + JavaScript + validation logic) ├─ You: Review code (looks good) ├─ Deploy: Send to production ├─ ├─ Problem surfaces (1 week later): │ ├─ Form doesn't match design system (colors, spacing wrong) │ ├─ Validation doesn't handle edge cases (phone number as email?) │ ├─ Doesn't integrate with analytics (can't track signup funnel) │ ├─ UX flow is weird (no error states, no loading states) │ ├─ Accessibility broken (no ARIA labels, no keyboard nav) │ ├─ Result: │ ├─ Code "works" (functionally correct) │ ├─ But product quality is bad (user experience sucks) │ ├─ You spend 5 hours fixing (worse than writing from scratch) │ ├─ Agent "saved" 1 hour of writing │ ├─ But cost you 5 hours of fixing │ ├─ Net: -4 hours (agent made you slower) │

Why? Because agent doesn't understand the "why" behind code. It only knows "what" (features, syntax). It's blind to design constraints, business requirements, system architecture. Result: Code that works, but isn't good. You need agent that understands context (design, UX, constraints). That's the whiteboard problem.

---

O problema real (por que agents geram código ruim)

Dilema 1: Agent só vê feature request (não vê contexto)

=== CONTEXT BLINDNESS === │ You tell agent: ├─ "Create a login form" │ Agent understands: ├─ Create form element ├─ Add email field ├─ Add password field ├─ Add submit button ├─ Add validation (email format) │ Agent doesn't understand: ├─ Design system (use these colors, fonts, spacing) ├─ Analytics integration (track signup success rate) ├─ Error handling (what if email already exists?) ├─ UX flow (loading state? confirmation email? multi-step?) ├─ Security (rate limit? CSRF token? password strength?) ├─ Accessibility (ARIA labels? keyboard navigation?) ├─ Business logic (does user auto-login after signup? or manual?) ├─ Performance (is this form on critical path? needs to be < 100ms?) ├─ Testing strategy (what test cases are important?) ├─ Deployment concerns (feature flags? A/B testing?) │ Result: ├─ Agent generates code that covers bare minimum ├─ Missing 80% of real requirements ├─ You spend hours fixing gaps │

Dilema 2: Agent can't ask clarifying questions (doesn't know what's missing)

=== QUESTION-ASKING GAP === │ Good developer (when given vague request): ├─ "Login form? I have questions:" ├─ "1. What's our design system (colors, fonts)?" ├─ "2. Do we track analytics?" ├─ "3. What error cases matter (duplicate email? network fail?)?" ├─ "4. Multi-step signup or one-step?" ├─ "5. Auto-login or manual? Email verification?" ├─ "6. Accessibility standards (WCAG 2.1 AA)?" ├─ "7. Performance budget?" ├─ "8. Feature flags needed?" │ Agent (when given same request): ├─ Assumes answers (guesses) ├─ Fills gaps with "standard" approaches (often wrong) ├─ Generates code without asking │ Result: ├─ Good developer: Asks 8 questions → builds right thing ├─ Agent: Guesses 8 answers → builds wrong thing ├─ You spend hours communicating what was missing │

Dilema 3: Agent doesn't understand system constraints (builds in isolation)

=== ISOLATION PROBLEM === │ Your system has: ├─ Database schema (users table has specific columns) ├─ API contracts (login endpoint returns specific JSON) ├─ Design system (button component has specific props) ├─ State management (Redux store structure) ├─ Error handling patterns (how to handle 401 vs 403) ├─ Naming conventions (camelCase vs snake_case) ├─ Code organization (where does this file go?) ├─ Testing patterns (how to test this function?) ├─ Performance constraints (this is on critical path, must be fast) │ Agent knows: ├─ General best practices (sometimes wrong for your system) ├─ Generic patterns (doesn't match your specific architecture) ├─ Nothing about your business (what's actually important?) │ Result: ├─ Agent generates code that is "correct" in isolation ├─ But breaks when integrated with your system ├─ You spend hours refactoring to fit constraints │

Dilema 4: You can't "whiteboard" with agent (no shared design space)

=== DESIGN COLLABORATION GAP === │ Human-to-human design session (whiteboard): ├─ You: "I'm thinking login form here" ├─ Dev: "Show me sketch" ├─ You: (draws on whiteboard) ├─ Dev: "Wait, what about error states?" ├─ You: "Good point, let me add that" ├─ Dev: "And mobile? How does it look on phone?" ├─ You: "Let me adjust width and stacking" ├─ Dev: "Better. What about accessibility?" ├─ You: "ARIA labels here and here" ├─ Dev: "I see. Now I understand the full picture." ├─ Dev: Goes and builds it correctly (first try) │ Human-to-agent workflow (current): ├─ You: "Create login form with email validation" ├─ Agent: Generates code ├─ You: "Wait, this doesn't match design system" ├─ Agent: "Oh, I didn't know that. Let me fix it." ├─ Agent: Regenerates (fixes one thing, breaks another) ├─ You: "Now the UX flow is wrong" ├─ Agent: "I'll adjust..." ├─ (Loop repeats 5+ times) │ Result: ├─ Human-to-human: 1 design session → correct code (first try) ├─ Human-to-agent: 10 iterations → mostly correct code (eventually) ├─ Agent model is broken (needs redesign) │

---

Solução (como Whiteboard resolve)

O conceito: "Whiteboard for code"

=== WHITEBOARD IDE CONCEPT === │ Whiteboard (tool built by Sid, Alex, Ketan, Milan @ YC W26): ├─ What it is: Open-source IDE where humans + agents collaborate ├─ How it works: │ ├─ Step 1: Human + agent enter shared workspace │ ├─ Step 2: Human sketches architecture (visual diagram) │ ├─ Step 3: Agent sees constraints (from diagram) │ ├─ Step 4: Agent generates code that matches diagram │ ├─ Step 5: Human reviews (sees code + diagram together) │ ├─ Step 6: Agent adjusts (based on feedback) │ ├─ Loop: Repeat until right │ ├─ Key feature: Shared context │ ├─ Agent can see design constraints (in visual form) │ ├─ Human can see agent's understanding (agent explains choices) │ ├─ Both working from same mental model (alignment) │ ├─ Key feature: Design-first │ ├─ Human draws architecture (components, data flow, constraints) │ ├─ Agent generates code that implements that architecture │ ├─ Result: Code matches design (by construction) │ ├─ Key feature: Integrated tools │ ├─ Plugs into Claude Code, VS Code, etc │ ├─ Uses your existing workflows │ ├─ Doesn't require learning new tool │

Como isso muda o game

=== OLD VS NEW WORKFLOW === │ OLD (Agent only): ├─ You: "Build login form" ├─ Agent: Guesses everything → code misses 80% of requirements ├─ You: Spend 5 hours fixing ├─ Result: Slower than if you coded manually │ NEW (Whiteboard + Agent): ├─ You: Draw architecture (5 min) │ ├─ Boxes: Components (LoginForm, ErrorMessage, LoadingSpinner) │ ├─ Arrows: Data flow (User input → Validation → API → Success) │ ├─ Constraints: Design system colors, performance budget, accessibility ├─ Agent: Sees diagram → generates code that matches (10 min) ├─ You: Review (2 min) - code matches design perfectly ├─ You: Small tweaks if needed (5 min) - mostly done ├─ Total: 22 minutes (vs 60+ minutes without diagram) │ Result: ├─ Agent understands context (from diagram) ├─ Code quality is high (matches design by construction) ├─ You spend less time fixing ├─ Agent is actually faster (not slower) │

---

Por que isso importa (para seu SaaS)

Problem 1: Code quality suffers (when agent doesn't understand constraints)

Scenario: You're using AI to generate customer support responses. │ Without context (agent blind): ├─ Customer: "My order is delayed" ├─ Agent: "I understand. Let me check our system." ├─ Agent: Generates response (generic template) ├─ Response: "Your order is in our system. Please wait." ├─ Customer: Unsatisfied (no actual help) ├─ Result: Churn │ With context (agent sees constraints): ├─ Customer: "My order is delayed" ├─ Agent sees: │ ├─ Your SLA: Respond in < 2 hours │ ├─ Your tone guide: Empathetic + solution-focused │ ├─ Your systems: Access to order DB, shipping API │ ├─ Your policies: Refund if >3 days late ├─ Agent generates response (contextual): │ ├─ "I see your order #12345 shipped on Sept 20, due today." │ ├─ "Currently 1 day overdue. I'm escalating to logistics." │ ├─ "If not delivered by Sept 24, I'll issue refund." │ ├─ "I'll follow up tomorrow." ├─ Customer: Satisfied (knows what's happening) ├─ Result: Retention │ Difference: ├─ Without context: Generic, unhelpful ├─ With context: Specific, actionable ├─ Context = Quality │

Problem 2: Speed doesn't matter (if direction is wrong)

Scenario: You're using AI to generate sales copy. │ Fast but wrong: ├─ Agent generates: "Our product is the best." ├─ Speed: 1 second (very fast) ├─ Quality: Bad (generic, non-persuasive) ├─ You: Rewrite (takes 30 minutes) ├─ Net: -29 minutes (slower than writing manually) │ Slow but right: ├─ You: Spend 5 minutes giving agent context │ ├─ "Our product is 10x cheaper than competitors" │ ├─ "Our customers are small e-commerce shops" │ ├─ "Their pain: High payment processing fees" │ ├─ "Our tone: Friendly, not corporate" ├─ Agent: Generates sales copy (using context) (10 seconds) ├─ Copy: "Stop overpaying for payments. We process at 1% (vs 3%)." ├─ Quality: Good (specific, persuasive) ├─ You: Minor tweaks (2 minutes) ├─ Net: +5 minutes (faster than manual) │ Difference: ├─ Fast + wrong = waste of time ├─ Slower + right = actually faster ├─ Context turns "fast" into "useful" │

Problem 3: Collaboration is broken (agent vs human friction)

Current model (agent only): ├─ You have vision (design, UX, business logic) ├─ Agent has speed (generate code fast) ├─ You: "Agent, build this." ├─ Agent: Builds (but misses your vision) ├─ You: "That's wrong. Fix it." ├─ Agent: "Fixing..." ├─ (Repeat 10 times) ├─ Outcome: Frustration (agent slow and wrong) │ Better model (whiteboard + agent): ├─ You + Agent: Sketch together (shared mental model) ├─ You: "I want these components" ├─ Agent: "I see. And these constraints?" ├─ You: "Yes, exactly." ├─ Agent: "Building..." ├─ Agent: Generates code (matches design perfectly) ├─ You: "Great. Small tweaks here..." ├─ Agent: "Got it." ├─ Outcome: Alignment (agent fast and right) │ Difference: ├─ Without shared space: Friction, rework ├─ With shared space: Alignment, efficiency │

---

Praktick implementacija (kako koristiti whiteboard pattern)

Za agente u customer support (atendimento)

=== SUPPORT AGENT WHITEBOARD === │ Setup (once): ├─ Create diagram of your support process │ ├─ Tier 1: FAQ responses (automated) │ ├─ Tier 2: Troubleshooting (guided) │ ├─ Tier 3: Escalation (human) ├─ Define constraints │ ├─ Response time: <2 hours │ ├─ Tone: Empathetic + professional │ ├─ Tools available: Order DB, ticket system, refund API │ ├─ Policies: Refund if >3 days late │ ├─ Do's: Acknowledge problem, provide timeline, offer solution │ ├─ Don'ts: Be generic, blame customer, avoid refund │ Usage (per ticket): ├─ Agent sees ticket ├─ Agent refers to diagram (which tier does this belong?) ├─ Agent checks constraints (what's allowed?) ├─ Agent generates response (based on diagram + constraints) ├─ Response quality: High (matches your spec) │ Benefit: ├─ Agent never generates generic response (always uses diagram) ├─ Response quality consistent (all follow same spec) ├─ You spend less time fixing (agent already knows what's right) │

Za agente u sales (automação de vendas)

=== SALES AGENT WHITEBOARD === │ Setup (once): ├─ Create diagram of your sales funnel │ ├─ Stage 1: Awareness (cold email) │ ├─ Stage 2: Engagement (reply to objection) │ ├─ Stage 3: Discovery (qualify lead) │ ├─ Stage 4: Pitch (present solution) │ ├─ Stage 5: Close (negotiate terms) ├─ Define constraints │ ├─ Tone: Personal (not corporate) │ ├─ Length: Short (2-3 sentences max) │ ├─ Personalization: Mention their company/role │ ├─ Pain points: Reference their specific problem │ ├─ CTA: Clear next step (call? demo? lunch?) │ ├─ Don'ts: Spam, long-winded, generic │ Usage (per lead): ├─ Agent sees lead profile ├─ Agent refers to diagram (which stage are they in?) ├─ Agent checks constraints (what should tone be?) ├─ Agent generates message (based on diagram + constraints) ├─ Message quality: High (personal + relevant) │ Benefit: ├─ Agent never sends generic email (always personalized) ├─ Conversion rates higher (personal emails convert better) ├─ You spend less time reviewing (agent already knows spec) │

Za agente sa product development (generisanje koda)

=== CODE GENERATION WHITEBOARD === │ Setup (once): ├─ Create architecture diagram │ ├─ Components: What are main parts? │ ├─ Data flow: How does data move? │ ├─ Constraints: Performance budget, accessibility, design system ├─ Document constraints │ ├─ Design system colors, fonts, spacing │ ├─ API contracts (what endpoints? what JSON?) │ ├─ Database schema (what columns?) │ ├─ Performance targets (<100ms) │ ├─ Accessibility: WCAG 2.1 AA │ ├─ Testing: What test cases matter? │ Usage (per feature): ├─ You: "Build login form" ├─ Agent: Refers to diagram (components, data flow) ├─ Agent: Checks constraints (design system, API, DB, performance) ├─ Agent: Generates code (matches diagram + constraints) ├─ Code quality: High (architecturally sound, meets all constraints) │ Benefit: ├─ Agent never generates code that breaks architecture ├─ Code integrates smoothly (matches your system) ├─ You spend less time refactoring (agent got it right first time) │

---

Próximos passos (actionable)

Esta semana

1. Map your constraints (1 hour) ├─ If support agent: Design matrix (tiers, tone, tools, policies) ├─ If sales agent: Sales funnel (stages, tone, personalization, CTA) ├─ If code agent: Architecture (components, data flow, constraints) ├─ Document: In visual form (diagram, not just text)

2. Test with agent (30 min) ├─ Give agent your diagram + constraints ├─ Ask agent to generate output (response/email/code) ├─ Review quality (better than before?) ├─ Iterate (refine diagram based on feedback)

3. Measure baseline (1 hour) ├─ Current: How much time do you spend fixing agent output? ├─ Document: Average fixes per response/email/code ├─ Baseline: 5 hours/week fixing? 10 hours? 20?

Time: ~2.5 hours Cost: R$0 (internal time) Output: Diagram + baseline metrics

Next 2 weeks

1. Implement constraints (4-6 hours) ├─ Add diagram to your agent prompt ├─ Add constraints to your agent prompt ├─ Document: "Agent, here's the spec. Follow it."

2. Test systematically (2-3 hours) ├─ Run 20 samples (responses/emails/code) ├─ Measure: Time to fix each output ├─ Compare: Before (no diagram) vs after (with diagram) ├─ Calculate: Time savings

3. Refine diagram (2-3 hours) ├─ Where did agent still fail? (diagram was missing constraint) ├─ Add missing constraint ├─ Re-test (better?) ├─ Repeat until satisfaction

Time: ~8-12 hours Cost: R$0 (internal time) Output: Working diagram + constraint list + data on time savings

Next month

1. Scale across team (2-3 weeks) ├─ If multiple agents: Apply diagram to each ├─ If multiple humans: Teach team the diagram ├─ Governance: Keep diagram updated

2. Measure impact (1-2 weeks) ├─ Metric 1: Time spent fixing agent output (should drop 30-50%) ├─ Metric 2: Quality of agent output (should improve 20-30%) ├─ Metric 3: Satisfaction (your satisfaction with agent, should improve)

3. ROI calculation ├─ Hours saved/month × your hourly rate = savings ├─ Investment (time to create diagram + train team) < Savings ├─ Result: Positive ROI in month 2-3

Time: ~4-6 weeks Cost: R$10K-30K (your time, team time) Output: Scaled whiteboard pattern + documented ROI

---

Conclusão

Simple verdade:

Your AI agent generates code fast, but blind (doesn't understand context). Result: Code that works, but quality is bad. You spend hours fixing. Agent is slower than manual. Solution: Add "whiteboard" (shared design space where human + agent collaborate). Human draws architecture + constraints. Agent generates code that matches. Result: Code quality is high (first try). You spend less time fixing. Agent is actually faster. Tool: Whiteboard (open-source IDE by YC founders) implements this pattern. Bottom line: Agents need context to be useful. Whiteboard provides that context.

3 facts:

1. Agents without context generate low-quality output (80% of real requirements missing). Reason: Agent doesn't know your design system, business logic, constraints. Agent guesses (wrong). You spend 5+ hours fixing what agent got wrong. Net: Agent makes you slower. Solution: Give agent context (through whiteboard/diagram). Agent then generates high-quality output (first try). You spend <1 hour tweaking. Net: Agent makes you faster. Context = everything.

2. Current AI workflows have collaboration broken (human vs agent friction). Problem: You have vision. Agent has speed. You tell agent what to build. Agent builds wrong thing (missed your vision). You say "fix it". Agent fixes one thing, breaks another. Loop repeats 10+ times. Frustration sets in. Solution: Use whiteboard model (human + agent design together). You sketch architecture. Agent sees it. Agent builds matching code. Alignment, not friction. Outcome: Faster + better.

3. Whiteboard pattern works for any AI task (not just code). Examples: Support responses (use diagram of tiers + tone). Sales emails (use diagram of funnel + personalization). Product copy (use diagram of messaging). Customer segmentation (use diagram of personas). Recommendation engine (use diagram of preferences). Principle: Whatever task your AI does, give it context (through diagram). Context makes it smarter.

3 action items (this week):

1. Map your AI's constraints (1 hour, today). If support: Draw matrix (tiers, tone, tools). If sales: Draw funnel (stages, tone, personalization). If code: Draw architecture (components, constraints). Make it visual (diagram, not just text). Share with team.**

2. Test with agent (30 min, today). Give agent your diagram. Ask agent to generate output (support response / sales email / code). Review quality. Is it better than without diagram? Document findings.**

3. Measure baseline (1 hour, this week). Currently: How much time do you spend fixing agent output? Track it (5 hours/week? 10?). This is your baseline. After implementing whiteboard pattern: Track again (should drop 30-50%). Calculate ROI.**

---

Próximos passos

Na OpenClaw, ajudamos SaaS builders implementar "whiteboard pattern" pra seus agentes de IA:

• Constraint Mapping: Extrair constraints de seu negócio (design system, policies, processes).
• Diagram Design: Desenhar arquitetura/fluxo (visual, não texto).
• Prompt Engineering: Integrar diagram + constraints na prompt do agent.
• Quality Testing: A/B test agent output (com diagram vs sem).
• Metrics & Monitoring: Track time savings, quality improvements, ROI.
• Team Training: Ensinar sua equipe usar whiteboard pattern.
• Scaling: Aplicar padrão a múltiplos agents (support, sales, code, etc).
• Documentation: Manter diagram atualizado (source of truth).
• Governance: Revisar constraint changes (regular).
• Custom Tools: Build visual diagram tool específico pro seu use case.
• Integration: Connect agents ao seu existing stack (not tool bloat).
• Feedback Loops: Agent aprende de feedback (refine diagram over time).

Whiteboard Pattern | Agent Context | Constraint Mapping | Output Quality | Collaboration Framework →