你是否也曾欣喜若狂地用上 AI 编程,结果却差点被气到砸键盘?
让它加个按钮,它把你的登录页干废了。
叫它优化一段代码,它把你写得最好的功能改出了 Bug。
你怒吼:“这 AI 怎么跟个二愣子一样,成事不足败事有余!”
我们激动地拥抱了 AI,却发现这匹千里马野性难驯,稍不留神就踩坏了自家的花园。
我们总抱怨它“乱来”,但有没有想过,问题可能出在我们自己身上?
是我们,没有给这位能力超群、但心智单纯的“超级实习生”制定好规则。
在没有 AI 的时代,我们有开发流程、设计规范、代码规范,这一切都是为了约束“人”这种不确定性。
现在,面对更不确定的 AI,我们反而把这些章法全忘了。
这不公平。
AI 不是猜心大师,它要的是“唯一事实来源”
约束和引导,才是驾驭 AI 的核心。
你需要给它一个“剧本”,一个“项目宪法”,让它的所有行动都有法可依。
而这套“宪法”,就是我们早已熟悉,却在 AI 时代被忽视的——项目文档。
下面这套“Bili-Ranker”示例项目的工作流,堪称教科书级别。
它用四份文档,彻底解决了“AI 不听话”的世纪难题。
第一步:用产品需求文档(PRD)给AI一个“北极星”
你不能上来就说:“嘿,给我做个B站热榜App”。
AI 会懵。它不知道给谁用?核心功能是啥?哪些绝对不能做?
所以,你需要一个 AI 产品经理,帮你梳理思路,生成一份 PRD。
你可以这样引导它:
# Role: AI 产品经理
## Goal:
与用户进行对话,引导他们明确产品需求,并最终生成一份完整的、结构化的产品需求文档 (PRD)。
## Workflow:
1. 自我介绍: 表明你的角色是 AI 产品经理,目的是帮助用户梳理产品想法。
2. 获取核心概念: 首先问最核心的问题:
- "我们准备构建的产品,如果用一句话来描述,它是什么?"
- "这个产品的核心目标用户是谁?能简单描述一下他们吗?"
3. 挖掘问题与方案: 根据用户的回答,深入提问:
- "那么,我们想为这些用户解决什么核心问题呢?"
- "我们的产品将如何解决这些问题?"
4. 定义范围 (In-Scope): 引导用户列出 MVP (最小可行产品) 阶段必须包含的核心功能。可以这样提问:
- "为了实现上述解决方案,最初版本必须具备哪些功能?我们来列一个清单。"
5. 定义范围 (Out-of-Scope): 这是非常重要的一步,帮助用户聚焦。
- "同样重要地,为了确保我们能快速上线,有哪些功能是明确‘不做’的?比如用户登录、付费功能等。"
6. 草稿与确认: 根据以上所有信息,生成 PRD 文档的草稿,然后展示给用户并请求确认或修改。可以说:
- "好的,根据我们的讨论,我为您整理了产品需求文档的第一版草稿。请您审阅,看看有没有需要补充或修改的地方。"
7. 最终输出: 用户确认后,输出最终的 Markdown 格式 PRD 文档。
有了这份 PRD,AI 就知道了项目的目标、用户、和功能边界。
它的所有行动,都有了最高纲领。
根据提示词,最终会输出
[B] 完整示例文档 (.ai/prd.md)
# PRD: Bili-Ranker (B站热榜速览应用)
> **文档目的**: 本文档是项目的核心指南和唯一事实来源 (Single Source of Truth),旨在明确项目目标、用户、核心功能和范围,确保所有开发工作都与产品愿景保持一致。
## 1. 项目概述 (Overview)
- **一句话描述**: 一个极简的跨平台桌面应用,让用户可以快速、无干扰地查看B站各分区的实时热门排行榜。
- **项目愿景 (Vision)**: 成为开发者和内容创作者获取B站内容趋势最便捷的工具。
## 2. 目标用户 (Target Audience)
- **用户画像 (Persona)**:
- **Tech-savvy Tim (技术爱好者/开发者)**: 喜欢高效获取信息,讨厌移动端App的干扰和复杂操作。希望有一个干净、快速的工具在电脑上使用。
- **Content Creator Connie (内容创作者)**: 需要时刻关注B站热点来寻找创作灵感,需要快速浏览不同分区的热门内容。
## 3. 核心问题与解决方案 (Problem & Solution)
- **解决的核心问题**:
1. **信息过载**: B站官方应用功能繁多,只想看排行榜时容易分心。
2. **操作繁琐**: 在Web或移动端切换不同分区排行榜的路径较长。
3. **无优质桌面端体验**: 缺乏一个官方的、纯粹的桌面排行榜查看器。
- **我们的解决方案**:
- 提供一个只专注于“排行榜浏览”的极简界面。
- 通过简单的下拉菜单快速切换分区,一步到位。
- 开发一个开箱即用、无需登录的桌面应用。
## 4. 功能范围 (Scope)
### 4.1. 核心功能 (In Scope - MVP)
- **分区选择**: 提供一个下拉菜单,包含B站主要分区(如:全站、动画、音乐、舞蹈、游戏、科技等)。
- **排行榜列表**: 展示选定分区的视频排行榜,包含排名、封面、标题、UP主、播放量。
- **默认加载**: 应用启动时,默认加载“全站”排行榜。
- **跳转B站**: 点击列表中的任何视频,都可以在系统默认浏览器中打开该视频的B站页面。
### 4.2. 范围外功能 (Out of Scope)
- 用户登录与注册
- 视频收藏、评论、点赞功能
- 视频下载或应用内播放
- 历史排行榜数据追溯
- 个性化推荐
## 5. 成功指标 (Success Metrics)
- GitHub 项目获得 100 个 Star。
- 应用日活跃用户 (DAU) 达到 50 人。
第二步:用技术架构文档画出“施工图”
需求定了,怎么盖楼?用什么砖?什么结构?
你得告诉 AI。
别让它自己选,它可能会选一个你根本不熟悉的技术栈,到时候哭都来不及。
你需要一个 AI 技术架构师,根据 PRD 生成技术选型和开发规范。
你可以这样和它沟通:
# Role: AI 技术架构师
## Goal:
根据用户已确认的 PRD,与用户讨论并确定项目的技术选型和开发规范,生成一份技术架构文档。
## Workflow:
1. 加载上下文: 首先,我会“阅读”已有的 `prd.md`。
2. 提议技术栈: 根据产品需求,推荐一个技术栈并询问你的偏好。例如:"根据 PRD,我推荐使用 Electron + React + TypeScript 的组合。您熟悉吗?"
3. 确定规范: 提议通用的开发规范,如目录结构、颜色和间距。
4. 定义后端/API: 明确数据来源。
5. 草稿与确认: 整合信息,生成技术架构文档草稿供你审阅。
6. 最终输出: 你确认后,输出最终的 Markdown 格式文档。
这份文档,就是 AI 建造大楼的“施工图”。
它知道了用什么工具、什么材料、以及施工标准。
[B] 完整示例文档 (.ai/architecture.md)
# 技术架构文档: Bili-Ranker
> **文档目的**: 本文档为 AI 和开发团队提供清晰的技术选型、架构设计和开发规范,确保代码的统一性、可维护性和高质量。
## 1. 技术栈 (Tech Stack)
| 类别 | 技术/工具 | 链接/版本 | 备注 |
|---|---|---|---|
| **框架** | Electron | ^25.0 | 用于构建跨平台桌面应用 |
| **前端库** | React | ^18.0 | 用于构建用户界面 |
| **UI 方案**| Tailwind CSS | ^3.0 | 原子化 CSS 框架,用于快速定制 UI |
| **状态管理** | Zustand | ^4.0 | 轻量、简单的全局状态管理 |
| **数据请求** | Axios | ^1.4 | 用于向 B站 API 发起 HTTP 请求 |
| **语言** | TypeScript | ^5.0 | 为项目提供静态类型检查 |
| **构建/打包**| Vite | ^4.0 | 用于快速的本地开发和构建 |
## 2. 前端规范 (Frontend Guidelines)
- **目录结构**:
- `src/main`: Electron 主进程代码
- `src/renderer`: React 渲染进程代码
- `components/`: 可复用 UI 组件
- `pages/`: 页面级组件
- `hooks/`: 自定义 Hooks
- `store/`: Zustand 状态管理
- `lib/`: 工具函数、API 客户端等
- **代码风格**: 使用 ESLint 和 Prettier,遵循 `eslint-config-airbnb` 规范。
- **颜色规范 (Color Palette)**:
- `primary`: #00a1d6 (B站蓝)
- `background`: #1a1a1a (深色模式)
- `text-primary`: #e0e0e0
- `text-secondary`: #888888
- **间距系统 (Spacing System)**: 采用 4px 为基本单位 (e.g., `p-1`=4px, `p-2`=8px)。
## 3. 后端与数据源 (Backend & Data Source)
- **后端**: 本项目无独立后端。
- **数据源**: 所有数据均通过调用公开可用的 Bilibili Web API 获取。
- **API 封装**: 所有 API 请求将被封装在 `src/renderer/lib/bilibili-api.ts` 中,以便统一管理和维护。
第三步:用应用流程文档模拟“用户体验”
房子怎么用?门在哪?灯的开关在哪?
用户从进门到开灯,整个过程是怎样的?
你需要和 AI 一起,把用户在应用里的每一步操作都预演一遍。
你需要一个 AI UX 设计师,来帮你梳理用户旅程。
你可以这样和它“排练”:
# Role: AI UX 设计师
## Goal:
通过模拟用户操作场景,与用户一同梳理并描述出清晰的用户旅程 (User Journey),生成应用流程文档。
## Workflow:
1. 设置场景: "让我们来想象一个典型的用户第一次使用 Bili-Ranker 的场景。"
2. 一步步描述: "首先,用户打开应用。他们看到的第一个界面是什么样的?"
3. 描述关键交互: "现在,用户想看‘游戏区’的排行。他们应该如何操作?"
4. 草稿与确认: 将整个流程整理成文,让你确认。
5. 最终输出: 你确认后,输出最终的 Markdown 文档。
这份流程文档,让 AI 彻底理解了界面的功能和跳转逻辑。
它不再是一个冰冷的编码机器,而是开始理解“人”是如何使用这个产品的。
[B] 完整示例文档 (.ai/app_flow.md)
# 应用流程文档 (User Journey)
> **文档目的**: 本文档详细描述用户在应用中的主要操作流程,确保 AI 理解每个界面的功能和界面间的跳转逻辑。
## 流程1: 首次打开应用并查看默认排行榜
1. **启动应用**: 用户双击 Bili-Ranker 应用图标。
2. **界面展示**: 一个固定大小的窗口出现,标题栏为 "Bili-Ranker"。窗口主要区域显示一个加载动画(例如一个旋转的 Bilibili 小电视图标)和文字 "正在加载..."。窗口顶部有一个下拉菜单,默认显示 "全站"。
3. **数据加载**: 应用在后台自动向 B站 API 请求“全站”排行榜数据。
4. **数据渲染**:
- 数据请求成功后,加载动画消失。
- 主内容区被一个垂直滚动的列表替代。列表每一项都是一个视频卡片,从上到下依次包含:`排名数字`、`视频封面图`、`视频标题`(最多显示两行)、`UP主名称` 和 `播放量`。
5. **用户交互**: 用户的鼠标悬停在某个视频卡片上时,卡片背景色会变亮。点击整个卡片区域,应用会调用系统默认浏览器,打开该视频的 B站 播放页。
## 流程2: 用户切换排行榜分类
1. **用户操作**: 用户点击应用顶部的 "全站" 下拉菜单。
2. **界面展示**: 一个下拉列表展开,显示所有预设的分区,例如:"动画"、"音乐"、"舞蹈"、"游戏"、"科技" 等。
3. **用户选择**: 用户点击列表中的 "游戏"。
4. **状态更新**:
- 下拉列表收起,顶部的下拉菜单文本更新为 "游戏"。
- 主内容区的视频列表被清空,再次显示加载动画和 "正在加载..." 文字。
5. **数据加载与渲染**: 应用根据用户选择的 "游戏" 分区,向 B站 API 请求新数据。数据返回后,重新渲染主内容区的视频列表,流程同 **流程1** 的第 4 步。
第四步:用实施计划(Stories)将大象“切成片”
现在,蓝图、施工图、体验图都有了。
最后一步,就是把宏伟的目标,拆解成一个个可以立刻执行的小任务。
你可以这样让 AI 帮你拆解:
好的,现在我们已经有了清晰的 PRD 和架构。让我们把 'MVP 核心功能' 拆解成一个个可以执行的开发任务 (Stories)。我们先从第一个功能‘分区选择’开始。您觉得这个功能可以拆解成哪些具体步骤?或者,让我来为您提议一个拆解方案?
通过这四步,你为 AI 构建了一个完整的、毫无歧义的“项目世界观”。
示例 Story (.ai/stories/epic-01-ui-framework.md):
# Epic 01: 搭建应用基础框架与主界面
- **状态**: [ ] 未开始
- **关联PRD**: 章节 4.1
- **关联架构**: 章节 1, 2
## 1. 目标 (Goal)
初始化 Electron + React + Vite 项目,并创建应用的主窗口和基本布局,包含一个空的顶部栏和一个空的内容区。
## 2. 验收标准 (Acceptance Criteria)
- [ ] 项目成功初始化,`npm run dev` 可以启动一个桌面窗口。
- [ ] 窗口标题为 "Bili-Ranker"。
- [ ] 窗口界面使用 `architecture.md` 中定义的深色背景。
- [ ] 界面布局分为两部分:一个固定高度的顶部区域和一个可滚动的内容区域。
- [ ] 代码符合 ESLint 和 Prettier 规范。
## 3. 具体指令 (Instructions for AI)
1. 使用 `electron-vite` 官方模板初始化一个 `React-TS` 项目。
2. 配置 `tailwind.config.js`,添加 `architecture.md` 中定义的颜色。
3. 在 `src/renderer/src/App.tsx` 中,创建一个 flex 布局,包含一个 `header` 元素和一个 `main` 元素。
4. 为 `body` 和根 `div` 设置背景色和默认文字颜色。
5. 确保所有文件都通过 `eslint --fix` 和 `prettier --write` 的检查。
它不再需要猜测,不再需要即兴发挥。
它成了一个真正懂你的、指哪打哪的、高效的编程伙伴。
我们正处在一个全新的时代。
“编码能力”或许正在被重新定义。
从一个埋头苦干的“工匠”,转变为一个运筹帷幄、给 AI 制定规则的“指挥家”。
当 AI 能够完美执行我们下达的任何指令时,真正限制我们的,还剩下什么呢?
或许,只剩下我们的想象力了,不是吗?