一切始于一个社区想法

一切始于 TRAE 周年庆前夕的一次社区征集。当“设计一个活动页面”的想法最终要落地为“周年庆正式项目”时，挑战随之而来。

为把这份“来自社区的生日礼物”按期交付，我和几位社区伙伴一起共创。我在项目中同时承担项目经理、UI 设计、前端开发、联调测试等角色，并用 TRAE 贯穿全过程：从文档生成、任务拆解，到基线代码生成、多人协作、缺陷定位与修复。

全程开发使用的是 TRAE国际版 IDE 和 SOLO 模式，主力模型为 GPT-5.2 和 Gemini-3-Pro，从想法到最终网页上线，用时一周，成品如下图：

第一步：从想法，到清晰需求

周年庆的目标是“做一个能让用户参与、愿意分享的小项目”。

我首先将这个笼统的目标拆解为三个需要具体解决的问题：

• 参与路径问题：周年节点需要一个统一入口，让用户“看见就能参与”，路径越短越好。
• 氛围与仪式感问题：只有列表会很平淡，地图能天然制造“点亮世界”的仪式感与参与反馈（每一条心愿都对应一个地点被点亮，越多人参与越直观）。
• 互动与传播问题：用户希望自己的内容被看见、被回应；活动需要自然传播抓手，例如点赞和分享链接。

为了系统性地梳理需求，我习惯于在项目开始时强制自己回答“灵魂 4 问”，并把这一步交给 TRAE 做第一轮头脑风暴，然后由我进行裁剪与定稿：

1. 系统要解决什么问题？
2. 包含哪些核心功能？
3. 输入输出是什么？
4. 依赖哪些组件与数据？

我向 TRAE 的自定义智能体“创意引导师”下达指令，让它围绕这四个问题进行分析。下图是 TRAE 生成的部分初步构想：

经过多轮讨论和我的裁剪，最终得出以下结论：

价值主张

• 把分散的“周年祝福”聚合成一个可视化的共同记忆（地图点亮 + 热力聚合）。
• 让用户在短路径内完成参与，并获得即时反馈（提交成功动效、实时弹幕、点赞增长）。
• 让内容具备可传播性（分享链接可打开特定心愿）。

业务边界

• 心愿提交依赖浏览器定位：用户授权后提交，经纬度写入数据库，省份由坐标推断。
• 心愿提交需要向用户申请位置信息，用户同意后才能提交愿望
• 点赞有防重复：前端本地去重 + 后端/数据库指纹去重，重复点赞返回错误。
• 点亮计数按 IP 限制：同一 IP 只能“点亮”一次。

附灵魂 4 问

1. 系统要解决什么问题？

• 参与路径问题：需要一个统一入口，让用户“快速参与”。
• 可视化与氛围问题：需要UI组件（地图 + 点亮 + 弹幕）来放大参与感。
• 互动与传播问题：用户希望自己的内容被看见、被反馈；活动需要自然传播抓手（点赞、分享链接）。
• 治理与可控问题：匿名参与不可避免带来内容风险，因此必须具备审核与快速处置能力。

2. 包含哪些核心功能？

用户侧

沉浸式开场：现有一个动画，之后进入主界面

地图交互与展示：

• MapLibre 地图（暗色风格）呈现；
• 心愿点位渲染、聚合与热力图层；
• 点击点位打开心愿详情

提交心愿：

• 用户可以输入内容与署名，选择本地头像；
• 提交前要求同意“定位使用说明”并开启定位权限；
• 由定位获得经纬度，并写入数据库

实时氛围：

• 弹幕展示最新心愿

点赞互动：

• 后端数据库 按照IP设置点赞

分享：

• 为单条心愿生成 可传播链接；
• 分享页打开后可直接点赞

心愿榜：按地区聚合，展示总点赞/心愿数排行

3. 输入输出是什么？

核心输入（用户侧）

内容输入：心愿内容 `content`、署名 `author`、头像引用 `avatar_url`。

- 定位输入：浏览器 返回 `latitude` / `longitude`。

- 互动输入：点赞（wishId）、分享（wishId）。

- 隐私/授权输入：是否同意定位说明 + 是否授予定位权限。

核心输出（用户侧）

- 地图层：点位、聚合、热力层；可从列表/弹窗聚焦到某个点位。

- 心愿卡片/详情：作者、头像、内容、点赞数、时间等。

- 实时氛围：弹幕。

- 分享链接：可打开指定心愿。

- 点亮编号：提交成功后返回全站点亮计数。

API 输入输出（面向系统）

• 主要接口：
  • POST /wishes：提交心愿（含经纬度、province_id 等）
  • GET /wishes?limit=...：拉取已审核心愿
  • POST /wishes/{id}/like：点赞（返回最新 likes）
  • GET /leaderboard：省份榜
  • GET /counter、POST /counter/increment、GET /counter/check-ip：点亮计数 + IP 限制
  • POST /shares、GET /shares/{token}：分享 token 生成与解析
  • GET /sse/wishes：SSE 实时推送

数据库输入输出（核心数据模型）

主表为 public.users（语义上承载“心愿”记录）：

• id（uuid）
• content
• author
• avatar_url
• province_id
• location
• likes
• status
• created_at

4. 依赖哪些组件与数据？

我在选型时关注的是“快速落地 + 生态成熟 + 可控成本”。

- 地图：MapLibre GL JS

• 原因：API 成熟、渲染能力强、社区资源多；对“点位 + 聚合 + 交互”非常贴合。

- 前端框架：React + TypeScript

• 原因：页面型项目交付速度快；路由与 API Routes 方便快速搭建接口层。

- 数据库：Supabase

• 原因：TRAE SOLO 可以直接连接，开发非常方便。

- 部署：Vercel

• 原因：TRAE SOLO 一键部署，方便快速展示成果。

第二步：从需求，到可执行的技术方案

有了清晰的需求，下一步是将其转化为结构化的技术文档。在过去，这通常需要耗费大量时间编写 PRD 和技术设计文档。但借助 TRAE ，这个过程可以被极大地加速。

我为 TRAE 准备了三个核心的 Prompt，分别用于生成需求文档（PRD）、技术文档和任务列表。这些 Prompt 不仅仅是简单的指令，更是一套标准化的“模板”，规定了文档的结构、编写规范和技术栈要求等。

生成项目需求提示词

请为 [项目名称] 生成一份完整的需求文档，遵循以下规范：

**文档结构要求：**
1. Introduction - 项目概述和背景
2. Glossary - 定义所有关键术语和系统名称
3. Requirements - 详细的需求列表

**需求编写规范：**
- 每个需求必须包含 User Story（用户故事）
- 每个需求必须包含 Acceptance Criteria（验收标准）
- 所有验收标准必须使用 EARS 模式之一：
  * Ubiquitous: THE <system> SHALL <response>
  * Event-driven: WHEN <trigger>, THE <system> SHALL <response>
  * State-driven: WHILE <condition>, THE <system> SHALL <response>
  * Unwanted event: IF <condition>, THEN THE <system> SHALL <response>
  * Optional feature: WHERE <option>, THE <system> SHALL <response>
  * Complex: [WHERE] [WHILE] [WHEN/IF] THE <system> SHALL <response>

**质量标准：**
- 使用主动语态，明确说明谁做什么
- 避免模糊术语（如"快速"、"合理"、"用户友好"）
- 不使用代词，使用 Glossary 中定义的具体术语
- 每个标准必须可测试和可验证
- 使用正面陈述（说明系统应该做什么，而非不应该做什么）
- 避免逃避条款（如"在可能的情况下"、"如果可行"）

**项目背景：**
[在此描述你的项目想法、目标用户、核心功能等]

请生成符合上述规范的需求文档。

生写项目技术文档提示词

请基于以下需求文档为 [项目名称] 生成一份完整的技术设计文档：

**需求文档路径：** [需求文档的路径或内容]

**文档结构要求：**
1. Overview - 系统概述、核心功能、技术栈选择
2. Architecture - 系统架构图（使用 Mermaid）、请求流程图
3. Components and Interfaces - 各组件的职责、接口定义、实现要点
4. Data Models - 数据库 Schema、Pydantic/数据模型定义
5. Correctness Properties - 可测试的正确性属性
6. Error Handling - 错误处理策略、错误码定义、日志策略
7. Testing Strategy - 单元测试和属性测试策略

**技术栈要求：**
- 编程语言：[指定语言，如 Python/TypeScript/Java]
- Web 框架：[如 FastAPI/Express/Spring Boot]
- 数据库：[如 PostgreSQL/MongoDB/MySQL]
- 缓存/队列：[如 Redis/RabbitMQ]
- 其他技术：[根据需求指定]

**Correctness Properties 要求：**
- 在编写 Correctness Properties 之前，必须先完成 prework 分析
- 每个属性必须以 "For any" 或 "For all" 开头（通用量化）
- 每个属性必须标注验证的需求编号：**Validates: Requirements X.Y**
- 属性应覆盖所有可测试的验收标准
- 消除冗余属性，确保每个属性提供独特的验证价值

**测试策略要求：**
- 明确单元测试和属性测试的互补关系
- 指定属性测试库（如 Hypothesis/fast-check/QuickCheck）
- 每个属性测试至少运行 100 次迭代
- 每个测试必须标注对应的设计属性编号

请生成符合上述规范的技术设计文档。

生成项目任务列表提示词

请基于以下需求文档和设计文档为 [项目名称] 生成一份完整的实现任务列表：

**需求文档路径：** [需求文档的路径]
**设计文档路径：** [设计文档的路径]

**实现语言：** [Python/TypeScript/Java 等]

**任务列表要求：**
1. 将设计转换为离散的编码步骤
2. 每个任务必须是可由代码生成 LLM 执行的具体编码任务
3. 任务必须增量构建，每个任务基于前一个任务
4. 最多两层层级（主任务和子任务）
5. 使用复选框格式：`- [ ] 任务描述`
6. 子任务使用小数编号：`- [ ] 1.1 子任务描述`

**任务内容要求：**
- 每个任务必须引用具体的需求编号：_需求: X.Y, X.Z_
- 包含属性测试子任务，标注属性编号和验证的需求
- 测试相关子任务标记为可选（后缀 `*`）：`- [ ]* 1.2 编写单元测试`
- 在合理的断点添加检查点任务

**禁止的任务类型：**
- 用户验收测试或用户反馈收集
- 部署到生产或预发布环境
- 性能指标收集或分析
- 运行应用进行端到端测试（应使用自动化测试）
- 用户培训或文档创建
- 业务流程或组织变更

**任务示例格式：**
```markdown
- [ ] 1. 实现核心功能
  - [ ] 1.1 实现组件 A
    - 编写核心逻辑实现
    - _需求: X.Y, X.Z_
  - [ ]* 1.2 编写属性测试
    - **Property N: [属性标题]**
    - **Validates: Requirements X.Y**
  - [ ] 1.3 实现组件 B
    - 编写支持逻辑
    - _需求: X.Z_

- [ ] 2. 检查点 - 确保所有测试通过
  - 确保所有测试通过，如有问题请询问用户。
请生成符合上述规范的实现任务列表。

2.1 生成项目文档

参考上面的提示词，可以给出 1周年项目文档、 1周年项目技术文档、1周年项目任务列表。

我们需要仔细检查这些文档，然后进行优化和裁剪。

1周年项目需求文档举例

1周年项目技术文档举例

1周年项目任务列表举例

第三步：用 TRAE 编码、协作与迭代（社区共创实践）

文档就位后，开发工作正式开始。这个过程同样深度融合了社区共创与 TRAE 辅助。

3.1 基线代码生成：用 TRAE 搭出第一个可用版本

为了快速验证核心方案，我需要先创建一个能够展示主页功能的地图页面。我向 TRAE 提供了此前生成的全部文档，并给出了具体指令：

TRAE 马上迎来 1 周年，我们想在这个节点做一个比较有参与感的小项目：TRAE 一周年许愿地图。
设想是做一个前端页面，用户可以选择自己的省份（中国地图）留下愿望，也可以点开查看其他人的留言，并进行点赞互动。

你是资深前端工程师（TypeScript + React/Next.js）。请严格引用并对齐以下三份文档中的要求，生成一个“带地图的最小展示页面（MVP）”，用于演示地图浏览与点选查看心愿信息。输出必须是可直接落地的代码（文件结构 + 每个文件完整内容），不要输出解释性文字，不要添加任何注释。

引用来源（必须在实现中体现）
1) 任务列表：1周年项目任务列表.md
   - 对齐任务：12.1/12.2/12.3/12.4（地图容器、聚合阈值切换、点选信息展示、移动端适配）

2) 需求文档：1周年项目需求文档.md
   - R-02 地图浏览与交互：地图可交互；zoom 阈值以下显示聚合 markers；阈值以上显示单点；点选展示关联心愿信息
   - R-23 性能要求：低 zoom 使用聚合/聚类（本 MVP 用阈值切换模拟即可）
   - R-24 兼容性与可访问性：移动端布局；键盘可达（至少关闭详情面板可用键盘操作）
3) 技术文档：1周年项目技术文档.md
   - 地图使用 MapLibre GL JS
   - 与“/api/map/points?bbox=&zoom=”接口契约保持一致

MVP 范围（最小可展示）
- 单个页面：MapPage（Next.js 页面或 React 路由页均可，但默认按 Next.js 实现）
- 地图能加载并可缩放/拖拽
- 可访问性：
  - 详情面板有“关闭”按钮，支持 Enter/Space 触发；按 Escape 关闭
- 移动端：
  - 页面高度自适应；详情面板在窄屏改为底部抽屉（或全屏 modal）


输出要求
1) 先输出文件结构清单（相对路径）
2) 再逐个文件输出完整代码（包含 package.json、next.config.*、pages 或 app 路由文件、地图页组件、最小数据层、样式文件）
3) 代码必须可运行：给出 npm scripts：dev/build/start
4) 不要写任何“如何运行”的说明文字（只通过 package.json scripts 体现即可）

简单迭代之后，第一个地图版本形成了，但我注意到提示词中缺少对页面风格的约束和创意，于是我使用 Gemini 3 Pro 200K, 补充了新的指令，让 TRAE 参考 国际版官方风格，同时上传了一张 TRAE 官网截图作为参考，让它基于现有代码修改。

经过多轮迭代优化，一个功能完整、风格统一的地图页面便完成了。

前端直接与 Supase 数据库直连，用户可以添加消息到数据库，地图上可以显示用户的留言。

使用 SOLO 中的 Supabae （数据库） 和 Vercel 部署

3.2 社区共创：从“使用者”到“共创者”

3.2.1 社区需求收集、任务分配

基线版本得到了 TRAE 官方同学的认可。于是，我们以此为基础，开始聚集社区里感兴趣的小伙伴进行功能扩展。大家通过线上讨论提出了很多优化方案，我负责收集、确认需求，并分配给参与项目的同学。

期间，通过私聊、多人线上讨论等方式，将需求落地。

（部分需求举例）

3.2.2 社区开源项目多人协作模式

大家通过 Fork 在各自仓库里独立开发，完成后向主仓库发起 PR。我在 PR 中做简单的代码审查，并要求通过基础检查后再合并。这样既能让多人并行开发，也能保证主干分支始终保持可用、稳定的版本。

所有人 Fork 主仓库独立开发：避免互相阻塞，减少冲突。

通过 PR 合并回主干：每个 PR 都必须能跑通基础检查，主干始终保持可用。

在这个过程中，大家也使用 TRAE 来辅助提交代码，自动生成规范的 Commit Message。

通过 TRAE 提交代码

通过PR合并代码到主干

社区伙伴们各自开发，然后通过PR合并到开发主干。

（部分PR举例）

3.3 增量开发与迭代：让文档和代码形成闭环

在增加新功能时，我们依然遵循“文档先行”的原则，并利用 TRAE 让文档与代码保持同步。例如，当需要增加新需求时，我们会：

1. 让 TRAE 阅读现有代码和新需求，生成一份实现方案文档。
2. 团队评审并确定最优方案。
3. 让 TRAE 根据最终方案生成代码。
4. 代码实现后，再由 TRAE 提交，完成闭环。

我们可以让TRAE先根据需求，阅读代码，然后生成一个实现文档

TRAE 生成的任务文档

仔细阅读上面的文档，然后选择一个最优的方案让TRAE实现

需求实现之后，让 TRAE提交代码。

3.4 用 TRAE 解决BUG

项目中，会遇到各种问题，推荐的解决步骤：

1. 让 TRAE 先分析问题，给出一个问题分析文档和推荐的修改方案。
2. 我们review 问题的 Root Cause 和 修改建议。
3. 确认方案后，让 TRAE 基于分析文档修改代码。

图：TRAE 生成的问题分析文档节选

写在最后

从一个模糊的想法，到最终上线的一份完整作品：这次经历不仅是技术上的实践，更是一次身份的转变——从产品的使用者，到价值的共创者。

在需要频繁切换视角、同时推进多项工作的情况下，TRAE 更像一个稳定可靠的搭档：帮我理清需求、输出文档、快速推进实现，也在反复调试和修改中节省了大量时间，让整个共创过程始终保持在可控的节奏里。

这次实践也证明了，在开放的社区中，每一位成员都有机会发起、组织并交付一个有价值的项目。如果你也有好的想法，不妨现在就开始，借助 TRAE 将创意快速变为现实。

期待在社区里，看到更多伙伴发起和完成属于自己的共创项目。