导读：作为一名开发者，同时也是琴童家长，我深知孩子练琴的痛点。这篇文章将分享我如何使用 Trae IDE，从零开始搭建一个基于浏览器的游戏化钢琴学习工具——PianoFlow，目前已迭代到 v1.5.0 版本。重点分享需求先行、文档驱动的完整开发流程。
项目体验
应用获取地址：https://papaya-strudel-27c468.netlify.app/
Web 离线应用，主打 Pad 端体验
- 纯前端架构：无需后端服务器，所有数据本地存储
- PWA 支持：支持添加到主屏幕，离线可用
- 跨端兼容：完美支持 iPad、Android 平板、桌面浏览器
- 推荐体验：使用 iPad 或 Android 平板，横屏模式，添加到主屏幕后获得最佳体验
一、项目背景：为什么做这个产品？
1.1 痛点洞察
作为一个 4 岁琴童的家长，我在陪练过程中深刻体会到两个核心痛点：
孩子端：
-
识谱练习枯燥乏味，反复练习同一个音符容易失去兴趣
-
缺乏即时反馈，不知道弹得对不对
-
没有成就感，练琴变成"完成任务"
家长端：
-
不懂音乐，无法正确指导孩子
-
不知道孩子的学习进度和薄弱环节
-
陪练过程容易情绪失控，“不写作业母慈子孝，一练钢琴鸡飞狗跳”
1.2 产品定位
基于这些痛点，我决定做一个产品：
PianoFlow - 专为 4-10 岁琴童打造的、基于浏览器端的游戏化视奏与节奏练习工具
它不替代钢琴老师，而是解决"识谱枯燥"和"练习缺乏正反馈"的痛点，通过即时反馈和虚拟经济系统，让枯燥的识谱练习变得像玩游戏一样有趣。
1.3 开发方式
整个项目完全使用 Trae IDE 从零开始搭建，通过 AI 辅助开发，持续迭代到 v1.5.0 版本。最重要的是：需求先行，文档驱动。
二、核心功能：产品长什么样？
2.1 三大练习模式
识谱练习 (Sight Reading)
-
随机出题、即时反馈、连击系统
-
支持升降号和等音等价判定
连音节奏 (Rhythm Game)
-
连音线识别、数字气泡键盘
-
TTS 智能伴读
音程训练 (Interval Training)
-
1-5 度音程识别
-
播放功能辅助学习
2.2 激励体系
-
星级评定（0-5 星） -
金币奖励机制 -
奖励商店（家长自定义奖励）
2.3 家长中心
-
数据看板（练习时长、错题分布） -
设置管理 -
PIN 码保护
2.4 特色体验
-
英雄系统（贝贝熊、跳跳兔、旋律猫） -
智能 TTS 语音引导 -
PWA 离线支持
三、技术栈
⚛️ React 19 + TypeScript
🔨 Rsbuild
🎨 Tailwind CSS v4
🎵 Tone.js
🔄 Zustand
💾 Dexie.js
🌍 i18next
✨ Framer Motion
📱 PWA
纯前端架构，无需后端，所有数据本地存储。
四、从 0 到 1 的完整开发流程（根据真实提交还原）
最重要的是：需求先行，文档驱动。在第一个代码提交之前，就已经准备好了完整的规划文档。
4.1 需求先行：完整的规划文档体系（关键）
在项目初始化时，.trae/documents/ 目录下就已经包含了三个核心规划文档：
文档 1: development-plan.md - 开发任务分解文档（52 行）
AI 帮我制定了详细的 4 阶段开发计划：
# 开发任务分解文档 (Development Task Breakdown)
## Phase 1: Foundation (P0) - 基础设施与核心引擎
| Task ID | 任务描述 | 技术栈 | 依赖 |
| DEV-001 | 项目初始化与构建配置 | React 19, Rsbuild, TailwindCSS | - |
| DEV-002 | 基础路由与布局搭建 | React Router, CSS | DEV-001 |
| DEV-003 | 核心音频引擎 (AudioArchitecture) | Tone.js | DEV-001 |
| DEV-004 | 五线谱渲染引擎 (StaffRenderer) | Canvas API | DEV-001 |
| DEV-005 | 存储服务层 (StorageService) | Dexie.js | DEV-001 |
| DEV-006 | 全局状态管理 (Global Store) | Zustand | DEV-005 |
| DEV-007 | PWA 基础配置 | vite-plugin-pwa | DEV-001 |
## Phase 2: Core Gameplay (P0) - 核心玩法与练习循环
| Task ID | 任务描述 | 技术栈 | 依赖 |
| DEV-008 | 虚拟琴键组件 (VirtualPiano) | React, Tone.js | DEV-003 |
| DEV-009 | 题目生成逻辑 | TypeScript | DEV-006 |
| DEV-010 | 游戏会话状态管理 (Session Store) | Zustand | DEV-006 |
| DEV-011 | 交互判定与防抖 | React, Lodash | DEV-008, DEV-004 |
| DEV-012 | 反馈系统 (Audio & Visual) | Tone.js, CSS Animations | DEV-003, DEV-010 |
| DEV-013 | 结算界面与流程 | React Components | DEV-010, DEV-006 |
| DEV-014 | 基础认知模式 (Learning Mode) | StaffRenderer | DEV-004 |
## Phase 3: Progression & Meta (P1) - 成长系统与元游戏
## Phase 4: Polish & Onboarding (P1/P2) - 打磨与新手引导
文档 2: user-stories.md - 用户故事分解文档（213 行）
AI 帮我拆分了 7 个 Epic，每个 Epic 下有详细的用户故事：
# 用户故事分解文档 (User Stories Breakdown)
## 1. Epic: Onboarding (新手引导)
### US-1.1: 角色选择与欢迎
* Priority: P0
* Story: 作为一名儿童用户，我想要在首次进入时选择一个动物伙伴
* Acceptance Criteria:
1. 首次打开应用，展示 3-4 个动物选项（小熊、小兔、小猫）
2. 点击某个动物时，播放对应的动物叫声和动作动画
3. 选中后进入主页，所选角色常驻显示
## 2. Epic: Learning Mode (学习模式 - 基础认知)
### US-2.1: 五线谱交互认知
* Story: 作为一名儿童用户，我想要点击五线谱的线或间，听到对应的音高
## 3. Epic: Practice Mode (练习模式 - 互动游戏)
### US-3.1: 题目生成与语音指令
### US-3.2: 触控回答与判定
### US-3.3: 正确反馈与连击
### US-3.4: 错误反馈与引导
### US-3.5: 结算与宝箱
## 4. Epic: Garden System (花园/奖励系统)
## 5. Epic: User Profile & Progress (成长/个人中心)
## 6. Epic: Settings & Parent Control (设置与家长控制)
## 7. Epic: System & Technical (系统与非功能)
文档 3: ui-ux-design-specs.md - UI/UX 设计规范文档（143 行）
AI 帮我制定了完整的视觉和交互规范：
# UI/UX 设计规范文档 (UI/UX Design Specifications)
## 2. 视觉语言体系 (Visual Language System)
### 2.1 彩虹音符配色 (Rainbow Note Palette)
| 音名 | 唱名 | 颜色名称 | HEX 值 | 视觉含义 |
| C | Do | 活力红 | #FF5252 | 基础、起始 |
| D | Re | 阳光橙 | #FF9800 | 温暖、向上 |
| E | Mi | 柠檬黄 | #FDD835 | 明亮 |
| F | Fa | 森林绿 | #66BB6A | 生长、自然 |
| G | Sol | 天空蓝 | #42A5F5 | 广阔、清脆 |
| A | La | 靛青蓝 | #3F51B5 | 深邃、稳定 |
| B | Si | 梦幻紫 | #BA68C8 | 神秘、连接 |
### 2.2 界面基础色 (UI Colors)
* 背景色: #FFF9E6 (暖米色，护眼，模拟纸张质感)
* 主色调: #FF6B6B (珊瑚红，用于主按钮、强调)
* 次色调: #4ECDC4 (薄荷绿，用于确认、装饰)
### 4.2 练习反馈状态
* 正确 (Correct):
- 音符爆发彩虹光圈或粒子特效
- 播放 C 大调欢快和弦
- 角色在角落做出欢呼动作
* 错误 (Incorrect):
- 切勿使用红色大叉 (X)
- 音符变成灰色或黯淡色
- 播放柔和的"Boing"弹簧声
### 5.1 关键动画 (Key Animations)
* 音符动作:
- 全音符: 像不倒翁一样左右滚动
- 二分音符: 像气球一样飘动
- 四分音符: 原地跳跃
* 星星奖励: 从正确位置飞出，沿抛物线落入宝箱
* Combo 连击: 连续答对 3 次，屏幕边缘出现彩色呼吸光晕
产出物（在第一个提交中就已存在）：
-
development-plan.md（52 行，4 个阶段，25 个开发任务）
-
user-stories.md（213 行，7 个 Epic，20+ 用户故事）
-
ui-ux-design-specs.md（143 行，完整的视觉和交互规范）
这些文档是在编写任何代码之前就已经完成的，体现了"需求先行，文档驱动"的开发理念。
4.2 Phase 1：基础搭建（第 1 天）
根据 development-plan.md 中的 Phase 1 任务和 user-stories.md 中的用户故事，完成了：
-
项目基础架构搭建
-
核心练习功能实现
-
基础 UI 界面设计
4.3 Phase 2：功能完善（第 2-7 天）
根据规划文档，完成了：
-
英雄系统与 TTS 语音引导
-
国际化支持
-
奖励商店与错题本
4.4 Phase 3：体验优化（第 8-12 天）
根据用户反馈和规划文档，完成了：
-
结算系统优化
-
连音节奏游戏模式
-
PWA 离线支持
4.5 Phase 4：功能扩展（第 13-14 天）
根据规划文档，完成了：
-
家长中心
-
音程训练模式
-
升降号支持
4.6 持续优化与修复
开发过程中持续修复问题和优化体验。
4.7 开发流程总结：完整的软件工程实践
完整的软件工程流程
这个项目严格按照软件工程流程进行开发：
需求分析 → 用户故事拆分 → 优先级排序 → 迭代计划
↓
每个迭代的详细开发计划（技术侧、产品侧、UE侧、测试侧）
↓
迭代开发 → 文档对齐 → 验收测试
↓
下一迭代
每个迭代都包含四个维度的详细计划：
-
技术侧：技术选型、架构设计、接口定义、性能优化
-
产品侧：功能需求、业务逻辑、数据流设计、边界情况
-
UE侧：交互设计、视觉规范、动画效果、用户反馈
-
测试侧：测试用例、验收标准、边界测试、回归测试
文档对齐的重要性：
每个迭代开发完成后，我都会对齐文档，确保代码和文档保持一致。这是实际软件开发中经常被忽视但非常重要的环节。代码和文档不一致会导致：
-
后续维护困难
-
新成员上手成本高
-
知识传承断层
-
技术债务累积
通过严格的文档对齐，我确保了：
-
代码实现与设计文档一致
-
API 文档与实际接口一致
-
用户故事与功能实现一致
-
测试用例与业务逻辑一致
真实迭代数据
版本演进：v1.0.0 → v1.5.0
总耗时：2 个月
提交次数：80+ commits
代码行数：5000+ LOC
组件数量：15+ components
页面数量：7 pages
测试覆盖：30+ test files
文档数量：前期 3 个核心文档，后期 1 个索引文档
开发时间线
实际开发时间：7 天（分散在 1.5 个月内）
第 0 阶段：需求梳理 + 文档编写（3 个核心文档）
第 1 天：基础框架搭建 + 核心功能实现
第 2-7 天：功能完善（英雄系统、国际化、奖励商店）
第 8-12 天：体验优化（结算系统、连音节奏、PWA）
第 13-14 天：功能扩展（家长中心、音程训练、升降号）
持续：Bug 修复和优化
每个迭代结束：文档对齐
时间跨度：1.5 个月（2026-01-11 至 2026-02-22）
实际开发：7 天（有代码提交的天数）
效率提升：AI 辅助开发效率提升约 6 倍
关键洞察
-
需求先行：先写规划文档，再开发，避免返工
-
文档驱动：每个功能都有据可依
-
四维规划：技术、产品、UE、测试四个维度全面考虑
-
文档对齐：每个迭代结束后对齐文档，确保一致性
-
小步快跑：平均每个功能 2-3 次提交完成
-
快速迭代：每周发布 1-2 个版本
-
测试驱动：每个功能都有对应测试
五、成果展示
5.1 获得的荣誉
-
成都 Trae 年终总结 DemoDay：现场投票前三甲
-
成都 WayToAGI：现场投票一等奖
5.2 实际效果
产品使用后，我观察到了一些变化：
孩子的行为：
-
会主动翻书查阅音符
-
做节奏计算时会扳手指
-
知道练习可以获取金币，金币可以兑换奖励
我的观察：
-
孩子对识谱练习不再那么抗拒
-
金币奖励机制确实有激励作用
-
数据记录让我能看到孩子的练习情况
5.3 功能完成度
核心功能已全部完成：识谱练习、连音节奏、音程训练、奖励商店、家长中心等。
六、经验总结：AI 辅助开发的得与失
6.1 核心收获
- 需求先行，文档驱动
-
在第一个代码提交之前，先准备好完整的规划文档
-
development-plan.md、user-stories.md、ui-ux-design-specs.md
-
避免返工，提高开发效率
- 完整的软件工程流程
-
需求分析 → 用户故事拆分 → 优先级排序 → 迭代计划
-
每个迭代包含四个维度：技术侧、产品侧、UE侧、测试侧
-
每个迭代结束后对齐文档，确保代码和文档一致
- AI 辅助开发的正确姿势
-
让 AI 帮你生成规划文档
-
让 AI 帮你拆分任务和用户故事
-
让 AI 帮你设计 UI/UX 规范
-
然后才开始编写代码
- 小步快跑，快速迭代
-
平均每个功能 2-3 次提交完成
-
每周发布 1-2 个版本
-
根据反馈快速调整
6.2 Token 消耗的权衡：文档先行的代价
实际消耗数据：
基础额度：
-
初始额度：600 次
-
周年庆赠送：800 次
-
合计：1400 次
后续充值：
-
多次叠加包充值
-
具体场景：在需求文档没有减少的情况下，用 solo 模式迭代两个功能模块充值了两次 $7 叠加包
主要消耗来源：
-
读取文档形成上下文（主要消耗，占比最大）
-
代码生成和修改
-
调试和问题解决
-
测试用例生成和执行
后期策略调整：
-
从维护 3 个核心文档 → 简化为 1 个索引文档
-
索引文档的作用：
-
作为代码的索引，快速定位功能
-
作为新需求的上下文，减少重复解释
-
记录关键决策和架构设计
我的最终选择：
-
前期：完整文档驱动，确保方向正确
-
后期：索引文档，降低 Token 消耗
-
关键：根据项目阶段灵活调整文档策略
6.3 文档先行的价值
虽然 Token 消耗较大，但文档先行确实有帮助：
我的实际体会：
-
写文档的过程让我想清楚了很多问题，避免了开发过程中的反复修改
-
有文档在，AI 能更快理解项目上下文，开发效率更高
-
文档让我对产品的整体方向有清晰的把控
成本权衡：
-
Token 消耗是实实在在的成本
-
但如果方向错了，返工的成本更高
-
所以我选择前期多花点 Token，确保方向正确
6.4 建议
如果你也想尝试 AI 辅助开发：
-
先写文档，再写代码：需求先行，文档驱动
-
根据阶段调整策略：
-
初期：完整文档，确保方向正确
-
后期：索引文档，降低成本
-
文档对齐很重要：每个迭代结束后对齐文档
-
Git 提交保留开发历史：
-
文档删了也可以从 Git 历史找回
-
方便后期写文章、复盘总结
-
保留完整的开发轨迹
- 降低 Token 消耗的技巧：
-
使用索引文档代替完整文档
-
只在必要时读取完整文档
-
定期清理过时的文档内容
-
将大文档拆分为小文档，按需读取
-
充分利用 AI：让 AI 帮你生成规划文档、用户故事、设计规范
-
AI 评审 + 人工审核：
-
先让 AI 从不同角度评审（需求评审、技术架构评审、设计评审、测试用例评审）
-
让不同的 Agent 从不同角度给出意见，就像"元芳你怎么看"
-
最后人工审核，做最终决策
- 持续迭代：小步快跑，快速迭代
结语
这个项目从最初的陪练痛点出发，通过 AI 辅助开发，一步步迭代成一个功能完整的产品。最重要的是：需求先行，文档驱动。在第一个代码提交之前，就已经准备好了完整的规划文档。
代码只是起点，创造才是终点。
PianoFlow 在 AI 的 demo 展示活动中获得好评，让我意识到：音乐教育不应该只是一个工具，而应该是一个有温度、有故事的世界。接下来我将开发一款全新的"音乐 + 游戏 + 教育"游戏，实现自己的梦想。
我的底气来自哪里？
-
幼时的游戏经历和动漫幻想，让我对世界观构建有独特的理解
-
9 年的软件领域经验，让我有能力将想法变为现实
-
AI 的双重加持：帮助我跨越游戏开发和音乐教育体系的知识鸿沟
希望 PianoFlow 能帮助更多琴童快乐学习，也希望能给同样在使用 AI 辅助开发的你一些启发。目前产品已申请软件著作权。
也许，这就是我一直在等待的机会。
欢迎交流讨论！ 
转载请注明出处
作者：Melody Architect（AI共创）
发布日期：2026 年 3 月
