我把设计文档交给 AI，然后看着它踩了10个坑

📋 目录

1. 设计文档交出去之后
2. 第一个”空白”
3. 习惯的养成
4. 时区问题卡了我最久
5. 还有一些小坑
6. 回头看

前两天，公司突然有了内部培训平台的需求。

HR 提了需求：做个系统，让员工在线看培训视频、做完考试才算完成。视频不能下载，学习记录要可追踪。技术栈是 Vue 3 加 FastAPI，我不想自己一点点写代码，于是找了两个 AI 帮手——Tiara 和 Claude Code。

现实比我想象中”丰富”一点。

设计文档交出去之后

Tiara（我的小可爱agent） 拿到任务后，花了大半天，输出了完整的设计包：

• 需求规格说明书 / 系统设计 / 数据库设计 / API 规范
• 15 个页面的 HTML 原型（员工端 8 个 + HR管理端 7 个）
• 安全设计 / bug 预防指南 / 实现注意事项

她还把产出分成两份：一份给我看的 Word 文档，一份给 Claude Code 看的结构化规范。我当时觉得，这活儿干得挺漂亮。

整个项目从接到需求到开发完成，前后一共花了一天半。

Claude Code 接手实现后的第一个晚上，我在旁边观察它的进度。它在跑代码，我在喝咖啡，一切看起来很和谐。然后我刷新了页面。

第一个”空白”

通知中心页面是空白的。

我以为是接口还没跑起来，等了几秒，再刷，还是空白。于是我去翻代码，发现路由写的是 /notifications，但实际路径是 /notification——少了一个字母。

这是我学到的第一课：AI 会复制粘贴，但它不会检查粘贴的位置对不对。

紧接着，考试历史页面也是空白的。理由更离谱——路由根本没注册，Claude Code 写完了页面但忘记告诉路由”有这回事”。学习报表页面也是。三个页面，三种死法。

习惯的养成

我开始习惯每天早上打开浏览器，先数一下今天有几个页面是空白的。

• 半天：通知中心空白 — 路由拼写错误
• 第二个半天：考试历史空白 — 路由未注册
• 又过了半天：跨域报错，端口配置差 2

跨域报错那天，Claude Code 跟我抱怨：请求被浏览器拦截，Access-Control-Allow-Origin。翻了半天发现，.env 里 API 端口写的是 8002，后端实际跑在 8000。

差了 2 就跑不通。很 AI。

时区问题卡了我最久

那天 Claude Code 报 500 错误，我以为是接口逻辑写错了，看日志看了半小时，最后定位到 Pydantic 验证器里一行代码：

`python

if v <= now:

raise ValueError(“截止日期必须晚于当前时间”)

看起来没问题。问题在于 now 是 naive datetime（不含时区），但 v 传进来是 aware datetime（含时区）。Python 不允许拿苹果和橘子比。

我翻了 Tiara 给的实现指南，里面确实写了”统一使用 UTC”，但 Claude Code 在某个验证器里漏了这一条。

这种事很 AI：你告诉它规则，它记住了大部分，少数地方脑子”漏风”。

还有一些小坑

还有一些问题，说大不大，但很影响体验：

• 通知中心的铃铛点不了。未读数永远显示 3。
• 保存视频进度，偶尔报 422——页面卸载时视频元素已不存在。
• 文档材料没办法标记完成，因为没有计时逻辑。而视频有。
• 培训详情页的计数不对——视频和文档混在一起统计，没有区分。

都是小问题，但小问题积累起来，会让人觉得”这系统不太好用”。

回头看

到现在，项目前后端核心功能已经跑通了。回头看这次人机协作，我最大的感受是：设计文档的质量，决定了 AI 写代码的质量上限。

Tiara 给的指南越细，Claude Code 实现时的偏差越小。漏掉的那些问题，往往也是设计阶段没有明确说清楚的点。AI 不会问你没写的东西。

但 AI 也不会自己判断”这个地方应该问一下”。它会按自己的理解硬来，然后等着你发现错了再改。

所以人还是得在。懂设计、懂业务、能在关键节点做判断。这是 AI 替代不了的。

这次踩的 10 个坑，都是可修复的。没有伤筋动骨。项目还在推进，下一阶段继续磨合。

项目仍在推进中，目前已完成前后端核心功能的实现。

10 个坑 | 6 种类型 | 0 个严重问题