用户画像文档（Persona Docs）

创建以用户为中心的文档，明确定义产品面向谁、以及他们如何与产品交互。用户画像文档为“以产品驱动开发”奠定基础——每一项功能决策、设计取舍和优先级判断，都源于对用户的深入理解。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install persona-docs

何时创建

用户画像文档应是任何产品启动时最先完成的内容。即使仅包含关于目标用户最简略的描述，也能有效引导开发与设计决策。

• 项目启动阶段 —— 在编写代码前，先明确你为谁而构建
• 转向新用户群体时 —— 明确记录用户定位变化，确保团队对齐
• 团队对目标用户缺乏共识时 —— 当成员就“这个产品是为谁服务的？”产生分歧
• 开展重大功能规划前 —— 验证计划中的功能是否真正服务于实际用户
• 新成员入职时 —— 帮助其快速理解所构建产品的目标用户

编写流程

1. 分析代码库 —— 查找已有的文档、README、落地页或市场文案，从中挖掘目标用户线索
2. 提出澄清问题（若目标用户尚不清晰）：
   • “该产品的核心用户是谁？”
   • “该产品为他们解决了什么问题？”
   • “他们如何发现这款产品？”
   • “找到产品后，他们的第一动作会是什么？”
3. 从最小可行版本起步 —— 每个章节写几句话，也远胜于空白
4. 阅读模板 —— 参见 references/template.md 获取完整结构
5. 持续迭代 —— 随着对真实用户的了解加深，不断回溯并扩展内容

核心组成部分

1. 目标用户画像

描述用户是谁、背景如何、所处场景为何。需足够具体，方具指导价值。

良好示例： “中型 SaaS 公司的后端工程师，常在时间压力下调试生产环境问题，具备 3–8 年工作经验，熟悉命令行工具。”

过于宽泛示例： “开发者。”

应包含：

• 角色、职位或典型用户类型（archetype）
• 技术能力水平及相关技能
• 所属行业或业务领域背景
• 使用该产品的典型时机与场景
• 所在团队规模及组织架构背景

2. 用户需求与痛点

本产品所解决的问题。他们在当前工作流中面临哪些挫败感或能力缺口？

建议按以下结构组织：

• 首要痛点 —— 你所解决的最关键问题
• 次要痛点 —— 其他你同时应对的问题
• 当前替代方案 —— 在没有本产品时，他们如何应对
• 现有方案为何失效 —— 已有替代方案有哪些？为何不足以满足需求

3. 发现路径

用户如何找到该产品。此部分直接影响市场策略、产品定位及首印象设计。

• 搜索渠道 —— 哪些关键词搜索会将其引向此处？
• 推荐来源 —— 口碑传播、同事推荐？
• 内容触达 —— 博客文章、教程、技术大会演讲？
• 应用市场 —— App Store、插件目录、包注册中心？
• 转化钩子 —— 是什么促使他们点击“注册”或“下载”？

4. 入门流程（Onboarding Flow）

从“我发现了这个产品”到“我正在获得价值”的最简可行路径。

需明确定义：

• 首次接触点 —— 落地页、应用商店列表、GitHub README 等
• 注册/登录方式 —— 最小可行认证方案（仅邮箱？OAuth？无需账号？）
• 价值实现耗时（Time to value） —— 用户多快能体验到核心价值？
• 首次成功时刻 —— 哪一具体操作会让他们产生“这很有用”的认知？
• 摩擦点 —— 用户在哪一步流失？如何最小化该流失？

示例流程：

用户访问首页 → 点击“立即试用” → 粘贴数据 → 30 秒内看到结果 → 决定注册账号

5. 用户旅程地图（User Journey Map）

覆盖用户全生命周期的关键触点与交互行为。

新用户（第 1 天）：

• 通过 [渠道] 发现产品
• 执行 [首个动作]
• 达成 [首次成功]

回归用户（第 1 周）：

• 高频重复执行的关键动作
• 主动探索的功能模块
• 配置的集成或自定义项

资深用户（第 1 个月及以上）：

• 重度依赖的高级功能
• 已形成的标准化工作流
• 他们向他人介绍该产品时的典型表述

6. 功能触点映射

标注用户在旅程各阶段接触关键功能的位置：

面向多类用户的复杂产品

若你的产品服务于多个截然不同的用户类型，请遵循：

1. 优先识别主用户画像 —— 哪一类用户是你生存所必需服务的对象？
2. 为次级用户画像单独建模 —— 每类用户对应一个独立文档文件
3. 明确标注冲突点 —— 当不同用户需求相互矛盾时，记录对应的权衡取舍
4. 严苛优先级排序 —— 无法同时为所有人做最优设计

输出位置

将用户画像文档置于：

• docs/PERSONA.md —— 简单产品适用的单文件方案
• docs/personas/ —— 多用户画像场景下的目录结构

务必保留在代码仓库中，使其随产品演进而同步更新。

质量标准

一份优质的用户画像文档应满足：

• 足够具体 —— 两名团队成员可依据同一份文档构建出一致的功能
• 包含证据支撑 —— 引用真实数据、用户原话或可观测行为，而非仅凭假设
• 具备可操作性 —— 阅读后应切实改变你的构建方式
• 持续维护 —— 过时的用户画像比没有更危险
• 诚实可信 —— 不描述理想中的用户，只描述真实的用户

绝对禁止事项

1. 绝不可跳过新产品的用户画像环节 —— 不了解用户即开始构建，本质是盲目猜测；而猜测代价高昂
2. 绝不可仅用人口统计特征描述用户 —— “25–34 岁男性”无法揭示其真实需求；应聚焦行为模式与目标诉求
3. 绝不可闭门造车式创建用户画像 —— 必须协同团队共同参与；单一个人的假设极易成为整个产品的盲区
4. 绝不可将用户画像视为一成不变 —— 用户在变，市场在变；需每季度回顾并更新画像
5. 初始阶段绝不可创建超过 3 类用户画像 —— 试图服务所有人，最终将无人受益；请始终从主用户出发
6. 绝不可撰写理想化（aspirational）用户画像 —— 文档应忠实反映实际使用者，而非你希望拥有的用户