实战演练：用 AI 从零构建一个待办事项（Todo）应用-育师

前言：

光说不练假把式。本节我们将通过一个极简的待办事项（Todo）管理应用，把本章学到的项目说明书、规则、五要素框架等技巧串联起来，完整走一遍“基于提示词的 AI 编程工作流”。

你不需要是资深全栈工程师，只需按照步骤操作，就能体验如何让 AI 帮你从零构建一个可运行的 Web 应用。

1. 项目背景与目标

我们要开发一个“麻雀虽小，五脏俱全”的 Todo 应用，它只包含 3 个核心操作：

新增：输入标题，添加一条待办事项。
查询：以列表形式展示所有待办事项。
标记完成：单击复选框，切换事项的完成状态。

技术栈选择

为了让你专注于 AI 编程工作流本身，而非数据库配置，我们采用了最轻量级的方案：

后端：Python 3.12 + FastAPI（现代 API 框架）。
前端：原生 HTML/CSS/JavaScript（单文件实现，无框架依赖）。
存储：内存存储（Python list）。程序重启后数据会清空，但这能让我们省去数据库配置的麻烦，直击 CRUD 逻辑核心。

预备知识：三剑客

在开始之前，简单认识一下我们的三位主角：

FastAPI：基于 Python 的现代 Web 框架，专为构建 API 设计。它能自动处理参数验证，还能自动生成交互式 API 文档。
Pydantic：FastAPI 的底层数据验证库。我们用 Python 类型注解定义数据模型（如title: str），它就能自动完成校验和格式转换。
Uvicorn：FastAPI 的运行服务器。它是一个轻量级的 ASGI 服务器，负责接收 HTTP 请求并转发给 FastAPI 处理。

三者关系：FastAPI 定义逻辑，Pydantic 确保数据格式正确，Uvicorn 让应用跑起来。

2. 第一步：项目初始化（给 AI 立规矩）

在向 AI 发出编程请求之前，我们需要先搭建好“基础设施”。这就像给新员工入职培训，先告诉它项目背景和规矩。

2.1 创建项目说明书 (AGENTS.md)

在 TRAE 中新建一个工程，在空目录下创建AGENTS.md，填入以下内容。这份文档就是 AI 的“项目圣经”。

# TodoApp - 待办事项管理应用 项目简介 学习用的待办事项管理应用，包含 FastAPI 后端和原生 HTML 前端。 数据存储在内存中（Python list），适合快速原型验证。 技术栈 Python 3.12 + FastAPI + Pydantic v2。 原生 HTML/CSS/JavaScript（无框架依赖）。 数据存储：内存中的 Python list。 项目结构 main.py: FastAPI 应用入口，包含内存存储和所有 API 路由。 schemas.py: Pydantic 数据模型。 templates/index.html: 前端单页应用。 架构约定 后端只负责 API 响应，不含 HTML 渲染逻辑。 前端通过 fetch 调用后端 API。 内存存储使用全局 list，id 自增使用 itertools.count。 常用命令 安装依赖: pip install fastapi uvicorn pydantic。 启动服务: uvicorn main:app --reload。 访问前端: http://localhost:8000/。

2.2 创建规则文件 (todo-style.md)

接着创建.trae/rules目录，并在该目录下创建todo-style.md。这是 AI 的“行为准则”。

--- alwaysApply: true --- TodoApp 编码规范 API 响应规范 创建成功: HTTP 201。更新成功: HTTP 200。 资源不存在: HTTP 404, body 格式为 {"detail": "Todo not found"}。 数据模型 Todo 使用 Pydantic 模型。 id 为 int，自增生成。 created_at 使用 datetime.now(timezone.utc)。 前端规范 使用原生 JavaScript，不引入任何前端框架。 所有 API 调用使用 fetch API。

3. 第二步：后端 API 开发

基础设施建好后，我们开始让 AI 写代码。将以下提示词输入 TRAE 的 Agent 模式。注意，我们不需要自己写一行代码，AI 会根据提示词生成main.py和schemas.py。

## 任务
实现 TodoApp 的后端 API，包含新增待办事项、查询待办事项和标记完成 3 个接口。
## 技术栈
Python 3.12 + FastAPI + Pydantic v2。
数据存储在内存中（Python list），id 使用 itertools.count 自增。
## 文件结构
(1) schemas.py: 定义 TodoCreate 和 TodoResponse 两个 Pydantic 模型。
- TodoCreate: title (str, 必填)。
- TodoResponse: id (int), title (str), is_completed (bool), created_at (datetime)。
(2) main.py: FastAPI 应用入口，包含以下路由。
## 接口清单
表格
方法路径说明
GET /todos 获取所有待办事项，返回 {"todos": [...]}
POST /todos 新增待办事项，请求体 {"title": "xxx"}，返回 HTTP 201
PUT /todos/{id} 更新待办事项，请求体 {"is_completed": true}，返回更新后的对象
## 约束
资源不存在时返回 HTTP 404，body 格式 {"detail": "Todo not found"}。
created_at 使用 datetime.now(timezone.utc)。
main.py 需要挂载 templates 目录，根路径"/"返回 index.html。
## 验收标准
POST /todos 创建成功 → HTTP 201，返回完整 Todo 对象。
GET /todos → 返回所有待办事项列表。
PUT /todos/{id} 更新 is_completed → 返回更新后的对象。
PUT /todos/999（不存在）→ HTTP 404。

方法	路径	说明
GET	/todos	获取所有待办事项，返回 {"todos": [...]}
POST	/todos	新增待办事项，请求体 {"title": "xxx"}，返回 HTTP 201
PUT	/todos/{id}	更新待办事项，请求体 {"is_completed": true}，返回更新后的对象

AI 生成代码后会告知生成了哪些文件、有哪些接口以及验证结果，以便我们进行确认。

4. 第三步：前端页面开发

后端搞定后，继续让 AI 实现前端。同样，我们不需要创建文件或编写代码，AI 会自动实现功能。

## 任务
创建 templates/index.html，为 TodoApp 提供可视化界面。
## 技术栈
原生 HTML + CSS + JavaScript（单文件实现，无框架依赖）。
API 调用使用原生 fetch。
## 页面结构
(1)标题: 顶部显示“待办事项管理”。
(2)添加区域: 一个文本输入框 + “添加”按钮。
(3)待办事项列表: 逐条显示所有待办事项，每条包含以下内容：
- 标题文字。
- 完成复选框（单击后切换完成状态）。
- 已完成项显示删除线样式。
## API 调用说明
表格
操作方法路径说明
获取列表 GET /todos 页面加载时调用
新增 POST /todos body: {"title": "xxx"}
切换状态 PUT /todos/{id} body: {"is_completed": true/false}
## json响应格式
// GET /todos 响应 {"todos": [{"id": 1, "title": "完成任务", "is_completed": false, "created_at": "2025-01-15T10:30:00"}]} // POST /todos 响应 {"id": 1, "title": "完成任务", "is_completed": false, "created_at": "2025-01-15T10:30:00"} // 错误响应 {"detail": "Todo not found"}
## CSS 样式要求
整体浅色系，白色背景，灰色边框。
主色调：浅蓝色 (#4A90D9)，仅用于按钮和标题。
已完成项：浅灰色文字 + 删除线。
布局：居中显示，最大宽度为 600px。
字体：无衬线字体 (sans-serif)。
## JavaScript 功能要求
(1) 页面加载时调用 GET /todos 获取列表并渲染。
(2) 单击“添加”按钮，调用 POST /todos，成功后刷新列表。
(3) 单击复选框，调用 PUT /todos/{id} 切换完成状态，成功后刷新列表。
(4) 所有操作失败时在控制台输出错误信息。
## 验收标准
页面加载后显示待办事项列表。
输入标题并单击“添加事项”，新待办事项出现在列表中。
单击复选框，待办事项完成状态切换，文字样式变化。

操作	方法	路径	说明
获取列表	GET	/todos	页面加载时调用
新增	POST	/todos	body: {"title": "xxx"}
切换状态	PUT	/todos/{id}	body: {"is_completed": true/false}

AI 生成前端代码后会告知部分细节，如页面结构、CSS 样式、JavaScript 功能等，以便我们进行审查。

小贴士：虽然后端和前端可以一次性开发完成，但基于实际项目经验，小步推进更好。一次只做一件事，以免 AI 因为幻觉导致返工和质量不稳定。

5. 第四步：运行应用

在后端和前端开发完成后，按以下步骤启动应用：

安装依赖。具体命令如下：
```
pip install fastapi uvicorn pydantic
```
启动服务。具体命令如下：
```
cd todo_app uvicorn main:app --reload
```
访问应用。打开浏览器访问http://localhost:8000/，即可看到 TodoApp 界面。在输入框中输入待办事项标题，单击“添加”按钮即可创建；单击待办事项前的复选框，即可切换完成状态。

由于 AI 越来越智能，以上步骤很可能不需要手动执行。AI 在编写完代码后，会根据项目说明书（AGENTS.md）中的运行方式，自动运行程序。如果缺少依赖，AI 也会自动安装相关的依赖。这也是项目说明书的价值所在，只要给 AI 足够的上下文，随着 AI 越来越聪明，它能够做的事情会越来越多。

本案例使用内存存储，程序重启后数据会清空。这是为了简化复杂度，让读者专注于理解 AI 编程工作流本身。