/designer - Design Before You Build

ai cagents claude designer planning workflow

Created: March 27, 2026 | Modified: March 27, 2026

This is Part 2 of a 10-part series on cAgents. | Previous: Getting Started with cAgents | Next: /run - Execute Tasks with Agents

Most projects fail at the requirements stage, not the build stage. You start with a vague idea - "I want a personal website" or "we need a content strategy" - and jump straight to execution. Then you build the wrong thing, or build the right thing in the wrong order, or finish and realize you forgot to think about who it's actually for.

/designer is the command you run before any of that. It asks you the questions you should have asked yourself, walks through your answers, and hands you an implementation-ready design document at the end. It's structured exploration on demand - a thinking partner that won't let you skip the important parts.

When to Use This

Use /designer when requirements are vague, the scope is unclear, or you want to think through the approach before committing to it. Some specific situations where it earns its keep:

You have an idea but not a plan
You're about to ask /run to build something and realize you haven't actually defined what "done" looks like
You're working on something creative or strategic (content, branding, positioning) where the problem space needs exploration before solutions make sense
You've built the wrong thing before and want to derisk it this time

Use /run instead when the task is already clear and defined - a specific feature to build, a specific bug to fix, a specific document to write. /designer is for the step before that.

A good rule of thumb: if you could hand the task to a competent human with no additional context and they'd know exactly what to do, skip /designer and go straight to /run. If they'd come back with five questions first, run /designer first.

The 4 Phases

/designer works through four phases, in order. You don't have to manage this - it happens automatically. But knowing what's coming helps you give better answers.

1. Discovery - Who is this for, and what problem are you actually solving? /designer starts here because most design mistakes are audience mistakes. You'll be asked about your users, their goals, and what success looks like. By the end, you should have a clear problem statement and concrete requirements.

2. Ideation - What are the possible approaches, and what specifically should this include? Before committing to a direction, /designer maps the options. This is where you discover that your first idea wasn't the only one - and where pages, features, content types, and channels get fleshed out.

3. Refinement - Does this actually work? Questions about edge cases, constraints, dependencies, and decisions you haven't made yet. This is where vague plans get stress-tested.

4. Specification - The output. A structured design document: architecture, components, decisions made, rationale documented, and a prioritized implementation roadmap. This is what you hand to /run.

Walkthrough -- Designing a Website

You finished the Getting Started setup from Part 1. You know you want a personal website with a homepage, an about page, a portfolio, and a blog. But you haven't thought much beyond that. Time for /designer.

/designer Build a personal website with homepage, about page, portfolio, and blog

The terminal output in these walkthroughs is illustrative - your actual results will vary in format and content.

/designer opens with the Discovery phase:

Phase 1/4 - Discovery

Let's start with who this site is for and what you want it to accomplish.

1. Who is your primary audience - potential employers, clients, collaborators, or
   general readers? Or some combination?
2. What action do you most want visitors to take after landing on your site?
3. Do you have an existing online presence (LinkedIn, GitHub, social) that this
   site should complement or replace?

You answer: primarily employers and clients, you want them to reach out or hire you, and you have a GitHub profile but no other personal site. Discovery continues to nail down the requirements:

Based on your answers: this is a professional credibility site, not a content hub.
The primary job is converting a first impression into a contact or hire.

Confirming the core requirements:
- The homepage should establish who you are and what you do within 5 seconds
- The portfolio needs to do the heavy lifting - it's the proof, not decoration
- The blog is secondary - content that builds credibility over time, not the main draw
- Contact should be easy from anywhere on the site

Does this match your intent? Any corrections before we continue?

You confirm. /designer moves to Ideation:

Phase 2/4 - Ideation

Now that we know who this is for, let's figure out what it should actually include
and how it should work.

1. Static site or CMS? Given you're using Claude Code, a static build (Next.js,
   Astro, or plain HTML) keeps things simple and fast. Any preference?
2. Visual direction - do you lean toward minimal and clean, bold and colorful,
   or something else? Any sites you admire?
3. For the portfolio: do you want case-study depth (problem, approach, outcome)
   or a lighter gallery with links?

You go with static (Next.js), minimal dark theme, and case-study style portfolio entries. Ideation maps out each page's purpose and content blocks - homepage hero, about page narrative structure, portfolio card layout, blog listing format.

Refinement surfaces decisions you hadn't considered:

Phase 3/4 - Refinement

Let's stress-test a few things before locking in the spec.

1. Mobile-first or desktop-first? Your audience (employers, clients) likely
   finds you via LinkedIn on mobile but reviews your portfolio on desktop.
2. Contact: a form, or just an email link? Forms add complexity. An email link
   with a clear CTA is simpler and often converts better.
3. Blog SEO: do you want posts indexed by search engines, or is the blog
   primarily for people already on the site?

You pick mobile-first with desktop polish, email link over a form, and yes to SEO indexing. Refinement catches a gap - you hadn't thought about an OpenGraph image strategy for social sharing - and adds it to the spec.

By the end, you have a specification document that covers:

Site architecture: 4 pages, static build, no CMS
Homepage: hero, 3-sentence bio, featured project card, contact CTA
About: longer narrative bio, timeline of experience, skills summary
Portfolio: project cards with descriptions, tech stack, outcome, and links
Blog: simple listing with tags, no comments
Visual direction: dark theme, clean typography, minimal decoration
Implementation order: homepage and navigation first, then about, then portfolio, then blog

That document is what you pass to /run in the next article.

Walkthrough -- Content Strategy Design

You're building a content marketing strategy for a SaaS product. You know you need blog posts, maybe a newsletter, maybe social media - but you haven't defined any of it. /designer handles this kind of exploratory work just as well as technical design.

/designer Content marketing strategy for a B2B SaaS product targeting small business owners

The Discovery phase looks different here - it's about audience rather than users:

Phase 1/4 - Discovery

Before designing the strategy, let's understand who you're trying to reach and
what they care about.

1. What's the primary pain point your product solves for small business owners?
2. Where do your best existing customers say they discovered you?
3. What does your competition publish, and where do they publish it?

You describe the product: it's project management software for service businesses. Your best customers came from word of mouth and one SEO article that ranked well. Competitors are publishing on LinkedIn and running newsletters.

Discovery surfaces the real constraint you hadn't stated:

Based on your answers, the strategy needs to solve a discovery problem, not a
retention problem. You're not producing content to keep existing customers engaged
- you're producing it to get in front of people who don't know you exist yet.

This changes the channel priority significantly. SEO content (articles targeting
specific search queries) should be the primary channel. LinkedIn and newsletter
are secondary amplification, not the foundation.

Is this framing correct?

By the Specification phase, you have a concrete content strategy:

Primary channel: SEO blog - 2 articles per month targeting long-tail queries from service business owners
Audience personas: two defined personas with goals, pain points, and typical search behavior
Topic pillars: 3 content themes mapped to product value propositions
Secondary channels: LinkedIn reposts of articles (low-effort amplification), email newsletter monthly digest
First month's plan: 2 articles with working titles, keyword targets, and outlines
Success metrics: organic traffic, email signups, trial conversions from organic

That's enough to hand to /run to write the first article, or to /team to produce four articles at once.

Key Flags

Flag	What It Does
`--deep`	Adds a research phase before Q&A. `/designer` pulls in relevant context (competitor examples, industry patterns, common approaches) to ask better questions. Useful when you're designing in an unfamiliar domain.
`--iterate`	Refines an existing design document rather than starting fresh. Point it at your existing spec and describe what changed - `/designer` runs the relevant phases and updates the document.

Flag Usage Examples

# Standard design session
/designer Build a landing page for a product launch

# Research-backed questions (slower, more thorough)
/designer --deep Design an onboarding flow for a mobile app

# Refine an existing spec after requirements changed
/designer --iterate The client added a requirement for multi-language support

Tips & Gotchas

"Research this for me" is a valid answer. When /designer asks about your target audience or competitors and you genuinely don't know, you can say "research this and make recommendations." /designer will pull relevant context and present options for you to choose from, rather than requiring you to already have the answers. This is especially useful in the Empathize and Conceptualize phases.

Chain /designer → /run, /team, or /org for best results. The design document /designer produces is structured specifically for downstream execution. When you run a command afterward, reference the design document - e.g. "/run Build the homepage based on the design document at design_document.md". The executing command will follow the spec rather than improvising. Use /run for single-domain tasks, /team when there are 3+ parallelizable items, or /org when the work spans multiple business domains.

Don't skip /designer for "simple" things that aren't actually simple. A landing page sounds simple. A content strategy sounds simple. Both involve a dozen decisions that will constrain everything downstream. The 15-20 minutes you spend in /designer prevents hours of rework later. If you're tempted to skip it, that's usually a sign the requirements are vaguer than they feel.

/designer produces a design, not a working plan. The output is a specification - it tells you what to build and why. It doesn't tell you which agents will do the work or how long it will take. That's what /run, /team, and /org are for. The design document is input to those commands, not output from them.

This is Part 2 of a 10-part series on cAgents. | Previous: Getting Started with cAgents | Next: /run - Execute Tasks with Agents