用 AI 从 0 到 1 做一个项目：Ask / Plan / Agent 协作流程
十步速览
- 写一句话描述和「明确不做」，Ask 挑刺
- Plan 整理待决问题，先清掉会卡住第一期的项
- 调研一轮：学什么、不学什么
- 写需求与验收清单，Ask 看能不能客观验收
- 做原型或示意，对齐布局与主路径
- 写总体设计，顺便问有没有过度设计
- 补详细规格与技术选型
- 让 AI 出 2～3 版界面设计稿，选定方向并写入样式规范
- 约定接口（有前后端时）、写 AGENTS.md / Cursor Rules，按需装 Skills
- Agent 打通一条主路径，按验收清单勾选并回写文档
对应四阶段：1～3 想清楚 · 4～8 写清楚 · 9 开工前准备 · 10 做出来。
三种模式
多数 AI 编码工具都有类似分工：只读问答、先规划再动手、直接改代码。名字可能不一样，职责差不多。
| 模式 | 干什么 | 什么时候用 |
|---|---|---|
| Ask | 只读讨论，不改仓库 | 挑刺、比方案、查文档和代码是否一致 |
| Plan | 先拆步骤、对齐再动手 | 定里程碑、列待决问题、拆多步任务 |
| Agent | 读写文件、跑命令 | 规格清楚后：写文档草稿、写代码、跑测试 |
Plan 会不会自动改代码，看具体工具。核心都是：先拆步骤、对齐边界，再动手。
几条硬习惯：
- 需求没定 → 别让 Agent 大规模写业务代码
- 任务跨多模块 → 先 Plan 拆开
- 改完一批 → 用 Ask 看有没有超范围、有没有和文档打架
模式怎么选：
- 拿不准 → Ask
- 步骤多 → Plan
- 规格清楚 → Agent
协作习惯（全程适用）：
| 习惯 | 做法 |
|---|---|
| 引用上下文 | 把需求、设计、相关源码放进对话，少让 Agent 猜 |
| 控制范围 | 一次只做一个模块或一条主路径，写清不得超出第一期 |
| 会话管理 | 聊太长就新开对话，结论先写进文件 |
| 开发服务器 | dev 尽量在自己终端跑；让 Agent 跑 build、test 这类短命令 |
| 审查 | 大改或合并前，Ask 或 @code-reviewer 对照 AGENTS.md 只读审查 |
开 Agent 写业务代码之前，至少满足：
- 第一期要做的事能列成可验收条目
- 关键技术选型定了，理由写下来了
- 页面、接口、数据之间的主路径说得清
- AGENTS.md（或等价项目说明书）和协作规则已经写好
全文地图
Ask、Plan、Agent 是全程工具；推进顺序分四段：想清楚 → 写清楚 → 开工前准备 → 做出来。
| 阶段 | 你在干什么 | 主要模式 | 做完的标志 |
|---|---|---|---|
| 1. 想清楚 | 定范围、挑刺、调研 | Ask、Plan | 说得清做什么、不做什么、第一期做到哪 |
| 2. 写清楚 | 需求、原型、设计、选型、界面定稿 | Ask、Plan | 写代码时不靠聊天里的口头约定 |
| 3. 开工前准备 | 接口约定、AGENTS.md、Rules、Skills | Plan → Agent | 主路径规格清楚，Agent 知道边界 |
| 4. 做出来 | 实现、联调、验收 | Agent 为主，Ask 审查 | 验收清单能勾掉，文档跟上代码 |
想清楚和写清楚常常占一半时间。返工多来自：需求含糊、边界漂移、文档与实现各说各话。
阶段一：想清楚
别带着含糊想法直接开工。
1. 用一句话说清项目
写下：
- 为谁做
- 解决什么问题
- 交付形态是什么
再写几条 「明确不做」。
「明确不做」往往比「想做什么」更管用：模型爱加功能，边界不划，它会一直「顺便」往里塞。
技术栈这会儿先别定。产品形态稳了再选型，理由一并记下。
Prompt 见 附录：一句话挑刺。
2. 反复问：需求合不合理、完不完善
一人全栈没有产品同事 Review，Ask 可以顶这个角色：先找漏洞，再要方案。
可以问这些：
- 谁用？打开第一眼看到什么？
- 怎样算做完？能不能客观验证？
- 从进入到完成关键任务，最短路径是什么？
- 没数据、失败、没权限时界面什么样？
- 第一期、第二期怎么切？第一期能不能单独演示？
- 依赖哪些外部系统？边界在哪？
Plan 怎么用：
- 整理成待决问题清单
- 卡第一期的问题，尽量写代码前清掉
- AI 给方案后追问利弊；也可以问「工期减半会怎样」「砍掉某模块会怎样」
结论必须落盘。 只留在聊天里，两周后你会忘为什么选 A、不选 B。
Prompt 见 附录：需求完整性。
3. 做一轮调研
写正式需求前，先看：
- 别人怎么做
- 学什么、坚决不学什么
- 你和他们的差异在哪
调研最好有：
- 几个参考：布局、能力、借鉴与不借鉴
- 能力对照：行业常见做法 vs 你的差异
- 第一期建议做哪些模块
- 性能、终端、安全、数据保留等非功能线索
每个参考都写「不借鉴什么」。只写「学什么」，无关能力很容易被一起带进来。
Prompt 见 附录：调研。Skill：grill-me、tavily-research、deep-research。
阶段二：写清楚
写清楚不是堆文档，是让人和 AI 共享同一套边界。重点是回答问题，不是凑固定文件名。
本阶段五步：
- 产品需求
- 原型与示意
- 总体设计
- 详细设计与技术选型
- 界面设计与定稿
有界面的项目走满五步；纯 CLI、纯 API 可跳过第 5 步。各体量最少留哪些文档，见 §什么时候可以少做几步。
0. 不同体量，最少留什么
| 项目类型 | 最少保留 | 可以后补 | 界面定稿 |
|---|---|---|---|
| 纯前端小工具 | 说明 + 验收清单 + 协作规则 | 总体设计、详细接口 | 建议做 |
| 前后端分离 | 上述 + 接口约定 + 样例数据 | 完整设计文档 | 建议做 |
| 纯 CLI / API | 说明 + 验收清单 | 原型、界面定稿 | 跳过 |
| 需长期维护 | 完整需求 + 设计 + 技术选型 | — | 必做 |
1. 产品需求
写清做什么、为谁、怎样算验收通过。一般不用写到每个接口字段。
至少包括：
- 背景与定位、明确不做
- 可量化的成功指标
- 用户角色与场景
- 页面划分与导航
- 按页面/模块的功能说明
- 性能、兼容、安全等底线
- 可勾选的验收清单
写完后 Ask 看：
- 有没有没法客观验收的句子？
- 主路径和主要异常覆盖了吗？
- 和「明确不做」矛盾吗？
验收句式可参考 附录：验收是否可测。
代码落地后要回写需求。 文档和代码长期不一致，Agent 会按旧文档改回交互。
2. 原型与示意
时机： 需求初稿后、总体设计前。
目标： 对齐页面怎么分、主路径顺不顺——偏布局与交互，不必纠结最终配色和字体。
为什么做：
- 很多歧义文字阶段看不出来
- 信息放不放得下、模块命名是否合理，原型一轮就露馅
注意：
- 布局、信息密度、交互流程可以参考示意稿
- 色值、字体、临时结构别直接照搬进生产代码
- 视觉定稿见下文 §5
3. 总体设计
有了需求和原型，再写：
- 模块怎么分
- 数据怎么流
- 和外部系统怎么接
- 有哪些架构红线
定方向和边界就行，不必细到每个字段。
写完可以 Ask：
- 一人全栈、第一期工期有限，这样拆是不是重了？
- 哪些模块能合并？
Prompt 见 附录：是否过度设计。
4. 详细设计与技术选型
规格写到「照着做也不容易歧义」。技术选型把「为什么选这套栈」记下来，免得实现过程中漂移。
按项目想清楚：
- 前后端技术栈、存储、鉴权及理由
- 页面路由、模块划分、样式规范放哪
- 有后端：接口路径、请求响应、错误形态的一份权威说明
- 关键实体、保留策略、写入路径
原则：
- 没写进规格的细节，别在代码里临时发明
- 缺了先补规格，再让 Agent 写
- 第一期只写够第一期用的；其余后补
5. 界面设计与定稿
时机： 详细规格和技术栈定后、写第一屏生产代码前。
为什么做：
- AI 直接写 UI 容易落成千篇一律的模板
- 先出 2～3 版互有差异的设计稿，你选定再实现，返工会少很多
和 §2「原型与示意」的分工：
| 原型与示意 | 界面设计与定稿 | |
|---|---|---|
| 时机 | 总体设计之前 | 详细规格与技术选型之后 |
| 目标 | 对齐布局、主路径、模块划分 | 选定配色、字体、密度、组件气质 |
| 保真度 | 低保真即可 | 2～3 版可对比的完整页面观感 |
| 产出 | 结构共识 | 写入样式规范 / Design Token |
怎么出 2～3 版：
- 写清约束（Plan / Ask）：设计哪些页面、参考哪些布局、明确不借鉴什么、样式落点（CSS 变量、Token 文件等）
- 要求互斥方向：气质明显不同的 2～3 套，不要换色微调
- 选对形式：HTML 单文件 mockup、
@frontend-design等 Skill；不必上框架 - 人类定方向：气质、信息密度、动效预算、首屏必须露出什么——最后一票在你
- 写进规格：色板、字体层级、间距、组件风格整理成 Token；hex 不要无脑复制
定稿记录： 选了哪版、为什么、不选另外几版的原因。
注意：
- 一次只 mock 主路径关键页
- Mockup 只作方向参考；生产样式以 Token / 规范文件为准
- 有品牌色或设计系统，写进约束
Prompt 见 附录：界面方向选型。Skill：frontend-design。
阶段三：开工前准备
写第一行业务代码前：接口约定 + 给 AI 立规矩。
1. 先约定前后端怎么说话
有前后端 → 先约定接口再并行实现，比边写边猜字段省事。
接口说明最好有：
- 路径、请求响应字段
- 几条真实响应样例
没有复杂后端的小工具 → 简化成「页面需要哪些数据、从哪来」。
开工前 Ask：
- 哪些验收项还没有对应能力？
- 哪些失败场景没覆盖？
Prompt 见 附录：能不能开始写代码。
2. 给 AI 立规矩
Agent 不知道你的红线。口头重复「别改接口、样式走规范、合并前跑 test」既费事也容易漏。
开工前把约定写进仓库，新会话自动带上上下文。
三层约定怎么分工
| 机制 | 放什么 | 何时加载 | 适合写什么 |
|---|---|---|---|
| AGENTS.md | 项目背景、目录职责、工作流、硬约束 | 每次对话 | 定位、先读哪些文档、常用命令、禁止事项 |
| Cursor Rules | 编码规范、按文件类型的约定 | 始终或匹配文件时 | Token、接口不得私增、UTF-8、测试命令 |
| Skills | 完整工作流 | 按需或 @ 引用 | 见下文 Skills 表 |
优先级： 产品需求与总体设计 > 详细设计与接口约定 > AGENTS.md > Rules > Skills。冲突时先改上层文档，再改代码。
AGENTS.md 最少写什么
格式遵循 agents.md 开放标准。
- 项目一句话、技术栈、目录各管什么
- Agent 工作流：动手前先读哪些规格、以代码还是文档为准
- 硬约束：密钥不进仓库、不得超第一期、合并前跑什么检查
- 常用命令：
install、build、test；dev 由人在外部终端跑（见上文「协作习惯」）
写太长没人维护。用 Ask 生成初稿，再删减到真正会 enforce 的条目。
Prompt 见 附录：生成 AGENTS.md。
Cursor Rules 怎么拆
路径：.cursor/rules/*.mdc
alwaysApply: true→ 全项目遵守- 配
globs→ 只在前端、API、文档等路径生效
对话可用 /create-rule。细则见 Cursor Rules。
还可以扩展什么
| 扩展 | 作用 | 典型场景 |
|---|---|---|
| Hooks | Agent 动作前后跑脚本 | 提交前格式化、敏感路径拦截 |
| MCP | 接外部工具与数据源 | 文档检索、Issue、设计稿 |
| 用户级 Rules / Skills | 跨项目个人习惯 | 提交信息格式、审查清单 |
0→1 早期先把 AGENTS.md 和少量 Rules 立住；MCP / Hooks 等项目稍稳再加。
全程可用的 Skills
安装与创建见 Cursor Skills。
| 阶段 | Skill（示例） | 用来干什么 |
|---|---|---|
| 想清楚 | grill-me | 追问需求漏洞 |
| 想清楚 | tavily-research / deep-research | 带引用调研、检索提纲 |
| 写清楚 | frontend-design | 2～3 版 mockup |
| 写清楚 | humanizer-zh | 对外文档去「AI 味」 |
| 开工前准备 | （自定义） | 开工前检查清单 |
| 做出来 | code-reviewer / frontend-code-review | 合并前审查 |
| 做出来 | update-docs | 代码改完同步文档 |
| 做出来 | webapp-testing | 主路径交互验证 |
| 做出来 | pr-creator | 写 PR 描述 |
项目专用 Skill 放 .cursor/skills/，把重复 Prompt 收成 SKILL.md。
规格和 AGENTS.md 定稿后再大规模写业务代码。
阶段四：做出来
1. 先打通一条主路径
纵向切片：先打通一条完整用户路径，别先做满所有页面壳。
- 应用壳：布局、导航、基础样式
- 打通第一期主路径
- 假数据或本地约定先跑通演示
- 接真实服务和数据
- 再做第二期横切能力
主路径尽早通，接口和交互的问题会早暴露。
2. 日常怎么和 AI 配合
| 你想做什么 | 模式 | 怎么配合 |
|---|---|---|
| 实现单个页面或模块 | Agent | 附需求/设计章节，写清不得超范围 |
| 跨多模块改动 | 先 Plan，再分步 Agent | 先要文件清单和顺序 |
| 判断交互是否合理 | Ask | 附说明或截图 |
| 修 Bug | Agent | 给复现步骤和期望结果 |
| 合并前检查 | Ask 或 @code-reviewer | 对照 AGENTS.md 与 Rules |
| 改完同步文档 | @update-docs | 需求/设计与代码不一致时回写 |
| 主路径手测 | @webapp-testing | Playwright 按验收清单跑主路径（见 §3） |
给 Agent 下任务时：
- 引用 AGENTS.md / Rules 里的章节，别每次从零写约束
- 写清：命名、接口字段、样式规范、改动范围
- 完成后列出已手动验证的路径
Prompt 见 附录：Plan 拆任务、附录：Agent 实现任务、附录：合并前审查。
编码期分步实现
跨模块改动不要一次丢给 Agent「帮我把第一期全做完」。更稳的顺序：
- Plan 出实现清单 — 每步：目标、依赖、改哪些文件、如何验证（用 附录：Plan 拆任务）
- 按纵向切片顺序做 — 与 §1 一致：先壳、再主路径、再假数据/真接口，不要跳步铺满页面壳
- 一步一 Agent 任务 — 每次只实现清单里的一步，任务里写清文件范围与不得超出的边界
- 每步小验收 — 跑
build/test（或该步约定的验证命令），对照验收清单里对应条目 - 再开下一步 — 上一步通过再 Plan/Agent 下一项；卡住用 Ask 查是否超范围或与文档不一致
单页或小模块可直接 Agent；只有步骤 ≥3 或跨目录时，才必须先 Plan。
3. 验收、测试与回写
验收清单格式： 前置条件 + 操作步骤 + 期望结果。
验证方式：
- 单元测试 /
build/test：Agent 可跑；适合逻辑与构建是否通过 - 固定几条手测主路径，大改后重走一遍
- 有 Web UI 时：用
@webapp-testing做主路径 E2E 冒烟（见下）
纯 CLI / API 项目可跳过浏览器测试。
用 AI + Playwright 测主路径（webapp-testing）
@webapp-testing Skill 会让 Agent 写 Python + Playwright 脚本，在本地用无头 Chromium 操作你的页面。适合把验收清单里的「操作步骤 + 期望结果」变成可重复跑的冒烟，不是替代完整测试体系。
大致原理（侦察 → 操作 → 验证）：
- 打开页面 — 访问你提供的 URL（如
http://localhost:3000）；动态站点会等网络空闲后再继续 - 截图与 DOM 侦察 — 先截全页或关键区域，读按钮、链接、输入框等选择器，再决定怎么点、怎么填
- 按步骤执行 — 模拟点击、输入、跳转，对照验收清单逐步走主路径
- 收集结果 — 可保存截图留档、读浏览器 console 日志；Agent 根据页面状态、文案或截图判断是否符合「期望结果」
这不是固定的「像素级自动对比图」流水线，而是 浏览器真跑一遍 + 截图/日志辅助 Agent 判断。你要给清楚 URL、前置条件（是否已登录、用什么测试账号）和期望看到什么。
Prompt 见 附录：主路径 E2E 测试。
回写：
- 大功能做完回写需求与设计
- 旧版归档，免得 Agent 读到过期内容
常见踩坑
前期
| 踩坑 | 对策 |
|---|---|
| 需求没清就让 Agent 开写 | 待决问题没清零，别大规模写业务代码 |
| AI 主动加功能 | 「明确不做」+ 第一期清单；任务里写不得超范围 |
| 结论只留在聊天里 | 结论落文件；重复约束写进 AGENTS.md / Rules |
| 文档写太多维护不动 | 详细规格只写卡第一期的 |
中期
| 踩坑 | 对策 |
|---|---|
| 需求和代码各说各话 | 定期 Ask 查一致性；养成回写习惯 |
| Agent 擅自改接口或自创字段 | 改接口先改约定文档 |
| 示意稿直接抄进生产 | 定稿方向写入 Token，生产样式单独维护 |
| 演示数据和真实联调对不上 | 尽早用真实路径验证主流程 |
编码期
| 踩坑 | 对策 |
|---|---|
| Agent 反复拉起 dev 服务器 | 见上文「协作习惯」；Agent 只跑 build / test |
| E2E 脚本与 dev 端口不一致 | 任务里写死当前 URL/端口；改端口后同步改脚本或 Prompt |
| 终端重定向写中文文档乱码 | 用编辑器直接写入 UTF-8 |
什么时候可以少做几步
不必每个项目都走满十步。按类型裁剪（与 §0 不同体量 对照）：
| 项目类型 | 可跳过或弱化 |
|---|---|
| 纯 CLI / API | 原型、界面定稿 |
| 内部工具、生命周期短 | 总体设计、完整 AGENTS.md |
| 个人练手、一次性 Demo | 调研缩为 2～3 个参考 |
| 有成熟设计系统的产品 | 界面定稿改为「对齐现有 Token」 |
不能跳的核心： 第一期范围清楚、验收可测、Agent 知道边界（哪怕只有几行 Rules）。
附录：Prompt 模板
按阶段复制使用。正文中已标注对应链接。
一句话挑刺
下面是我的项目一句话描述和「明确不做」列表。
请当挑剔的产品顾问：
1. 哪些词含糊、需要定义？
2. 「不做」是否够用，还缺哪些常见边界？
3. 如果工期很紧，第一期最少该保留什么？
不要写代码，只提问和建议。需求完整性
请当挑剔的产品顾问。基于下面的一句话描述和「明确不做」，
列出我可能还没想到的问题，按用户、数据、非功能、交付分组。调研
请调研 5～8 个可参考的开源或公开 Demo（附链接）。
每个说明：布局特点、值得借鉴、明确不借鉴。
汇总能力对照表，并给出第一期模块建议。输出 Markdown。验收是否可测
把下面这些验收描述改成「前置条件 + 操作步骤 + 期望结果」。
改不了的，说明还缺什么信息。是否过度设计
我是一人全栈，第一期工期有限。下面这套模块划分能否再合并？
请给出更小但仍然够用的方案，并说明理由。界面方向选型
请基于需求与详细规格，为「页面名」出 3 套互斥视觉方向。
每套：气质一句话、主色/背景、字体层级、首屏布局；各一份 HTML mockup 或等价可预览稿。
3 套差异要明显，不要换色微调。注明建议 Design Token 命名。
不要写生产代码。能不能开始写代码
我准备开始实现第一期主路径。
请对照现有需求和设计，列出仍然缺失、会阻塞实现的规格。
有则列出，无则明确说可以开工。生成 AGENTS.md
请根据下面已定的需求、设计和目录结构，起草一份 AGENTS.md。
包含：项目概述、目录职责、Agent 工作流、硬约束、常用命令、禁止事项。
遵循 agents.md 开放标准，条目要可执行，不要空泛口号。
不要写代码。Plan 拆任务
我要实现第一期主路径。请拆成有序步骤：
每步说明目标、依赖、建议改哪些文件、如何验证。
不要直接写代码，只输出计划。Agent 实现任务
实现「模块名」，对照「需求/设计章节」。
约束：
- 不得超出第一期范围
- 接口字段不得私自新增
- 样式走项目统一规范
- 最小改动，不重构无关文件
完成后列出已手动验证的路径。合并前审查
请只读审查这次变更：
是否超出约定范围？是否引入文档未定义的接口字段？
是否违反项目说明书里的硬约束？主路径 E2E 测试
我已在本地终端启动 dev，地址：http://localhost:____
请使用 @webapp-testing，为下面验收条目写 Playwright 冒烟脚本并运行：
【粘贴：前置条件 + 操作步骤 + 期望结果】
要求：
- 先打开页面、等待加载完成，必要时截图侦察再定位元素
- 按步骤操作，失败时保存截图并说明与期望的差异
- 不要启动 dev 服务器，只连接上述 URL
- 脚本可复用，放在项目内合适目录延伸阅读
- 站内： 借助 AI 工具设计公司官网：优秀路径与方法（含多方向 Mockup 选型）
- 站内： AI 编程工具快速指南（含 AGENTS.md 与 Skills 入门）
- 站内： Cursor Rules：给 Agent 的持久化项目约定
- 站内： Cursor Skills：查找、安装与协作（含
webapp-testing等 Skill 说明） - Skill 目录： skills.sh（搜索
webapp-testing安装 Playwright 主路径冒烟） - 开放标准： agents.md
