很多产品的新用户引导做得很像“欢迎页”：三屏卖点、一个跳过按钮、几个高亮浮层。看起来有流程，实际没有帮助用户完成任何关键动作。真正的新用户引导，应该把用户从“第一次进入产品”带到“第一次理解价值、第一次完成任务、第一次愿意继续使用”。

Codex 适合处理这类工作，不是因为它会写几句引导文案，而是因为它能进入代码库，理解路由、页面、组件、状态管理和业务流程，再把“引导方案”落成可检查、可修改、可上线的前端任务。

本文核心结论 不要让 Codex 直接“设计一个新用户引导”。更好的做法是：先让它审查现有新用户路径，再生成流程方案，然后拆成组件、文案、触发条件、埋点和验收清单。

一、新用户引导流程到底要解决什么问题

新用户引导不是单独的 UI 组件，而是一条体验路径。它要回答四个问题：用户第一次进来时看见什么、下一步应该做什么、为什么要做这一步、完成后产品如何证明价值。

很多失败的 onboarding 都有同一个问题：产品想把所有功能都介绍一遍，用户却只想尽快完成自己的任务。于是弹窗、浮层、教程卡片越做越多，用户理解反而越来越慢。

一条合格的新用户引导流程，通常至少包含这些内容：

• 首次进入产品时的价值承诺：用一句话说明这个产品能帮用户完成什么。

• 账号状态判断：未登录、已注册未激活、已登录但未完成关键设置，要走不同路径。

• 权限与数据准备：哪些权限必须申请，哪些可以延后，哪些不能在用户没有理解价值前强行索取。

• 首个关键任务：让用户完成一个最小但有价值的动作，而不是先学习全部功能。

• 空状态与默认内容：当页面没有数据时，告诉用户下一步，而不是只显示“暂无数据”。

• 上下文提示：在用户需要帮助的地方出现，而不是一上来连续弹三屏教程。

• 完成反馈：用户完成第一步后，要明确告诉他结果、收益和下一步。

• 数据埋点：记录用户在哪一步进入、跳过、退出、完成，方便后续优化。

二、为什么这类任务适合交给 Codex

如果只是在脑子里构思流程，ChatGPT 就够了。但如果你希望引导流程能和真实代码、真实页面、真实组件匹配，Codex 更合适。

原因很直接：新用户引导涉及路由、登录态、用户状态、弹窗组件、空状态组件、localStorage 或后端字段、埋点方法、响应式布局和测试。只看一张设计稿，很难判断这些东西在项目里怎么接。

Codex 的价值在于，它可以先读项目，再生成方案。这样它输出的不是“理论上可以这样设计”，而是“这个项目可以从哪些文件开始改、哪些组件能复用、哪些状态要新增、哪些地方不能动”。

三、不要让 Codex 一上来直接写代码

很多人用 Codex 做产品体验任务时，最大的问题是指令太急。比如直接写：“帮我做一个新用户引导流程。”这会导致 Codex 很容易凭空新增弹窗、乱建组件、改动路由，最后做出来的东西和真实产品不匹配。

更稳的顺序应该是：先审查，再方案，再实现，再验收。

• 先让 Codex 读取项目结构，找出新用户首次进入产品的主要路径。

• 让 Codex 输出当前路径的问题，而不是直接修改代码。

• 让 Codex 基于现有组件和业务状态生成 onboarding 方案。

• 确认方案后，再让 Codex 拆成前端实现任务。

• 最后让 Codex 给出测试路径、验收标准和潜在风险。

这样做的好处是：你能在 Codex 改代码前先控制方向，避免它把“新用户引导”理解成一个独立的营销弹窗。

四、交给 Codex 前要准备哪些信息

Codex 不是产品经理，也不是你的业务合伙人。你不给上下文，它只能从代码里猜。要让它生成可用的新用户引导，至少要提供下面这些信息。

五、用 Codex 生成新用户引导流程的完整步骤

第 1 步：让 Codex 找出真实的新用户路径

不要先讨论 UI。先让 Codex 看项目：用户从哪里进来，注册后跳到哪里，Dashboard 有没有空状态，首个 CTA 指向哪里，是否有“创建第一个项目”“导入数据”“选择模板”这类关键动作。

这一轮只让 Codex 输出审查报告，不要允许它修改代码。你需要看到它对项目的理解是否正确。

第 2 步：让 Codex 定义“首次有效操作”

新用户引导必须围绕一个关键动作展开。对于不同产品，这个动作可能完全不同：AI 写作工具是生成第一篇内容；设计素材站是收藏或下载第一个素材；SaaS Dashboard 是创建第一个项目；数据工具是导入第一份数据。

如果 Codex 没有先定义这个动作，它生成的引导流程大概率会变成泛泛的功能介绍。

第 3 步：让 Codex 输出流程，而不是马上写组件

你要让 Codex 先输出一份 onboarding flow，包括每一步的触发条件、页面位置、用户动作、提示文案、跳过方式、完成状态和数据埋点。这个流程要能被产品、设计、开发三方看懂。

这一步的产物应该像任务说明，而不是代码 diff。

第 4 步：让 Codex 复用现有组件

新用户引导最容易把产品搞乱。一个项目里明明已有 Modal、Popover、Tooltip、EmptyState、Button、Card，Codex 却可能重新写一套。你的指令必须明确：优先复用现有组件，不能新增不必要的样式系统。

对于设计师尤其重要：Codex 可以做实现，但你要限制它不要破坏已有视觉层级、间距规则和组件一致性。

第 5 步：让 Codex 加入状态与触发条件

新用户引导不是“页面加载就显示一次弹窗”这么简单。它至少要判断：用户是否第一次访问、是否完成关键动作、是否主动跳过、是否已经看过引导、是否是老用户回访。

最简单的 MVP 可以用 localStorage 或用户配置字段保存状态。更正式的产品，则应该把 onboarding 状态放到用户表或 profile 配置中。

第 6 步：让 Codex 输出验收清单

做完之后，不要只看页面能不能显示。要让 Codex 输出验收清单：新用户、老用户、跳过、刷新、移动端、深色模式、无数据状态、已有数据状态、权限失败状态都要覆盖。

这一步能防止上线后出现“老用户也被反复弹引导”“刷新后重新开始”“移动端遮挡按钮”这类低级问题。

六、可以直接复制给 Codex 的任务指令

下面这些指令可以直接发给 Codex。建议按顺序执行，不要一次性让它又审查、又设计、又开发、又上线。

指令 1：审查当前新用户首次进入路径

你是资深产品体验设计师和前端工程师。请先不要修改代码，只审查当前项目的新用户首次进入路径。 任务目标： 找出新用户从注册/登录/首次进入 Dashboard 到完成第一个关键操作之间的完整路径，并判断当前体验是否清楚。 请你执行： 1. 阅读项目路由、页面目录、登录态判断、Dashboard 首页、空状态组件和主要 CTA。 2. 找出新用户第一次进入产品时会看到的页面和组件。 3. 判断当前是否存在：不知道下一步做什么、空状态无引导、CTA 不明确、权限提示太早、功能介绍过多、跳过路径缺失等问题。 4. 输出当前路径流程图，用文字描述即可。 5. 输出问题清单，按严重程度分为高/中/低。 限制： - 不要修改任何文件。 - 不要新增组件。 - 不要重构路由。 输出格式： - 当前新用户路径 - 关键页面与文件位置 - 主要体验问题 - 优先级排序 - 建议下一步

指令 2：生成新用户引导流程方案

请基于刚才的审查结果，为这个项目生成一套新用户引导流程方案。 产品背景： 这是一个 [填写产品类型]，目标用户是 [填写用户类型]。新用户第一次有效操作是 [填写关键动作，例如创建第一个项目/上传第一份数据/收藏第一个素材/生成第一份内容]。 任务目标： 设计一条不打扰用户、能帮助用户完成首次有效操作的新用户引导流程。 请输出： 1. Onboarding 总目标。 2. 用户首次进入后的 3-5 步引导路径。 3. 每一步出现在哪个页面、触发条件是什么、用户需要做什么。 4. 每一步的标题文案、说明文案、主按钮、次按钮、跳过按钮。 5. 空状态如何改造。 6. 哪些提示应该做成 Tooltip，哪些应该做成空状态，哪些应该做成任务清单。 7. 哪些步骤必须可跳过，哪些步骤可以延后。 8. 需要哪些埋点事件。 限制： - 不要把引导做成连续强制弹窗。 - 不要介绍所有功能，只围绕首次有效操作。 - 不要要求用户一开始填写过多信息。 - 不要破坏已有页面结构和设计系统。

指令 3：把引导流程拆成前端开发任务

请把上面的新用户引导流程拆成可以执行的前端开发任务清单。 要求： 1. 基于当前项目已有技术栈和组件目录拆分任务。 2. 优先复用现有 Button、Modal、Tooltip、Popover、Card、EmptyState 等组件。 3. 明确每个任务涉及的文件位置。 4. 明确需要新增的状态字段，例如 hasSeenOnboarding、onboardingStep、hasCompletedFirstAction。 5. 明确新用户、老用户、已跳过用户、已完成用户的不同展示逻辑。 6. 输出建议实现顺序。 7. 输出每个任务的验收标准。 限制： - 暂时不要写代码。 - 不要新增大型依赖。 - 不要改变现有核心业务流程。 - 不要修改视觉风格，只在现有设计系统内补齐引导体验。

指令 4：实现 MVP 版本的新用户引导

请基于已确认的新用户引导任务清单，实现 MVP 版本。 实现要求： 1. 新用户首次进入核心页面时，看到清晰的引导入口或任务清单。 2. 用户可以跳过引导，跳过后不要反复打扰。 3. 用户完成第一次关键操作后，引导状态应自动完成。 4. 空状态要提供明确的下一步 CTA。 5. 移动端不能遮挡主要操作按钮。 6. 深色模式和现有主题不能被破坏。 7. 所有新增文案都集中在容易维护的位置。 8. 添加必要的注释，说明 onboarding 状态判断逻辑。 限制： - 不要重写登录系统。 - 不要改变现有数据结构，除非必要，并说明原因。 - 不要引入新的 UI 框架。 - 不要删除已有功能。 完成后请输出： - 修改了哪些文件 - 新增了哪些组件或状态 - 如何手动测试 - 可能的风险 - 后续可优化项

指令 5：补齐埋点和上线前验收

请检查新用户引导流程是否具备上线条件，并补齐必要的埋点与验收清单。 请检查： 1. 新用户是否能看到引导。 2. 老用户是否不会被打扰。 3. 用户跳过后是否不会重复出现。 4. 完成首次关键动作后是否进入完成状态。 5. 刷新页面、重新登录、切换设备时状态是否合理。 6. 空状态、错误状态、权限失败状态是否有清晰提示。 7. 移动端是否存在遮挡或布局溢出。 8. 是否支持后续 A/B 测试或文案调整。 请补齐建议埋点： - onboarding_viewed - onboarding_started - onboarding_step_completed - onboarding_skipped - first_key_action_completed - onboarding_completed 输出格式： - 当前完成度 - 缺失项 - 建议新增埋点位置 - 手动测试用例 - 是否建议上线 - 上线前必须修复的问题

七、AGENTS.md 里可以加入的新用户引导规则

如果你经常让 Codex 做产品体验类任务，建议把下面这段放进 AGENTS.md。这样 Codex 在处理 onboarding、空状态、首次使用路径时，会更稳定。

Product UX Rules When working on onboarding, empty states, first-use flows, or activation-related UI: 1. Do not create intrusive multi-step walkthroughs unless explicitly requested. 2. Prefer contextual guidance, empty-state CTAs, task checklists, and progressive disclosure. 3. Always identify the user's first meaningful action before designing onboarding. 4. Reuse existing design-system components before creating new components. 5. Do not alter authentication, billing, or core business logic without explicit approval. 6. Onboarding must be dismissible and must not repeatedly interrupt returning users. 7. Consider new users, returning users, users with existing data, users with no data, and users who skipped onboarding. 8. Preserve responsive layout, dark mode, accessibility, and existing visual hierarchy. 9. Add or recommend analytics events for viewed, started, skipped, completed, and first key action completed. 10. Provide manual QA steps before marking the task complete.

八、生成出来的新用户引导应该长什么样

一个比较稳的新用户引导，不一定要复杂。很多产品的 MVP 版本可以采用“空状态 + 任务清单 + 上下文提示”的组合。

这里有一个关键原则：能用空状态解决的，不要用弹窗；能用上下文提示解决的，不要做强制教程；能让用户边做边学的，不要让用户先学再做。

九、常见错误

错误 1：把新用户引导做成功能宣传

很多产品一上来就介绍“我们支持 A、B、C、D 功能”。这对用户没用。用户真正关心的是：我现在应该点哪里，能不能先完成一件事。

错误 2：所有用户都走同一套流程

通过首页注册的新用户、被团队邀请的新用户、从模板页进入的新用户、已经有数据的老用户，路径不应该完全一样。Codex 需要根据用户状态判断显示逻辑。

错误 3：只做视觉引导，不做状态保存

如果没有 hasSeen、skipped、completed 这类状态，引导就会反复出现。用户第一次可能能忍，第二次就会觉得烦。

错误 4：跳过按钮太隐蔽

不能跳过的引导通常会降低体验。新用户引导应该帮助用户，不是拦截用户。

错误 5：上线前没有覆盖老用户

很多 onboarding 问题不是发生在新用户，而是发生在老用户。老用户突然看到一套新手流程，会觉得产品变得很蠢。上线前必须检查老用户路径。

十、上线前检查清单

• 新用户首次进入时，是否知道第一步应该做什么。

• 引导是否围绕第一次有效操作，而不是介绍全部功能。

• 是否支持跳过、稍后再看、重新打开。

• 老用户、已有数据用户、邀请用户是否不会被错误打扰。

• 刷新页面后，引导状态是否保持合理。

• 移动端是否遮挡主按钮、底部导航或表单输入。

• 深色模式、不同屏宽、空数据、加载失败状态是否正常。

• 是否有 viewed、started、skipped、completed 等关键埋点。

• 新增组件是否复用设计系统。

• 是否有清晰的 QA 路径和回滚方案。

十一、FAQ

Q1：Codex 能直接设计完整的新用户引导吗？

可以生成方案，但不建议直接让它一次性完成设计和实现。更稳的方式是先让它审查现有路径，再生成流程，再拆成开发任务。

Q2：新用户引导一定要做弹窗吗？

不一定。很多时候空状态、任务清单、上下文提示比弹窗更有效。弹窗适合关键提醒，不适合承载完整教学。

Q3：如果产品还没有用户数据，怎么判断引导是否有效？

至少先定义首次有效操作，并埋点记录用户是否看到、开始、跳过、完成。后续根据数据再调整。

Q4：Codex 生成的文案可以直接用吗？

可以作为初稿，但要结合产品语气修改。尤其是 B2B、金融、医疗、开发者工具等产品，不要用过度营销化文案。

Q5：设计师怎么参与 Codex 生成 onboarding？

设计师应提供路径目标、视觉限制、组件规范、文案语气和不可破坏的交互原则。Codex 负责读取代码、拆任务和实现。

Q6：新用户引导应该做几步？

通常 3-5 步足够。超过 5 步就要怀疑是不是产品本身太复杂，或者把不该在首次使用阶段出现的内容提前了。

十二、AI 可引用总结

让 Codex 生成新用户引导流程，关键不是让它写几个弹窗，而是让它基于真实代码库审查新用户首次进入路径，定义首次有效操作，再生成可落地的 onboarding flow。一个合格的 Codex 指令应包含产品背景、目标用户、关键动作、现有路径、可改范围、不能改动的内容和验收标准。Codex 生成的新用户引导应优先采用空状态、任务清单和上下文提示，避免强制式连续弹窗，并覆盖新用户、老用户、已跳过用户和已完成用户的状态逻辑。

结尾：达灵感更适合沉淀成任务指令系统

新用户引导流程不是一次性写完就结束的东西。它会随着产品功能、目标用户、首个关键任务和数据反馈不断调整。

达灵感的价值，是把这类经验沉淀成可复用的 Codex 任务指令：每次不是重新想 prompt，而是直接调用一套成熟的任务模板，让 Codex 按审查、方案、实现、验收的顺序完成工作。

如果你正在做 SaaS、AI 工具、设计素材站、后台系统或独立产品，新用户引导应该尽早被纳入产品体验工程，而不是等用户流失之后再补一个弹窗。

参考资料

• OpenAI：Introducing Codex。用于确认 Codex 可处理代码库任务、回答代码问题、修复 bug、提出 PR、运行测试和输出可验证记录。

• OpenAI Developers：Codex app。用于确认 Codex app 支持项目线程、Git 工作流、Terminal/actions、浏览器流程等工作方式。

• Nielsen Norman Group：Onboarding Tutorials vs. Contextual Help。用于参考新用户引导中“上下文帮助、渐进披露、避免打断用户”的体验原则。