persona-docs（角色文档）

Persona Docs

Create user-centered documentation that defines who a product is for and how they interact with it. Persona docs establish the foundation for product-driven development — every feature decision, design choice, and prioritization call flows from understanding your users.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install persona-docs

When to Create

Persona docs should be the first thing fleshed out for any product. Even minimal documentation about who uses the product helps direct development and design decisions.

• Project inception — before writing code, define who you're building for
• Pivoting to a new audience — document the shift so the team aligns
• Team lacks clarity on target users — when people disagree on "who is this for?"
• Before major feature planning — validate that planned features serve actual users
• New team member onboarding — give them context on who they're building for

Process

1. Analyze the codebase — look for existing documentation, README, landing pages, or marketing copy that hints at the target audience
2. Ask clarifying questions if the target user isn't clear:

- "Who is the primary user of this product?" - "What problem does this solve for them?" - "How would they discover this product?" - "What's the first thing they'd do after finding it?"

1. Start minimal — a few sentences per section is better than nothing
2. Read the template — see references/template.md for the full structure
3. Iterate — revisit and expand as you learn more about actual users

Core Components

1. Target User Profile

Who they are, their background, their context. Be specific enough to be useful.

Good: "Backend engineers at mid-size SaaS companies who debug production issues under time pressure, typically 3-8 years of experience, comfortable with command-line tools."

Too vague: "Developers."

Include:

• Role, job title, or archetype
• Technical level and relevant skills
• Industry or domain context
• When and where they'd use this product
• Team size and organizational context

2. User Needs and Pain Points

The problems this product solves. What frustrations or gaps exist in their current workflow?

Structure as:

• Primary pain point — the single biggest problem you solve
• Secondary pain points — additional problems you address
• Current workarounds — what they do today without your product
• Why existing solutions fail — what alternatives exist and why they're insufficient

3. Discovery Path

How they find the product. This informs marketing, positioning, and first-impression design.

• Search — what queries lead them here?
• Referral — word of mouth, colleague recommendation?
• Content — blog posts, tutorials, conference talks?
• Marketplace — app store, plugin directory, package registry?
• The hook — what makes them click "sign up" or "download"?

4. Onboarding Flow

The simplest possible path from "I found this" to "I'm getting value."

Define:

• First encounter — landing page, app store listing, GitHub README
• Registration/Login — minimum viable auth (email-only? OAuth? no account?)
• Time to value — how quickly can they experience the core benefit?
• First success moment — the specific action that makes them think "this is useful"
• Friction points — where do users drop off, and how do you minimize that?

Example flow:

User lands on homepage → clicks "Try it" → pastes their data → sees result in <30 seconds → decides to create account

5. User Journey Map

Key touchpoints and interactions across the user lifecycle.

New User (Day 1):

• Discovers product via [channel]
• Takes [first action]
• Achieves [first success]

Returning User (Week 1):

• Key repeated action they perform
• Features they explore
• Integrations or customizations they set up

Power User (Month 1+):

• Advanced features they rely on
• Workflows they've established
• How they'd describe the product to others

6. Feature Touchpoints

Map where users encounter key features in their journey:

Multi-Persona Products

If your product serves multiple distinct user types:

1. Identify the primary persona first — who must you serve to survive?
2. Document secondary personas separately — one file per persona
3. Note conflicts — where persona needs clash, document the tradeoff
4. Prioritize ruthlessly — you can't optimize for everyone simultaneously

Output Location

Place persona docs at:

• docs/PERSONA.md — single file for simple products
• docs/personas/ — directory for multiple personas

Keep it in the repo so it evolves with the product.

Quality Criteria

A good persona doc should:

• Be specific enough that two team members would build the same feature from it
• Include evidence — data, quotes, or observations, not just assumptions
• Be actionable — reading it should change how you build
• Be maintained — outdated personas are worse than none
• Be honest — don't describe aspirational users; describe actual users

NEVER Do

1. NEVER skip personas for a new product — building without knowing your user is guessing, and guessing is expensive
2. NEVER describe users as demographics alone — "25-34 male" tells you nothing about what they need; describe behaviors and goals
3. NEVER create personas in isolation — involve the team; one person's assumptions become the whole product's blind spots
4. NEVER treat personas as permanent — users change, markets shift; review personas quarterly
5. NEVER create more than 3 personas initially — if you try to serve everyone, you serve no one; start with your primary user
6. NEVER write aspirational personas — document who actually uses your product, not who you wish did