别再骂 Cursor 笨了，是你没给AI「上规矩」！

本文链接：https://blog.youkuaiyun.com/solblog/article/details/148606068

你是否也曾欣喜若狂地用上 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 能够完美执行我们下达的任何指令时，真正限制我们的，还剩下什么呢？

或许，只剩下我们的想象力了，不是吗？